> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webless.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Listen to Webless analytics events

> Subscribe to Webless lifecycle events in the browser and forward them to your analytics stack.

<Info>
  Webless emits DOM custom events with the `webless:` prefix and a structured
  `event.detail` payload.
</Info>

## Add listeners after Webless initializes

```javascript theme={null}
const eventTypes = [
  "session_start",
  "searchbar_visible",
  "searchbar_hidden",
  "searchbar_close",
  "searchbar_click",
  "suggested_question_click",
  "tile_click",
  "click_cta",
  "floating_button_visible",
  "floating_button_click"
];

eventTypes.forEach((eventType) => {
  document.addEventListener(`webless:${eventType}`, (event) => {
    console.log(`[Webless Event: ${eventType}]`, event.detail);

    // Forward to your analytics service here.
    // analytics.track(eventType, event.detail);
  });
});
```

## Supported events

<AccordionGroup>
  <Accordion title="Session and initialization" icon="play-circle">
    | Event                   | Fired when                | Core fields                           |
    | ----------------------- | ------------------------- | ------------------------------------- |
    | `webless:session_start` | A new user session starts | `sessionId`, `timeStamp`, `eventType` |
  </Accordion>

  <Accordion title="Search bar visibility" icon="eye">
    | Event                       | Fired when                            | Core fields                                       |
    | --------------------------- | ------------------------------------- | ------------------------------------------------- |
    | `webless:searchbar_visible` | The search bar enters the viewport    | `sessionId`, `location`, `timeStamp`, `eventType` |
    | `webless:searchbar_hidden`  | The search bar leaves the viewport    | `sessionId`, `location`, `timeStamp`, `eventType` |
    | `webless:searchbar_close`   | A user closes the floating search bar | `sessionId`, `location`, `timeStamp`, `eventType` |
  </Accordion>

  <Accordion title="User interaction" icon="pointer">
    | Event                              | Fired when                         | Core fields                                    |
    | ---------------------------------- | ---------------------------------- | ---------------------------------------------- |
    | `webless:searchbar_click`          | A user submits a search query      | `query`, `sessionId`, `timeStamp`, `eventType` |
    | `webless:suggested_question_click` | A user clicks a suggested question | `query`, `sessionId`, `timeStamp`, `eventType` |
    | `webless:tile_click`               | A user clicks a result tile        | `query`, `sessionId`, `timeStamp`, `eventType` |
    | `webless:click_cta`                | A user clicks the CTA button       | `query`, `sessionId`, `timeStamp`, `eventType` |
  </Accordion>

  <Accordion title="Floating button" icon="circle-dot">
    | Event                             | Fired when                              | Core fields                                       |
    | --------------------------------- | --------------------------------------- | ------------------------------------------------- |
    | `webless:floating_button_visible` | The floating button enters the viewport | `sessionId`, `location`, `timeStamp`, `eventType` |
    | `webless:floating_button_click`   | A user clicks the floating button       | `sessionId`, `location`, `timeStamp`, `eventType` |
  </Accordion>
</AccordionGroup>

## Payload shape

```typescript theme={null}
interface ClientEventPayload {
  eventType: string;
  timeStamp: number;
  sessionId: string;
  location?: "floating" | "nav";
  query?: string;
  [key: string]: unknown;
}
```

## Example payloads

<CodeGroup>
  ```json session_start.json theme={null}
  {
    "sessionId": "abc123-def456-ghi789",
    "timeStamp": 1703123456789,
    "eventType": "session_start"
  }
  ```

  ```json searchbar_click.json theme={null}
  {
    "query": "What is artificial intelligence?",
    "sessionId": "abc123-def456-ghi789",
    "timeStamp": 1703123456789,
    "eventType": "searchbar_click"
  }
  ```

  ```json floating_button_click.json theme={null}
  {
    "sessionId": "abc123-def456-ghi789",
    "location": "floating",
    "timeStamp": 1703123456789,
    "eventType": "floating_button_click"
  }
  ```
</CodeGroup>

## Performance and troubleshooting

<AccordionGroup>
  <Accordion title="Events are not firing" icon="triangle-alert">
    * Make sure Webless finished initializing before you add listeners.
    * Make sure your listener script appears after the Webless script.
    * Make sure no browser console errors stop later scripts from running.
  </Accordion>

  <Accordion title="Visibility events fire too often" icon="timer">
    Debounce frequent events before forwarding them to your analytics service.

    ```javascript theme={null}
    const debounce = (fn, wait) => {
      let timeout;
      return (...args) => {
        clearTimeout(timeout);
        timeout = setTimeout(() => fn(...args), wait);
      };
    };

    const debouncedTrack = debounce((eventName, data) => {
      analytics.track(eventName, data);
    }, 1000);
    ```
  </Accordion>
</AccordionGroup>