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="https://firstdistro.com/sdk/sdk.js"></script>
<script>
  FirstDistro.init({
    vendorId: 'your-vendor-id',
    apiKey: 'your-api-key'
  });
</script>
That's it! Your AI persona, branding, and settings are automatically loaded from your dashboard configuration. Changes you make in the dashboard apply instantly without redeploying code.

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 reference

All configuration options (most are optional and use dashboard defaults)

💡 Best Practice: Use Dashboard Configuration

The minimal SDK setup (vendorId + apiKey) automatically loads your settings from the dashboard. This gives you industry-smart defaults, instant updates without code changes, and centralized configuration.

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.namestringNoAI assistant name (defaults to industry-smart name from dashboard)
aiPersona.greetingstringNoGreeting message (defaults to industry-smart greeting from dashboard)
debugbooleanNoEnable console logging (default: false)
mobile.fullscreenbooleanNoFull-screen on mobile (default: true)
analytics.enabledbooleanNoEnable automatic tracking (default: true)

Advanced configuration

Override dashboard settings for specific use cases

When to use advanced options

  • You need different personas on different pages/domains
  • A/B testing different AI personalities
  • White-label deployments for multiple clients

Example: Override AI persona

FirstDistro.init({
  vendorId: 'your-vendor-id',
  apiKey: 'your-api-key',

  // Override dashboard persona for this specific page
  aiPersona: {
    name: 'Alex',
    greeting: 'Hi! I\'m Alex, your telecom solutions expert.'
  },

  // Optional: Custom theme
  theme: {
    primaryColor: '#ff6600'
  },

  // Optional: Custom position
  position: 'bottom-right'
});
Note: Hardcoded values override dashboard settings. You'll need to redeploy code to make changes. For most use cases, we recommend configuring in the dashboard instead.

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.