Guides
Help Center

Browser Events

Hook into key moments of the alby widget’s lifecycle in order to enable custom functionality and seamless integration with your website.

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

List of Events

Legacy Events

These events maintain their original names for backward compatibility:

  • generativeQARendered
  • generativeQAEmpty

Core Events

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

  • alby:GenerativeQA::Rendered
  • alby:GenerativeQA::Empty
  • alby:GenerativeQA::Viewed
  • alby:GenerativeQA::ThreadCreated
  • alby:GenerativeQA::ResponseFinished
  • alby:GenerativeQA::InputSubmitted
  • alby:GenerativeQA::Click:Button
  • alby:GenerativeQA::Click:FollowUpButton
  • alby:GenerativeQA::Click:UserFeedback
  • alby:GenerativeQA::Click:Link
  • alby:GenerativeQA::Failed

Event Details

generativeQARendered / alby:GenerativeQA::Rendered

  • Description: This event is dispatched when the alby is fully loaded, and the alby widget 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: 

    /*
{
  questions: string[];   // Questions that are shown initially
  widgetId?: string;    // Unique identifier for the widget instance
}
*/
document.addEventListener('generativeQARendered', function() { 
  const { questions, widgetId } = e.detail;
  
  analytics.track('Widget Rendered', { questions, widgetId });
});

generativeQAEmpty / alby:GenerativeQA::Empty

  • Description: This event is dispatched when the widget is unable to be displayed, which can happen for various reasons. These include data not being available due to a background job still processing data, or intentional conditions like the user being part of a holdout group for testing purposes or a product not found in the alby database. This event informs the browser that the alby widget cannot be rendered at the moment, but the underlying cause may vary. If possible, a reason if provided on why the alby widget could not show.

  • Usage: You can listen for this event to trigger fallback logic, such as displaying an error message, retrying the data load, or logging the failure for debugging and analytics purposes.

  • Payload / Example: 

    enum EmptyEventReason {
  NO_BUTTONS = "NO_BUTTONS",
  PRODUCT_NOT_FOUND = "PRODUCT_NOT_FOUND",
  VARIANT_NOT_FOUND = "VARIANT_NOT_FOUND",
}
/*
{
  reason?: EmptyEventReason;   // Reason why the widget was unable to render
  widgetId?: string;    			 // Unique identifier for the widget instance
}
*/ 
document.addEventListener('generativeQAEmpty', function(e) { 
    const { reason, widgetId } = e.detail;
    console.log('alby widget unable to load.'); // Custom fallback logic (e.g., hide loading animation) 
});

alby:GenerativeQA::Viewed

  • Description: Dispatched when the alby 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: 

    /*
{
  productId: string;    // External product identifier
  variantId?: string;   // Optional variant identifier of the product
  widgetId?: string;    // Unique identifier for the widget instance
}
*/

document.addEventListener('alby:GenerativeQA::Viewed', function(e) {
  const { productId, variantId, widgetId } = e.detail;
  
  analytics.track('Widget Viewed', { productId, variantId, widgetId });
});

alby:GenerativeQA::ThreadCreated

  • Description: Fired when a new conversation thread is initiated, either through a user's freeform question or clicking a predefined button. This event contains the unique thread identifier and the method of initiation.

  • Usage: Use this event to track conversation starts, associate analytics with specific threads, or trigger UI updates when a new conversation begins.

  • Payload / Example: 

    /*
 {
  threadId: string;     // Unique identifier for the conversation thread
  type: "freeform" | "button";  // How the thread was initiated - via free text or predefined button
  content?: string;     // The initial question or button text that started the thread
  widgetId?: string;    // Unique identifier for the widget instance
}
*/

document.addEventListener('alby:GenerativeQA::ThreadCreated', function(e) {
  const { threadId, type, content, widgetId } = e.detail;
  console.log(`New thread ${threadId} started via ${type}`);
});

alby:GenerativeQA::ResponseFinished

  • Description: Triggered when the AI has completed generating a response to a user's question. This event includes the full response text and associated metadata.

  • Usage: Listen for this event to handle completed responses, update UI elements, track response metrics, or trigger follow-up actions.

  • Payload / Example: 

    /*
{
  threadId: string;     // Unique identifier for the conversation thread
  messageId: string;    // Unique identifier for this specific message
  type: "freeform" | "button";  // Whether this response was to a free text question or button click
  question: string;     // The user's submitted text
  response: string;     // The complete AI-generated response text
  widgetId?: string;    // Unique identifier for the widget instance
}
*/

document.addEventListener('alby:GenerativeQA::ResponseFinished', function(e) {
  const { threadId, messageId, response, type, widgetId } = e.detail;
  analytics.track('AI Response Complete', {
    threadId,
    messageId,
    responseLength: response.length
  });
});

alby:GenerativeQA::InputSubmitted

  • Description: Dispatched when a user submits a question through the input field, before the AI begins generating a response.

  • Usage: Use this event to track user questions, update UI states, or perform pre-processing actions before the response generation begins.

  • Payload / Example: 

    /*
{
  text: string;         // The user's submitted text
  threadId: string;     // Unique identifier for the conversation thread
  widgetId?: string;    // Unique identifier for the widget instance
  answer: string;       // The complete AI-generated response text
}
*/

document.addEventListener('alby:GenerativeQA::InputSubmitted', (e) => {
  const { text, threadId, widgetId, answer } = e.detail;
  analytics.track('User Question Submitted', {
    question: text,
    threadId,
    widgetId,
    questionLength: text.length
  });
});

alby:GenerativeQA::Click:Button

  • Description: Fired when a user clicks on a predefined question button in the widget interface.

  • Usage: Track button engagement, trigger UI updates, or perform analytics tracking for predefined question usage.

  • Payload / Example: 

    /*
{
  label: string;        // Text content of the button clicked
  widgetId?: string;    // Unique identifier for the widget instance
  threadId: string;			// Unique identifier for the conversation thread
  answer: string;  			// Text content of the reply
}
*/

document.addEventListener('alby:GenerativeQA::Click:Button', (e) => {
  const { label, widgetId, threadId, answer } = e.detail;
  analytics.track('Predefined Question Clicked', {
    label,
    widgetId,
    threadId,
    answer
  });
});

alby:GenerativeQA::Click:FollowUpButton

  • Description: Dispatched when a user clicks on a follow-up question suggestion after receiving an AI response. These are contextual questions that help users explore related topics.

  • Usage: Use this event to track engagement with follow-up suggestions or trigger additional UI behaviors when users explore related questions.

  • Payload / Example: 

    /*
{
  label: string;        // Text content of the follow-up question clicked
  widgetId?: string;    // Unique identifier for the widget instance
  threadId: string;			// Unique identifier for the conversation thread
  answer: string;  			// Text content of the reply
}
*/

document.addEventListener('alby:GenerativeQA::Click:FollowUpButton', function(e) {
  const { label, widgetId, threadId, answer } = e.detail;
  analytics.track('Follow-up Question Clicked', { label, widgetId, threadId, answer });
});

alby:GenerativeQA::Click:UserFeedback

  • Description: Fired when a user provides feedback on an AI response through thumbs up/down or similar feedback mechanisms. This helps track user satisfaction and response quality.

  • Usage: Listen for this event to collect user feedback, track satisfaction metrics, or trigger feedback-based actions.

  • Payload / Example: 

    /*
{
  isPositive: boolean;  // Whether the feedback was positive (true) or negative (false)
  threadId: string;     // Unique identifier for the conversation thread
  messageId: string;    // Unique identifier for the message being rated
  widgetId?: string;    // Unique identifier for the widget instance
  label: string;        // Text content of the users question
  answer: string;  			// Text content of the reply the user feedback was submitted on
}
*/

document.addEventListener('alby:GenerativeQA::Click:UserFeedback', function(e) {
  const { isPositive, threadId, messageId, widgetId, label, answer } = e.detail;
  analytics.track('Response Feedback', {
    threadId,
    messageId,
    sentiment: isPositive ? 'positive' : 'negative',
    label,
    answer
  });
});

alby:GenerativeQA::Click:Link

  • Description: Fired when the AI response generation encounters an error. This event helps track and handle failures in the generative QA process.

  • Usage: Listen for this event to track link interactions, validate outbound links, or analyze which types of resources users find most helpful in AI responses.

  • Payload / Example: 

    /*
{
  url: string;        // The URL that was clicked
  widgetId?: string;  // Unique identifier for the widget instance
}
*/

document.addEventListener('alby:GenerativeQA::Click:Link', (e) => {
  const { url, widgetId } = e.detail;
  analytics.track('Response Link Clicked', {
    url,
    widgetId,
    domain: new URL(url).hostname
  });
});

alby:GenerativeQA::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:

    /*
{
  widgetId: string;  // Unique identifier for the widget instance
}
*/

document.addEventListener('alby:GenerativeQA::Failed', (e) => {
  const { widgetId } = e.detail;
  analytics.track('alby widget failed to load', {
  	widgetId
  });
})

Updated 5 days ago