EDU-18149: add VTEX Ads metrics and attribution article

docs/en/tutorials/retail-media/vtex-ads-metrics-and-attribution.md

@@ -0,0 +1,135 @@
+---
+title: 'VTEX Ads metrics and attribution'
+createdAt: '2026-05-04T10:00:00.000Z'
+updatedAt: '2026-05-05T10:00:00.000Z'
+contentType: tutorial
+productTeam: Others
+slugEN: vtex-ads-metrics-and-attribution
+locale: en
+---
+
+[VTEX Ads](/en/docs/tracks/retail-media) provides a set of metrics to help advertisers, publishers, and marketing agencies measure campaign performance and the return on ad spend. The metrics are available across all VTEX Ads dashboards as **metric cards** at the top of each screen and as **columns** in the corresponding tables.
+
+This article describes the available metrics and the attribution model that determines how the platform credits conversions to ads.
+
+> ℹ️ For broader retail media terminology, see the [Retail media glossary](/en/docs/tracks/retail-media-glossary).
+
+## Performance metrics
+
+The following metrics describe the volume, efficiency, and cost of campaigns:
+
+| Metric | What it measures | Formula |
+| :---- | :---- | :---- |
+| **Impressions** | Number of times the ad was displayed to users. | - |
+| **Clicks** | Number of times users clicked on the ad. | - |
+| **Conversions** | Number of purchases attributed to the ad. | - |
+| **Sales** | Total monetary value of sales attributed to the ad. | - |
+| **CTR** (Click-through rate) | Percentage of impressions that resulted in clicks. | (Clicks / Impressions) × 100 |
+| **Conversion rate** | Percentage of clicks that resulted in conversions. | (Conversions / Clicks) × 100 |
+| **CPM** (Cost per mille) | Average cost per 1,000 impressions. | (Cost / Impressions) × 1,000 |
+| **Cost** | Total amount spent on the campaign. | - |
+| **Revenue** | Total revenue attributed to the ad. | - |
+| **ACOS** (Advertising Cost of Sales) | Share of revenue spent on advertising. The lower the ACOS, the more efficient the campaign. | (Cost / Revenue) × 100 |
+
+> ℹ️ Metrics that report a count or a monetary total (impressions, clicks, conversions, sales, cost, and revenue) are direct measures and don't have a derived formula.
+
+## Attribution model
+
+VTEX Ads attributes a conversion to an ad when a user interacts with the ad and later makes a purchase that meets the platform's attribution rules. The rules below determine which ad receives the credit, within what time frame, and how journeys with multiple interactions are resolved.
+
+### Attribution window
+
+The attribution window is 14 days. Any conversion that happens within 14 days of an eligible ad interaction (click or view) can be attributed to that ad.
+
+For example, if a user clicks an ad today, a purchase of the advertised product made within the next 14 days can be credited to that ad.
+
+### Measurement signal by campaign type
+
+The interaction that counts as the attribution signal depends on the campaign type:
+
+- **Sponsored products:** Attributed by click. A conversion is only counted when the user clicked the ad before purchasing.
+- **Banner, video, and sponsored brands:** Attributed by view (impression). A conversion is counted when the user viewed the ad before purchasing.
+
+> ℹ️ This distinction is what powers the **ROAS click** and **ROAS view** metrics described in [ROAS metrics](#roas-metrics).
+
+### Direct conversions and assisted sales
+
+Every ad-influenced purchase is classified into one of two mutually exclusive categories:
+
+- **Direct conversion:** The user bought the advertised product itself. The sale is credited to the ad based on the most recent eligible interaction:
+  - **Click conversion:** A direct conversion attributed to a click on the ad.
+  - **View conversion:** A direct conversion attributed to a view of the ad.
+- **Assisted sale:** The user bought a different product from the same seller as the advertised product, after at least one ad interaction (click or view) and with no direct conversion attributed to the ad.
+
+
+### Attribution hierarchy
+
+A single purchase is never credited to more than one campaign. When a user interacts with several ads before buying, the platform decides which campaign receives the credit using this priority order:
+
+1. **Offsite campaigns:** If an active [offsite](/en/docs/tracks/retail-media-glossary) campaign was the user's last touchpoint, it has full priority.
+2. **Last click:** Otherwise, the platform looks for the most recent click on a click-attributed campaign within the 14-day window.
+3. **Last view:** If no eligible click exists, the credit goes to the most recent view on a view-attributed campaign (banner, video, or sponsored brands).
+
+> ℹ️ The interaction (click or view) must occur before the order is placed for the conversion to be valid.
+
+### Product mapping
+
+A campaign can only be credited for products that are explicitly associated with it.
+
+- **Sponsored products (1:1 mapping):** Each ad represents a single product. A click on the ad for product A can only generate a conversion for product A.
+- **Banner, video, and sponsored brands (N:1 mapping):** A creative is associated with a list of SKUs. An interaction with the creative can attribute to any product in that list.
+
+> ℹ️ Within a campaign, each individual creative reports performance independently, so you can compare different ad pieces in the same campaign.
+
+## Assisted sales metrics
+
+Assisted sales surface the influence an ad had on purchases that didn't convert directly. For example, a user sees an ad for a Samsung S26 and, two days later, buys a Samsung S25 from the same seller. That sale is counted as assisted to the Samsung S26 ad.
+
+A sale is counted as assisted when all the following conditions are true:
+
+- The sold item belongs to the same seller as the advertised product.
+- There is no direct conversion attributed to the ad.
+- The user interacted with the ad at least once before the purchase.
+
+When more than one ad interaction is eligible, the assisted sale is credited to the most recent eligible interaction before the purchase.
+
+> ℹ️ Matching is based on the seller. Any product from the same seller can generate an assisted sale, regardless of brand or product line.
+
+The metrics derived from assisted sales data are:
+
+| Metric | What it measures |
+| :---- | :---- |
+| **Assisted sales** | Revenue from sales the ad influenced without direct conversion. |
+| **Assisted orders** | Number of orders attributed as assisted. |
+| **Assisted items** | Number of items sold attributed as assisted. |
+| **Assisted ROAS** | Return on ad spend from assisted revenue (assisted revenue / total cost). |
+
+## ROAS metrics
+
+**ROAS** (Return on Ad Spend) measures the return on ad investment. ROAS variants differ in which revenue is included in the numerator. They all share the same denominator (total ad cost), so they are directly comparable.
+
+The revenue terms used in the formulas are:
+
+- **Direct revenue:** Revenue from direct conversions of the advertised product, combining click and view conversions.
+- **Click conversion revenue:** Revenue from direct conversions credited to clicks.
+- **View conversion revenue:** Revenue from direct conversions credited to views.
+- **Assisted revenue:** Revenue from [assisted sales](#assisted-sales-metrics).
+
+| Metric | What it measures | Formula |
+| :---- | :---- | :---- |
+| **ROAS** | Return on ad spend from direct conversions (click and view combined). | Direct revenue / total cost |
+| **ROAS click** | Return on ad spend from direct conversions credited to clicks. | Click conversion revenue / total cost |
+| **ROAS view** | Return on ad spend from direct conversions credited to views. | View conversion revenue / total cost |
+| **Overall ROAS** | Consolidated return that includes both direct and assisted revenue. | (Direct revenue + assisted revenue) / total cost |
+
+Comparing **ROAS click** and **ROAS view** helps identify which campaign types drive return primarily through clicks versus views. This is useful when evaluating sponsored products against banner or sponsored brands campaigns.
+
+**Overall ROAS** combines direct and assisted revenue against the same total cost, providing a unified view of total return.
+
+> ⚠️ ROAS click and ROAS view are available to users with administrator-level permissions on VTEX Ads. Standard users won't see these two metrics on dashboards or in tables.
+
+## Data availability and access
+
+- Performance metrics and assisted metrics are available historically. There is no date restriction on their data.
+- **ROAS click**, **ROAS view**, and **Overall ROAS** are available from March 25, 2026 onward. There is no historical data for these fields prior to that date.
+- When data is absent for a given metric, the field displays zero.

docs/es/tutorials/retail-media/metricas-y-atribucion-de-vtex-ads.md

@@ -0,0 +1,11 @@
+---
+title: 'Métricas y atribución de VTEX Ads'
+createdAt: '2026-05-04T10:00:00.000Z'
+updatedAt: '2026-05-05T10:00:00.000Z'
+contentType: tutorial
+productTeam: Others
+slugEN: vtex-ads-metrics-and-attribution
+locale: es
+---
+
+> ⚠️ Contenido en traducción.

docs/pt/tutorials/retail-media/metricas-e-atribuicao-do-vtex-ads.md

@@ -0,0 +1,135 @@
+---
+title: 'Métricas e atribuição do VTEX Ads'
+createdAt: '2026-05-04T10:00:00.000Z'
+updatedAt: '2026-05-05T10:00:00.000Z'
+contentType: tutorial
+productTeam: Others
+slugEN: vtex-ads-metrics-and-attribution
+locale: pt
+---
+
+O [VTEX Ads](/pt/docs/tracks/retail-media) oferece um conjunto de métricas para ajudar anunciantes, publishers e agências de marketing a medir o desempenho das campanhas e o retorno sobre o investimento em publicidade. As métricas estão disponíveis em todos os dashboards do VTEX Ads como **cards de métricas** no topo de cada tela e como **colunas** nas tabelas correspondentes.
+
+Este artigo descreve as métricas disponíveis e o modelo de atribuição que determina como a plataforma credita conversões aos anúncios.
+
+> ℹ️ Para terminologia mais ampla de retail media, consulte o [Glossário de Retail Media](/pt/docs/tracks/glossario-de-retail-media).
+
+## Métricas de desempenho
+
+As métricas a seguir descrevem o volume, a eficiência e o custo das campanhas:
+
+| Métrica | O que mede | Fórmula |
+| :---- | :---- | :---- |
+| **Impressões** | Número de vezes que o anúncio foi exibido para os usuários. | - |
+| **Cliques** | Número de vezes que os usuários clicaram no anúncio. | - |
+| **Conversões** | Número de compras atribuídas ao anúncio. | - |
+| **Vendas** | Valor monetário total das vendas atribuídas ao anúncio. | - |
+| **CTR** (Click-through rate) | Porcentagem de impressões que resultaram em cliques. | (Cliques / Impressões) × 100 |
+| **Taxa de conversão** | Porcentagem de cliques que resultaram em conversões. | (Conversões / Cliques) × 100 |
+| **CPM** (Custo por mil impressões) | Custo médio por 1.000 impressões. | (Custo / Impressões) × 1.000 |
+| **Custo** | Valor total gasto na campanha. | - |
+| **Receita** | Receita total atribuída ao anúncio. | - |
+| **ACOS** (Advertising Cost of Sales) | Proporção da receita gasta com publicidade. Quanto menor o ACOS, mais eficiente a campanha. | (Custo / Receita) × 100 |
+
+> ℹ️ Métricas que reportam uma contagem ou um total monetário (impressões, cliques, conversões, vendas, custo e receita) são medidas diretas e não possuem fórmula derivada.
+
+## Modelo de atribuição
+
+O VTEX Ads atribui uma conversão a um anúncio quando um usuário interage com o anúncio e, posteriormente, faz uma compra que atende às regras de atribuição da plataforma. As regras a seguir determinam qual anúncio recebe o crédito, em que prazo e como jornadas com múltiplas interações são resolvidas.
+
+### Janela de atribuição
+
+A janela de atribuição é de 14 dias. Qualquer conversão que ocorra dentro de 14 dias após uma interação elegível com o anúncio (clique ou visualização) pode ser atribuída a esse anúncio.
+
+Por exemplo, se um usuário clicar em um anúncio hoje, uma compra do produto anunciado realizada nos próximos 14 dias pode ser creditada a esse anúncio.
+
+### Sinal de medição por tipo de campanha
+
+A interação que conta como sinal de atribuição depende do tipo de campanha:
+
+- **Produtos patrocinados:** atribuídos por clique. Uma conversão só é contada quando o usuário clicou no anúncio antes da compra.
+- **Banner, vídeo e marcas patrocinadas:** atribuídos por visualização (impressão). Uma conversão é contada quando o usuário visualizou o anúncio antes da compra.
+
+> ℹ️ Essa distinção é o que diferencia as métricas **ROAS click** e **ROAS view**, descritas em [Métricas de ROAS](#metricas-de-roas).
+
+### Conversões diretas e vendas assistidas
+
+Toda compra influenciada por anúncios é classificada em uma de duas categorias mutuamente exclusivas:
+
+- **Conversão direta:** o usuário comprou o próprio produto anunciado. A venda é creditada ao anúncio com base na interação elegível mais recente:
+  - **Conversão por clique:** uma conversão direta atribuída a um clique no anúncio.
+  - **Conversão por visualização:** uma conversão direta atribuída a uma visualização do anúncio.
+- **Venda assistida:** o usuário comprou um produto diferente do mesmo seller do produto anunciado, após pelo menos uma interação com o anúncio (clique ou visualização) e sem nenhuma conversão direta atribuída ao anúncio.
+
+
+### Hierarquia de atribuição
+
+Uma única compra nunca é creditada para mais de uma campanha. Quando um usuário interage com vários anúncios antes de comprar, a plataforma decide qual campanha recebe o crédito usando esta ordem de prioridade:
+
+1. **Campanhas offsite:** se uma campanha [offsite](/pt/docs/tracks/glossario-de-retail-media) ativa foi o último ponto de contato do usuário, ela tem prioridade total.
+2. **Último clique:** caso contrário, a plataforma busca o clique mais recente em uma campanha atribuída por clique dentro da janela de 14 dias.
+3. **Última visualização:** se não houver clique elegível, o crédito vai para a visualização mais recente em uma campanha atribuída por visualização (banner, vídeo ou marcas patrocinadas).
+
+> ℹ️ A interação (clique ou visualização) deve ocorrer antes do pedido ser efetuado para que a conversão seja válida.
+
+### Mapeamento de produtos
+
+Uma campanha só pode ser creditada por produtos explicitamente associados a ela.
+
+- **Produtos patrocinados (mapeamento 1:1):** cada anúncio representa um único produto. Um clique no anúncio do produto A só pode gerar conversão para o produto A.
+- **Banner, vídeo e marcas patrocinadas (mapeamento N:1):** um criativo está associado a uma lista de SKUs. Uma interação com o criativo pode atribuir a qualquer produto dessa lista.
+
+> ℹ️ Dentro de uma campanha, cada criativo individual reporta o desempenho de forma independente, permitindo comparar diferentes peças de anúncio na mesma campanha.
+
+## Métricas de vendas assistidas
+
+Vendas assistidas revelam a influência que um anúncio teve em compras que não converteram diretamente. Por exemplo, um usuário vê um anúncio de um Samsung S26 e, dois dias depois, compra um Samsung S25 do mesmo seller. Essa venda é contada como assistida ao anúncio do Samsung S26.
+
+Uma venda é contada como assistida quando todas as condições a seguir são verdadeiras:
+
+- O item vendido pertence ao mesmo seller do produto anunciado.
+- Não há conversão direta atribuída ao anúncio.
+- O usuário interagiu com o anúncio pelo menos uma vez antes da compra.
+
+Quando mais de uma interação com o anúncio é elegível, a venda assistida é creditada à interação elegível mais recente antes da compra.
+
+> ℹ️ A correspondência é baseada no seller. Qualquer produto do mesmo seller pode gerar uma venda assistida, independentemente da marca ou linha de produto.
+
+As métricas derivadas dos dados de vendas assistidas são:
+
+| Métrica | O que mede |
+| :---- | :---- |
+| **Vendas assistidas** | Receita das vendas que o anúncio influenciou sem conversão direta. |
+| **Pedidos assistidos** | Número de pedidos atribuídos como assistidos. |
+| **Itens assistidos** | Número de itens vendidos atribuídos como assistidos. |
+| **ROAS assistido** | Retorno sobre o investimento em publicidade a partir da receita assistida (receita assistida / custo total). |
+
+## Métricas de ROAS
+
+O **ROAS** (Return on Ad Spend) mede o retorno sobre o investimento em publicidade. As variantes de ROAS diferem em qual receita é incluída no numerador. Todas compartilham o mesmo denominador (custo total de publicidade), portanto são diretamente comparáveis.
+
+Os termos de receita usados nas fórmulas são:
+
+- **Receita direta:** receita das conversões diretas do produto anunciado, combinando conversões por clique e por visualização.
+- **Receita de conversão por clique:** receita das conversões diretas creditadas a cliques.
+- **Receita de conversão por visualização:** receita das conversões diretas creditadas a visualizações.
+- **Receita assistida:** receita das [vendas assistidas](#metricas-de-vendas-assistidas).
+
+| Métrica | O que mede | Fórmula |
+| :---- | :---- | :---- |
+| **ROAS** | Retorno sobre o investimento em publicidade a partir das conversões diretas (clique e visualização combinados). | Receita direta / custo total |
+| **ROAS click** | Retorno sobre o investimento em publicidade a partir das conversões diretas creditadas a cliques. | Receita de conversão por clique / custo total |
+| **ROAS view** | Retorno sobre o investimento em publicidade a partir das conversões diretas creditadas a visualizações. | Receita de conversão por visualização / custo total |
+| **Overall ROAS** | Retorno consolidado que inclui tanto a receita direta quanto a assistida. | (Receita direta + receita assistida) / custo total |
+
+Comparar **ROAS click** e **ROAS view** ajuda a identificar quais tipos de campanha geram retorno principalmente por cliques ou por visualizações. Isso é útil ao avaliar produtos patrocinados em comparação com banners ou marcas patrocinadas.
+
+O **Overall ROAS** combina receita direta e assistida sobre o mesmo custo total, oferecendo uma visão unificada do retorno total.
+
+> ⚠️ ROAS click e ROAS view estão disponíveis para usuários com permissões de administrador no VTEX Ads. Usuários padrão não verão essas duas métricas nos dashboards ou nas tabelas.
+
+## Disponibilidade e acesso aos dados
+
+- Métricas de desempenho e métricas de vendas assistidas estão disponíveis historicamente. Não há restrição de data para esses dados.
+- **ROAS click**, **ROAS view** e **Overall ROAS** estão disponíveis a partir de 25 de março de 2026. Não há dados históricos para esses campos antes dessa data.
+- Quando não há dados para uma métrica, o campo exibe zero.