Feedback Widget API Documentation & Examples

The Boost Toad widget includes a JavaScript API for programmatic control. This guide documents all available methods with examples.

What you'll learn:

✓Initializing the widget
✓Opening/closing programmatically
✓Passing user data
✓Listening to events
✓Error handling
✓Advanced use cases

Getting Started

▸Script Tag Installation

First, add the widget to your site:

<script src="https://boosttoad.com/api/widget/bundle?projectId=YOUR_PROJECT_ID" async></script>

html

The widget loads asynchronously and exposes window.FeedbackWidget.

if (window.FeedbackWidget) {
  // Widget is loaded
} else {
  // Wait for load
  window.addEventListener('feedbackWidgetLoaded', () => {
    // Widget ready
  })
}

javascript

API Reference

▸window.FeedbackWidget.init()

Initialize or re-initialize the widget with custom settings.

window.FeedbackWidget.init({
  projectId: 'YOUR_PROJECT_ID',  // Required
  user: {                         // Optional: User identification
    email: 'user@example.com',
    name: 'John Doe',
    id: 'user-123'
  },
  metadata: {                     // Optional: Custom metadata
    plan: 'pro',
    signupDate: '2025-01-01'
  },
  onOpen: () => {                 // Optional: Callback when opened
    console.log('Widget opened')
  },
  onClose: () => {                // Optional: Callback when closed
    console.log('Widget closed')
  },
  onSubmit: (data) => {           // Optional: Callback after submission
    console.log('Feedback submitted:', data)
  }
})

javascript

Parameters:

✓projectId (string, required): Your Boost Toad project ID
✓user (object, optional): User information

- email (string): User's email - name (string): User's name - id (string): Your internal user ID

✓metadata (object, optional): Custom key-value pairs attached to feedback
✓onOpen (function, optional): Called when widget opens
✓onClose (function, optional): Called when widget closes
✓onSubmit (function, optional): Called after successful submission

Returns: Promise that resolves when widget is ready

Example with React:

import { useEffect } from 'react'
import { useAuth } from './hooks/useAuth'

function App() {
  const { user } = useAuth()

  useEffect(() => {
    if (user) {
      window.FeedbackWidget?.init({
        projectId: process.env.REACT_APP_FEEDBACK_PROJECT_ID,
        user: {
          email: user.email,
          name: user.displayName,
          id: user.uid
        },
        metadata: {
          plan: user.subscription?.plan,
          signupDate: user.createdAt
        }
      })
    }
  }, [user])

  return <div>Your app</div>
}

tsx

▸window.FeedbackWidget.open()

Programmatically open the widget.

window.FeedbackWidget.open()

// Or open to specific type
window.FeedbackWidget.open('bug')      // Open bug report form
window.FeedbackWidget.open('feature')  // Open feature request form
window.FeedbackWidget.open('nps')      // Open NPS survey

javascript

Parameters:

✓type (string, optional): 'bug' | 'feature' | 'nps' | 'feedback'

Example: Open from Custom Button

function FeedbackButton() {
  return (
    <button onClick={() => window.FeedbackWidget?.open('bug')}>
      Report a Bug
    </button>
  )
}

tsx

▸window.FeedbackWidget.close()

Close the widget if it's open.

window.FeedbackWidget.close()

javascript

▸window.FeedbackWidget.status()

Get current widget status.

const status = window.FeedbackWidget.status()

console.log(status)
// {
//   isOpen: false,
//   isLoaded: true,
//   projectId: 'abc123'
// }

javascript

Returns:

✓isOpen (boolean): Whether widget modal is currently open
✓isLoaded (boolean): Whether widget has finished loading
✓projectId (string): Current project ID

▸Events

Listen to widget events:

// Widget loaded and ready
window.addEventListener('feedbackWidgetLoaded', () => {
  console.log('Widget ready')
})

// Widget opened
window.addEventListener('feedbackWidgetOpened', () => {
  console.log('Widget opened')
})

// Widget closed
window.addEventListener('feedbackWidgetClosed', () => {
  console.log('Widget closed')
})

// Feedback submitted
window.addEventListener('feedbackWidgetSubmitted', (event) => {
  console.log('Submitted:', event.detail)
  // event.detail contains: { type, content, user }
})

javascript

▸Error Handling

try {
  await window.FeedbackWidget.init({ projectId: 'invalid' })
} catch (error) {
  if (error.code === 'INVALID_PROJECT_ID') {
    console.error('Project ID is invalid')
  } else if (error.code === 'NETWORK_ERROR') {
    console.error('Network error, check connection')
  }
}

javascript

▸Advanced Examples

Example: Context-Aware Feedback

// Attach page context to feedback
function openFeedbackWithContext() {
  window.FeedbackWidget.init({
    projectId: 'YOUR_ID',
    metadata: {
      currentPage: window.location.pathname,
      userAgent: navigator.userAgent,
      screenSize: `${window.innerWidth}x${window.innerHeight}`
    }
  })
  window.FeedbackWidget.open()
}

javascript

Example: Conditional Widget Loading

// Only load widget for logged-in users
if (user.isLoggedIn) {
  const script = document.createElement('script')
  script.src = `https://boosttoad.com/api/widget/bundle?projectId=${PROJECT_ID}`
  script.async = true
  document.body.appendChild(script)
}

javascript

Example: A/B Testing Integration

window.FeedbackWidget.init({
  projectId: 'YOUR_ID',
  metadata: {
    experiment: 'checkout-redesign',
    variant: 'B'
  }
})

javascript

▸TypeScript Support

declare global {
  interface Window {
    FeedbackWidget?: {
      init: (config: FeedbackConfig) => Promise<void>
      open: (type?: FeedbackType) => void
      close: () => void
      status: () => FeedbackStatus
    }
  }
}

interface FeedbackConfig {
  projectId: string
  user?: {
    email?: string
    name?: string
    id?: string
  }
  metadata?: Record<string, any>
  onOpen?: () => void
  onClose?: () => void
  onSubmit?: (data: FeedbackData) => void
}

type FeedbackType = 'bug' | 'feature' | 'nps' | 'feedback'

interface FeedbackStatus {
  isOpen: boolean
  isLoaded: boolean
  projectId: string
}

typescript

Common Use Cases

▸1. Authenticated User Identification

// Identify users for better support
auth.onAuthStateChanged((user) => {
  if (user) {
    window.FeedbackWidget?.init({
      projectId: 'YOUR_ID',
      user: {
        email: user.email,
        name: user.displayName,
        id: user.uid
      }
    })
  }
})

javascript

▸2. Pre-fill Bug Reports

// Open bug report with error context
function reportError(error) {
  window.FeedbackWidget?.init({
    projectId: 'YOUR_ID',
    metadata: {
      errorMessage: error.message,
      errorStack: error.stack,
      timestamp: new Date().toISOString()
    }
  })
  window.FeedbackWidget?.open('bug')
}

javascript

▸3. Analytics Integration

window.FeedbackWidget?.init({
  projectId: 'YOUR_ID',
  onSubmit: (data) => {
    // Track in analytics
    analytics.track('Feedback Submitted', {
      type: data.type,
      page: window.location.pathname
    })
  }
})

javascript

Wrapping Up

The Boost Toad JavaScript API gives you full control over the widget. Use it to identify users, attach context, and integrate with your app's workflow.

Get started with Boost Toad →

Feedback Widget API Documentation & Examples

Getting Started

▸Script Tag Installation

▸Checking if Widget is Loaded

API Reference

▸window.FeedbackWidget.init()

▸window.FeedbackWidget.open()

▸window.FeedbackWidget.close()

▸window.FeedbackWidget.status()

▸Events

▸Error Handling

▸Advanced Examples

▸TypeScript Support

Common Use Cases

▸1. Authenticated User Identification

▸2. Pre-fill Bug Reports

▸3. Analytics Integration

Wrapping Up

Ready to build a product users love?