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

# Ad Interaction Events Reporting

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>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.citrusad.com/retail-media-interface/integration/data-api/api-overview/ad-interaction-events-reporting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.