> For the complete documentation index, see [llms.txt](https://developers.citrusad.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.citrusad.com/integration/reference/ad-interaction-events-reporting.md).

# Ad Interaction Events Reporting

{% hint style="info" %}
Epsilon Retail Media's documentation is now centralized with our knowledgebase!

For up to date guides, please view [this page](https://help.citrusad.com/retail-media-interface/integration/data-api/api-overview/ad-interaction-events-reporting) in the new Integration APIs space of our documentation.
{% endhint %}

Ad interaction event reporting provides an additional layer of reporting to campaigns that allows you and your brands to understand how customers are interacting with your ads.

Shoppable Banner X and Video Banner X integrations send events to the same endpoint with the same transport, authentication, and core fields. Read this once, then follow the guide for the report you want to enable.

## How the Integrations Fit Together

The interactions endpoint powers three reporting outcomes. This page is the shared reference; each outcome has its own task guide that links back here for the plumbing.

```
Ad serving (returns a realised adId)
        │
        ▼
GET /v1/events/ad/interaction   ← this reference: transport, auth, core fields, dedup, errors
        │
        ├─ adInteraction .......... Shoppable Banner reporting
        └─ adInteraction .......... Video reporting
```

| **Outcome**      | **Endpoint**   | **Interaction types (summary)**                                  |
| ---------------- | -------------- | ---------------------------------------------------------------- |
| Shoppable Banner | ad/interaction | productImpression, productClick, creativeClick, cart             |
| Video            | ad/interaction | videoCreativeView, videoPlay, quartiles, videoComplete, controls |

## Before You Start (Shared Prerequisites)

| **Prerequisite**                                                                    | **Purpose**                                                                   |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Retailer namespace / catalogue provisioned and integration base URL issued          | Confirms the retailer environment is ready to receive interaction events.     |
| Served ads return a realised adId                                                   | Allows each event to be attached to the served ad.                            |
| Catalog IDs (productCode, catalogId) available in the ad context; videoId for video | Provides the product or video context needed by the relevant reporting guide. |
| Consistent tracking ids (sessionId, customerId, or dtmToken) per ad session         | Enables attribution and deduplication across events in the same session.      |
| Reporting enablement confirmed for the account                                      | Ensures accepted events can flow through to reporting outputs.                |

### Endpoint & Transport

* **Method:** HTTPS `GET` with query parameters; no request body.
* **Endpoint:** `GET https://integration.{retailer}.citrusad.com/v1/events/ad/interaction`
* **Response:** `HTTP 200` on accept, `HTTP 400` on validation failure, `5xx` on platform error.

### Authentication & Security

* **Fire-and-forget:** use `navigator.sendBeacon`, a 1×1 image, or `fetch(…, { keepalive: true })` so events survive page unload.
* **Do not retry an HTTP 400** — it is malformed and will fail again. Fix the request instead.
* **URL-encode all values**, especially the consent string and any URL fields.

### Core Fields (Every Event)

| Field                                   | Type   | Required      | Description                                                                                           | Accepted values            |
| --------------------------------------- | ------ | ------------- | ----------------------------------------------------------------------------------------------------- | -------------------------- |
| `adId`                                  | string | Yes           | Realised ad id from the served ad                                                                     | —                          |
| `interactionType`                       | string | Yes           | Event type (case-sensitive camelCase)                                                                 | See the per-outcome guides |
| `timestamp`                             | string | Yes           | Event time (ISO 8601; use UTC or retailer-local consistently)                                         | ISO 8601                   |
| `sessionId` / `customerId` / `dtmToken` | string | Yes (any one) | Tracking id — at least one required; if all are missing the event can't be attributed and is rejected | —                          |

Reuse one tracking id for the whole ad session and reuse the same `adId` across every event for that served ad. Each `interactionType` maps to a specific reporting metric — see the per-outcome guide for the "reporting purpose" of each type.

### Identifiers

The ids that tie events to ads, products, and sessions. Per-event field requirements are in each guide; this is the shared definition of where each id comes from.

| Identifier                              | What it is                      | Where it comes from             | Used by                 |
| --------------------------------------- | ------------------------------- | ------------------------------- | ----------------------- |
| `adId`                                  | Realised ad id                  | The served ad response          | Every event             |
| `productCode` / `catalogId`             | SKU + its catalogue scope       | Retailer catalogue / ad context | Product and cart events |
| `videoId`                               | Stable video asset id           | The video creative              | Video events            |
| `creativeId`                            | Non-product creative element id | The creative                    | `creativeClick`         |
| `sessionId` / `customerId` / `dtmToken` | Tracking id (any one)           | Retailer session / login / DTM  | Every event             |

### Implementation Pattern (Beacon)

Use a 1×1 image, `fetch` with `keepalive`, or `navigator.sendBeacon` pointed at the full GET URL. Don't rely on parsing the response body for UX. The same helper serves all three integrations — the per-outcome guides only differ in which `interactionType` and fields you pass.

```javascript
function fireAdInteraction(params) {
  const qs = new URLSearchParams(params);
  const url = `https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?${qs}`;
  if (navigator.sendBeacon) {
    navigator.sendBeacon(url);
  } else {
    new Image().src = url; // fallback
  }
}

// Example: product click (see the Shoppable Banner guide for the full set)
fireAdInteraction({
  adId: "shotgun_0001",
  timestamp: new Date().toISOString(),
  sessionId: getSessionId(),
  productCode: "prod-00001-01",
  catalogId: "catlg-custom-DAA001",
  interactionType: "productClick",
});
```

<br>