alby-single-button-embed

Allow customers a way to access your AI assistant with a simple button.

This documentation provides information about the events that the alby-single-button-embed widget publishes to the browser during its lifecycle.

Core Events

All core events follow the alby:SingleButtonEmbed:: namespace pattern:

  • alby:SingleButtonEmbed::Rendered
  • alby:SingleButtonEmbed::Viewed
  • alby:SingleButtonEmbed::Clicked
  • alby:SingleButtonEmbed::Failed

Event Details

alby:SingleButtonEmbed::Rendered

  • Description: This event is dispatched when the widget is fully loaded and is rendered on the screen.

  • Usage: You can listen for this event to trigger any post-render actions, such as adjusting layout, displaying additional elements, or logging analytics data.

  • Payload / Example:

    /*
    {
      widgetId: string;    // Unique identifier for the widget instance
    }
    */
    document.addEventListener('alby:SingleButtonEmbed::Rendered', function() { 
      const {  widgetId } = e.detail;
      
      analytics.track('Widget Rendered', { widgetId });
    });
    

alby:SingleButtonEmbed::Viewed

  • Description: Dispatched when the widget becomes visible in the viewport. This indicates that the widget has been successfully loaded and is now within the user's view.

  • Usage: Listen for this event to track widget visibility, trigger analytics, or perform actions that should occur when the widget enters the user's viewport.

  • Payload / Example:

    /*
    {
      widgetId: string;    // Unique identifier for the widget instance
    }
    */
    document.addEventListener('alby:SingleButtonEmbed::Viewed', function() { 
      const {  widgetId } = e.detail;
      
      analytics.track('Widget Viewed', { widgetId });
    });
    

alby:SingleButtonEmbed::Clicked

  • Description: Fired when a user clicks on the widget.
  • Usage: Track button engagement, trigger UI updates, or perform analytics tracking.
  • Payload / Example:
    /*
    {
      widgetId: string;    // Unique identifier for the widget instance
    }
    */
    document.addEventListener('alby:SingleButtonEmbed::Clicked', function() { 
      const {  widgetId } = e.detail;
      
      analytics.track('Widget Clicked', { widgetId });
    });
    

alby:SingleButtonEmbed::Failed

  • Description: Fired when widget initialization encounters an unexpected error. This event helps track and handle failures in the initialization process.

  • Usage: Listen for this event to handle error states, display appropriate error messages or log to an external server.

  • Payload / Example:

    enum FailedEventReason {
      MISSING_WIDGET_ID = "MISSING_WIDGET_ID",
      FAILED_TO_INITIALISE_WIDGET = "FAILED_TO_INITIALISE_WIDGET",
    }
    
    /*
    {
      widgetId: string;    // Unique identifier for the widget instance
      error: FailedEventReason;
    }
    */
    document.addEventListener('alby:SingleButtonEmbed::Clicked', function() { 
      const {  widgetId, error } = e.detail;
      
      analytics.track('Widget Failed', { widgetId, errror });
    });