Skip to main content
This page covers the browser events you dispatch. For lifecycle events emitted by Webless itself, see Listen to Webless analytics events.

​
Install the widget

Add the Webless widget script to your site. Webless will provide the production script URL for your account. 
<script src="YOUR_WIDGET_SCRIPT_URL"></script>

​
Open the search popup

Dispatch the webless-search event whenever a user clicks a custom button, link, or CTA. 
document.dispatchEvent(new CustomEvent("webless-search"));

​
Send custom tracking events

Dispatch the webless-event custom event when you want to send additional tracking context into Webless analytics. 
document.dispatchEvent(
  new CustomEvent("webless-event", {
    detail: {
      event_type: "search_button_click",
      page: window.location.pathname,
      query: "pricing",
      metadata: {
        placement: "header",
        campaign: "spring-launch"
      }
    }
  })
);

​
Event payload

FieldRequiredDescription
event_typeYesA short identifier for the event
pageNoThe current page path
queryNoThe active search query
metadataNoAny additional structured details

​
Common pattern

Use one handler to track the click and open the widget in the same interaction. 
document.getElementById("search-btn").addEventListener("click", () => {
  document.dispatchEvent(
    new CustomEvent("webless-event", {
      detail: {
        event_type: "search_button_click",
        page: window.location.pathname
      }
    })
  );

  document.dispatchEvent(new CustomEvent("webless-search"));
});
Keep event_type values stable and machine-readable. That makes downstream analytics, Clay enrichment, and internal dashboards much easier to maintain.