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

# UTM tracking

> Keep campaign attribution when visitors follow links your agent shares.

The JavaScript embed automatically adds the visitor's campaign parameters to
links your agent shares back to your website. A visitor arriving from an ad can
follow a pricing or signup link in chat without losing the campaign that
brought them in.

| Visitor lands on | Agent shares | Visitor follows |
| - | - | - |
| `example.com/?utm_source=google&utm_campaign=spring_sale` | `example.com/pricing` | `example.com/pricing?utm_source=google&utm_campaign=spring_sale` |

## Set it up

Install the [JavaScript embed](https://cntillion.com/docs/channels/website.md#the-floating-widget) on every page of
your website, including campaign landing pages. Use the current snippet from
**Channels → Install → Website widget**, with `embed.js?v=5` or later.

```html theme={null}
<script
  src="https://app.cntillion.com/embed.js?v=9"
  data-centillion-agent="YOUR_AGENT_ID"
  defer
></script>
```

No extra instructions or `identify` calls are needed. Tracking works for
anonymous visitors and visitors you
[identify with a signed token or hash](https://cntillion.com/docs/customer-data/identity-verification.md).
Keep your existing identity setup.

## What gets saved

The embed reads these five parameters when its script runs:

* `utm_source`
* `utm_medium`
* `utm_campaign`
* `utm_term`
* `utm_content`

It saves the first nonempty set in your website's `sessionStorage`, under
`centillion:utm:v1`. Navigating to another page or arriving from a different
campaign in the same tab keeps that first campaign. If the first page has no
UTMs, the first later page with UTMs supplies them.

Resetting the chat keeps this campaign. When a published chat reloads to start
a new conversation, the embed sends the saved parameters to the widget again.
Selecting a different [agent release](https://cntillion.com/docs/agents/releases-and-workflows.md) for that
conversation does not clear the campaign stored on your website.

Values last for the tab session. The embed ignores unrelated query parameters,
blank values, and individual values longer than 1,000 characters. It preserves
accepted values exactly, including spaces and non-English text, and URL-encodes
them when adding them to a link.

If browser settings block session storage, the embed can still use the current
page's UTMs. It cannot keep them across page loads in that case.

## Which links get campaign parameters

Tracking applies to web links in agent replies, including replies as they
appear, action buttons, and product links. The destination must have the same
hostname as the website hosting the embed. For an embed on `example.com`, a
link to `shop.example.com` is a different hostname and stays unchanged.

Relative links resolve against the website page where the chat is open.
Existing query parameters and fragments stay on the link. If a link already
has one of the visitor's UTM keys, the saved visitor value replaces it without
adding duplicates.

Links to other websites, email addresses, telephone numbers, and in-page
anchors stay unchanged. Visitor messages also stay unchanged. When there are
no saved UTMs, links keep their original destinations.

This feature requires the JavaScript embed on your website. A bare iframe,
Help page, Center Stage, and the dashboard Playground do not receive campaign
parameters from your website.

## Test on your website

1. Open your website in a fresh tab with
   `?utm_source=test&utm_campaign=embed_check` in the address.
2. Ask the agent for a link to a page on that website, such as pricing.
3. Copy the link address. It should contain `utm_source=test` and
   `utm_campaign=embed_check`.
4. Navigate to another page on the same website without UTMs and ask again.
   The link should still carry the same campaign values.
5. Reset the chat, wait for it to load, and ask for another link to your website.
   The new conversation should still use the same campaign values.
6. Ask for a link to another website. That link should stay unchanged.

## Troubleshooting

If campaign parameters are missing, check that the landing page runs the
current embed script. In that page's developer console, inspect
`sessionStorage.getItem("centillion:utm:v1")`. A missing value means the embed
has not captured a campaign in this tab, or storage is unavailable.

To repeat a test with a different campaign, clear the stored value with
`sessionStorage.removeItem("centillion:utm:v1")`, then reload the landing page
with the new UTMs. Changing the address alone does not replace a campaign that
the embed already captured.

If the saved values look right, compare the link's hostname to the website
hosting the embed. They must match exactly. Test through the widget on your
website so it can receive that page's campaign parameters.


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