> 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/integrate-banner-x-shoppable-banner-interaction-reporting.md).

# Integrar la notificación de interacción de Banner X Shoppable

Un banner comprable es un Banner X anuncio con varios puntos de interés de productos complementarios en una sola ubicación. Una vez que estos eventos fluyen, el informe de la campaña desglosa el rendimiento del banner para cada producto complementario (impresiones, clics y CTR, además de las acciones del carrito donde esté integrado) en lugar de un único total a nivel de banner.

Esta guía solo cubre los tipos de interacción de banner comprable. Para obtener información sobre el punto de conexión, la autenticación, los campos principales (`adId`, `timestamp`id de seguimiento), la mecánica de balizas, la desduplicación y las pruebas, consulte la [Referencia técnica de informes de eventos de interacción con el anuncio](https://help.citrusad.com/retail-media-interface/integration/es/data-api/api-overview/ad-interaction-events-reporting).

## Requisitos previos

| Requisito previo                                                                                                                                   | Propósito                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Lea la [Referencia técnica](https://help.citrusad.com/retail-media-interface/integration/es/data-api/api-overview/ad-interaction-events-reporting) | Confirma el punto de conexión, la autenticación, los campos principales y los requisitos de desduplicación. |
| Productos complementarios configurados en la Banner X Creatividad                                                                                  | Garantiza que las interacciones a nivel de producto se puedan atribuir a la Creatividad.                    |
| Los anuncios servidos devuelven un objeto realizado `adId`                                                                                         | Enlaza cada evento con la instancia de anuncio entregada.                                                   |
| `productCode` y `catalogId` disponible por producto complementario                                                                                 | Identifica el producto y el catálogo utilizados en los informes.                                            |
| Regla de visibilidad acordada para las fichas de productos                                                                                         | Define cuándo una ficha de producto se considera vista para `productImpression`.                            |
| Id de seguimiento constante por sesión de anuncio                                                                                                  | Admite la atribución y la desduplicación mediante `sessionId`, `customerId`, or `dtmToken`.                 |

## Tipos de interacción para los informes de banner comprable

Estos son `adInteraction` eventos (sin `moduleId`). Envíe los campos principales más los campos clave a continuación. `productImpression` y `productClick` son los dos eventos que desbloquean la pestaña Productos: active ambos.

| `interactionType`   | Campos clave                                                    | Cuándo activar                                                              | Propósito de los informes                                                               |
| ------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `productImpression` | `productCode`, `catalogId`                                      | Una ficha de producto/SKU se vuelve visible según sus reglas de visibilidad | Impresiones por producto: rellena la columna de impresiones (y las filas de cero clics) |
| `productClick`      | `productCode`, `catalogId`                                      | El comprador hace clic en una ficha de producto/SKU                         | Clics por producto: impulsa los clics y el CTR                                          |
| `creativeClick`     | `creativeId`                                                    | Clic en un elemento de Creatividad que no es un producto                    | Interacción con una Creatividad que no es un producto                                   |
| `cart`              | `productCode`, `catalogId`, `units`, opcional `conversionValue` | Cambio de carrito desde el contexto del anuncio                             | Intención de añadir al carrito / valor del producto                                     |

## Reglas de visibilidad para `productImpression`

| Regla                                                          | Orientación                                                                                                                                       |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Definir cuándo una ficha se considera vista                    | Acuerde una regla de visibilidad, como el porcentaje visible más el tiempo en pantalla, y aplíquela de forma coherente en la web y la aplicación. |
| Activar las impresiones una vez por cada evento de visibilidad | Elimine los rebotes por temblor de desplazamiento y las re-renderizaciones para que una sola visualización no se cuente muchas veces.             |

## Carrito: enviar unidades actuales absolutas

Active `cart` en cada interacción del carrito: adición inicial, cada `+`cada `−`y eliminación (de vuelta a `0`) — con `units` establecido en el recuento absoluto de unidades actuales, no un delta. Volver a enviar el total actual mantiene los recuentos correctos en el proceso de desduplicación. Añada `conversionValue` cuando lo tenga.

{% hint style="info" %}
**Ejemplo**: un comprador añade un producto, lo incrementa dos veces y luego lo elimina:\*\* `cart {units: 1}` → `cart {units: 2}` → `cart {units: 3}` → `cart {units: 0}`
{% endhint %}

## Implementación paso a paso

### Paso 1: capturar el contexto del anuncio

Lea la entidad realizada `adId` del anuncio servido, y `productCode`/`catalogId` para cada ficha complementaria. Establezca un id de seguimiento para la sesión y reutilícelo en impresiones y clics.

### Paso 2: activar las impresiones de productos

Cuando una ficha cumpla con su regla de visibilidad, active `productImpression` una vez para ese producto.

```javascript
navigator.sendBeacon(
  "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" +
  new URLSearchParams({
    adId, interactionType: "productImpression", sessionId,
    timestamp: new Date().toISOString(), productCode, catalogId
  })
);
```

### Paso 3: activar un clic en el producto

```javascript
navigator.sendBeacon(
  "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" +
  new URLSearchParams({
    adId, interactionType: "productClick", sessionId,
    timestamp: new Date().toISOString(), productCode, catalogId
  })
);
```

### Paso 4: activar los cambios en el carrito

Al añadir/actualizar, active `cart` con el valor absoluto actual `units` para ese producto (y `conversionValue` si lo tienes) — consulta la regla de carrito anterior.

## Solicitudes de ejemplo

URL de GET completas (con salto de línea para facilitar la lectura — enviar como una sola cadena de consulta codificada).

### Impresión de producto

```http
GET https://integration.retailer.citrusad.com/v1/events/ad/interaction
  ?adId=shotgun_0001
  &timestamp=2026-05-20T10:15:00Z
  &sessionId=12345gsyuhf-6678ghsj
  &productCode=prod-00001-01
  &catalogId=catlg-custom-DAA001
  &interactionType=productImpression
```

### Clic en el producto

```http
GET https://integration.retailer.citrusad.com/v1/events/ad/interaction
  ?adId=shotgun_0001
  &timestamp=2026-05-20T10:15:30Z
  &sessionId=12345gsyuhf-6678ghsj
  &productCode=prod-00001-01
  &catalogId=catlg-custom-DAA001
  &interactionType=productClick
```

### Añadir al carrito desde el anuncio

```http
GET https://integration.retailer.citrusad.com/v1/events/ad/interaction
  ?adId=shotgun_0001
  &timestamp=2026-05-20T10:16:00Z
  &customerId=cust-abc-123
  &productCode=prod-00001-01
  &catalogId=catlg-custom-DAA001
  &interactionType=cart
  &units=2
  &conversionValue=29.99
```

## Cómo se ve un resultado correcto

| Comprobación                                    | Detalle                                                                                                                               |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Los eventos devuelven HTTP 200                  | `productImpression` y `productClick` devuelven HTTP 200 en PRE/QA.                                                                    |
| La pestaña Productos está completamente poblada | Aparece cada producto complementario configurado, incluidas las filas sin interacción (las impresiones rellenan las filas sin clics). |
| La deduplicación funciona                       | Los recuentos se mantienen estables cuando vuelves a activar la misma impresión/clic.                                                 |

## Solución de problemas (específico para banners comprables)

| Síntoma                                                          | Solución                                                                                                                                                                            |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No llegan los eventos de producto requeridos                     | Confirma que el banner esté Banner X con productos complementarios en la etapa de creatividad, y que `productImpression` y `productClick` se activen con `productCode`/`catalogId`. |
| Las impresiones se activan con cada desplazamiento/renderización | Activa uno `productImpression` por producto y por cada ocurrencia de legibilidad; aplica debounce.                                                                                  |
| La pestaña Productos muestra productos incorrectos o faltantes   | Probablemente una `productCode`/`catalogId` discrepancia con el catálogo: reconcilia los ID que envías con la fuente del catálogo.                                                  |
| Las unidades del carrito parecen incorrectas                     | Estás enviando deltas — envía el valor absoluto actual `units`.                                                                                                                     |

Para la solución general de problemas de puntos de enlace, consulta la [Referencia técnica de informes de eventos de interacción con el anuncio](https://help.citrusad.com/retail-media-interface/integration/es/data-api/api-overview/ad-interaction-events-reporting) sección de solución de problemas.


---

# 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/integrate-banner-x-shoppable-banner-interaction-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.