Listen to Webless analytics events

Webless emits DOM custom events with the webless: prefix and a structured event.detail payload.

Add listeners after Webless initializes

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

Session and initialization

Event	Fired when	Core fields
`webless:session_start`	A new user session starts	`sessionId`, `timeStamp`, `eventType`

Search bar visibility

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`

User interaction

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`

Floating button

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`

Payload shape

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

Example payloads

{
  "sessionId": "abc123-def456-ghi789",
  "timeStamp": 1703123456789,
  "eventType": "session_start"
}

{
  "query": "What is artificial intelligence?",
  "sessionId": "abc123-def456-ghi789",
  "timeStamp": 1703123456789,
  "eventType": "searchbar_click"
}

{
  "sessionId": "abc123-def456-ghi789",
  "location": "floating",
  "timeStamp": 1703123456789,
  "eventType": "floating_button_click"
}

Performance and troubleshooting

Events are not firing

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.

Visibility events fire too often

Debounce frequent events before forwarding them to your analytics service.

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);

Start here

Search experience

Integrations

Listen to Webless analytics events

Add listeners after Webless initializes

Supported events

Payload shape

Example payloads

Performance and troubleshooting

​Add listeners after Webless initializes

​Supported events

​Payload shape

​Example payloads

​Performance and troubleshooting

Add listeners after Webless initializes

Supported events

Payload shape

Example payloads

Performance and troubleshooting