> 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/brand-pages/brand-page-retailer-integration-guide/tracking-attribution.md). # Rastreamento e atribuição ## Como compor um URL de rastreamento A resposta fornece três fontes para combinar: * Nível de página `trackers.impression`: por exemplo, uma impressão de página usa `type: "impression"` e `params` incluindo `ts` e `iabConsentString`. * Compartilhado `trackingTemplates`: um conjunto de `client`(relativo) e `server` modelos de URL (absoluto), já contendo parâmetros de consulta de sessão e posicionamento. * Por nó `trackers.click` e/ou `trackers.addToCart` em um módulo, linha ou item de galeria: `type`+ `params` para aquele evento específico (por exemplo, `modId`, `rurl`, `productCode`). ### Qual modelo? Use o do nó `tracking.type` para procurar `trackingTypes.`. Isso define o válido `client.*` e `server.*` chaves para essa interação (por exemplo, para link: `client.clickRedirect`, `client.clickEvent`, `server.clickEvent)`. ### Cliente vs Servidor * Cliente (`trackingTemplates.client.*`): Os valores são caminhos relativos (incluindo strings de consulta). Prepend seu URL base do proxy reverso (`BASEURL`). * Servidor (`trackingTemplates.server.`): Os valores são modelos de URL absolutos no Epsilon host de rastreamento. Componha o URL final da mesma forma que o C2S: modelo + `"&"` + `queryString(trackers.params)`. {% hint style="info" %} Não altere o host ou o caminho do modelo e não envie chamadas S2S por meio do seu proxy reverso. {% endhint %} ### Exemplos práticos (pseudocódigo) #### Clique C2S para uma CTA HERO ``` url = BASEURL + trackingTemplates.client.clickRedirect + "&" + queryString(trackers.click.params) ``` #### Impessão de página S2S ``` url = trackingTemplates.server.impressionEvent + "&" + queryString(trackers.impression.params) ``` #### Adição ao carrinho S2S para uma linha de produtos ``` url = trackingTemplates.server.addToCartEvent + "&" + queryString(trackers.addToCart.params) ``` Substituição de macro * Substitua {TS} pelo timestamp de milissegundo atual, {RURL} pelo destino codificado em URL e `{TCF}` com a string TCF v2 atual da sua CMP antes de disparar. * Para adição ao carrinho, também substitua {QTY} pela quantidade absoluta desse SKU no carrinho no momento do disparo (não um delta), e {CONVERSION\_VALUE} pelo valor monetário absoluto desses itens (quantidade × preço unitário, menos quaisquer descontos aplicados). {% hint style="info" %} * Apenas `trackingTemplates.client.impressionPixelUrls` são pixels verdadeiros (GIFs 1×1). * `clickRedirect` é um endpoint de redirecionamento 302. * `clickEvent` e `addToCartEvent` são beacons de evento que retornam 204 No Content. {% endhint %} {% hint style="danger" %} Não meça C2S e S2S para o mesmo evento lógico (por exemplo, não envie um evento de clique C2S e uma notificação de clique S2S para o mesmo clique). {% endhint %} ## Rastreamento – Cliente para Servidor (C2S) O rastreamento C2S é implementado no navegador usando URLs compostos. Prepend `BASEURL` para os caminhos em `trackingTemplates.client` e anexe o apropriado `trackers.params` (veja [Como compor um URL de rastreamento](#how-to-compose-a-tracking-url)). Apenas `client.impressionPixelUrls` são pixels (GIF 1×1). Os outros modelos de cliente não são pixels: * `client.clickRedirect`: endpoint de redirecionamento 302. Epsilon registra o clique e redireciona o navegador para o rurl decodificado. Use isso como um destino de navegação do navegador. * `client.clickEvent`: **Beacon de evento** retorna 204 No Content). Dispare usando `navigator.sendBeacon` or `fetch({ keepalive: true })`. Não renderize como ``. * `client.addToCartEvent`: **Beacon de evento** (retorna 204). Usa o mesmo padrão de disparo que `clickEvent`. ### Etapas de implementação 1. Renderize o conteúdo da página da marca retornado pela API. 2. Após a renderização, dispare pixels de impressão no navegador (todas as entradas em `trackingTemplates.client.impressionPixelUrls`, como imagens 1×1). 3. Quando um usuário clica em um nó rastreável, ou:\ (a) redirecione através do composto `client.clickRedirect` URL, ou\ (b) dispare o composto `client.clickEvent` URL como um beacon de evento e navegue você mesmo até o destino.\ Use um ou outro por clique, não ambos. ### Pixel de impressão Depois que a página da marca for renderizada, acione cada caminho em `trackingTemplates.client.impressionPixelUrls` como uma imagem 1×1, (veja[ Como compor um URL de rastreamento](#how-to-compose-a-tracking-url)). ```html ``` Etapas: 1. Para cada string em `trackingTemplates.client.impressionPixelUrls`, adicione antes o seu `BASEURL` (por exemplo, `https://www.retailer.com/epsilon`). 2. Anexe `&` + `queryString(trackers.impression.params)`, substituindo `{TS}` pelo carimbo de data/hora em milissegundos atual e `{TCF}` pela string de consentimento atual do seu CMP. 3. Acione como um 1×1 `< img src="...">` no navegador (ou equivalente). ### Rastreamento de cliques #### Opção A: Redirecionamento de clique (`client.clickRedirect`) Navegue o usuário através do URL composto. Epsilon registra o clique e responde com **HTTP 302** para o decodificado `rurl`. Este endpoint é **apenas GET**, e `rurl` é obrigatório; #### Opção B: Beacon de evento de clique (`client.clickEvent`) Dispare como um beacon e navegue. Aceita GET ou POST, retorna 204 No Content. Não é uma imagem; não renderize como``. ### Adicionar ao carrinho (C2S) Disparar `trackingTemplates.client.addToCartEvent` como um beacon de evento (não um pixel) quando o usuário adicionar um produto ao carrinho. Aceita GET ou POST, retorna 204 No Content. {% hint style="info" %} Não combine adição ao carrinho C2S e S2S para a mesma ação de carrinho. {% endhint %} ## Rastreamento – Servidor a Servidor (S2S) O rastreamento S2S é implementado no seu backend. Componha URLs da mesma forma que o C2S: comece a partir do `trackingTemplates.server` adequada e, em seguida, anexe `trackers.params`. Os modelos do servidor já são absolutos — não há `BASEURL`para adicionar antes. (veja [Como compor um URL de rastreamento](#how-to-compose-a-tracking-url)). {% hint style="info" %} Não altere o host ou o caminho do modelo do servidor e não envie solicitações S2S por meio do seu proxy reverso. {% endhint %} ### Quando usar o rastreamento S2S * Sua arquitetura exige o disparo de eventos no lado do servidor. * Você precisa de rastreamento em ambientes onde os pixels do lado do cliente não são confiáveis. * Você quer misturar estratégias - por exemplo, impressões C2S + adição ao carrinho S2S. Isso é suportado, mas nunca acione C2S e S2S para o mesmo evento. ### Notificação de impressão S2S Após a página da marca ser renderizada, seu servidor envia um **GET** ou **POST** para a URL de impressão composta: `trackingTemplates.server.impressionEvent` + `trackers.impression.params` (substitua `{TS}` e `{TCF}` antes de enviar). ### Notificação de clique S2S Compor: `trackingTemplates.server.clickEvent` + `trackers.click.params` (substitua `{TS}`, {RURL}, e `{TCF}`), depois emita GET ou POST. ### Notificação de adição ao carrinho S2S Compor: `trackingTemplates.server.addToCartEvent` + `trackers.addToCart.params` (substitua `{TS}`, {QTY}, {CONVERSION\_VALUE}, e `{TCF}`), depois emita GET ou POST. ### Parâmetros S2S | Parâmetro | Origem | Notas | | ----------------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `catalogId`, `sessionId`, `customerId`, `dtmId`, `placementId`, `lsid`, `utcOffset` | `trackingTemplates` query strings | Preserve esses valores como estão ao disparar a solicitação. Não os remova nem modifique. | | `modId` | `trackers..params` | Identificador do módulo ou da linha de conteúdo. | | `ts` | `trackers..params` | Substitua `{TS}` pelo carimbo de data/hora atual em milissegundos antes de disparar a solicitação. | | `iabConsentString` | `trackers..params` | Substitua `{TCF}` pela string de consentimento TCF v2 atual do CMP antes de disparar a solicitação. Se um valor já for fornecido, use-o como está. | | `rurl` | `trackers..params` | Destino de redirecionamento codificado em URL. Substitua `{RURL}` quando presente. | | `productCode`, `sellerId` | `trackers..params` | Valores derivados de nós de produtos. | | `qty` | `trackers.addToCart.params` | Substitua `{QTY}` pela quantidade absoluta do SKU no carrinho no momento em que a solicitação é disparada. Não use a variação de quantidade. | | `conVal` | `trackers.addToCart.params` | Substitua `{CONVERSION_VALUE}` pelo valor monetário total dos itens (quantidade × preço unitário, menos quaisquer descontos aplicáveis). | ## Referência de macro | Símbolo | Descrição | Encontrado em | Substitua por | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------- | | `BASEURL` (seu prefixo) | A URL base do seu site com protocolo e caminho de proxy - adicione antes de cada `trackingTemplates.client.*` caminho. | Rastreamento C2S | `https://www.retailer.com/epsilon` | | `{TS}` | Timestamp para quebra de cache (milissegundos) | `trackers..params` | `1737485823910` | | `{RURL}` | Destino do redirecionamento codificado em URL | `trackers..params.rurl` | `https%3A%2F%2Fwww.retailer.com%2Fprodukt%2F9221200653341` | | `{TCF}` | Placeholder da string de consentimento do IAB TCF v2. Presente quando `regs.consent` foi omitido na requisição. | `trackers..params.iabConsentString` | String TC atual da sua CMP, ex.: via `__tcfapi` `getTCData` → `tcString` | | `{QTY}` | Quantidade absoluta deste SKU no carrinho no momento do disparo (não é um delta; ex.: se o comprador tinha 1 e adiciona outro, envie `2`). | `trackers.addToCart.params.qty` | `2` | | `{CONVERSION_VALUE}` | Valor monetário absoluto desses itens: quantidade × preço unitário, menos quaisquer descontos aplicados. | `trackers.addToCart.params.conVal` | `49.99` | | `{RURL_KID}` | ID da chave de assinatura de redirecionamento. Presente em `trackers.click.redirectParams` quando a assinatura de redirecionamento da plataforma estiver habilitada. | `trackers.click.redirectParams.rurlKid` | ID da chave de assinatura retornado pelo endpoint de assinatura em lote | | `{RURL_SIG}` | Assinatura de redirecionamento. Presente em `trackers.click.redirectParams` quando a assinatura de redirecionamento da plataforma estiver habilitada. | `trackers.click.redirectParams.rurlSig` | Assinatura Ed25519 (base64url) retornada pelo endpoint de assinatura em lote | ### Referência de Codificação de URL Ao codificar `{RURL}`, use a codificação percentual padrão: | Caractere | Codificar como | | --------- | -------------- | | `:` | `%3A` | | `/` | `%2F` | | `?` | `%3F` | | `=` | `%3D` | | `&` | `%26` | ### redirectParams e Assinatura de Redirecionamento Quando a assinatura de redirecionamento da plataforma está habilitada, `trackers.click` pode incluir um `redirectParams`objeto ao lado de `params`. As chaves em `7`são mescladas apenas em `client.clickRedirect` URLs — não em `clickEvent`ou qualquer URL de servidor. Dois casos: **Destinos de link incorporados** (URL fixa em `params.rurl`): a plataforma assina o redirecionamento no momento da exibição e emite valores literais `rurlKid`e `rurlSig`em `redirectParams`. Adicione estes como estão à `clickRedirect` URL. **Redirecionamentos controlados pelo varejista** (`params.rurl` é {RURL}): `redirectParams` contém as macros {RURL\_KID} e {RURL\_SIG}. Chame o endpoint de assinatura em lote (`redirectSigning.url` da resposta) para obter o ID da chave e a assinatura para sua URL de destino, depois substitua antes de adicionar. O objeto de nível superior `redirectSigning`, quando presente, fornece o endpoint de `POST /ads/v3/redirect/sign` em lote e o limite do `maxUrls`lote. Entre em contato com Epsilon para confirmar se a assinatura de redirecionamento está habilitada para sua integração. ### Composição de clickRedirect com redirectParams: ``` BASEURL + trackingTemplates.client.clickRedirect + "&" + queryString(trackers.click.params) + "&" + queryString(trackers.click.redirectParams) ```
## Guia de Estilo Antes de habilitar as Brand Pages em seu site, precisamos capturar a identidade visual do seu site. Preencha a tabela abaixo com seus valores de design. Nossa equipe usará isso para configurar a experiência de pré-visualização da página da marca. #### Logo | Campo | Descrição | Seu Valor | | ----------- | ---------------------------------------- | --------- | | URL do Logo | URL para o logo do seu site (SVG ou PNG) | | #### Cores | Campo | Descrição | Seu Valor | | ------------------------ | ----------------------------------------------------- | --------- | | Cor Primária | Cor principal da marca (hex) | | | Cor de Fundo | Cor de fundo da página (hex) | | | Cor da Superfície | Cor de fundo do cartão/seção (hex) | | | Cor do Texto Primário | Cor principal do texto (hex) | | | Cor do Texto Secundário | Cor do texto suavizado (hex) | | | Texto sobre Cor Primária | Cor do texto usada em fundos com a cor primária (hex) | | | Cor da Borda | Cor padrão da borda (hex) | | #### Tipografia | Campo | Descrição | Seu Valor | | ---------------------------------- | ------------------------------------------------------------- | --------- | | Família da fonte dos títulos | Fonte usada para títulos (ex.: "Google Sans, sans-serif") | | | Família da fonte do corpo do texto | Fonte usada para o corpo do texto (ex.: "Roboto, sans-serif") | | | Tamanho base da fonte | Tamanho de fonte padrão do corpo do texto (ex.: 16px) | | #### Botões | Campo | Descrição | Seu Valor | | -------------------------------- | ---------------------------------------------------------------- | --------- | | Fundo do botão principal | Cor de fundo para botões principais | | | Cor do texto do botão principal | Cor do texto para botões principais | | | Raio da borda do botão principal | Arredondamento dos cantos (ex.: 8px) | | | Estilo do botão secundário | Descreva a aparência do botão secundário (contorno, ghost, etc.) | | ## Requisitos de conteúdo dos módulos Brand Pages são compostas por módulos de conteúdo. Para cada tipo de módulo, forneça as restrições de conteúdo que seu site exige. Nossa equipe as usará para configurar as regras de validação de modelos. ### Módulos de IMAGEM | Requisito | Descrição | Seu Valor | | -------------------------------------- | ------------------------------------------------------------------ | --------- | | Largura mínima | Largura mínima da imagem em pixels (ex.: 1920) | | | Altura mínima | Altura mínima da imagem em pixels (ex.: 500) | | | Tamanho máximo do arquivo | Tamanho máximo do arquivo em MB (ex.: 10). Deve ser menor que 4MB. | | | Formatos aceitos | Formatos de imagem aceitos (ex.: jpg, png, gif, svg) | | | Limite máximo de caracteres da legenda | Limite máximo de caracteres para a legenda da imagem, se aplicável | | | `alt`Opcionalidade da tag | Se `alt` é obrigatório nas imagens. | | ### Módulos de TEXTO | Requisito | Descrição | Seu Valor | | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | Variante | “headline”, “tagline”, “body” ou “lines”. Determina o estilo no qual o texto é exibido. | | | Alinhamento | “left”, “center” ou “right”. Determina o alinhamento horizontal do texto. | | | Configuração de “Lines” |

Configuração para texto de várias linhas (quando variant = lines). Para cada linha de texto, forneça o seguinte:

nome do campo de texto
“required” ou “allowed”?
se isso deve ser um hiperlink para outra URL

| | | Limite máximo de caracteres do título | Limite máximo de caracteres para o texto do título | | | Limite máximo de caracteres da descrição | Limite máximo de caracteres para o texto de descrição | | | Limite máximo de caracteres do corpo/rodapé | Limite máximo de caracteres para o texto do corpo ou rodapé | | | Botão CTA | Obrigatório, opcional ou não necessário? | | | Limite máximo de caracteres do texto do CTA | Limite máximo de caracteres para o rótulo do botão CTA | | ### Módulos PRODUCT\_GRID | Requisito | Descrição | Seu Valor | | ------------------------------------------------- | ----------------------------------------------------- | --------- | | Mínimo de produtos | Número mínimo de produtos para exibir (ex.: 4) | | | Máximo de produtos | Número máximo de produtos para exibir (ex.: 12) | | | Título da seção | Obrigatório ou opcional? | | | Limite máximo de caracteres do título da seção | Número máximo de caracteres para o título da seção | | | Descrição da seção | Obrigatório ou opcional? | | | Número máximo de caracteres da descrição da seção | Número máximo de caracteres para a descrição da seção | | | Botão CTA | Obrigatório, opcional ou não necessário? | | ### Módulos de IMAGE\_GALLERY O módulo Galeria de Imagens herda as mesmas propriedades de configuração do módulo IMAGE. Além disso, ele também aceita as seguintes propriedades específicas de galeria: | Requisito | Descrição | Seu Valor | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | | Mínimo de imagens | Número mínimo de imagens na galeria (ex.: 2) | | | Máximo de imagens | Número máximo de imagens na galeria (ex.: 4) | | | Título da seção | Se o texto do título da seção é obrigatório ou opcional. | | | Descrição da seção | Se o texto da descrição da seção é obrigatório ou opcional. | | | `alt` Opcionalidade da tag | Se `alt` é obrigatório nas imagens. | | | Opcionalidade de chamada para ação | Se o botão ou link de chamada para ação é obrigatório, permitido ou desativado. | | | Linhas de texto adicionais |

Para cada texto adicional que deve ser associado a cada imagem na galeria de imagens, forneça o seguinte:

nome do campo de texto
“required” ou “allowed”?
- se o texto deve funcionar como um hiperlink para outro URL

| | ### Módulos de SPLIT\_LAYOUT O módulo de Layout Dividido permite que dois módulos sejam exibidos lado a lado. Atualmente, apenas os módulos de Texto e Imagem são suportados. Além das configurações individuais para os módulos de Texto e Imagem (descritas nas seções acima), as seguintes propriedades adicionais são obrigatórias: | Requisito | Descrição | Seu Valor | | ------------------- | ------------------------------------------- | --------- | | Proporção do layout | Proporção da coluna (50:50, 33:67 ou 67:33) | | ## Identidade e privacidade ### Identificadores aceitáveis * ID de sessão - identificador de sessão anônimo (não PII) * ID de cliente - identificador de cliente do varejista (não PII, ex.: hash de ID de fidelidade) {% hint style="danger" %} Não passe endereços de e-mail com hash, números de telefone ou qualquer PII em nenhum parâmetro ou URL. {% endhint %} ### Requisitos de privacidade Os varejistas devem: * Divulgar o rastreamento de medições em sua política de privacidade * Fornecer links de recusa (opt-out): * NAI: * DAA: ### GDPR / Consentimento Passe o `regs`objeto em `POST /ads/v3/brand-pages`: * `regs.gdpr`: `1` quando a solicitação estiver sujeita ao GDPR (tratamento para UE/EEE/Reino Unido conforme sua política); `0`caso contrário. * `regs.consent`: Quando `gdpr` is `1`, passe a string de consentimento TCF v2 atual do seu CMP (o mesmo valor que você apresentaria a outros parceiros de anúncios). Não invente nem insira uma string codificada manualmente—use o que o navegador/aplicativo do usuário consentiu. * `iabConsentString`: Isso aparece nos parâmetros de cada espaço de rastreador, não em `trackingTemplates`. Quando `regs.consent` foi fornecida, o valor é a string TC literal e nenhuma ação adicional é necessária. * Quando `regs.consent` foi omitida, o valor é a `{TCF}`macro — substitua a string TCF v2 atual do seu CMP no momento do disparo antes de enviar qualquer solicitação de rastreamento. --- # 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/brand-pages/brand-page-retailer-integration-guide/tracking-attribution.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.