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

# Click Tracking

> See how often visitors use the buttons, links and fields in your widgets, and the click-through rate of each one.

Add a `trackingId` to an element in your widget's code, and Chatbase counts how often visitors see it and use it. No code on your website is needed. The counts and the click-through rate appear in [Analytics → Widgets](https://chatbase.co/docs/user-guides/chatbot/analytics.md#widgets).

```jsx theme={null}
<Card>
  <Col gap={3}>
    <Title value="Find a dealer near you" />
    <Button label="Find a dealer" trackingId="Find a dealer" onClickAction={{ functionName: "findDealer" }} />
    <Button label="Call us" trackingId="Call us" onClickAction={{ functionName: "callUs" }} />
  </Col>
</Card>
```

The `trackingId` is also the element's label in analytics, so give each one a short name a person can read.

## Add a trackingId

In the [code editor](https://chatbase.co/docs/developer-guides/widgets/code-editor.md), add `trackingId` to any element you want to track. It appears in autocomplete, and hovering it shows the rules.

![The code editor showing trackingId on each element of a dealer finder widget, with its hover help open](https://mintcdn.com/chatbase/63YjsEzKEXBi6euZ/images/widgets/tracking-id-hover.png?fit=max\&auto=format\&n=63YjsEzKEXBi6euZ\&q=85\&s=09f09196c469a892b8078c1c965bf1ca)

With the [AI Widget Builder](https://chatbase.co/docs/developer-guides/widgets/ai-widget-builder.md), ask for it in your own words, for example "track clicks on the main buttons". The builder only adds trackingIds when you ask.

### Rules

* The value is plain text written in the code: `trackingId="Find a dealer"`. Variables, expressions and template literals such as ``trackingId={`Find ${city}`}`` are not allowed.
* The value can't be empty and is at most 100 characters.
* Elements that share a `trackingId` count as one element. Use this for items rendered from a list, for example `trackingId="Product card"` on every card.
* Renaming a `trackingId` starts a new row in analytics. The old name keeps its history.

When a rule is broken, the editor shows the error and blocks saving until you fix it.

![The code editor showing the error trackingId must be plain text after a template literal was used as a trackingId](https://mintcdn.com/chatbase/63YjsEzKEXBi6euZ/images/widgets/tracking-id-error.png?fit=max\&auto=format\&n=63YjsEzKEXBi6euZ\&q=85\&s=8ba2f3882ccbeed85c35e797841e9f49)

### Supported elements

| Element | What counts as an interaction |
| - | - |
| `Button` | A click |
| `Image`, `ListViewItem` | A click. They need an `onClickAction`. |
| `Form` | A submit |
| `Input`, `Textarea` | Leaving the field after changing its text |
| `Select`, `RadioGroup`, `DatePicker` | Choosing a value |
| `Checkbox` | Checking or unchecking it |
| `Slider` | Releasing the handle at a new value |
| `Dropzone`, `FileInput` | Picking or dropping files |
| `Markdown` | A click on a link inside it |

Layout components, text components and `Map` don't accept a `trackingId`. Focusing or hovering an element is never counted.

## What Gets Counted

Each time your agent shows a widget in a conversation is one **appearance**. For every tracked element in that appearance, Chatbase counts:

* **Impressions:** 1 if the element was on screen. An element inside a [state](https://chatbase.co/docs/developer-guides/widgets/states.md) that never became active, a step the visitor never reached, or an empty list gets no impression.
* **Interactions:** 1 if the visitor used the element at least once. Clicking a button five times in the same appearance still counts once.

The **rate** is interactions divided by impressions. Days are split by when the widget appeared, so each day's rate stays between 0% and 100%.

Widgets count in conversations from the chat widget, iframe embeds, Center Stage, Search and the Help page. Conversations from the API, MCP, the mobile SDKs, the Playground and the action and Q\&A previews are not counted.

## Visitor Privacy and Consent

When a visitor sees or uses a tracked element, their browser reports it to Chatbase. The report holds the element's `trackingId` and links it to the conversation. It sends nothing the visitor typed or chose.

If your consent tool still loads the chat when a visitor declines analytics, turn the reports off for that visitor with the `disableWidgetTracking` [runtime option](https://chatbase.co/docs/developer-guides/website-integration/chat-interface-control.md#runtime-options):

```javascript theme={null}
// The visitor declined analytics
window.chatbase.setOptions({ disableWidgetTracking: true });

// The visitor accepted analytics later
window.chatbase.resetOptions({ disableWidgetTracking: true });
```

While the option is on, the chat sends no reports at all. Elements shown in that time get no impressions, so visitors who opt out don't lower your rates. Elements still on screen when the option is cleared are counted from then on.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.