Measure interactions with analytics events
On this page
Smart Assistant can publish events that describe how your visitors interact with it: when they open the chat, click a suggestion, receive product recommendations, ask for an agent, and so on.
The events are not tied to any particular tool. Smart Assistant publishes them in the visitor’s browser, and your own page decides what to do with them: send them to Google Analytics, to Google Tag Manager, to another analytics tool, or ignore them.
1. Ask us to enable the events
Analytics events are disabled by default. To enable them for your instance, contact the Usizy team. Until we enable them, Smart Assistant publishes nothing, so adding the code below has no effect.
2. Listen to the events
Every event is published as a standard browser CustomEvent named sa:event, and the event itself is in its detail property.
The event bubbles up through the page, so you can listen on document without referencing the assistant:
document.addEventListener('sa:event', (e) => {
console.log(e.detail.event, e.detail)
})
To keep it simple, you can also listen on the <smart-assistant> element itself:
document.querySelector('smart-assistant').addEventListener('sa:event', (e) => {
console.log(e.detail)
})
chat_opened, which can happen as soon as the page loads.3. What an event looks like
{
"event": "product_clicked",
"version": 1,
"event_id": "01a1caf0-e3de-7146-bf14-4dbe0ca5d8ca",
"timestamp": "2026-11-11T10:00:00.000Z",
"source": "widget",
"instance": "your-instance",
"conversation_id": null,
"anonymous_id": "",
"properties": { "product_id": "12345" }
}
| Field | Description |
|---|---|
event | Name of the event, in lowercase snake_case. See the list below. |
version | Version of the event format. It is 1 today. |
event_id | Unique identifier of the event. Use it to discard duplicates in your analytics tool. |
timestamp | When the event happened, in ISO 8601 format. |
source | widget for events that happen on the screen (clicks, opening the chat) and backend for events that happen in the conversation (a recommendation, a handoff to an agent). |
instance | Identifier of your Smart Assistant instance. |
conversation_id | Identifier of the conversation. Only present on backend events. |
anonymous_id | Pseudonymous identifier of the visitor, stable within your instance. Only present on backend events. It cannot be traced back to the visitor and is different for every instance. |
properties | Extra details about the event. They are plain values (text, numbers, true/false), never nested objects. |
None of the events contains personal data: they never include the visitor’s messages, name, email or any other text the visitor has typed.
4. Events
Events from the screen (source: widget)
| Event | When | Properties |
|---|---|---|
chat_opened | The chat window goes from closed to open. | None |
chat_closed | The chat window is closed. | None |
suggestion_clicked | The visitor clicks a suggestion or menu button. | label: text of the button. subtopic: topic of the button, or null. |
product_clicked | The visitor clicks a product in a recommendation carousel. | product_id: identifier of the product in your catalogue. |
Events from the conversation (source: backend)
| Event | When | Properties |
|---|---|---|
conversation_started | A new conversation begins and the assistant greets the visitor. | language: language of the conversation, for example en. |
product_recommended | The assistant shows a carousel of products or outfits. | kind: products or outfits. count: number of products (or outfits) shown. flow: internal name of the flow that produced it. |
flow_started | The assistant starts a guided process (a size recommendation, an order lookup…). | flow: internal name of the process. |
flow_completed | A guided process finishes. | flow: internal name of the process. |
handoff_to_agent | The conversation is handed over to a human agent. | ticket_system: zendesk, email or native. reason: why the handoff happened, one of request, suggested, critical, angry, unknown or none. |
feedback_given | The visitor rates the conversation or a message. | scope: conversation or message. rating: the score given. For message, 1 is thumbs up and 0 is thumbs down. feedback_type: only for conversation, one of Star, CSAT, NPS or Binary. |
flow values are internal names. Treat them as opaque labels to group events, and do not build logic that depends on their exact spelling, since they can change.backend events travel through the live chat connection, so they are published while the chat is connected.
5. Send the events to Google Tag Manager
If you use Google Tag Manager, the simplest option is to let Smart Assistant push its events to the dataLayer. Add the analytics-datalayer attribute to the Smart Assistant element:
<smart-assistant api-key="YOUR_API_KEY" analytics-datalayer></smart-assistant>
Every event is then pushed to window.dataLayer with the name prefixed by sa_, so it never collides with your own events:
{
event: 'sa_product_clicked',
product_id: '12345',
sa_event_id: '01a1caf0-e3de-7146-bf14-4dbe0ca5d8ca',
sa_instance: 'your-instance',
sa_conversation_id: null
}
The properties of the event (here product_id) are added to the same object, and the identifying fields get the sa_ prefix. The dataLayer does not include anonymous_id, source or timestamp. If you need them, use the browser event described in section 2.
In Google Tag Manager:
- Create a Custom Event trigger whose event name is, for example,
sa_product_clicked. Use Some Custom Events with a regular expression such as^sa_to catch all of them with one trigger. - Create Data Layer Variables for the properties you want to use, for example
product_id. - Create a tag (for instance a Google Analytics: GA4 Event tag) that fires on that trigger and sends the parameters you need.
6. Send the events to Google Analytics without Tag Manager
If you use gtag directly, listen to the browser event and translate it. This example maps the product click to the recommended GA4 event select_item and sends the rest as custom events:
document.addEventListener('sa:event', (e) => {
const { event, properties } = e.detail
if (event === 'product_clicked') {
gtag('event', 'select_item', {
items: [{ item_id: properties.product_id }]
})
return
}
gtag('event', `sa_${event}`, properties)
})
count or kind) only appear in reports after you register them as custom dimensions or metrics in your GA4 property.7. Consent and privacy
Smart Assistant only publishes the events in the visitor’s browser, and it never includes personal data in them. Whether those events are then sent to Google Analytics or to any other tool is decided by your page.
Make sure your listener (or your Google Tag Manager tags) respects your visitors’ choices. For example, only start sending events once the visitor has accepted the analytics category in your cookie banner:
document.addEventListener('sa:event', (e) => {
if (!window.myConsent?.analytics) {
return
}
// send the event to your analytics tool
})
Here window.myConsent stands for whatever your own consent management platform provides.
See Consent Management for how consent works in Smart Assistant.