> 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/integrate-banner-x-shoppable-banner-interaction-reporting.md). # Integrar relatório de interação do Banner X Shoppable Banner Um banner comprável é um Banner X anúncio com vários hotspots de produtos complementares em um único posicionamento. Assim que esses eventos fluem, o relatório da campanha detalha o desempenho do banner para cada produto complementar — impressões, cliques e CTR (além de ações de carrinho, onde estiver integrado) — em vez de um total único no nível do banner. Este guia cobre apenas os tipos de interação do banner comprável. Para o ponto de extremidade, autenticação, campos principais (`adId`, `timestamp`, ID de rastreamento), mecânica de beacon, eliminação de duplicadas e testes, consulte a [Referência técnica de relatórios de eventos de interação de anúncios](https://help.citrusad.com/retail-media-interface/integration/pt-br/data-api/api-overview/ad-interaction-events-reporting). ## Pré-requisitos | Pré-requisito | Finalidade | | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Leia a [Referência técnica](https://help.citrusad.com/retail-media-interface/integration/pt-br/data-api/api-overview/ad-interaction-events-reporting) | Confirma os requisitos de ponto de extremidade, autenticação, campos principais e eliminação de duplicadas. | | Produtos complementares configurados no Banner X Criativo | Garante que as interações no nível do produto possam ser atribuídas ao criativo. | | Os anúncios exibidos retornam um `adId` | Conecta cada evento à instância de anúncio veiculada. | | `productCode` e `catalogId` disponível por produto complementar | Identifica o produto e o catálogo usados nos relatórios. | | Regra de visualização acordada para blocos de produtos | Define quando um bloco de produto é considerado visto para `productImpression`. | | ID de rastreamento consistente por sessão de anúncio | Suporta atribuição e eliminação de duplicadas usando `sessionId`, `customerId`, or `dtmToken`. | ## Tipos de interação para relatórios de banner comprável Estes são `adInteraction` eventos (sem `moduleId`). Envie os campos principais mais os campos-chave abaixo. `productImpression` e `productClick` são os dois eventos que desbloqueiam a aba Produtos — acione ambos. | `interactionType` | Campos-chave | Quando acionar | Finalidade do relatório | | ------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `productImpression` | `productCode`, `catalogId` | Um bloco de produto/SKU torna-se visível de acordo com suas regras de visualização | Impressões por produto — preenche a coluna de impressões (e linhas sem cliques) | | `productClick` | `productCode`, `catalogId` | O comprador clica em um bloco de produto/SKU | Cliques por produto — impulsiona cliques e CTR | | `creativeClick` | `creativeId` | Clique em um elemento do criativo que não é um produto | Engajamento com criativo que não é produto | | `cart` | `productCode`, `catalogId`, `units`, opcional `conversionValue` | Alteração no carrinho a partir do contexto do anúncio | Intenção de adicionar ao carrinho / valor do produto | ## Regras de visualização para `productImpression` | Regra | Orientação | | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Defina quando um bloco é considerado visto | Acorde uma regra de visualização, como porcentagem visível mais tempo na tela, e aplique-a de forma consistente na web e no aplicativo. | | Acione impressões uma vez por ocorrência de visualização | Remova oscilações de rolagem e renderizações sucessivas para que uma única visualização não seja contada várias vezes. | ## Carrinho: envie unidades atuais absolutas Acione `cart` em cada interação do carrinho — adição inicial, cada `+`, cada `−`e remoção (de volta para `0`) — com `units` definido para a contagem absoluta de unidades atuais, não um delta. Reenviar o total atual mantém as contagens corretas na eliminação de duplicadas. Adicione `conversionValue` quando tiver. {% hint style="info" %} **Exemplo** — um comprador adiciona um produto, incrementa duas vezes e depois o remove:\*\* `cart {units: 1}` → `cart {units: 2}` → `cart {units: 3}` → `cart {units: 0}` {% endhint %} ## Implementação passo a passo ### Etapa 1 — Capturar contexto do anúncio Leia o `adId` realizado a partir do anúncio veiculado, e `productCode`/`catalogId` para cada bloco complementar. Estabeleça um ID de rastreamento para a sessão e reutilize-o em impressões e cliques. ### Etapa 2 — Acionar impressões de produtos Quando um bloco atender à sua regra de visualização, acione `productImpression` uma vez para esse produto. ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productImpression", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Etapa 3 — Disparar um clique no produto ```javascript navigator.sendBeacon( "https://integration.{retailer}.citrusad.com/v1/events/ad/interaction?" + new URLSearchParams({ adId, interactionType: "productClick", sessionId, timestamp: new Date().toISOString(), productCode, catalogId }) ); ``` ### Etapa 4 — Disparar alterações no carrinho Ao adicionar/atualizar, dispare `cart` com o atual absoluto `units` para esse produto (e `conversionValue` se você o tiver) — consulte a regra do carrinho acima. ## Exemplos de solicitações URLs GET completas (quebradas em linhas para facilitar a leitura — envie como uma única string de consulta codificada). ### Impressão de produto ```http GET https://integration.retailer.citrusad.com/v1/events/ad/interaction ?adId=shotgun_0001 ×tamp=2026-05-20T10:15:00Z &sessionId=12345gsyuhf-6678ghsj &productCode=prod-00001-01 &catalogId=catlg-custom-DAA001 &interactionType=productImpression ``` ### Clique no produto ```http GET https://integration.retailer.citrusad.com/v1/events/ad/interaction ?adId=shotgun_0001 ×tamp=2026-05-20T10:15:30Z &sessionId=12345gsyuhf-6678ghsj &productCode=prod-00001-01 &catalogId=catlg-custom-DAA001 &interactionType=productClick ``` ### Adicionar ao carrinho a partir do anúncio ```http GET https://integration.retailer.citrusad.com/v1/events/ad/interaction ?adId=shotgun_0001 ×tamp=2026-05-20T10:16:00Z &customerId=cust-abc-123 &productCode=prod-00001-01 &catalogId=catlg-custom-DAA001 &interactionType=cart &units=2 &conversionValue=29.99 ``` ## Como deve ser o resultado correto | Verificação | Detalhe | | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Eventos retornam HTTP 200 | `productImpression` e `productClick` retornam HTTP 200 em PRE/QA. | | A aba Produtos está totalmente preenchida | Todos os produtos complementares configurados aparecem, incluindo linhas com zero engajamento (as impressões preenchem as linhas com zero cliques). | | A eliminação de duplicidades está funcionando | As contagens permanecem estáveis quando você dispara novamente a mesma impressão/clique. | ## Solução de problemas (Especificidades do banner direcionado para compra) | Sintoma | Correção | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Os eventos de produto obrigatórios não estão chegando | Confirme se o banner está Banner X com produtos complementares na etapa do Criativo e que `productImpression` e `productClick` disparem com `productCode`/`catalogId`. | | Impressões disparando a cada rolagem/re-renderização | Dispare um `productImpression` por produto por ocorrência de visualização; aplique debounce. | | A aba Produtos mostra produtos incorretos ou ausentes | Provavelmente uma incompatibilidade de `productCode`/`catalogId` com o catálogo — reconcilie os IDs enviados com o feed do catálogo. | | As unidades do carrinho parecem incorretas | Você está enviando deltas — envie o atual absoluto `units`. | Para solução de problemas gerais de endpoint, consulte a [Referência técnica de relatórios de eventos de interação de anúncios](https://help.citrusad.com/retail-media-interface/integration/pt-br/data-api/api-overview/ad-interaction-events-reporting) seção de solução 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/pt-br/data-api/api-overview/ad-interaction-events-reporting/integrate-banner-x-shoppable-banner-interaction-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.