> 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/es/data-api/api-overview/ad-interaction-events-reporting.md).
# Notificación de eventos de interacción con el anuncio
Los informes de eventos de interacción con anuncios proporcionan una capa adicional de informes a las campañas que les permite a ti y a tus marcas comprender cómo interactúan los clientes con tus anuncios.
Comprable Banner X y Vídeo Banner X las integraciones envían eventos al mismo punto de enlace con el mismo transporte, autenticación y campos principales. Lee esto una vez y, a continuación, sigue la guía del informe que desees habilitar.
## Cómo encajan las integraciones
El punto de enlace de interacciones alimenta tres resultados de informes. Esta página es la referencia compartida; cada resultado tiene su propia guía de tareas que se enlaza de nuevo aquí para la infraestructura.
```
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
```
| Resultado | Punto de enlace | Tipos de interacción (resumen) |
| ---------------- | --------------- | ------------------------------------------------------------------- |
| Banner comprable | ad/interaction | productImpression, productClick, creativeClick, cart |
| Vídeo | ad/interaction | videoCreatividadView, videoPlay, quartiles, videoComplete, controls |
## Antes de empezar (requisitos previos compartidos)
| Requisito previo | Propósito |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Espacio de nombres / catálogo del minorista aprovisionado y URL base de integración emitida | Confirma que el entorno del minorista está listo para recibir eventos de interacción. |
| Los anuncios servidos devuelven un objeto realizado adId | Permite que cada evento se adjunte al anuncio servido. |
| ID de catálogo (productCode, catalogId) disponibles en el contexto del anuncio; videoId para vídeo | Proporciona el contexto de producto o vídeo necesario para la guía de informes correspondiente. |
| ID de seguimiento coherentes (sessionId, customerIdo dtmToken) por sesión de anuncio | Permite la atribución y la deduplicación entre eventos de la misma sesión. |
| Habilitación de informes confirmada para la cuenta | Garantiza que los eventos aceptados puedan fluir hacia los resultados de los informes. |
### Punto de enlace y transporte
* Método:\*\* HTTPS `GET` con parámetros de consulta; sin cuerpo de solicitud.
* Punto de enlace: `GET https://integration.{retailer}.citrusad.com/v1/events/ad/interaction`
* Respuesta: `HTTP 200` al aceptar, `HTTP 400` en caso de fallo de validación, `5xx` en caso de error de la plataforma.
### Autenticación y seguridad
* Fuego y olvido:\*\* usa `navigator.sendBeacon`, una imagen de 1×1, o `fetch(…, { keepalive: true })` para que los eventos sobrevivan a la descarga de la página.
* **No reintentes un HTTP 400**: está mal formado y volverá a fallar. Corrige la solicitud en su lugar.
* **Codifica en URL todos los valores**, especialmente la cadena de consentimiento y cualquier campo de URL.
### Campos principales (cada evento)
| Campo | Tipo | Requerido | Descripción | Valores aceptados |
| --------------------------------------- | ------ | ------------------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `adId` | string | Sí | ID de anuncio realizado a partir del anuncio servido | — |
| `interactionType` | string | Sí | Tipo de evento (camelCase sensible a mayúsculas y minúsculas) | Consulta las guías por resultado |
| `timestamp` | string | Sí | Hora del evento (ISO 8601; usa UTC o la hora local del minorista de forma coherente) | ISO 8601 |
| `sessionId` / `customerId` / `dtmToken` | string | Sí (cualquiera de ellos) | ID de seguimiento: se requiere al menos uno; si faltan todos, el evento no se puede atribuir y se rechaza | — |
Reutiliza un ID de seguimiento para toda la sesión del anuncio y reutiliza el mismo `adId` en cada evento para ese anuncio servido. Cada `interactionType` se asigna a una métrica de informes específica; consulta la guía por resultado para conocer el "propósito de informes" de cada tipo.
### Identificadores
Los ID que vinculan los eventos con los anuncios, los productos y las sesiones. Los requisitos de campos por evento se encuentran en cada guía; esta es la definición compartida de dónde proviene cada ID.
| Identificador | Qué es | De dónde proviene | Utilizado por |
| --------------------------------------- | ------------------------------------------------- | ------------------------------------------ | ----------------------------- |
| `adId` | ID del anuncio realizado | La respuesta del anuncio servido | Cada evento |
| `productCode` / `catalogId` | SKU + su alcance de catálogo | Catálogo del retail / contexto del anuncio | Eventos de producto y carrito |
| `videoId` | ID estable del activo de video | La creatividad de video | Eventos de video |
| `creativeId` | ID del elemento de creatividad que no es producto | La creatividad | `creativeClick` |
| `sessionId` / `customerId` / `dtmToken` | ID de seguimiento (cualquiera) | Sesión del retail / inicio de sesión / DTM | Cada evento |
### Patrón de implementación (Beacon)
Utilice una imagen de 1×1, `fetch` con `keepalive`, or `navigator.sendBeacon` apuntando a la URL GET completa. No confíe en analizar el cuerpo de la respuesta para la UX. El mismo asistente sirve para las tres integraciones; las guías por resultado solo difieren en cuál `interactionType` y qué campos pasa.
```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",
});
```
---
# 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/es/data-api/api-overview/ad-interaction-events-reporting.md?ask=&goal=
```
`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.