alby-guided-questionnaire

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

Core Events

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

• alby:GuidedQuestionnaire::Rendered
• alby:GuidedQuestionnaire::Viewed
• alby:GuidedQuestionnaire::Clicked
• alby:GuidedQuestionnaire::Failed

Event Details

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

  TypeScript

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

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

  TypeScript

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

alby:GuidedQuestionnaire::Clicked

• Description: Fired when a user clicks on one of the questionnaire option buttons.
• Usage: Track user engagement with questionnaire options, trigger UI updates, or perform analytics tracking.
• Payload / Example:
  TypeScript

  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
  }
  */
  document.addEventListener('alby:GuidedQuestionnaire::Clicked', function(e) { 
    const { widgetId } = e.detail;
    
    analytics.track('Guided Questionnaire Option Clicked', { widgetId });
  });
  

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

  TypeScript

  enum FailedEventReason {
    MISSING_WIDGET_ID = "MISSING_WIDGET_ID",
    FAILED_TO_INITIALISE_WIDGET = "FAILED_TO_INITIALISE_WIDGET",
    MISSING_CHATBOT = "MISSING_CHATBOT",
    MISSING_CATEGORY = "MISSING_CATEGORY",
    MISSING_PRODUCT_IDS = "MISSING_PRODUCT_IDS",
    NO_DYNAMIC_QUESTIONNAIRE_FOUND = "NO_DYNAMIC_QUESTIONNAIRE_FOUND"
  }
  
  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
    error: FailedEventReason;
  }
  */
  document.addEventListener('alby:GuidedQuestionnaire::Failed', function(e) { 
    const { widgetId, error } = e.detail;
    
    analytics.track('Guided Questionnaire Failed', { widgetId, error });
    
    // Handle specific error cases
    switch(error) {
      case 'MISSING_WIDGET_ID':
        console.error('Widget ID is required');
        break;
      case 'MISSING_CHATBOT':
        console.error('Chatbot configuration is missing');
        break;
      case 'MISSING_CATEGORY':
        console.error('Category is required for dynamic questionnaires');
        break;
      case 'NO_DYNAMIC_QUESTIONNAIRE_FOUND':
        console.error('No dynamic questionnaire found for the given parameters');
        break;
    }
  });
  

Error Scenarios

The Failed event can be triggered in the following scenarios:

• MISSING_WIDGET_ID: No widgetId attribute is provided
• FAILED_TO_INITIALISE_WIDGET: Unable to fetch widget configuration from the server
• MISSING_CHATBOT: No chatbot is configured for the given brandId
• MISSING_CATEGORY: No category attribute is provided (required for dynamic questionnaires)
• MISSING_PRODUCT_IDS: No productIds attribute is provided (required for dynamic questionnaires)
• NO_DYNAMIC_QUESTIONNAIRE_FOUND: No dynamic questionnaire found for the given category and product IDs