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 Dashboard
2

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-captured to sync with CRM (HubSpot, Salesforce, Pipedrive)
  • • Track recommendation-clicked for product analytics
  • • Monitor error events with Sentry or Datadog
  • • Measure engagement time using widget-expanded / widget-collapsed

Configuration Options

OptionTypeRequiredDescription
vendorIdstringYesYour vendor ID from dashboard
apiKeystringYesYour API key for authentication
positionstringNobottom-left, bottom-center, bottom-right (default: bottom-center)
theme.primaryColorstringNoWidget primary color (default: #0066ff)
aiPersona.namestringNoCustom AI assistant name
aiPersona.greetingstringNoCustom greeting message
debugbooleanNoEnable console logging (default: false)
mobile.fullscreenbooleanNoFull-screen on mobile (default: true)
analytics.enabledbooleanNoEnable 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

Still having issues?

Our team is here to help you get up and running.