# Ads exposure tracking

You can track the exposition of users to the different kind of Ads format that exist today:

* **Display Ads**: All Ads that are either static image/animations or HTML5 animated Ads
* **Video Ads**: All Video Ads that the User can see through a marketing campaign

All Ads tracking is done using **Pixels** and **Click Tracking URLs**.

{% hint style="info" %}
You should consider using this feature to get ad view and ad click directly within your datamart when using DSPs .
{% endhint %}

{% hint style="info" %}
Activities tracked through this method will be of `DISPLAY_AD` *$type* and `NO_SESSION` *$session\_status*. See [User activity object](https://developer.mediarithmics.io/user-points/user-activities#user-activity-object) for more information.
{% endhint %}

## Associated user events

There are two predefined [user events](https://developer.mediarithmics.io/user-points/user-activities#predefined-event-names) that should be tracked during the exposition of a user to an Ad :

| Event name | Tracking method    | Description                                         |
| ---------- | ------------------ | --------------------------------------------------- |
| $ad\_view  | Pixel              | The 'view/impression' of the Display Ad to the User |
| $ad\_click | Click Tracking URL | The 'click' of the Ad by the User                   |

## Display Ad Pixel

Use the following URL in your tracking pixel to send an `$ad_view` event to the platform.

```markup
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
```

| Field                    | Type                      | Description                                                                                                            |
| ------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| $ev                      | String                    | The event name. **$ad\_view for Display Ad impression tracking**                                                       |
| $dat\_token              | String                    | The **token** (not the ID) of the datamart in the mediarithmics platform.                                              |
| $catn                    | String                    | Campaign technical name                                                                                                |
| $scatn                   | String                    | Sub-campaign technical name                                                                                            |
| $crtn                    | String                    | Creative technical name                                                                                                |
| $cb                      | String                    | The cache buster parameter. It should contain a random string. optional                                                |
| $cuid                    | String                    | User account [identifier](https://developer.mediarithmics.io/user-points#user-identifiers) of the user                 |
| $uaid                    | String                    | Mobile identifier of the user to identify the [User agent](https://developer.mediarithmics.io/user-points#user-agents) |
| $email\_hash             | String                    | Email Hash [identifier](https://developer.mediarithmics.io/user-points#user-identifiers) of the user                   |
| $comp\_token             | String                    | Compartment token (not the ID)                                                                                         |
| $uids                    | JSON as string (Optional) | The list of [user identifiers](#passing-user-identifiers-in-pixel-based-tracking) of the user.                         |
| gdpr                     | Number                    | TCF v2.2 parameter to indicate if gdpr applies or not (values: 1 or 0)                                                 |
| gdpr\_consent            | String                    | TCF v2.2 parameter containing the encoded consent string                                                               |
| any custom property name | Any Type                  | Any custom property. optional                                                                                          |

{% hint style="info" %}
Please note that before declaring a custom property, we recommend that you inform our PS team so that it can be indexed to your data schema (and therefore used for segmentation and/or dataviz), see our [data model documentation](https://developer.mediarithmics.io/schema).
{% endhint %}

## Ad Click tracking URL

Use the following click-tracking URL to send an `$ad_click` event to the platform.

```markup
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
```

| Field                    | Type                      | Description                                                                                               |
| ------------------------ | ------------------------- | --------------------------------------------------------------------------------------------------------- |
| $ev                      | String                    | The event name. **$ad\_click for Display Ad click tracking**                                              |
| $dat\_token              | String                    | The id of the audience datamart in the mediarithmics platform.                                            |
| $redirect                | String                    | The redirect url. This string should be URL Encoded. (RFC 3986)                                           |
| $catn                    | String                    | Campaign technical name                                                                                   |
| $scatn                   | String                    | Sub-campaign technical name                                                                               |
| $crtn                    | String                    | Creative technical name                                                                                   |
| $cb                      | String                    | The cache buster parameter. It should contain a random string. optional                                   |
| $cuid                    | String                    | User account ID [identifier](https://developer.mediarithmics.io/user-points#user-identifiers) of the user |
| $email\_hash             | String                    | Email Hash [identifier](https://developer.mediarithmics.io/user-points#user-identifiers) of the user      |
| $comp\_token             | String                    | Compartment token (not the ID)                                                                            |
| $uids                    | JSON as string (Optional) | The list of [user identifiers](#passing-user-identifiers-in-pixel-based-tracking) of the user.            |
| gdpr                     | Number                    | TCF v2.2 parameter to indicate if gdpr applies or not (values: 1 or 0)                                    |
| gdpr\_consent            | String                    | TCF v2.2 parameter containing the encoded consent string                                                  |
| any custom property name | Any Type                  | Any custom property. optional                                                                             |

{% hint style="info" %}
If you want to integrate with an external DSP / Ad Server such as Google Ad Manager or App Nexus, you can use the ids of the creative ad groups and campaign from your external DSP as technical names. See the integrations below for examples.
{% endhint %}

## Campaign tracking on Google

### Display Video 360

*You can use the following macros as a minimum configuration for tracking on DV 360 (ex-Doubleclick Bid Manager):*&#x20;

```markup
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}
```

```markup
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}
```

{% hint style="info" %}
More info on DV360 macros available here: <https://support.google.com/displayvideo/answer/2789508>
{% endhint %}

### Campaign Manager 360 integration

*You can use the following macros as a minimum configuration for tracking on Campaign Manager 360 (ex-Doubleclick* Campaign Manage&#x72;*):*

```markup
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
```

```markup
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>
```

{% hint style="info" %}
More info on Google Campaign Manager 360 macros can be found here: <https://support.google.com/campaignmanager/table/6096962>

And for TCF integration: <https://support.google.com/campaignmanager/answer/10031693?hl=en>
{% endhint %}

### Ad Manager integration

*You can use the following macros as a minimum configuration for tracking on Ad Manager:*

```markup
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%%
```

```markup
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>
```

{% hint style="info" %}
More info on Google Ad Manager macros can be found here: <https://support.google.com/admanager/answer/2376981>
{% endhint %}

## Campaign tracking on Xandr

*You can use the following macros as a minimum configuration for tracking on Xandr:*

```markup
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}
```

```markup
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}
```

{% hint style="info" %}
More info on Xandr supported macros can be found here: <https://learn.microsoft.com/fr-fr/xandr/monetize/supported-creative-macros>
{% endhint %}

## Campaign tracking on The Trade Desk

*You can use the following macros as a minimum configuration for tracking on The Trade Desk:*

```markup
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}
```

```markup
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%%
```

{% hint style="info" %}
More info on The Trade Desk supported macros can be found here (a The Trade Desk account is requiered to access this page): <https://desk.thetradedesk.com/knowledge-portal/en/faq-macros.html>
{% endhint %}

You can track additional properties by using custom properties such as:

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

{% hint style="info" %}
Please note that before declaring a custom property, we recommend that you inform our PS team so that it can be indexed to your data schema (and therefore used for segmentation and/or dataviz), see our [data model documentation](https://developer.mediarithmics.io/schema).
{% endhint %}

## Video Ad Tracking

Basic video ad tracking can be 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 setup based on the visit pixel (with custom completion events) and an Activity Analyzer. Please advise with your Account Representatives during the design phase.

## Passing user identifiers in pixel-based tracking

The following is true for all types of pixel-based tracking (events, ads, email, conversions, ...) which use the `events.mediarithmics.com/v1/touches/pixel` API endpoint

You can pass one or more user identifiers when using the `$uids` field.&#x20;

```
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>&
	gdpr=<GDPR>&
	gdpr_consent=<GDPR_CONSENT>&
	$cb=<CACHEBUSTER>&
	$uids=jso-[{"$tpe":"AG","$agid":"vec:1234"}]&
	... any custom property
```

{% hint style="info" %}
`jso-` prefix means that the rest of the string will be interpreted as a json object.
{% endhint %}

{% hint style="warning" %}
Don't forget to correctly encode the URL &#x20;
{% endhint %}

### User Account

| Field | Type            | Description                     |
| ----- | --------------- | ------------------------------- |
| $tpe  | Constant String | AC                              |
| $ctok | String          | The token of the compartment    |
| $acid | String          | The user account id of the user |

### User Email

| Field | Type              | Description     |
| ----- | ----------------- | --------------- |
| $tpe  | Constant String   | EM              |
| $eh   | String            | The email hash  |
| $e    | String (Optional) | The "raw" email |

### User Agent

| Field | Type            | Description                                                                                                                                                  |
| ----- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| $tpe  | Constant String | AG                                                                                                                                                           |
| $agid | String          | The [user agent id](https://developer.mediarithmics.io/user-points/user-identifiers/userdevicetechnicalid#user_agent_id-formatting-cookie-based-identifiers) |

{% hint style="warning" %}
Use the registry token, not the id, when formatting the user agent id.

Eg: `dev:<registry_token>:<value>`
{% endhint %}