> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/ads-exposure-tracking.md).

# Ads exposure tracking

Bring ad views and clicks into your datamart with pixels and click-tracking URLs.

## Your goal

Get the exposure of your users to display and video ads into your own datamart, so impressions and clicks sit on the same timeline as your site and CRM data.

## Expected outcome

`$ad_view` and `$ad_click` events arriving from your DSP or ad server, carrying the campaign, ad group, and creative identifiers you can report on.

## What you can track

| Format          | What it covers                                        |
| --------------- | ----------------------------------------------------- |
| **Display ads** | Static images, animations, and HTML5 animated ads.    |
| **Video ads**   | Video ads the user sees through a marketing campaign. |

All ads tracking is done with **pixels** and **click-tracking URLs**.

| Event       | Tracking method    | Meaning                                       |
| ----------- | ------------------ | --------------------------------------------- |
| `$ad_view`  | Pixel              | The view or impression of the ad by the user. |
| `$ad_click` | Click-tracking URL | The click on the ad by the user.              |

{% hint style="info" %}
Activities tracked this way have `$type` set to `DISPLAY_AD` and `$session_status` set to `NO_SESSION`. See [the UserActivity object](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time.md#the-useractivity-object).

This is the feature to use when you want ad views and clicks directly in your datamart while buying through DSPs.
{% endhint %}

## The display ad pixel

```
https://events.mediarithmics.com/v1/touches/pixel?
  $ev=$ad_view&
  $dat_token=<DATAMART_TOKEN>&
  $catn=<CAMPAIGN_TECHNICAL_NAME>&
  $scatn=<AD_GROUP_TECHNICAL_NAME>&
  $crtn=<CREATIVE_TECHNICAL_NAME>&
  $cb=<CACHEBUSTER>&
  gdpr=<GDPR>&
  gdpr_consent=<GDPR_CONSENT_184>
  <any custom property>
```

## The click-tracking URL

```
https://events.mediarithmics.com/v1/touches/click?
  $ev=$ad_click&
  $dat_token=<DATAMART_TOKEN>&
  $catn=<CAMPAIGN_TECHNICAL_NAME>&
  $scatn=<AD_GROUP_TECHNICAL_NAME>&
  $crtn=<CREATIVE_TECHNICAL_NAME>&
  $cb=<CACHEBUSTER>&
  $redirect=<CLICK_URL>&
  gdpr=<GDPR>&
  gdpr_consent=<GDPR_CONSENT_184>
  <any custom property>
```

## Parameters

| Field                 | Type                     | Description                                                                |
| --------------------- | ------------------------ | -------------------------------------------------------------------------- |
| `$ev`                 | String                   | The event name: `$ad_view` for impressions, `$ad_click` for clicks.        |
| `$dat_token`          | String                   | The **token** of the datamart - not the ID.                                |
| `$catn`               | String                   | Campaign technical name.                                                   |
| `$scatn`              | String                   | Sub-campaign - ad group - technical name.                                  |
| `$crtn`               | String                   | Creative technical name.                                                   |
| `$redirect`           | String                   | **Clicks only.** The redirect URL, URL-encoded (RFC 3986).                 |
| `$cb`                 | String, optional         | Cache buster - a random string.                                            |
| `$cuid`               | String                   | The user account identifier.                                               |
| `$comp_token`         | String                   | The compartment **token** - not the ID.                                    |
| `$email_hash`         | String                   | The user's email hash.                                                     |
| `$uaid`               | String                   | The mobile identifier of the user, identifying the user agent. Pixel only. |
| `$uids`               | JSON as string, optional | A list of user identifiers - see below.                                    |
| `gdpr`                | Number                   | TCF v2.2 parameter indicating whether GDPR applies: `1` or `0`.            |
| `gdpr_consent`        | String                   | TCF v2.2 parameter containing the encoded consent string.                  |
| *any custom property* | Any, optional            | A custom property.                                                         |

{% hint style="warning" %}
Before declaring a custom property, tell the mediarithmics Professional Services team so it can be indexed in your data schema - otherwise it arrives but cannot be used for segmentation or data visualisation. See [Schema definition](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/schema-definition.md).
{% endhint %}

## Passing user identifiers with `$uids`

This applies to **all** pixel-based tracking that uses the `events.mediarithmics.com/v1/touches/pixel` endpoint - ads, email, conversions.

`$uids` carries one or more identifiers as a JSON array:

```
$uids=jso-[{"$tpe":"AG","$agid":"vec:1234"}]
```

The `jso-` prefix means the rest of the string is interpreted as a JSON object. **Encode the URL correctly.**

{% tabs %}
{% tab title="User account" %}

| Field        | Type            | Description                       |
| ------------ | --------------- | --------------------------------- |
| `$tpe`       | Constant string | `AC`                              |
| `$ctok`      | String          | The **token** of the compartment. |
| `$acid`      | String          | The user account ID.              |
| {% endtab %} |                 |                                   |

{% tab title="User email" %}

| Field        | Type             | Description     |
| ------------ | ---------------- | --------------- |
| `$tpe`       | Constant string  | `EM`            |
| `$eh`        | String           | The email hash. |
| `$e`         | String, optional | The raw email.  |
| {% endtab %} |                  |                 |

{% tab title="User agent" %}

| Field   | Type            | Description        |
| ------- | --------------- | ------------------ |
| `$tpe`  | Constant string | `AG`               |
| `$agid` | String          | The user agent ID. |

{% hint style="warning" %}
Use the registry **token**, not the ID, when formatting the user agent ID here - for example `dev:<registry_token>:<value>`.
{% endhint %}
{% endtab %}
{% endtabs %}

## Platform integrations

To integrate with an external DSP or ad server, use **the IDs of the creative, ad group, and campaign from that platform as the technical names**. Each platform exposes them as macros.

{% tabs %}
{% tab title="Display & Video 360" %}

```
https://events.mediarithmics.com/v1/touches/pixel?
  $ev=$ad_view&
  $dat_token=<DATAMART_TOKEN>&
  $catn=${CAMPAIGN_ID}&
  $scatn=${INSERTION_ORDER_ID}&
  $crtn=${CREATIVE_ID}&
  gdpr=${GDPR}&
  gdpr_consent=${GDPR_CONSENT_184}&
  $cb=${CACHEBUSTER}
```

```
https://events.mediarithmics.com/v1/touches/click?
  $ev=$ad_click&
  $dat_token=<DATAMART_TOKEN>&
  $catn=${CAMPAIGN_ID}&
  $scatn=${INSERTION_ORDER_ID}&
  $crtn=${CREATIVE_ID}&
  gdpr=${GDPR}&
  gdpr_consent=${GDPR_CONSENT_184}&
  $cb=${CACHEBUSTER}&
  $redirect=${CLICK_URL_ENC}
```

{% endtab %}

{% tab title="Campaign Manager 360" %}

```
https://events.mediarithmics.com/v1/touches/pixel?
  $ev=$ad_view&
  $dat_token=<DATAMART_TOKEN>&
  $catn=%ebuy!&
  $scatn=%eaid!&
  $crtn=%ecid!&
  gdpr=${GDPR}&
  gdpr_consent=${GDPR_CONSENT_184}&
  $cb=%n
```

```
https://events.mediarithmics.com/v1/touches/click?
  $ev=$ad_click&
  $dat_token=<DATAMART_TOKEN>&
  $catn=%ebuy!&
  $scatn=%eaid!&
  $crtn=%ecid!&
  gdpr=${GDPR}&
  gdpr_consent=${GDPR_CONSENT_184}&
  $cb=%n&
  $redirect=<CLICK_URL>
```

{% endtab %}

{% tab title="Google Ad Manager" %}

```
https://events.mediarithmics.com/v1/touches/pixel?
  $ev=$ad_view&
  $dat_token=<DATAMART_TOKEN>&
  $catn=%ebuy!&
  $scatn=%eaid!&
  $crtn=%ecid!&
  gdpr=${GDPR}&
  gdpr_consent=${GDPR_CONSENT_184}&
  $cb=%%CACHEBUSTER%%
```

```
https://events.mediarithmics.com/v1/touches/click?
  $ev=$ad_click&
  $dat_token=<DATAMART_TOKEN>&
  $catn=%ebuy!&
  $scatn=%eaid!&
  $crtn=%ecid!&
  gdpr=${GDPR}&
  gdpr_consent=${GDPR_CONSENT_184}&
  $cb=%%CACHEBUSTER%%&
  $redirect=<CLICK_URL>
```

{% endtab %}

{% tab title="Xandr" %}

```
https://events.mediarithmics.com/v1/touches/pixel?
  $ev=$ad_view&
  $dat_token=<DATAMART_TOKEN>&
  $catn=${CP_CODE}&
  $scatn=${CPG_CODE}&
  $crtn=${CREATIVE_CODE}&
  gdpr=${GDPR}&
  gdpr_consent=${GDPR_CONSENT_184}&
  $cb=${CACHEBUSTER}
```

```
https://events.mediarithmics.com/v1/touches/click?
  $ev=$ad_click&
  $dat_token=<DATAMART_TOKEN>&
  $catn=${CP_CODE}&
  $scatn=${CPG_CODE}&
  $crtn=${CREATIVE_CODE}&
  $cb=${CACHEBUSTER}&
  gdpr=${GDPR}&
  gdpr_consent=${GDPR_CONSENT_184}&
  $redirect=${CLICK_URL_ENC}
```

{% endtab %}

{% tab title="The Trade Desk" %}

```
https://events.mediarithmics.com/v1/touches/pixel?
  $ev=$ad_view&
  $dat_token=<DATAMART_TOKEN>&
  $catn=%%TTD_CAMPAIGNID%%&
  $scatn=%%TTD_ADGROUPID%%&
  $crtn=%%TTD_CREATIVEID%%&
  $cb=%%TTD_CACHEBUSTER%%&
  gdpr=${GDPR}&
  gdpr_consent=${GDPR_CONSENT_184}
```

```
https://events.mediarithmics.com/v1/touches/click?
  $ev=$ad_click&
  $dat_token=<DATAMART_TOKEN>&
  $catn=%%TTD_CAMPAIGNID%%&
  $scatn=%%TTD_ADGROUPID%%&
  $crtn=%%TTD_CREATIVEID%%&
  $cb=%%TTD_CACHEBUSTER%%&
  gdpr=${GDPR}&
  gdpr_consent=${GDPR_CONSENT_184}&
  $redirect=%%TTD_CLK_ESC%%
```

Additional properties can be tracked as custom properties:

```
domain=%%TTD_SITE%%&
device=%%TTD_DEVICETYPE%%
```

{% endtab %}
{% endtabs %}

Each platform documents its own macro list; use it to confirm the exact macro names before going live.

## Video ads

Basic video ad tracking is achieved by integrating **the display ad pixel** with `$ad_view` events and **the click-tracking URL** with `$ad_click` events into your video ad format.

For more advanced capabilities, a specific integration can be set up based on the visit pixel with custom completion events, plus an [activity analyzer](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/activity-analyzers.md). Discuss this with your account representatives during the design phase.

## Verify

* `$ad_view` and `$ad_click` events appear with `$type` `DISPLAY_AD`.
* Campaign, ad group, and creative technical names are populated, not left as raw macros - an unresolved `%%MACRO%%` in the stored data means the platform did not substitute it.
* Clicks redirect correctly.
* Custom properties you rely on are indexed in the schema.

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Conversions</strong></td><td>Recording that the exposure led to a goal.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/conversions.md">Conversions</a></td></tr><tr><td><strong>Email tracking</strong></td><td>The same pixel mechanics for email.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/email-tracking.md">Email tracking</a></td></tr><tr><td><strong>Collect data in real time</strong></td><td>The activity origin, filled from these events.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time.md">Collect data in real time</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/ads-exposure-tracking.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.