Widget SDK v0.1.0
FirstDistro Widget SDK
Embed our AI-powered customer success widget on your website in minutes. Transform product confusion into customer success.
Quick Integration
Add 3 lines of code to your website. No complex setup or dependencies required.
Secure & Private
API key authentication with rate limiting. Your data stays secure.
Works Everywhere
Compatible with any website. React, Vue, vanilla HTML - it just works.
Quick Start Guide
1
Get Your API Key
Log in to your dashboard and generate an API key from the Chat Widget settings.
Go to Dashboard2
Add SDK to Your Website
Copy this code snippet and paste it before the closing </body> tag of your HTML.
<!-- FirstDistro Widget SDK -->
<script src="/sdk/sdk.js"></script>
<script>
FirstDistro.init({
vendorId: 'your-vendor-id',
apiKey: 'your-api-key',
position: 'bottom-center',
aiPersona: {
name: 'Sarah',
greeting: 'Hi! I'm Sarah, your AI advisor.'
},
theme: {
primaryColor: '#0066ff'
},
debug: false
});
</script>You're Done!
The widget will appear on your website. Customize it further from your dashboard.
Event Listeners
Track widget interactions and integrate with your CRM, analytics, and custom workflows.
Available Events
// Get widget instance
const widget = FirstDistro.getInstance();
// Widget is ready and loaded
widget.on('widget-ready', (data) => {
console.log('Widget initialized!', data.sessionId);
});
// Lead captured (email/contact info submitted)
widget.on('lead-captured', (data) => {
console.log('New lead:', data.email, data.name);
// Send to your CRM
sendToHubSpot(data.email, data.name);
// Track in analytics
analytics.identify(data.email, {
name: data.name,
sessionId: data.sessionId
});
});
// Conversation started
widget.on('conversation-started', (data) => {
console.log('User started chatting');
analytics.track('Conversation Started');
});
// Product recommendation clicked
widget.on('recommendation-clicked', (data) => {
console.log('Product clicked:', data.productTitle);
analytics.track('Product Interest', {
product: data.productTitle,
confidence: data.confidence
});
});
// Widget expanded/collapsed
widget.on('widget-expanded', () => {
console.log('Widget opened');
});
widget.on('widget-collapsed', () => {
console.log('Widget minimized');
});
// Error handling
widget.on('error', (data) => {
console.error('Widget error:', data.error);
// Send to error tracking (Sentry, etc.)
});💡 Integration Tips
- • Use
lead-capturedto sync with CRM (HubSpot, Salesforce, Pipedrive) - • Track
recommendation-clickedfor product analytics - • Monitor
errorevents with Sentry or Datadog - • Measure engagement time using
widget-expanded/widget-collapsed
Configuration Options
| Option | Type | Required | Description |
|---|---|---|---|
| vendorId | string | Yes | Your vendor ID from dashboard |
| apiKey | string | Yes | Your API key for authentication |
| position | string | No | bottom-left, bottom-center, bottom-right (default: bottom-center) |
| theme.primaryColor | string | No | Widget primary color (default: #0066ff) |
| aiPersona.name | string | No | Custom AI assistant name |
| aiPersona.greeting | string | No | Custom greeting message |
| debug | boolean | No | Enable console logging (default: false) |
| mobile.fullscreen | boolean | No | Full-screen on mobile (default: true) |
| analytics.enabled | boolean | No | Enable automatic tracking (default: true) |
Troubleshooting
Widget not appearing on page?
✓Check browser console for errors (F12 → Console tab)
✓Verify API key is active (not revoked) in dashboard
✓Ensure script is placed before closing
</body> tag✓Try adding
debug: true to see detailed logs"Invalid API key" error?
✓Check API key is copied correctly (no extra spaces)
✓Verify API key status is "active" in dashboard
✓Don't commit API keys to public repositories (use environment variables)
✓Create a new API key if you suspect it's compromised
Seeing CORS warnings in console?
ℹThis is normal behavior. The widget uses iframe isolation for security.
ℹCORS warnings can be safely ignored - they don't affect functionality.
ℹNo action needed from your side.
Widget script not loading?
✓Check Network tab in DevTools to see if
/sdk/sdk.js is loading✓Verify no Content Security Policy (CSP) is blocking the script
✓Try loading the script with
defer attribute if there are conflicts