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.

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",
});