Clarity event tracking

Event tracking helps you understand how users interact with Clarity. Each interaction provides insights into engagement, performance, and potential issues. This article outlines the events Clarity captures.

Overview

Few core mechanics influence how Clarity tracks events and attributes:

Two-level A/B testing: Clarity runs A/B tests at two levels. The global level determines whether a shopper sees Clarity or is assigned to a control group. The use-case level decides which specific use case a shopper sees.
Third-party A/B testing: Clarity supports third-party tools for variant assignment, including tests with 3 or more variants. For example, Clarity versus a test experience versus a control group.
Traffic throttling: Traffic throttling lets Clarity limit the amount of site traffic entering a Clarity experiment without changing the variant split. This supports gradual rollouts while keeping the test setup consistent.

Event types

Clarity events are grouped as:

A/B test events: Impression-level events that support variant analysis and measure Clarity's overall performance.
Interaction events: Shopper behavior inside the chat widget, plus Clarity's responses. Analyze how shoppers engage with the Clarity interface.
Safety events: Errors and performance issues, so you can detect and resolve problems fast.

To build event reporting, see Clarity analytics and Clarity dashboard metrics.

Default event attributes

Every shopper event is also enriched with browser, device, operating system, and geolocation fields (browser, device, os, city, country, state, latitude, longitude, ip, and similar).

Attribute	Description	Values
`action`	The event action type. Identifies the event.	One of the action values documented on this page (for example, `use_case_session_start`, `user_respond`)
`agent_id`	The Clarity agent configured for the account.	Example: `0199a817-49f6-73f3-8769-12e853567c30`
`banner_id`	Unique identifier for the widget.	Example: `68e02f017fe069386bb3073e`
`banner_name`	Display name of the widget.	Example: `Clarity-Embedded-Chat`
`banner_type`	Type classification of the widget.	Example: `medium_rectangle`
`chat_id`	Unique identifier for the chat session.	Example: `c123456789`
`global_variant_id`	Identifier for the global A/B test variant.	`0`, `1`
`global_variant_name`	Name of the global A/B test variant.	Example: `Clarity`
`variant_id`	Identifier for the use-case-level variant.	`0`, `1`
`variant_name`	Name of the use-case-level variant.	Example: `Variant A`
`variant_origin`	Source of the variant assignment.	`ABtest`, `contextual personalisation`
`experiment_id`	Identifier of the experiment when a third-party A/B testing tool provides the variant.	Example: `584sa5729971a4f992sj9`
`experiment_source`	Source of the third-party experiment.	Example: `bloomreach`
`global_rank`	A/B split rank used to determine control-group membership.	Integer 0–99
`throttle_rank`	The throttle bucket used to limit traffic exposure.	Integer 0–99
`clarity_session_state`	The shopper's current session state with respect to Clarity.	`unseen`, `seen`, `interacted`
`clarity_session_interaction_count`	Number of interactions in the current session.	Integer; `-1` before the first show
`path`	Page URL.	Example: `https://www.example.com/products/47748`
`interaction`	Whether the event resulted from a shopper interaction.	`true`, `false`

Non-Clarity events

To get a complete view of Clarity’s impact, track relevant external custom events:

Required events: cart_update, purchase, view_item
Recommended events: checkout, view_category