> 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/pt-br/data-api/api-overview/ad-interaction-events-reporting.md).

# Relatório de eventos de interação com o anúncio

O relatório de eventos de interação com o anúncio fornece uma camada adicional de relatórios para campanhas que permite que você e suas marcas entendam como os clientes estão interagindo com seus anúncios.

Shoppable Banner X e vídeo Banner X as integrações enviam eventos para o mesmo endpoint com o mesmo transporte, autenticação e campos principais. Leia isto uma vez e depois siga o guia para o relatório que deseja habilitar.

## Como as integrações se encaixam

O endpoint de interações alimenta três resultados de relatórios. Esta página é a referência compartilhada; cada resultado tem seu próprio guia de tarefas que vincula de volta para aqui para a estrutura básica.

```
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        | Endpoint       | Tipos de interação (resumo)                                      |
| ---------------- | -------------- | ---------------------------------------------------------------- |
| Banner Shoppable | ad/interaction | productImpression, productClick, creativeClick, cart             |
| Vídeo            | ad/interaction | videoCriativoView, videoPlay, quartiles, videoComplete, controls |

## Antes de começar (pré-requisitos compartilhados)

| Pré-requisito                                                                                   | Finalidade                                                                           |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Namespace do varejista / catálogo provisionado e URL base de integração emitida                 | Confirma que o ambiente do varejista está pronto para receber eventos de interação.  |
| Os anúncios veiculados retornam um realizado adId                                               | Permite que cada evento seja anexado ao anúncio veiculado.                           |
| IDs de catálogo (productCode, catalogId) disponíveis no contexto do anúncio; videoId para vídeo | Fornece o contexto de produto ou vídeo necessário pelo guia de relatórios relevante. |
| IDs de rastreamento consistentes (sessionId, customerId, ou dtmToken) por sessão de anúncio     | Permite atribuição e desduplicação em eventos na mesma sessão.                       |
| Habilitação de relatórios confirmada para a conta                                               | Garante que os eventos aceitos possam fluir para as saídas de relatórios.            |

### Endpoint e transporte

* Método:\*\* HTTPS `GET` com parâmetros de consulta; sem corpo de requisição.
* Endpoint: `GET https://integration.{retailer}.citrusad.com/v1/events/ad/interaction`
* Resposta: `HTTP 200` ao aceitar, `HTTP 400` em caso de falha de validação, `5xx` em caso de erro da plataforma.

### Autenticação e segurança

* Fire-and-forget:\*\* use `navigator.sendBeacon`, uma imagem 1×1, ou `fetch(…, { keepalive: true })` para que os eventos sobrevivam ao descarregamento da página.
* **Não tente novamente um HTTP 400** — ele está malformado e falhará novamente. Em vez disso, corrija a requisição.
* **Codifique todos os valores na URL**, especialmente a string de consentimento e quaisquer campos de URL.

### Campos principais (todos os eventos)

| Campo                                   | Tipo   | Obrigatório         | Descrição                                                                                                                         | Valores aceitos                 |
| --------------------------------------- | ------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `adId`                                  | string | Sim                 | ID do anúncio realizado a partir do anúncio veiculado                                                                             | —                               |
| `interactionType`                       | string | Sim                 | Tipo de evento (camelCase sensível a maiúsculas e minúsculas)                                                                     | Consulte os guias por resultado |
| `timestamp`                             | string | Sim                 | Hora do evento (ISO 8601; use UTC ou o horário local do varejista de forma consistente)                                           | ISO 8601                        |
| `sessionId` / `customerId` / `dtmToken` | string | Sim (pelo menos um) | ID de rastreamento — pelo menos um é obrigatório; se todos estiverem ausentes, o evento não poderá ser atribuído e será rejeitado | —                               |

Reutilize um ID de rastreamento para toda a sessão do anúncio e reutilize o mesmo `adId` em cada evento para aquele anúncio veiculado. Cada `interactionType` mapeia para uma métrica de relatório específica — consulte o guia por resultado para o "propósito de relatório" de cada tipo.

### Identificadores

Os IDs que vinculam eventos a anúncios, produtos e sessões. Os requisitos de campo por evento estão em cada guia; esta é a definição compartilhada de onde vem cada ID.

| Identificador                           | O que é                                              | De onde vem                                 | Usado por                     |
| --------------------------------------- | ---------------------------------------------------- | ------------------------------------------- | ----------------------------- |
| `adId`                                  | ID do anúncio realizado                              | A resposta do anúncio servido               | Cada evento                   |
| `productCode` / `catalogId`             | SKU + seu escopo de catálogo                         | Catálogo do varejista / contexto do anúncio | Eventos de produto e carrinho |
| `videoId`                               | ID estável do recurso de vídeo                       | O Criativo de vídeo                         | Eventos de vídeo              |
| `creativeId`                            | ID do elemento de criativo não relacionado a produto | O Criativo                                  | `creativeClick`               |
| `sessionId` / `customerId` / `dtmToken` | ID de rastreamento (qualquer um)                     | Sessão do varejista / login / DTM           | Cada evento                   |

### Padrão de implementação (Beacon)

Use uma imagem 1×1, `fetch` com `keepalive`, or `navigator.sendBeacon` apontado para a URL GET completa. Não confie na análise do corpo da resposta para UX. O mesmo auxiliar atende a todas as três integrações — os guias por resultado diferem apenas em qual `interactionType` e campos você passa.

```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/pt-br/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.