---
updatedAt: 2025-12-10T17:31:58.000Z
agentTools:
  projectIndex: https://developers.alby.com/llms.txt
---

# alby-questionnaire

Help customers find the right products by presenting a series of questions that narrow down products within a category.

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

## Core Events

All core events follow the `alby:Questionnaire::` namespace pattern:

* `alby:Questionnaire::Rendered`
* `alby:Questionnaire::Viewed`
* `alby:Questionnaire::Clicked`
* `alby:Questionnaire::Failed`

## Event Details

### alby:Questionnaire::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:Questionnaire::Rendered', function(e) { 
    const { widgetId } = e.detail;
    
    analytics.track('Questionnaire Rendered', { widgetId });
  });
  ```

### alby:Questionnaire::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:Questionnaire::Viewed', function(e) { 
    const { widgetId } = e.detail;
    
    analytics.track('Questionnaire Viewed', { widgetId });
  });
  ```

### alby:Questionnaire::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:Questionnaire::Clicked', function(e) { 
    const { widgetId } = e.detail;
    
    analytics.track('Questionnaire Option Clicked', { widgetId });
  });
  ```

### alby:Questionnaire::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:Questionnaire::Failed', function(e) { 
    const { widgetId, error } = e.detail;
    
    analytics.track('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