From 2df193f86aa8a8e7bc00125c5affc13c21def3d8 Mon Sep 17 00:00:00 2001 From: Pedro Antunes <47991446+PedroAntunesCosta@users.noreply.github.com> Date: Mon, 18 May 2026 19:53:42 -0300 Subject: [PATCH 1/2] docs: redirect API reference pages to VTEX Developers Portal --- en/docs/1-summary.md | 23 +- en/docs/10-attribution-window.md | 101 +---- en/docs/2-glossary.md | 20 +- en/docs/3-authentication.md | 14 +- en/docs/4-data-security.md | 31 +- en/docs/5-ad-integration.md | 28 +- en/docs/5.1-api-integration.md | 26 +- en/docs/5.2-vtex-integration.md | 36 +- en/docs/5.3-catalog-synchronization.md | 196 +-------- en/docs/5.4-audience-integration.md | 102 +---- en/docs/5.5-ad-query.md | 399 +----------------- en/docs/5.5.1-placement-naming.md | 37 +- en/docs/5.6-events.md | 369 +--------------- en/docs/5.7-transparent-integration.md | 119 +----- en/docs/6-data-export.md | 65 +-- en/docs/7-script-agent.md | 81 +--- en/docs/8-credit-transfer.md | 77 +--- en/docs/9-sso.md | 36 +- es/docs/1-resumen.md | 23 +- es/docs/10-ventana-atribucion.md | 101 +---- es/docs/2-glosario.md | 20 +- es/docs/3-autenticacion.md | 14 +- es/docs/4-seguridad-de-datos.md | 31 +- es/docs/5-integracion-de-anuncios.md | 28 +- es/docs/5.1-integracion-via-api.md | 26 +- es/docs/5.2-integracion-vtex.md | 36 +- es/docs/5.3-sincronizacion-de-catalogo.md | 197 +-------- es/docs/5.4-integracion-de-audiencias.md | 102 +---- es/docs/5.5-consulta-de-anuncios.md | 398 +---------------- ...-recomendacion-de-nombres-de-placements.md | 37 +- es/docs/5.6-eventos.md | 369 +--------------- es/docs/5.7-integracion-transparente.md | 119 +----- es/docs/6-exportacion-de-datos.md | 65 +-- es/docs/7-script-agent.md | 81 +--- es/docs/8-repasse.md | 77 +--- es/docs/9-sso.md | 36 +- pt/docs/1-resumo.md | 28 +- pt/docs/10-janela-atribuicao.md | 101 +---- pt/docs/2-glossario.md | 20 +- pt/docs/3-autenticacao.md | 14 +- pt/docs/4-seguranca-de-dados.md | 31 +- pt/docs/5-integracao-de-anuncios.md | 28 +- pt/docs/5.1-integracao-via-api.md | 26 +- pt/docs/5.2-integracao-vtex.md | 36 +- pt/docs/5.3-sincronizacao-de-catalogo.md | 197 +-------- pt/docs/5.4-integracao-de-audiencias.md | 102 +---- pt/docs/5.5-consulta-de-anuncios.md | 399 +----------------- ...5.1-recomendacao-de-nomes-de-placements.md | 37 +- pt/docs/5.6-eventos.md | 369 +--------------- pt/docs/5.7-integracao-transparente.md | 119 +----- pt/docs/6-exportacao-de-dados.md | 65 +-- pt/docs/7-script-agent.md | 108 +---- pt/docs/8-repasse.md | 77 +--- pt/docs/9-sso.md | 36 +- 54 files changed, 324 insertions(+), 4989 deletions(-) diff --git a/en/docs/1-summary.md b/en/docs/1-summary.md index 06833df..4514d49 100644 --- a/en/docs/1-summary.md +++ b/en/docs/1-summary.md @@ -1,19 +1,8 @@ ## 1. Summary -This document details the integration with the **Retail Media API**, the central connection point between the VTEX Ads solution and the retailer's (publisher's) platform. The solution was developed under an **API-first** concept, ensuring total flexibility for retailers to integrate and display ads on any digital channel: e-commerce, marketplace, app, or even on physical totems and screens (Digital Signage). - -Our architecture is **cookie-less**, meaning we do not rely on third-party cookies. Identification and targeting are based on proprietary identifiers (`user_id`, `session_id`) and first-party data, ensuring a robust solution that complies with new privacy policies and is prepared for the future of digital retail. - -Through this REST API, your platform will be able to: -* Synchronize the product catalog and inventory. -* Request relevant ads in real-time for the user's Browse context. -* Send interaction events (impression, view, click, conversion) for performance measurement. - -We adopt the **Progressive Extensibility** principle to ensure maximum stability and security for our partners' operations. - -Our formal compatibility policy guarantees: -* **Non-breaking evolution:** all API updates are incremental. New fields, capabilities, and options are added without changing or removing the behavior of existing contracts. -* **Integration preservation:** current integrations remain fully operational after new releases, minimizing recurring technical rework. -* **Business continuity:** by preserving the integrity of previous contracts, we prevent operational disruptions and allow new capabilities to be adopted at your own pace. - -This approach reflects our commitment to a robust, scalable platform where technological innovation and operational predictability evolve together. +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/10-attribution-window.md b/en/docs/10-attribution-window.md index 6c32053..433fc6e 100644 --- a/en/docs/10-attribution-window.md +++ b/en/docs/10-attribution-window.md @@ -1,97 +1,8 @@ # Attribution Window and Conversion Models -This document details the rules, models, and timelines that govern the attribution of conversions (sales) and the billing of advertising campaigns on our platform. - -## 1. What is the Attribution Window? - -The "attribution window" (or conversion window) is the time period _after_ a user interacts with an ad (either by clicking or viewing) during which a conversion can be credited to that ad. - -- **Default Window:** 14 days. -- **Flexibility:** This period is the default for all campaigns, but can be customized according to strategic needs. - -**Example:** If a user clicks on an ad today, any purchase they make of the associated product in the next 14 days can be attributed to that ad. - -## 2. Measurement (Attribution) vs. Billing (Invoicing) - -It is essential to differentiate the event that _measures_ attribution (what we use to count a conversion) from the event that _generates billing_ (what we charge the advertiser). - -### 2.1. Measurement Events (Attribution) - -This defines _how_ we know that an ad "worked" to generate a sale: - -- **Product Campaigns (Product Ads):** - - **Event:** Click. - - **Logic:** The conversion is only counted if the user _clicked_ on the ad before purchasing. - -- **Other Campaigns (Banner, Video, and Sponsored Brands):** - - **Event:** View (Impression). - - **Logic:** The conversion can be counted even if the user only _saw_ the ad (and did not necessarily click), following the hierarchy rules (see section 3). - -### 2.2. Billing Models (Invoicing) - -This defines _what_ the advertiser pays for: - -- **CPC (Cost Per Click):** The advertiser pays each time a user clicks on the ad. - - _Used in:_ Product Campaigns, Sponsored Brands. - -- **CPM (Cost Per Thousand Impressions):** The advertiser pays a fixed amount for every 1,000 times the ad is displayed. - - _Used in:_ Banner, Video, Sponsored Brands. - -- **Hybrid Model (CPC + CPM):** - - **Sponsored Brands** campaigns are unique, as they charge for _both_ clicks (CPC) and impressions (CPM) generated. - -#### Billing Calculation Example (CPM) - -CPM defines the value for 1,000 impressions, but the actual charge is proportional to each individual impression. - -- **Scenario:** A video campaign has a CPM of **$10.00**. -- **Result:** The campaign generates **10 impressions**. - -**Calculation:** - -1. **Cost per individual impression:** $10.00 (CPM) / 1,000 (impressions) = **$0.01 per impression**. -2. **Total Cost:** 10 (impressions generated) * $0.01 (cost per impression) = **$0.10**. - -The total cost of this campaign would be **ten cents**. - -## 3. Attribution Rules (The Decision Hierarchy) - -When a user interacts with multiple ads before purchasing, an attribution model decides which campaign will receive credit for the sale. - -**Fundamental Principle:** Attribution is exclusive. A sold order is **never** attributed to two different campaigns; credit is always given to a single campaign. - -The decision follows this priority order: - -1. **Priority 1: Offsite Campaigns** - - If there is an active _offsite_ campaign (bringing external traffic to the site) and it was the user's last point of contact, it will have total preference in the sale attribution. - -2. **Priority 2: Last Click** - - In the absence of a recent offsite click, the system looks for the _last ad_ (within the platform) that the user _clicked_ within the 14-day window. - -3. **Priority 3: Last View** - - If the user did not click on any ad during the period, the system attributes the sale to the _last ad_ they _viewed_ (as long as it is a campaign type that measures by view, such as Banner or Video). - -**Time Rule:** For a conversion to be valid, the interaction event (click or view) must have occurred _before_ the order was finalized. - -## 4. Product Mapping in Attribution - -A campaign can only receive attribution for products that are _explicitly linked to it_. - -### 4.1. Product Campaigns (1:1 Attribution) - -- **How it works:** Each ad (AD) within the campaign represents a specific product. -- **Logic:** Attribution is direct and 1-to-1. A click on the "Product A" ad can only generate a conversion for "Product A". - -### 4.2. Other Campaigns (Banner, Video, etc.) (N:1 Attribution) - -- **How it works:** These campaigns have a _list_ of associated products (SKUs). -- **Logic:** Interaction (click or view) with a single creative (banner or video) can generate attribution for _any_ of the products contained in that campaign list. - -**Note on Creatives:** Within a campaign (e.g., Banner), each creative (e.g., "Banner A" and "Banner B") tracks its information independently. This allows analysis of the individual performance of each ad piece. - -## 5. Data Latency (Attribution Delay) - -It is important to note that there is a natural delay between the moment the customer creates the order and the moment that sale is associated (attributed) to the correct campaign in the reports. - -- **API Integration:** Delay of approximately **30 minutes**. -- **VTEX Platform:** Delay of up to **2 hours**. +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/2-glossary.md b/en/docs/2-glossary.md index 9905fb5..b3c0f0b 100644 --- a/en/docs/2-glossary.md +++ b/en/docs/2-glossary.md @@ -1,16 +1,8 @@ ## 2. Glossary -| Term | Description | -| :--- | :--- | -| **Advertiser** | Companies, sellers, or individuals who promote their products, services, or ideas through campaigns. | -| **Publisher (Retailer)** | The entity that owns and operates the digital platform (website, app) and makes ad spaces available. | -| **Campaign** | An action created by an advertiser to promote products and generate conversions (sales). | -| **Impression** | Counted each time an ad is displayed on the user's screen. | -| **View** | Counted when an impression becomes visible on the user's screen for a specified time. | -| **Click** | User interaction by clicking on an ad to be redirected to the landing page. | -| **Conversion** | A valuable action generated by an ad, typically a sale. | -| **Ad Revenue** | Revenue earned by retailers from monetizing their ad spaces. | -| **Sales Revenue** | Total revenue a company obtains from the sales of products or services. | -| **CTR (Click-Through Rate)** | Formula: `(Clicks / Impressions) * 100`. Measures the attractiveness of an ad. | -| **ROAS (Return on Ad Spend)**| Return on Advertising Spend. Formula: `Revenue Generated by Ads / Advertising Cost`. | -| **Conversion Rate** | The percentage of conversions relative to the total number of clicks or visits. | +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/3-authentication.md b/en/docs/3-authentication.md index 2071ce3..49223ed 100644 --- a/en/docs/3-authentication.md +++ b/en/docs/3-authentication.md @@ -1,10 +1,8 @@ ## 3. Authentication -Authentication is required for catalog submission, report consumption, and management. Other calls, such as ad queries and event notifications, are public and do not require authentication. - -For protected endpoints, credentials must be sent via HTTP header. Request your credentials from your account manager. - -| Attribute | Description | -| :--- | :--- | -| `x-app-id` | Your application's unique ID for the integration. | -| `x-api-key` | API key associated with your application. | +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/4-data-security.md b/en/docs/4-data-security.md index 975cccc..cfdf405 100644 --- a/en/docs/4-data-security.md +++ b/en/docs/4-data-security.md @@ -1,27 +1,8 @@ # 4. Data Security -Data security is a fundamental pillar of our platform. From the outset, our architecture was designed to ensure that no sensitive information is collected and that user data remains protected and non-identifiable at all times. - -## Non-Identifiable Data - -We do not collect sensitive user data, such as names, emails, or personal documents. The information we do receive, like emails or identification numbers (PII - Personally Identifiable Information), already arrives on our platform as an irreversible cryptographic hash. - -This means the original data is never transmitted to or stored in our systems. The result is an anonymous identifier that allows us to group behaviors and audiences without ever knowing who the actual user is. - -**Why is this secure?** - -* **Irreversibility:** The hashing process is a one-way street. Even if someone gained access to the hash, they could not uncover the original data. -* **Anonymity:** Since we do not store the original data, we have no way of identifying the user. For all intents and purposes, the data is anonymous. - -## Encryption in Transit and at Rest - -All data, whether they are anonymous identifiers or information about campaigns and ads, is handled with the highest security standards: - -* **Encryption in Transit:** All communication between our systems and with partners is conducted using secure protocols like TLS 1.2+, ensuring that data cannot be intercepted during transfer. -* **Encryption at Rest:** Data stored in our databases and file systems is encrypted. We use robust and market-recognized solutions such as **Amazon RDS**, **Amazon S3**, **Amazon Redshift** and **Snowflake**, which apply AES-256 encryption, one of the most secure algorithms in existence. - -## Restricted Access - -Access to data is strictly controlled and limited to a select group of senior engineers and analysts. Every access is audited and monitored, and permissions are granted based on the principle of least privilege, meaning each person has access only to what is strictly necessary to perform their job. - -This combination of non-identifiable data, end-to-end encryption, and rigorous access control ensures that your information and that of your customers are always secure. +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/5-ad-integration.md b/en/docs/5-ad-integration.md index bf94385..50483b3 100644 --- a/en/docs/5-ad-integration.md +++ b/en/docs/5-ad-integration.md @@ -1,24 +1,8 @@ # 5. Ad Integration -This section provides detailed information on how to integrate with the VTEX Ads platform to display ads on your website. - -## 5.0 Integration Flow Overview - -Complete VTEX Ads integration flow - -The complete integration flow is divided into four main phases that continuously feed back into each other: - -1. **Preparation and Onboarding:** Align scope and timeline with the VTEX Ads team, receive API credentials, and validate access to environments and webhooks. -2. **Operational Data Synchronization:** Load catalog (products and inventory) and, optionally, audiences. This step ensures that only available products and valid segmentations are eligible to appear. -3. **Ad Delivery:** Structure site placements, configure naming conventions, and query ads in real-time for each context (home, search, category, PDP, etc.), displaying the "Sponsored" label. -4. **Measurement and Optimization:** Fire impression, view, click, and conversion events using `navigator.sendBeacon()`, monitor performance metrics, and adjust bids, segmentation, and positioning according to results. - -The following sections detail how to execute each of these phases, with request examples and specific best practices. - -- [5.1. API Integration](./5.1-api-integration.md): For a more customized integration, use our REST API to manage the entire ad lifecycle. -- [5.2. VTEX Integration](./5.2-vtex-integration.md): If your store is on the VTEX platform, use our VTEX IO app to simplify the process. -- [5.3. Catalog Synchronization](./5.3-catalog-synchronization.md): Keep your product catalog and inventory synchronized with VTEX Ads. -- [5.4. Audience Integration](./5.4-audience-integration.md): Send audience data to improve targeting and ad relevance. -- [5.5. Ad Query](./5.5-ad-query.md): Request from the API the ads that should be displayed on different pages and contexts. -- [5.5.1. Placement Naming](./5.5.1-placement-naming.md): Recommended standard for naming placements to enable accurate measurement. -- [5.6. Events](./5.6-events.md): Notify the API of user interactions with ads and conversions. +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/5.1-api-integration.md b/en/docs/5.1-api-integration.md index fd25a8c..232548a 100644 --- a/en/docs/5.1-api-integration.md +++ b/en/docs/5.1-api-integration.md @@ -1,22 +1,8 @@ # 5.1 API Integration -The integration is based on three pillars that ensure the solution's functionality. - -### Integration Pillars - -1. **[Catalog Synchronization](./5.2-catalog-synchronization.md):** Keep VTEX Ads synchronized with your product catalog and inventory (price and stock). Essential for product ads. -2. **[Ad Query](./5.3-ad-query.md):** Your platform requests from the API the ads that should be displayed on different pages and contexts. -3. **[Events](./5.4-events.md):** Your platform notifies the API of all user interactions with the ads and, crucially, of conversions (sales). - -### Ad Types - -| Ad Type | API Type | Description | -| :--- | :--- |:------------------------------------------------| -| **Sponsored Products** | `product` | Ads for individual products. | -| **Display** | `banner` | Visual ads (static image or video). | -| **Sponsored Brands** | `sponsored_brand` | Brand ads with a title, logo, and products. (static image or video) | -| **Digital Signage** | `digital_signage`| Content for physical screens and totems. | - -### Audience Integration - -Target ads to specific audiences to increase relevance. See more in [Audience Integration](./5.2-audience-integration.md). +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/5.2-vtex-integration.md b/en/docs/5.2-vtex-integration.md index 5e28dbb..38942b5 100644 --- a/en/docs/5.2-vtex-integration.md +++ b/en/docs/5.2-vtex-integration.md @@ -1,32 +1,8 @@ # 5.1 VTEX Integration (VTEX IO App) -For stores on the VTEX platform, Newtail offers a storefront app (`Newtail Media APP VTEX`) that drastically simplifies implementation. The app includes visual components and all the logic for ad queries and event notifications. -* **Step 1: Catalog Synchronization** - * Synchronizing the product catalog is a prerequisite. It can be done in two ways: - 1. **Via API:** By providing Newtail with API keys to read your catalog. - 2. **Via XML:** By providing a link to a Google Shopping format XML feed, which must contain the `SKU` field for product identification. - -* **Step 2: App Installation** - 1. **Add as Dependency:** In your theme's `manifest.json` file, add `"newtail.media": "0.x"` to the `peerDependencies`. - 2. **Install the App:** Run the command `vtex install newtail.media@0.x` in your terminal. - -* **Step 3: Configuration** - 1. **Publisher ID:** In your VTEX store's admin, go to `Store Settings > Newtail Media` and enter your `Publisher ID` provided by Newtail. - 2. **Content Security Policy (CSP):** Add the following directives to your `policies.json`: - ```json - { - "contentSecurityPolicy": { - "default-src": ["'self'", "newtail-media.newtail.com.br"], - "connect-src": ["'self'", "newtail-media.newtail.com.br"] - } - } - ``` - -* **Step 4: Using the Blocks** - * Declare the app's blocks in your theme's templates to display the ads. - - * **Available Components:** - * `newtail-media-banner`: Renders sponsored banners. - * `newtail-media-shelf`: Renders a shelf of sponsored products. - * `newtail-media-search`: Adds "Sponsored" badges to products in search results. - * `newtail-media-conversion`: An essential component that manages the sending of conversion events. **Must be included on all pages.** \ No newline at end of file +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/5.3-catalog-synchronization.md b/en/docs/5.3-catalog-synchronization.md index d5f2ecd..5d47602 100644 --- a/en/docs/5.3-catalog-synchronization.md +++ b/en/docs/5.3-catalog-synchronization.md @@ -1,192 +1,8 @@ ## 5.2. Catalog Synchronization -The first step is synchronization, which occurs on two fronts: - -> **Note for VTEX stores:** For stores on the VTEX platform, catalog synchronization occurs transparently, with no additional integration required for this purpose. - -#### **Product Synchronization** -Sends product registration information. Requires authentication. - -* **Endpoint:** `POST https://api-retail-media.newtail.com.br/product/bulk/products` -* **Limits:** 500 products per request; 3 simultaneous requests. - -| Field | Description | Type | Required? | -| :--- | :--- | :--- | :--- | -| `product_sku` | Unique product ID/SKU. | String | Yes | -| `parent_sku` | Parent product SKU (for variations). | String | No | -| `name` | Product name. | String | Yes | -| `url` | Canonical URL of the product page. | String | Yes | -| `image_url`| URL of the main product image. | String | No | -| `categories` | List of categories. | Array[String] | Yes | -| `brand` | Product brand. | String | No | -| `gtins` | Barcodes (EAN). **Required for campaigns on the VTEX Ads Network.**| Array[String] | No/Yes | -| `tags` | "Tags" to contextualize searches. Max 10 per SKU, 64 chars per tag. Only for `product` campaigns. | Array[String] | No | -| `sellers` | List of sellers who sell the product (in a marketplace). | Array[String] | No | -| `metadata` | Object for additional information (key-value). | Object | No | - ---- - -### **Structuring Categories** - -> **Important:** The `categories` field is crucial for campaign targeting and product organization. It must be structured hierarchically, representing the full path from the root category to the product's specific category. - -The `categories` field must be an array of strings, where each string is a level of the category tree. The hierarchy is built by sending all parent categories up to the most specific one. - -**Correct Example:** - -For a product in the "For Women" perfume category, the `categories` array should be: - -```json -"categories": [ - "Beauty", - "Beauty > Fragrances", - "Beauty > Fragrances > Perfume", - "Beauty > Fragrances > Perfume > For Women" -] -``` - -This structure allows the platform to understand the product's context at all levels, from the broadest ("Beauty") to the most specific ("For Women"). - ---- - -**Request Example:** - -```bash -curl --location 'https://api-retail-media.newtail.com.br/product/bulk/products' \ ---header 'x-app-id: XXXX' \ ---header 'x-api-key: YYYY' \ ---header 'Content-Type: application/json' \ ---data '[ - { - "product_sku": "allan", - "name": "allan", - "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616", - "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629", - "categories": [ - "Beauty", - "Beauty > Fragrances", - "Beauty > Fragrances > Perfume", - "Beauty > Fragrances > Perfume > For Women" - ], - "brand": "SALVADOR DALÍ", - "profit_margin": null, - "gtins": [ - "3331438450103" - ], - "sellers": [], - "skus": [] - }, - { - "product_sku": "allan2", - "name": "allan2", - "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616", - "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629", - "categories": [ - "Beauty", - "Beauty > Fragrances", - "Beauty > Fragrances > Perfume", - "Beauty > Fragrances > Perfume > For Women" - ], - "brand": "SALVADOR DALÍ", - "profit_margin": null, - "gtins": [ - "3331438450103" - ], - "sellers": [], - "skus": [], - "tags": ["Abart", "Mega Maio"] - } -]' -``` - -**Success Response Example:** - -``` -Status: 202 Accepted -Content-Type: application/json - -{ - "messages": [ - "products will be processed soon" - ] -} -``` - ---- - -#### **Inventory Synchronization** -Sends price and stock information for products. Requires authentication. - -* **Endpoint:** `POST https://api-retail-media.newtail.com.br/product/bulk/inventories` -* **Limits:** 500 products per request; 3 simultaneous requests. - -| Field | Description | Type | Required? | -| :--- | :--- | :--- | :--- | -| `product_sku` | Unique product ID/SKU. | String | Yes | -| `price` | Current product price. | Float | Yes | -| `promotional_price` | "From" price (list/original). | Float | Yes | -| `is_available` | Available product (in stock). | Boolean | Yes | -| `store_id` | Store ID. If store_id is not provided, it will be interpreted as meaning this inventory information will be used for all stores. | String | No | -| `metadata` | Object for additional information (key-value). | Object | No | - -**Request Example:** - -```bash -curl --location 'https://api-retail-media.newtail.com.br/product/bulk/inventories' \ ---header 'x-app-id: XXXX' \ ---header 'x-api-key: YYYY' \ ---header 'Content-Type: application/json' \ ---data '[ - { - "product_sku": "120210", - "store_id": "1", - "price": 18.20, - "promotional_price": 16.32, - "is_available": true - }, - { - "product_sku": "120212", - "price": 18.20, - "promotional_price": 0, // Remove promotional price - "is_available": true - } -]' -``` - -**Success Response Example:** - -``` -Status: 202 Accepted -Content-Type: application/json - -{ - "messages": [ - "inventory will be processed soon" - ] -} -``` - ---- - -### **Best Practices for Synchronization** - -1. **Complete Initial Synchronization:** - * Send the entire catalog in the first synchronization. - * Divide into batches of up to 500 products to avoid timeouts. - -2. **Incremental Updates:** - * After the initial synchronization, send only new or changed products. - * Keep a record of the last modification date of each product. - -3. **Update Frequency:** - * Prices and stock: Update at least once a day, ideally in real-time for significant changes. - * Registration information: Update when there are changes. - -4. **Error Handling:** - * Implement retries with exponential backoff for temporary failures. - * Monitor API responses to identify persistent problems. - -5. **Data Validation:** - * Verify that all required fields are filled in. - * Ensure that product and image URLs are valid and accessible. - * Make sure categories follow the recommended hierarchical structure. \ No newline at end of file +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/5.4-audience-integration.md b/en/docs/5.4-audience-integration.md index b0154ca..c08c952 100644 --- a/en/docs/5.4-audience-integration.md +++ b/en/docs/5.4-audience-integration.md @@ -1,98 +1,8 @@ ## 5.4. Audience Integration -> **Note:** Audience integration is optional, but highly recommended to improve campaign targeting and ad relevance. - -Audience integration has a single integration method: **Batch Submission** to the S3 bucket provided by VTEX Ads. - -> **Important:** FTP/SFTP integration is **deprecated** and should only be used for legacy implementations. New projects must use the S3 bucket exclusively. - -> **Warning:** If there is no audience integration, you must open a ticket with your Account Manager requesting pre-population of segmentation information with base data (`STATE`, `CITY`, `GENDER`, and `AGE`). You can also provide a list of audiences to be registered, and we recommend keeping these audiences updated periodically. - -### Batch Submission - S3 Bucket - -The integration connection occurs through periodic audience uploads to the publisher's dedicated S3 bucket. Access credentials (IAM key/secret or cross-account role) and the bucket base path must be requested from your Newtail contact. - -* **File Format:** `Parquet` with `Snappy` compression. -* **Directory Pattern (S3 key):** Upload files using: - `s3:////audiences/YYYY/mm/dd/TIMESTAMP.parquet.snappy` - -| Attribute | Description | Example | -| :--- | :--- | :--- | -| `PREFIX` | The prefix will be provided by Newtail. | `xyz` | -| `YYYY` | 4-digit year of generation. | `2023` | -| `mm` | Two-digit month of generation (January = 01 and December = 12). | `09` | -| `dd` | Two-digit day of generation (from 01 to 31). | `31` | -| `TIMESTAMP`| Timestamp is the number of seconds since 1970 (the file name can be anything, the timestamp is just a suggestion that will never be repeated). | `1694812122` | - -> **Recommendation for submission:** In the initial integration, it is essential that all data be sent. This data can be sent in multiple files (depending on the size of the base, a good number is 1 million lines per file). After the first integration, the ideal is to send only the delta of the rows that had any modification. - -> **Legacy compatibility:** If you are already integrated via SFTP, contact the VTEX Ads team to plan the migration to the S3 bucket. The SFTP flow will no longer receive new enhancements and may be discontinued. - -### Runtime Alternative Without Prior Integration - -If you choose not to integrate audiences via batch, you can still use segmentation at runtime by sending the data in the `segmentation` field of the ad query request. See [5.5. Ad Query](5.5-ad-query.md). - -### Audience File Attributes - -Most attributes are not mandatory, however, the more complete this information is, the better the relevance will be. - -> The columns are **case-sensitive**. Keep the column names as they are presented. - -| Column | Type | Required? | Description | -| :--- | :--- | :--- | :--- | -| `CUSTOMER_ID` | String | Yes | Unique customer identifier. | -| `EMAIL_HASHED` | String | No | PII based on the customer's email. | -| `PHONE_HASHED` | String | No | PII based on the customer's primary phone number. | -| `SOCIAL_ID_HASHED` | String | No | PII based on the customer's CPF. | -| `FIRST_NAME_HASHED` | String | No | PII based on the customer's First Name. | -| `LAST_NAME_HASHED` | String | No | PII based on the customer's Last Name. | -| `GENDER` | String | No | Indicates the customer's gender (`F` for female, `M` for male, `O` for others, `NULL` for unidentified). | -| `AGE` | Int | No | Indicates the customer's age. | -| `CEP` | String | No | Indicates the customer's postal code. | -| `COUNTRY` | String | No | Indicates the user's country. | -| `STATE` | String | No | Indicates the state where the customer resides. | -| `CITY` | String | No | Indicates the city where the customer resides. | -| `NEIGHBORHOOD` | String | No | Indicates the neighborhood where the customer resides. | -| `AUDIENCES` | String | No | A list of audiences, separated by a semicolon (;). | -| `NBO_PRODUCTS` | String | No | A list of product SKUs, separated by a semicolon (;). | -| `NBO_CATEGORIES` | String | No | A list of categories, separated by a semicolon (;). The list can receive a category tree using " > " as a separator (e.g., `Tablets;Beverages > Non-Alcoholic Beverages;Books > Gastronomy > Bar and Restaurant Guides`). | - -### Field Hashing - -Confidential data must be encrypted before being sent using the **SHA256** algorithm. - -* `EMAIL_HASHED` -* `PHONE_HASHED` -* `SOCIAL_ID_HASHED` -* `FIRST_NAME_HASHED` -* `LAST_NAME_HASHED` - -> Before generating the hash of the data, it is necessary to remove all **SPACES** and convert its values to **LOWERCASE**. -> For the `PHONE_HASHED` attribute, it will be necessary to format it in the **E.164** standard and include the country calling code. - -#### E.164 Format - -1. Remove all non-numeric characters, such as spaces, hyphens, parentheses, and symbols. -2. Add the country code with the plus sign (+) at the beginning. -3. Add the area code (if applicable) without the leading zero. -4. Include the local phone number without the leading zero (if applicable). - -**Example:** - -* A phone number from the United States, with area code 212 and local number 555-1234, would be formatted as: `+12125551234` - -#### Creating a HASH in Python - -```python -import re -import hashlib - -hash_obj = hashlib.sha256() - -def create_hash(x): - cleaned = re.sub('\s+', '', x.lower()) - hash_obj.update(cleaned.encode('utf-8')) - return hash_obj.hexdigest() - -create_hash(' Allan ') #=> 8c01ade3cb71d3ac7c718ed5a0c565155a4c05a216d9e59013c5d7b49e916914 -``` +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/5.5-ad-query.md b/en/docs/5.5-ad-query.md index cd0ea1a..b2eabdf 100644 --- a/en/docs/5.5-ad-query.md +++ b/en/docs/5.5-ad-query.md @@ -1,395 +1,8 @@ ## 5.5. Ad Query -With the catalog synchronized, your platform requests ads to fill the ad spaces (`placements`). The request is a `POST` and the `publisher_id` must be provided in the URL. - -* **Endpoint:** `POST https://newtail-media.newtail.com.br/v1/rma/:publisher_id` -* **Content-Type:** All requests must include the `Content-Type: application/json` header. - -#### Request Best Practices - -- **HTTP persistence:** Prefer persistent connections (`Connection: keep-alive`). -- **Timeout:** Apply a 500–600 ms timeout to the ad query (see 5.6 for events guidance). - -#### **Request Parameters** - -| Field | Description | Type | Required? | -| :--- | :--- | :--- | :--- | -| `session_id` | Persistent visitor identifier (≥ 14 days). For mobile applications, the device ID should be sent as the session_id (GAID on Android and IDFA on iOS), so that the session is maintained indefinitely. | String | Yes | -| `user_id` | Unique ID of the logged-in user (alphanumeric). | String | No (Recommended) | -| `store_id` | Filters ads by a specific store's stock. | String | No | -| `channel` | Access channel: `site`, `msite`, `app` (for ad query). | String | Yes | -| `context` | Context: `home`, `category`, `search`, `product_page`, `brand_page`, `digital_signage`.| String | Yes | -| `term` | Term searched by the user. | String | Only `context: 'search'` | -| `category_name` | Browsed category (full breadcrumb).| String | Only `context: 'category'`| -| `product_sku` | SKU of the product being viewed. | String | Only `context: 'product_page'` | -| `brand_name` | Name of the brand being viewed. | String | Only `context: 'brand_page'` | -| `device_id` | Unique device ID (screen, totem). | String | Only `context: 'digital_signage'` | -| `store_name` | Name of the store where the device is located. | String | Only `context: 'digital_signage'` | -| `placements` | Object defining the ad `placements`. | Object | Yes | -| `placements.{name}.quantity` | Desired number of ads. | Integer | Yes | -| `placements.{name}.size` | Expected size (Image: `desktop`/`mobile`; Video: `1080p`/`720p`/`480p`/`360p`/`320p`). | String | Only `types: ['banner', 'sponsored_brand']` | -| `placements.{name}.types` | Allowed types (`product`, `banner`, etc.). | Array[String] | Yes | -| `placements.{name}.assets_type`| Accepted media (`image`, `video`). Default: `["image"]`. | Array[String] | Only `types: ['banner', 'sponsored_brand']` | -| `placements.{name}.allow_sku_duplications` | Allows the same SKU to appear more than once within the same placement. | Boolean | No (Default=false) | -| `userAgent` | Client environment identification (body field, not the HTTP `User-Agent` header). | String | No | -| `segmentation` | Data for real-time targeting. | Array[Object] | No | -| `segmentation.#.key` | The type of segmentation. | String | No | -| `segmentation.#.values` | Array of values for the segmentation. | Array[String] | No | -| `tags` | "Tags" to contextualize searches (primarily for `search`). Max 10 per SKU, 64 chars per tag. Only for `product` campaigns. | Array[String] | No | -| `brand` | Publisher's site name. | String | Required when the publisher has multiple sites | -| `dedup_campaign_ads` | Deduplicate by campaign (response contains at most one ad per campaign). | Boolean | No (Default=false) | -| `dedup_ads` | Deduplicate by `ad_id` across multiple placements (use only when querying multiple placements at the same time). | Boolean | No (Default=false) | -| `skus` | Filters ad results to return only ads for the specified SKUs. Only compatible with Sponsored Products (product campaigns). | Array[String] | No | - -##### Fields by Context - -| Context | Additional required fields | -| :--- | :--- | -| `home` | — | -| `search` | `term` | -| `category` | `category_name` | -| `product_page` | `product_sku` | -| `brand_page` | `brand_name` | -| `digital_signage` | `device_id`, `store_name` | - -#### **⚠️ Important Context and Ad Eligibility Rules** - -##### Filter Limitations - -> **Important:** It is not possible to filter by specific `placement`. Ad selection is based on `context` and request parameters. - -##### Eligibility by Context - -###### `home` Context - -In the **home** context, the following can be returned: - -- ✅ **Banner/Video/Sponsored Brands Ads** that use **category** as a targeting criterion -- ✅ **Product Ads (Sponsored Products)** are also eligible - -**Example:** -```json -{ - "context": "home", - "placements": { - "site_home_middle_banner": { - "quantity": 3, - "types": ["banner", "sponsored_brand"], - "assets_type": ["image", "video"], - "size": "desktop" - }, - "site_home_shelf_product": { - "quantity": 10, - "types": ["product"] - } - } -} -``` - -###### `brand_page` Context - -In the **brand_page** context, the following can be returned: - -- ✅ **Banner/Video/Sponsored Brands Ads** for the brand -- ✅ **Product Ads (Sponsored Products)** from the brand - -**Example:** -```json -{ - "context": "brand_page", - "brand_name": "Nike", - "placements": { - "site_brand_top_banner": { - "quantity": 1, - "types": ["banner", "sponsored_brand"], - "assets_type": ["image"], - "size": "desktop" - }, - "site_brand_shelf_product": { - "quantity": 12, - "types": ["product"] - } - } -} -``` - -###### `digital_signage` Context - -In the **digital_signage** context, ads can be returned for physical screens/totems. - -**Example:** -```json -{ - "context": "digital_signage", - "device_id": "totem-abc-001", - "store_name": "Downtown Store", - "placements": { - "totem_home_main_video": { - "quantity": 1, - "types": ["banner"], - "assets_type": ["video"], - "size": "720p" - } - } -} -``` - -###### `search` Context - -In the **search** context, the following can be returned: - -- ✅ **Banner/Video/Sponsored Brands Ads** that are **keyword-based** -- ✅ **Any Product Campaign (Sponsored Products)** - -**⚠️ Exact Keyword Matching:** - -Keyword matching in the `search` context is **exact** (no stemming/synonyms). This means: - -- The advertiser **must specify exactly** which keywords they want to use in the Banner/Video/Sponsored Brands campaign -- If a user searches for "nike shoes", the ad will only be eligible if the advertiser registered exactly the keyword "nike shoes" -- There is no approximate matching or similar words matching - -**Example:** -```json -{ - "context": "search", - "term": "nike shoes", - "placements": { - "site_search_top_banner": { - "quantity": 1, - "types": ["banner", "sponsored_brand"], - "assets_type": ["image"], - "size": "desktop" - }, - "site_search_shelf_product": { - "quantity": 20, - "types": ["product"] - } - } -} -``` - -**Expected behavior:** -- **Banner/Sponsored Brand:** Will only appear if the advertiser registered the exact keyword "nike shoes" in the campaign -- **Sponsored Products:** Products related to the search term will be returned - -###### `category` Context - -In the **category** context, the following can be returned: - -- ✅ **Banner/Video/Sponsored Brands Ads** that use the corresponding **category** -- ✅ **Product Ads (Sponsored Products)** from the category - -**Example:** -```json -{ - "context": "category", - "category_name": "Sports > Shoes > Sneakers", - "placements": { - "site_category_top_banner": { - "quantity": 1, - "types": ["banner", "sponsored_brand"], - "assets_type": ["image", "video"] - } - } -} -``` - -###### `product_page` Context - -In the **product_page** context, the following can be returned: - -- ✅ **Product Ads (Sponsored Products)** related to the viewed product - -**Example:** -```json -{ - "context": "product_page", - "product_sku": "12345", - "placements": { - "site_product_recommendation": { - "quantity": 5, - "types": ["product"] - } - } -} -``` - -#### **Query Response** -The response is a JSON where each key is a `placement` name. The structure of each ad in the response depends on its type. - -##### **Common Response Fields for All Ad Types** -These fields are present in all ad types: - -| Field | Description | -| :--- | :--- | -| `{placementName}.#.ad_id` | Unique ad ID. | -| `{placementName}.#.type` | Ad type (`product`, `banner`, `sponsored_brand`, `digital_signage`). | -| `{placementName}.#.click_url`| **URL to notify the click event.** | -| `{placementName}.#.impression_url`| **URL to notify the impression event.**| -| `{placementName}.#.view_url` | **URL to notify the view event.** | -| `{placementName}.#.seller_id` | ID of the seller of the advertised product (optional). | - -##### **Type-Specific Response Fields** - -###### **Product Ads** -Additional fields for ads of type `product`: - -| Field | Description | -| :--- | :--- | -| `{placementName}.#.product_sku`| SKU of the product being advertised. | - -###### **Banner Ads** -Additional fields for ads of type `banner`: - -| Field | Description | -| :--- | :--- | -| `{placementName}.#.media_url`| URL of the image or video to be displayed. | - -###### **Sponsored Brand Ads** -Additional fields for ads of type `sponsored_brand`: - -| Field | Description | -| :--- | :--- | -| `{placementName}.#.media_url`| URL of the image or video to be displayed. | -| `{placementName}.#.products`| Array of products associated with the sponsored brand. | -| `{placementName}.#.products.#.product_sku`| SKU of the associated product. | -| `{placementName}.#.products.#.media_url`| URL of the product image. | - -###### **Digital Signage Ads** -Additional fields for ads of type `digital_signage`: - -| Field | Description | -| :--- | :--- | -| `{placementName}.#.media_url`| URL of the image or video to be displayed. | -| `{placementName}.#.duration`| Duration of the ad display in seconds. | - -##### Example Response (multi-placement) - -```json -{ - "site_home_middle_banner": [ - { - "ad_id": "ad-001", - "type": "banner", - "media_url": "https://cdn.example.com/banner1.jpg", - "impression_url": "https://events.../impression/abc", - "view_url": "https://events.../view/abc", - "click_url": "https://events.../click/abc" - } - ], - "site_home_shelf_product": [ - { - "ad_id": "ad-101", - "type": "product", - "product_sku": "SKU-123", - "seller_id": "SELLER-9", - "impression_url": "https://events.../impression/def", - "view_url": "https://events.../view/def", - "click_url": "https://events.../click/def" - } - ] -} -``` - -### Best Practices - -#### Placement Naming - -Adopt a clear standard, such as `{channel}_{context}_{position}_{type}` (e.g., `msite_search_top-shelf_product`). For detailed recommendations, see `en/docs/5.5.1-placement-naming.md`. - -| channel | context | position | type | example | -| --- | --- | --- | --- | --- | -| site | home | middle | banner | site_home_middle_banner | -| msite | product | top-shelf | product | msite_product_top-shelf_product | -| app | search | top-shelf | product | app_search_top-shelf_product | -| app | search | top-shelf | banner | app_search_top-shelf_banner | -| site | category | bottom-shelf | banner | site_category_bottom-shelf_banner | -| site | product | filter-bar | product | site_product_filter-bar_product | - -#### IAB Standard Image Sizes - -For banner-type ads, it is important to use images in the standard formats defined by the IAB (Interactive Advertising Bureau). This ensures compatibility and a better visual experience across different sites and devices. - -**Main Formats:** - -* **Medium Rectangle:** 300x250 pixels -* **Leaderboard:** 728x90 pixels -* **Wide Skyscraper:** 160x600 pixels -* **Mobile Leaderboard:** 320x50 pixels -* **Billboard:** 970x250 pixels -* **Half Page:** 300x600 pixels - -#### Video Size Options - -For video ad requests, you should specify the size parameter to filter by video resolution. The available options are: - -* **1080p** (1920x1080 pixels) - Recommended only for full-screen videos -* **720p** (1280x720 pixels) - Recommended only for full-screen videos -* **480p** (854x480 pixels) -* **360p** (640x360 pixels) -* **320p** (568x320 pixels) - Recommended for mobile devices - -**Important:** When requesting video ads, use only the resolution identifier (e.g., `"720p"`) in the size parameter, not the full dimensions. For example, to filter by 1280x720 resolution, use `"size": "720p"` in your ad request. - -### Ad Targeting - -Target ads to specific audiences to increase relevance. - -#### **Real-Time Targeting** -Send demographic or audience data directly in the body of the **ad query**, in the `segmentation` field. - -The `segmentation` field is an array of objects, where each object contains: -- `key`: The type of segmentation (e.g., "STATE", "CITY", "GENDER") -- `values`: Array of values for the segmentation - -**Segmentation Example:** - -```json -[ - { - "key": "STATE", - "values": [ - "CA" - ] - }, - { - "key": "CITY", - "values": [ - "San Francisco" - ] - } -] -``` - -**Available Segmentation Types:** - -| Key | Description | Example Values | -| :--- | :--- | :--- | -| `STATE` | User's state | "CA", "NY", "TX" | -| `CITY` | User's city | "San Francisco", "New York" | -| `GENDER` | User's gender | "M", "F" | -| `AGE` | User's age | "22", "35" | -| `AUDIENCES` | Custom audience | "high_value_customers", "cart_abandoners" | -| `NBO_CATEGORIES` | Indicates the possible categories that the user intends to buy | "Electronics", "Books" | - -### Response Codes and Errors - -- **200 OK:** Query processed successfully (returns JSON per placement). -- **422 Unprocessable Entity:** Field validation error (JSON Schema/Ajv-like format). -- **400 Bad Request / 404 Not Found:** Invalid request or resource not found. -- **429 Too Many Requests:** Rate limit exceeded. -- **5xx:** Internal errors. - -Example 422 (partial): -```json -[ - { - "instancePath": "/context", - "keyword": "enum", - "message": "must be equal to one of the allowed values", - "params": {"allowedValues": ["home","category","search","product_page","brand_page","digital_signage"]}, - "schemaPath": "#/properties/context/enum" - } -] -``` +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/5.5.1-placement-naming.md b/en/docs/5.5.1-placement-naming.md index c7b85e4..96097a4 100644 --- a/en/docs/5.5.1-placement-naming.md +++ b/en/docs/5.5.1-placement-naming.md @@ -1,33 +1,8 @@ # 5.5.1. Placement Naming Recommendations -Using clear, consistent placement names is essential to correctly measure the performance of each ad area on your site/app, make reporting easier, and speed up troubleshooting. - -Recommended naming pattern: - -``` -{channel}_{context}_{position}_{type} -``` - -Where: -- channel: access channel, e.g., site, msite (mobile site), app -- context: page/navigation context, e.g., home, category, search, product, brand_page, digital_signage -- position: block location on the page, e.g., top-vitrine, middle, bottom-vitrine, filter-bar -- type: creative type, e.g., product, banner, sponsored_brand - -Best practices: -- Use lowercase and no spaces (use hyphen for compounds, e.g., top-vitrine). -- Avoid obscure abbreviations; keep consistency across pages and channels. -- The name should be stable over time (do not include dates, campaign names, etc.). - -Examples: - -| channel | context | position | type | example | -| --- | --- | --- | --- | --- | -| site | home | middle | banner | site_home_middle_banner | -| msite | product | top-vitrine | product | msite_product_top-vitrine_product | -| app | search | top-vitrine | product | app_search_top-vitrine_product | -| app | search | top-vitrine | banner | app_search_top-vitrine_banner | -| site | category | bottom-vitrine | banner | site_category_bottom-vitrine_banner | -| site | product | filter-bar | product | site_product_filter-bar_product | - -Note: Use the same channel and context values you send in Ad Query (5.5) to keep traceability between requests and reports. \ No newline at end of file +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/5.6-events.md b/en/docs/5.6-events.md index ca2a864..f616e35 100644 --- a/en/docs/5.6-events.md +++ b/en/docs/5.6-events.md @@ -1,365 +1,8 @@ ## 5.6. Events -Event notification is **crucial** for attribution and measurement. - -#### Best Practices - -* **HTTP Persistence:** Use persistent HTTP connections (`Connection: keep-alive` in the header) to optimize performance. -* **Timeout (ad query):** For ad query calls (see section 5.5), implement a 500–600 ms timeout to avoid harming the user experience. - -#### **User and Session Identification** - -* **`session_id`:** Persistent visitor identifier. Required in all events. Must remain consistent during browsing and across sessions within the conversion window (≥ 14 days). The `session_id` should be unique per user and ideally not expire during this period. For mobile applications, the device ID should be sent as the session_id (GAID on Android and IDFA on iOS), so that the session is maintained indefinitely. -* **`user_id`:** Unique customer ID on the platform, consistent across channels. **Required in conversion**. **Optional (recommended)** for impression, view, and click. The `user_id` must be the same across app, website, and physical store. - -After identifying the user and the session, follow these guidelines when firing events: - -* **Impression (`impression_url`):** Fire the event as soon as you decide to display the Ads returned by the ad server, even if the Ad ultimately is not shown to the user (e.g., due to layout changes or blocking). -* **View (`view_url`):** Fire the event when at least 50% of the Ad stays within the user's viewport for a continuous 1 second. -* **Click (`click_url`):** Fire the event every time the user clicks the Ad. - -There is no need to persist event state across page loads, but make sure each event is sent only once for the same Ad and context. - -#### **Impression, View, and Click Notification** - -Send a `POST` request to the respective event URL (`impression_url`, `view_url`, `click_url`) provided in the ad query, with a JSON body containing `session_id` (**required**) and `user_id` (**when available**). - -* **When to send:** `impression_url` when the Ad is rendered; `view_url` when the Ad is visible (if you measure viewability); `click_url` on user click. -* **Event URLs:** always use the event URLs returned in the ad query; do not derive them manually. -* **Content-Type:** All requests must include the `Content-Type: application/json` header. -* **Required Method (Browser):** It is **mandatory** to use `navigator.sendBeacon()` to ensure asynchronous sending without blocking navigation and prevent loss of events when the user navigates to another page or closes the browser. -* **Success Response:** `HTTP 202 Accepted`. - -See browser event sending examples in `examples/EVENTS_IMPRESSIONS_VIEWS_CLICKS_BROWSER.md`. - -**Example of sending an event using Beacon API:** - -```javascript -// Function to send impression event -function sendImpressionEvent(impressionUrl, userId, sessionId) { - // Event data - const eventData = { - user_id: userId, - session_id: sessionId - }; - - // Check if browser supports Beacon API - if (navigator.sendBeacon) { - // Convert data to JSON - const blob = new Blob([JSON.stringify(eventData)], {type: 'application/json'}); - - // Send event asynchronously - const success = navigator.sendBeacon(impressionUrl, blob); - - if (!success) { - console.error('Failed to send event via Beacon API'); - // Implement fallback if needed - } - } else { - // Fallback for browsers that don't support Beacon API - const xhr = new XMLHttpRequest(); - xhr.open('POST', impressionUrl, true); // true for asynchronous - xhr.setRequestHeader('Content-Type', 'application/json'); - xhr.send(JSON.stringify(eventData)); - } -} - -// Example usage -sendImpressionEvent( - 'https://events.newtail-media.newtail.com.br/v1/beacon/impression/123456', - 'user-123', - 'session-456' -); -``` - -> **Important:** Using the Beacon API is mandatory to ensure that events are sent even when the user navigates to another page or closes the browser. This prevents loss of events and ensures more accurate measurement. - -#### **Conversion Notification** - -When a purchase is completed, send the order data. - -* **Endpoint:** `POST https://events.newtail-media.newtail.com.br/v1/beacon/conversion` -* **Content-Type:** All requests must include the `Content-Type: application/json` header. -* **Request Body:** The object must contain the order data. The item price should not be multiplied by the quantity. - -See conversion examples in `examples/EVENTS_CONVERSION_BROWSER.md` (Browser) and `examples/EVENTS_CONVERSION_CURL.md` (cURL). - -| Order Field | Description | Type | Required? | -| :--- | :--- | :--- | :--- | -| `publisher_id` | Publisher ID. | String | Yes | -| `user_id` | ID of the user who made the purchase. | String | Yes | -| `session_id` | Session ID of the purchase. | String | Yes | -| `order_id` | Order ID. | String | Yes | -| `created_at` | Order date/time (ISO 8601 in UTC). | String | Yes | -| `items` | List of order items. | Array[Item] | Yes | -| `channel` | Sales channel (e.g., ecommerce, app, physical store). | String | Yes | -| `brand` | Brand/site where the sale occurred (required when there is more than one site). | String | No/Yes | -| `gender` | Indicates the customer's gender. F: for female, M: for male, O: for others, null: for unidentified. | String | No (Recommended) | -| `uf` | Indicates the state of the order purchase. | String | No (Recommended) | -| `city` | Indicates the city where the customer made the purchase. | String | No (Recommended) | -| `is_company` | Indicates if the sale was made to a company or individual. | Boolean | No (Recommended) | -| `email_hashed` | User's email in hash format (SHA256). | String | Yes | -| `phone_hashed`| User's phone in hash (SHA256). | String | No (Recommended) | -| `social_id_hashed`| User's Tax ID (CPF/CNPJ) in hash (SHA256). | String | No (Recommended) | -| `first_name_hashed` | User's First Name (hashed). | String | No (Recommended) | -| `last_name_hashed` | User's Last Name (hashed). | String | No (Recommended) | - -> Recommended normalization for hashing: -> - `email_hashed`: lowercase and trim the email; SHA-256 hash in hexadecimal. -> - `phone_hashed`: phone in E.164 format (e.g., +15551234567), no masks; SHA-256 hash in hexadecimal. -> - `social_id_hashed`: tax ID digits only (no punctuation); SHA-256 hash in hexadecimal. -> - `first_name_hashed` / `last_name_hashed`: names normalized (trim, no double spaces); SHA-256 hash in hexadecimal. - -#### **Order Items Structure** - -##### Item Object Fields - -| Field | Description | Type | Required | -|-------|-----------|------|-----------------| -| `sku` | Unique product SKU identifier | String | **Required** | -| `quantity` | Quantity of product purchased | Double | **Required** | -| `price` | Original product price (list price) | Double | **Required** | -| `promotional_price` | Promotional product price (sale price) | Double | **Required** | -| `seller_id` | Seller identifier | String | Optional | -| `product_id` | Unique product identifier that encompasses the SKU | String | Optional | - -##### ⚠️ Important Notes - -1. **Unit values**: The `price` and `promotional_price` fields must contain the **unit** value of the product, **not** multiplied by quantity -2. **Required fields for measurement**: If `price` and `promotional_price` are not provided correctly, the conversion **cannot be measured** -3. **Monetary format**: Values must be sent as decimal numbers (e.g., 1899.00) - -#### **Usage Examples** - -##### Individual Item Example -```json -{ - "sku": "12221", - "seller_id": "1234", - "product_id": "4567", - "quantity": 1, - "price": 2000.00, - "promotional_price": 1899.00 -} -``` - -##### Complete Request Example - -```http -POST https://events.newtail-media.newtail.com.br/v1/beacon/conversion HTTP/1.1 -Accept: application/json -Content-Type: application/json -``` - -```json -{ - "channel": "ecommerce", - "publisher_id": "xxx", - "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", - "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", - "order_id": "123", - "email_hashed": "xyz", - "items": [ - { - "sku": "12221", - "seller_id": "1234", - "product_id": "4567", - "quantity": 1, - "price": 2000.00, - "promotional_price": 1899.00 - }, - { - "sku": "12222", - "seller_id": null, - "product_id": "4568", - "quantity": 2, - "price": 500.00, - "promotional_price": 400.00 - } - ], - "created_at": "2023-01-01T09:20:00Z" -} -``` - -**Note**: In the example above, observe that: -- The first item has quantity 1 with unit price of $2,000.00 -- The second item has quantity 2 with unit price of $500.00 (not $1,000.00) - -#### **API Responses** - -##### ✅ Success Response (HTTP 202) -```json -{ - "messages": [ - "conversion will be processed soon" - ] -} -``` - -##### ❌ Validation Error Response (HTTP 422) -The API returns validation errors in a JSON Schema–compatible (Ajv-like) format. - -Example error response: -```json -[ - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'user_id'", - "params": { - "missingProperty": "user_id" - }, - "schemaPath": "#/required" - }, - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'order_id'", - "params": { - "missingProperty": "order_id" - }, - "schemaPath": "#/required" - }, - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'publisher_id'", - "params": { - "missingProperty": "publisher_id" - }, - "schemaPath": "#/required" - }, - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'items'", - "params": { - "missingProperty": "items" - }, - "schemaPath": "#/required" - }, - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'created_at'", - "params": { - "missingProperty": "created_at" - }, - "schemaPath": "#/required" - } -] -``` - -#### **🎯 Product Match Rule for Conversions** - -##### Important: Product and Campaign Matching - -Conversions are **only computed** for campaigns when a **product match** occurs. This means: - -- ✅ **Conversion is measured**: When the product purchased by the user **belongs** to the campaign in which the user was impacted -- ❌ **Conversion is NOT measured**: When the purchased product **does not belong** to the campaign in which the user was impacted - -##### Practical Example: - -**Scenario 1 - With Match (Conversion Computed)** -- User viewed ad from Campaign A (products: SKU-001, SKU-002, SKU-003) -- User purchased product SKU-002 -- ✅ Conversion is attributed to Campaign A - -**Scenario 2 - Without Match (Conversion NOT Computed)** -- User viewed ad from Campaign B (products: SKU-004, SKU-005) -- User purchased product SKU-999 -- ❌ Conversion is NOT attributed to Campaign B - -#### **Code Example** - -##### JavaScript (Browser) -```javascript -const sendConversion = async (orderData) => { - const payload = { - channel: "ecommerce", - publisher_id: "xxx", - user_id: orderData.userId, - session_id: orderData.sessionId, - order_id: orderData.orderId, - email_hashed: orderData.emailHash, - items: orderData.items.map(item => ({ - sku: item.sku, - seller_id: item.sellerId || null, - product_id: item.productId || null, - quantity: item.quantity, - price: item.unitPrice, // Unit value, not multiplied - promotional_price: item.unitPromotionalPrice // Unit value, not multiplied - })), - created_at: new Date().toISOString() - }; - - try { - // Convert data to JSON - const blob = new Blob([JSON.stringify(payload)], {type: 'application/json'}); - - // Send event asynchronously using Beacon API - if (navigator.sendBeacon) { - const success = navigator.sendBeacon( - 'https://events.newtail-media.newtail.com.br/v1/beacon/conversion', - blob - ); - - if (success) { - console.log('Conversion sent successfully'); - } else { - console.error('Failed to send conversion via Beacon API'); - } - } else { - // Fallback for browsers that don't support Beacon API - const response = await fetch('https://events.newtail-media.newtail.com.br/v1/beacon/conversion', { - method: 'POST', - headers: { - 'Accept': 'application/json', - 'Content-Type': 'application/json' - }, - body: JSON.stringify(payload) - }); - - if (response.status === 202) { - console.log('Conversion sent successfully'); - } else if (response.status === 422) { - const errors = await response.json(); - console.error('Validation errors:', errors); - } - } - } catch (error) { - console.error('Error sending conversion:', error); - } -}; - -// Example usage -const order = { - userId: "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", - sessionId: "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", - orderId: "123", - emailHash: "xyz", - items: [ - { - sku: "12221", - sellerId: "1234", - productId: "4567", - quantity: 1, - unitPrice: 2000.00, - unitPromotionalPrice: 1899.00 - } - ] -}; - -sendConversion(order); -``` - -#### **Attribution and Deduplication Rules** - -* **Conversion Window:** The period after an interaction during which a sale can be attributed to the ad. - * **Click (for `product`):** 14 days. - * **View (for `display`/`video`):** 14 days. -* **Event Deduplication:** For the same user and ad, events are ignored for a period. - * **Impressions:** 1 minute. - * **Clicks:** 1 hour. - * **Conversions:** Idempotent by `order_id` (re-sending the same `order_id` within 30 days is ignored). +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/5.7-transparent-integration.md b/en/docs/5.7-transparent-integration.md index 25f5ac9..3aa1280 100644 --- a/en/docs/5.7-transparent-integration.md +++ b/en/docs/5.7-transparent-integration.md @@ -1,115 +1,8 @@ # Transparent Integration -> Note: This tool is only able to serve Banner and Video ads. - -The goal of transparent integration is to reduce friction as much as possible to start the VTEX Ads integration setup in the simplest way possible. - -## Requirements for the Proof of Concept (PoC) - -For this Proof of Concept to work, the following requirements are essential: - -1. **Catalog Integration:** A catalog integration needs to be up and running. - -2. **Script Installation:** Our script must be added to the website. - -3. **Conversion Event Trigger:** The conversion event needs to be triggered on the client side. - - -### 1\. Catalog Integration - -The catalog synchronization follows the format already defined for all integrations. - -### 2\. Script Installation - -Add the following script as early as possible in the page's `` tag or on your website/msite: - -``` - -``` - -#### Script Requirements - -For the script to work correctly, the client must inform us of the origin of two important parameters: `session_id` and `user_id`. These parameters are usually stored in cookies, `sessionStorage`, or `localStorage`. - -### 3\. Conversion Event - -The conversion event must be sent after the order is created, without the need for payment confirmation. - -The following script demonstrates how to send data to an API endpoint using the `navigator.sendBeacon` interface. The `sendBeacon` method is ideal for sending small amounts of data asynchronously without impacting the page's performance. It is particularly useful for sending analytics data before the user navigates away from the page. - -``` -/** - * This script demonstrates how to send data to an API endpoint - * using the `navigator.sendBeacon` interface. - * - * The `sendBeacon` method is designed to send small amounts of data - * asynchronously without affecting the performance of the current page - * or the load time of the next one. - * - * It is particularly useful for sending analytics data before - * a user navigates away from a page. - */ - -// 1. Define the data you want to send. -const data = { - "publisher_id": "d4dff0cb-1f21-4a96-9acf-d9426a5ed08c", - "user_id": "26119121", - "order_id": "1758035060", - "channel": "site|msite|app", - "created_at": "2025-09-16T15:04:19.794Z", - "items": [ - { - "price": 12, - "promotional_price": 10, - "quantity": 1, - "sku": "sku1" - }, - { - "price": 15, - "promotional_price": 13, - "quantity": 1, - "sku": "sku2", - "seller_id": "seller1" - }, - { - "price": 19, - "promotional_price": 17, - "quantity": 1, - "sku": "sku3", - "product_id": "prod3" - }, - { - "price": 30, - "promotional_price": 25, - "quantity": 2, - "sku": "sku4", - "product_id": "prod4", - "seller_id": "seller2" - } - ] -}; - -// 2. Convert the data object into a JSON string. -const rawData = JSON.stringify(data); - -// 3. Create a Blob from the JSON string. -// This allows us to explicitly set the Content-Type for the request. -const blob = new Blob([rawData], { type: 'application/json' }); - -// 4. Define the endpoint URL. -const url = "https://newtail-media.newtail.com.br/v1/beacon/conversion"; - -// 5. Use `navigator.sendBeacon` to send the data. -// The method returns `true` if the browser queues the request -// for delivery and `false` otherwise. -// Note that `sendBeacon` does not return a Promise, so there is no -// `.then()` or `.catch()`. Delivery is not guaranteed, but it is -// highly likely. -const success = navigator.sendBeacon(url, blob); - -if (success) { - console.log("Beacon request successfully queued!"); -} else { - console.error("Failed to queue beacon request."); -} -``` +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/6-data-export.md b/en/docs/6-data-export.md index 19fe429..ca14021 100644 --- a/en/docs/6-data-export.md +++ b/en/docs/6-data-export.md @@ -1,61 +1,8 @@ ## 6. Data Export -Data export allows you to receive detailed information about events and aggregated data systematically and periodically. The integration occurs through an S3 connection, and the data is delivered in specific formats for each type of export. - -### 6.1. Reports - -In addition to exporting via S3, it is possible to extract reports via the API. The routes return JSON by default, but can be exported as XLSX files by including the `download=true` parameter in the query. - -* `GET /report/v2/advertisers`: Advertiser information (publisher view) [[Example]](../../examples/EXPORT_ADVERTISER_DATA.md) -* `GET /report/v2/publishers`: Publisher information (advertiser view) [[Example]](../../examples/EXPORT_PUBLISHER_DATA.md) -* `GET /report/network/publishers`: Network publishers (for Network type accounts) [[Example]](../../examples/EXPORT_NETWORK_PUBLISHERS_DATA.md) -* `GET /campaign/v2`: Campaign listing report [[Example]](../../examples/EXPORT_CAMPAIGNS_LIST_DATA.md) -* `GET /campaign/:id`: Detailed campaign report [[Example]](../../examples/EXPORT_CAMPAIGN_DATA.md) -* `GET /report/advertisers/campaigns-detailed`: Detailed mixed campaign report for advertiser accounts, including subpublisher information for network campaigns [[Example]](../../examples/EXPORT_ADVERTISER_CAMPAIGNS_DETAILED_DATA.md) -* `GET /report/advertisers/ads-detailed`: Detailed ad report for advertiser accounts, including subpublisher breakdown for network campaigns [[Example]](../../examples/EXPORT_ADVERTISER_ADS_DETAILED_DATA.md) -* `GET /ad/results/v2`: Performance report for individual ads [[Example]](../../examples/EXPORT_ADS_DATA.md) - -### 6.2. Data Export - -The integration will always occur using an S3 (or compatible) connection that must be provided by the data recipient. The credentials must be passed to the Newtail team securely. - -The integration is compatible with: - -* **AWS S3:** `Access Key Id` and `Access Key Secret`. -* **Google Cloud Storage:** `Service Account`. -* **Azure Blob Storage**. - -#### Event Export - -Event export sends raw data of user interactions. - -* **Format:** `PARQUET` with `Snappy` compression. -* **Frequency:** Daily (D-1 data). -* **Folder Structure:** `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.snappy.parquet` -* **De-duplication:** It is guaranteed that all events will be sent, but not that they will be sent only once. Therefore, events must always be de-duplicated using the `event_id` or the combination of `order_id` and `product_sku` for conversion items. - -##### Event Types - -* **Impressions, Views, and Clicks:** - * **Fields:** `event_id` (de-duplication key), `session_id`, `user_id`, `ad_id`, `campaign_id`, `request_id`, `ad_type`, `placement_name`, `context`, `created_at`, `site`. -* **Conversions:** - * **Fields:** `event_id`, `session_id`, `user_id`, `order_id` (de-duplication key), `channel`, `placed_at`, `site`. -* **Conversion Items:** - * **Fields:** `event_id`, `session_id`, `user_id`, `order_id` (de-duplication key), `product_sku` (de-duplication key), `ad_id`, `campaign_id`, `request_id`, `ad_size`, `ad_type`, `placement_name`, `context`, `event_created_at`, `price`, `promotional_price`, `quantity`, `total_value`. - -#### Aggregated Data Export - -Aggregated data export sends consolidated reports. - -* **Format:** `CSV` with `UTF-8` encoding, comma-separated, and numbers in American format (decimal point). -* **Frequency:** Daily (D-1 data, with the publisher's timezone). -* **Folder Structure:** `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.csv` - -##### Report Types - -* **Advertisers:** - * **Fields:** `advertiser`, `advertiser_id`, `seller_id`, `wallet_balance`, `daily_budget`, `currency`. -* **Campaigns:** - * **Fields:** `day`, `name`, `campaign_id`, `campaign_type`, `campaign_status`, `impressions_total`, `clicks_total`, `ctr`, `ad_revenue`, `conversions_total`, `conversion_rate`, `sales_revenue`, `start_date`, `end_date`, `advertiser_id`. -* **Ads:** - * **Fields:** `day`, `ad_id`, `campaign_id`, `ad_status`, `ad_media_url`, `cpm`, `cpc`, `impressions_total`, `clicks_total`, `ctr`, `ad_revenue`, `conversions_total`, `conversion_rate`, `sales_revenue`, `product_sku`. +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/7-script-agent.md b/en/docs/7-script-agent.md index 0f22eab..d61832d 100644 --- a/en/docs/7-script-agent.md +++ b/en/docs/7-script-agent.md @@ -1,77 +1,8 @@ # 7. VTEX Ads - Script Agent -## 7.1. Objective - -This document details the procedure for installing the **VTEX Ads** tracking script on all pages of a website (except for checkout pages) using Google Tag Manager (GTM). The correct implementation of this script is essential for collecting browsing data that allows for the optimization and targeting of Retail Media campaigns. - -## 7.2. Data Collected - -The VTEX Ads script was developed to exclusively collect non-sensitive browsing data, with the aim of personalizing the user experience and optimizing campaigns. - -**Data Collected:** - -- **For off-site campaigns:** - - `session_id`: Anonymous identifier for the browsing session. - - `ad_id`: Identifier of the ad that originated the traffic. -- **For audience segmentation (Page View):** - - `session_id`: Anonymous identifier for the browsing session. - - **Page Information:** URL, title (``), and description (`<meta name="description">`). - -> **Important:** The script **does not collect** any personally identifiable information (PII), such as name, email, CPF, phone number, address, or payment data. Data collection complies with major data protection laws. - -## 7.3. Script Details - -The script should be loaded asynchronously so as not to impact the page load time. - -- **Script URL:** `https://cdn.newtail.com.br/retail-media/scripts/vtexrma-agent.1.0.0.js` - -## 7.4. Step-by-Step Guide for Implementation via Google Tag Manager (GTM) - -To ensure the script runs as early as possible during page load, we recommend using the **Initialization** trigger. - -### Step 7.4.1: Create the Custom HTML Tag - -1. Access your GTM container and go to the **"Tags"** section. -2. Click **"New"** to create a new tag. -3. Give the tag a clear name, for example: **"Custom HTML - VTEX Ads Agent"**. -4. Click on **"Tag Configuration"** and select the **"Custom HTML"** tag type. -5. In the HTML field, insert the following code: - ```html - <script type="text/javascript" async src="https://cdn.newtail.com.br/retail-media/scripts/vtexrma-agent.1.0.0.js"></script> - ``` - -### Step 7.4.2: Configure the Main Trigger - -1. Below the tag configuration, click on **"Triggering"**. -2. Select the **"Initialization - All Pages"** trigger. This trigger ensures that the script is fired before most other tags on all pages. - -### Step 7.4.3: Create and Add a Trigger Exception - -To prevent the script from running on checkout pages, we will create an exception. - -1. Still in the tag configuration, in the **"Triggering"** section, click **"Add Exception"**. -2. Click the **"+"** icon in the upper right corner to create a new exception trigger. -3. Give the trigger a name, for example: **"Trigger Exception - Checkout Pages"**. -4. Click on **"Trigger Configuration"** and choose the **"Initialization"** type. -5. Under **"This trigger fires on"**, select **"Some Initializations"**. -6. Configure the condition to identify the checkout pages. The condition may vary depending on your site's URL structure. Common examples: - - `Page Path` | `contains` | `/checkout` - - `Page URL` | `matches RegEx (ignore case)` | `/checkout/|/orderPlaced/` -7. Save the new exception trigger. It will be automatically added to your tag. - -### Step 7.4.4: Save and Publish - -1. Save the newly created tag. -2. Submit and publish the changes in your GTM container. - -## 7.5. User Session Configuration - -For the VTEX Ads platform to correctly correlate user interactions, it is necessary to inform which session identifier is used by your e-commerce. - -**Action Required:** - -The team responsible for the e-commerce must inform the VTEX Ads team of the **name of the attribute in the `cookie` or `sessionStorage`** that stores the user's session ID. - -- **Example:** If the session ID is stored in a cookie named `vtex_session`, this information must be passed on. - -This configuration allows the script to read the correct identifier and associate it with browsing events. +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/8-credit-transfer.md b/en/docs/8-credit-transfer.md index ca9aa4c..448af60 100644 --- a/en/docs/8-credit-transfer.md +++ b/en/docs/8-credit-transfer.md @@ -1,73 +1,8 @@ ## 8. Credit Transfer -Credit transfer is the flow that allows the marketplace to transfer advertising credits to its sellers. This documentation details the endpoints that the marketplace must implement and the webhook it must consume to integrate with VTEXAds. - -<div align="center"> - <img src="../../diagrams/images/en/credit-transfer.png" alt="Credit Transfer Flow" /> -</div> - - * **Endpoints to be implemented by the Marketplace (Authentication: Basic Auth):** - 1. **Check Balance (`GET /checking_account`)** - * **Objective:** Check the seller's available balance. - * **Query Parameters:** `seller_id`, `publisher_id` (optional, only applies to cases where an entity manages multiple publishers). - * **Success Response (200 OK):** - ```json - { "total": "1111.00" } - ``` - - 2. **Request Transfer (`POST /checking_account/transfer`)** - * **Objective:** Request the transfer of a specific amount. - * **Request Body:** - ```json - { - "amount": "10.00", - "seller_id": "SELLER_ID", - "publisher_id": "PUBLISHER_ID", - "transfer_identity_id": "uuid" - } - ``` - * **Responses:** - - **Synchronous (Success):** `201 Created` - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "success" - } - ``` - - **Synchronous (Failure):** `400 Bad Request` - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "failure", - "message": "Reason for refusal" - } - ``` - - **Asynchronous:** `202 Accepted` - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "processing" - } - ``` - - * **Webhook to be consumed by the Marketplace:** - * **Objective:** Notify VTEXAds about the final status of the transfer. - * **Endpoint:** `POST https://api-retail-media.newtail.com.br/webhook/marketplace/transfers/:publisher_id` - * **Authentication:** `x-api-key` and `x-secret-key`. - * **Payload:** - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "success" - } - ``` - or - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "failure", - "message": "Problem description" - } - ``` - * **Retry Logic:** In case of a webhook call failure, the marketplace must retry. - * **Expected Response:** `204 No Content` \ No newline at end of file +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/en/docs/9-sso.md b/en/docs/9-sso.md index 4c31f94..d564653 100644 --- a/en/docs/9-sso.md +++ b/en/docs/9-sso.md @@ -1,32 +1,8 @@ ## 8. SSO (Single Sign-On) -API for unified seller login. When calling this API, Newtail generates a redirect URL that allows the user to access the Newtail platform without needing to log in again. - -* **Endpoint:** `POST /sso/marketplace` -* **Request Body:** - -| Field | Description | Type | Required? | -| :--- | :--- | :--- | :--- | -| `sso_token` | User identification token generated by the marketplace. | String | Yes | -| `email` | User's (seller's) email. | String | Yes | -| `user_id` | Unique user ID in the marketplace. | String | Yes | -| `name` | User's name. | String | Yes | -| `marketplace_name` | Name of the marketplace. | String | Yes | - -* **Request Example:** - ```json - { - "sso_token": "sso-token-12345", - "email": "seller@example.com", - "user_id": "seller123", - "name": "Seller Name", - "marketplace_name": "My Marketplace" - } - ``` - -* **Success Response:** `HTTP 200 OK` with the redirect URL. - ```json - { - "redirect_url": "https://app.ads.vtex.com/sso/auth?token=GENERATED_TOKEN" - } - ``` \ No newline at end of file +> [!IMPORTANT] +> **This page has moved.** +> +> The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Please update your bookmarks. This page is no longer maintained. diff --git a/es/docs/1-resumen.md b/es/docs/1-resumen.md index 5230b2d..51dad11 100644 --- a/es/docs/1-resumen.md +++ b/es/docs/1-resumen.md @@ -1,19 +1,8 @@ ## 1. Resumen -Esta documentación detalla la integración con la **Retail Media API**, el punto central de conexión entre la solución de VTEX Ads y la plataforma del minorista (publisher). La solución fue desarrollada bajo el concepto **API-first**, garantizando flexibilidad total para que los minoristas integren y exhiban anuncios en cualquier canal digital: e-commerce, marketplace, aplicación o incluso en tótems y pantallas físicas (Digital Signage). - -Nuestra arquitectura es **cookie-less**, lo que significa que no dependemos de cookies de terceros. La identificación y segmentación se basan en identificadores propios (`user_id`, `session_id`) y datos primarios (first-party data), garantizando una solución robusta, en conformidad con las nuevas políticas de privacidad y preparada para el futuro del retail digital. - -A través de esta API REST, su plataforma podrá: -* Sincronizar el catálogo de productos e inventario. -* Solicitar anuncios relevantes en tiempo real para el contexto de navegación del usuario. -* Enviar eventos de interacción (impresión, visualización, clic, conversión) para la medición de performance. - -Adoptamos el principio de **Extensibilidad Progresiva** para garantizar la máxima estabilidad y seguridad en las operaciones de nuestros socios. - -Nuestra política formal de compatibilidad garantiza: -* **Evolución sin rupturas:** todas las actualizaciones de API se realizan de forma incremental. Se agregan nuevos campos, funcionalidades y opciones sin alterar ni eliminar el comportamiento de los contratos existentes. -* **Preservación de integraciones:** las integraciones actuales permanecen plenamente operativas tras nuevos lanzamientos, reduciendo el retrabajo técnico recurrente. -* **Continuidad del negocio:** al preservar la integridad de los contratos anteriores, evitamos interrupciones operativas y permitimos adoptar nuevas capacidades al ritmo de su negocio. - -Este enfoque refleja nuestro compromiso con una plataforma robusta y escalable, donde la innovación tecnológica y la previsibilidad operativa evolucionan juntas. +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/10-ventana-atribucion.md b/es/docs/10-ventana-atribucion.md index e5744db..47f5ade 100644 --- a/es/docs/10-ventana-atribucion.md +++ b/es/docs/10-ventana-atribucion.md @@ -1,97 +1,8 @@ # Ventana de Atribución y Modelos de Conversión -Este documento detalla las reglas, modelos y plazos que rigen la atribución de conversiones (ventas) y la facturación de las campañas publicitarias en nuestra plataforma. - -## 1. ¿Qué es la Ventana de Atribución? - -La "ventana de atribución" (o ventana de conversión) es el período de tiempo _después_ de que un usuario interactúa con un anuncio (ya sea haciendo clic o visualizándolo) durante el cual una conversión puede ser acreditada a ese anuncio. - -- **Ventana Predeterminada:** 14 días. -- **Flexibilidad:** Este período es el predeterminado para todas las campañas, pero puede personalizarse según las necesidades estratégicas. - -**Ejemplo:** Si un usuario hace clic en un anuncio hoy, cualquier compra que realice del producto asociado en los próximos 14 días podrá atribuirse a ese anuncio. - -## 2. Medición (Atribución) vs. Facturación - -Es fundamental diferenciar el evento que _mide_ la atribución (lo que usamos para contar una conversión) del evento que _genera la facturación_ (lo que cobramos al anunciante). - -### 2.1. Eventos de Medición (Atribución) - -Esto define _cómo_ sabemos que un anuncio "funcionó" para generar una venta: - -- **Campañas de Producto (Product Ads):** - - **Evento:** Clic. - - **Lógica:** La conversión solo se cuenta si el usuario _hizo clic_ en el anuncio antes de comprar. - -- **Otras Campañas (Banner, Video y Sponsored Brands):** - - **Evento:** Visualización (Impresión). - - **Lógica:** La conversión puede contarse incluso si el usuario solo _vio_ el anuncio (y no necesariamente hizo clic), siguiendo las reglas de jerarquía (ver sección 3). - -### 2.2. Modelos de Facturación - -Esto define _por qué_ paga el anunciante: - -- **CPC (Costo Por Clic):** El anunciante paga cada vez que un usuario hace clic en el anuncio. - - _Usado en:_ Campañas de Producto, Sponsored Brands. - -- **CPM (Costo Por Mil Impresiones):** El anunciante paga un valor fijo por cada 1.000 veces que se muestra el anuncio. - - _Usado en:_ Banner, Video, Sponsored Brands. - -- **Modelo Híbrido (CPC + CPM):** - - Las campañas de **Sponsored Brands** son únicas, ya que cobran _tanto_ por los clics (CPC) como por las impresiones (CPM) generadas. - -#### Ejemplo de Cálculo de Facturación (CPM) - -El CPM define el valor para 1.000 impresiones, pero el cargo real es proporcional a cada impresión individual. - -- **Escenario:** Una campaña de video tiene un CPM de **$10,00**. -- **Resultado:** La campaña genera **10 impresiones**. - -**Cálculo:** - -1. **Costo por impresión individual:** $10,00 (CPM) / 1.000 (impresiones) = **$0,01 por impresión**. -2. **Costo Total:** 10 (impresiones generadas) * $0,01 (costo por impresión) = **$0,10**. - -El costo total de esta campaña sería de **diez centavos**. - -## 3. Reglas de Atribución (La Jerarquía de Decisión) - -Cuando un usuario interactúa con múltiples anuncios antes de comprar, un modelo de atribución decide qué campaña recibirá el crédito por la venta. - -**Principio Fundamental:** La atribución es exclusiva. Un pedido vendido **nunca** se atribuye a dos campañas distintas; el crédito siempre se otorga a una sola campaña. - -La decisión sigue este orden de prioridad: - -1. **Prioridad 1: Campañas Offsite** - - Si existe una campaña _offsite_ activa (trayendo tráfico externo al sitio) y fue el último punto de contacto del usuario, tendrá preferencia total en la atribución de la venta. - -2. **Prioridad 2: Último Clic (Last Click)** - - En ausencia de un clic offsite reciente, el sistema busca el _último anuncio_ (dentro de la plataforma) en el que el usuario _hizo clic_ dentro de la ventana de 14 días. - -3. **Prioridad 3: Última Visualización (Last View)** - - Si el usuario no hizo clic en ningún anuncio durante el período, el sistema atribuye la venta al _último anuncio_ que _visualizó_ (siempre que sea un tipo de campaña que mida por visualización, como Banner o Video). - -**Regla de Tiempo:** Para que una conversión sea válida, el evento de interacción (clic o visualización) debe haber ocurrido _antes_ de que se finalizara el pedido. - -## 4. Mapeo de Productos en la Atribución - -Una campaña solo puede recibir atribución por productos que están _explícitamente vinculados a ella_. - -### 4.1. Campañas de Producto (Atribución 1:1) - -- **Cómo funciona:** Cada anuncio (AD) dentro de la campaña representa un producto específico. -- **Lógica:** La atribución es directa y 1 a 1. El clic en el anuncio del "Producto A" solo puede generar conversión para el "Producto A". - -### 4.2. Otras Campañas (Banner, Video, etc.) (Atribución N:1) - -- **Cómo funciona:** Estas campañas tienen una _lista_ de productos asociados (SKUs). -- **Lógica:** La interacción (clic o visualización) con un solo creativo (banner o video) puede generar atribución para _cualquiera_ de los productos contenidos en esa lista de la campaña. - -**Observación sobre Creativos:** Dentro de una campaña (ej: Banner), cada creativo (ej: el "Banner A" y el "Banner B") mide su información de forma independiente. Esto permite analizar el rendimiento individual de cada pieza publicitaria. - -## 5. Latencia de Datos (Retraso en la Atribución) - -Es importante notar que existe un retraso natural entre el momento en que el cliente crea el pedido y el momento en que esa venta es asociada (atribuida) a la campaña correcta en los informes. - -- **Integración vía API:** Retraso de aproximadamente **30 minutos**. -- **Plataforma VTEX:** Retraso de hasta **2 horas**. +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/2-glosario.md b/es/docs/2-glosario.md index 2cd744d..0717406 100644 --- a/es/docs/2-glosario.md +++ b/es/docs/2-glosario.md @@ -1,16 +1,8 @@ ## 2. Glosario -| Término | Descripción | -| :--- | :--- | -| **Advertiser (Anunciante)** | Empresas, sellers o individuos que promocionan sus productos, servicios o ideas a través de campañas. | -| **Publisher (Minorista)** | La entidad que posee y opera la plataforma digital (sitio, app) y pone a disposición los espacios para la exhibición de anuncios. | -| **Campaña** | Acción creada por un anunciante para promocionar productos y generar conversiones (ventas). | -| **Impresión** | Se contabiliza cada vez que un anuncio se exhibe en la pantalla del usuario. | -| **Visualización (View)**| Se contabiliza cuando una impresión se vuelve visible en la pantalla del usuario por un tiempo determinado. | -| **Clic** | Interacción del usuario al hacer clic en un anuncio para ser dirigido a la página de destino. | -| **Conversión** | Acción de valor generada por un anuncio, típicamente una venta. | -| **Ingresos por Anuncios** | Valor obtenido por los minoristas al monetizar sus espacios publicitarios. | -| **Ingresos por Ventas** | Valor total obtenido por una empresa a partir de las ventas de productos o servicios. | -| **CTR (Click-Through Rate)** | Tasa de Clics. Fórmula: `(Clics / Impresiones) * 100`. Mide el atractivo de un anuncio. | -| **ROAS (Return on Ad Spend)**| Retorno de la Inversión Publicitaria. Fórmula: `Ingresos Generados por Anuncios / Costo de la Publicidad`. | -| **Tasa de Conversión** | Porcentaje de conversiones en relación con el total de clics o visitas. | +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/3-autenticacion.md b/es/docs/3-autenticacion.md index 12465c4..3df2c72 100644 --- a/es/docs/3-autenticacion.md +++ b/es/docs/3-autenticacion.md @@ -1,10 +1,8 @@ ## 3. Autenticación -La autenticación es necesaria para el envío de catálogos, el consumo de informes y la gestión. Las demás llamadas, como consulta de anuncios y notificación de eventos, son públicas y no requieren autenticación. - -Para los endpoints protegidos, las credenciales deben ser enviadas vía encabezado (header) HTTP. Solicite sus credenciales al gerente de cuenta. - -| Atributo | Descripción | -| :--- | :--- | -| `x-app-id` | ID exclusivo de su aplicación para la integración. | -| `x-api-key` | Clave de API asociada a su aplicación. | +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/4-seguridad-de-datos.md b/es/docs/4-seguridad-de-datos.md index 6584eed..1fac336 100644 --- a/es/docs/4-seguridad-de-datos.md +++ b/es/docs/4-seguridad-de-datos.md @@ -1,27 +1,8 @@ # 4. Seguridad de Datos -La seguridad de los datos es un pilar fundamental de nuestra plataforma. Desde el principio, nuestra arquitectura fue diseñada para garantizar que no se recopile información sensible y que los datos de los usuarios permanezcan siempre protegidos y no identificables. - -## Datos No Identificables - -No recopilamos datos sensibles de los usuarios, como nombre, correo electrónico o documentos. La información que recibimos, como correos electrónicos o números de identificación (PII - *Personally Identifiable Information*), ya llega a nuestra plataforma con un hash criptográfico irreversible. - -Esto significa que el dato original nunca viaja o se almacena en nuestros sistemas. El resultado es un identificador anónimo que nos permite agrupar comportamientos y audiencias sin saber nunca quién es el usuario real. - -**¿Por qué es esto seguro?** - -* **Irreversibilidad:** El proceso de hashing es de una sola vía. Incluso si alguien tuviera acceso al hash, no podría descubrir el dato original. -* **Anonimato:** Como no almacenamos el dato original, no tenemos forma de identificar al usuario. A todos los efectos, los datos son anónimos. - -## Cifrado en Tránsito y en Reposo - -Todos los datos, ya sean identificadores anónimos o información sobre campañas y anuncios, se tratan con los más altos estándares de seguridad: - -* **Cifrado en Tránsito:** Toda la comunicación entre nuestros sistemas y con socios se realiza utilizando protocolos seguros como TLS 1.2+, garantizando que los datos no puedan ser interceptados durante la transferencia. -* **Cifrado en Reposo:** Los datos almacenados en nuestras bases de datos y sistemas de archivos están cifrados. Utilizamos soluciones robustas y reconocidas en el mercado, como **Amazon RDS**, **Amazon S3**, **Amazon Redshift** y **Snowflake**, que aplican cifrado AES-256, uno de los algoritmos más seguros que existen. - -## Acceso Restringido - -El acceso a los datos está rigurosamente controlado y limitado a un grupo selecto de ingenieros y analistas senior. Cada acceso es auditado y monitoreado, y los permisos se conceden con base en el principio del menor privilegio, es decir, cada persona tiene acceso solo a lo estrictamente necesario para realizar su trabajo. - -Esta combinación de datos no identificables, cifrado de extremo a extremo y control de acceso riguroso garantiza que su información y la de sus clientes estén siempre seguras. +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/5-integracion-de-anuncios.md b/es/docs/5-integracion-de-anuncios.md index 509e309..f83014a 100644 --- a/es/docs/5-integracion-de-anuncios.md +++ b/es/docs/5-integracion-de-anuncios.md @@ -1,24 +1,8 @@ # 5. Integración de Anuncios -Esta sección proporciona información detallada sobre cómo integrarse con la plataforma de VTEX Ads para mostrar anuncios en su sitio web. - -## 5.0 Visión General del Flujo de Integración - -<img src="../../diagrams/images/es/integration-end-to-end.png" alt="Flujo completo de integración con VTEX Ads" /> - -El flujo de integración completo se divide en cuatro fases principales que se retroalimentan continuamente: - -1. **Preparación y Onboarding:** Alinee el alcance y cronograma con el equipo de VTEX Ads, reciba las credenciales de API y valide el acceso a ambientes y webhooks. -2. **Sincronización de Datos Operacionales:** Cargue el catálogo (productos e inventario) y, opcionalmente, audiencias. Este paso garantiza que solo los productos disponibles y segmentaciones válidas estén aptos para aparecer. -3. **Entrega de Anuncios:** Estructure los placements del sitio, configure convenciones de nombre y consulte anuncios en tiempo real para cada contexto (home, búsqueda, categoría, PDP, etc.), mostrando el sello "Patrocinado". -4. **Medición y Optimización:** Dispare los eventos de impresión, visualización, clic y conversión usando `navigator.sendBeacon()`, monitoree las métricas de desempeño y ajuste pujas, segmentaciones y posicionamientos de acuerdo con los resultados. - -Las siguientes secciones detallan cómo ejecutar cada una de estas fases, con ejemplos de solicitudes y mejores prácticas específicas. - -- [5.1. Integración vía API](./5.1-integracion-via-api.md): Para una integración más personalizada, utilice nuestra API REST para gestionar todo el ciclo de vida de los anuncios. -- [5.2. Integración VTEX](./5.2-integracion-vtex.md): Si su tienda está en la plataforma VTEX, utilice nuestra aplicación VTEX IO para simplificar el proceso. -- [5.3. Sincronización de Catálogo](./5.3-sincronizacion-de-catalogo.md): Mantenga su catálogo de productos e inventario sincronizado con VTEX Ads. -- [5.4. Integración de Audiencias](./5.4-integracion-de-audiencias.md): Envíe datos de audiencia para mejorar la segmentación y la relevancia de los anuncios. -- [5.5. Consulta de Anuncios](./5.5-consulta-de-anuncios.md): Solicite a la API los anuncios que deben ser exhibidos en diferentes páginas y contextos. -- [5.5.1. Recomendación de Nombres de Placements](./5.5.1-recomendacion-de-nombres-de-placements.md): Estándar recomendado de nombres de placements para una medición precisa. -- [5.6. Eventos](./5.6-eventos.md): Notifique a la API sobre todas las interacciones del usuario con los anuncios y las conversiones. +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/5.1-integracion-via-api.md b/es/docs/5.1-integracion-via-api.md index f10e2df..475e00f 100644 --- a/es/docs/5.1-integracion-via-api.md +++ b/es/docs/5.1-integracion-via-api.md @@ -1,22 +1,8 @@ # 5.1 Integración vía API -La integración se fundamenta en tres pilares que garantizan el funcionamiento de la solución. - -### Pilares de la Integración - -1. **[Sincronización de Catálogo](./5.2-sincronizacion-de-catalogo.md):** Mantener a VTEX Ads sincronizado con su catálogo de productos e inventario (precio y stock). Esencial para anuncios de producto. -2. **[Consulta de Anuncios](./5.3-consulta-de-anuncios.md):** Su plataforma solicita a la API los anuncios que deben ser exhibidos en diferentes páginas y contextos. -3. **[Eventos](./5.4-eventos.md):** Su plataforma notifica a la API sobre todas las interacciones del usuario con los anuncios y, crucialmente, sobre las conversiones (ventas). - -### Tipos de Anuncios - -| Tipo de Anuncio | API Type | Descripción | -| :--- | :--- |:------------------------------------------------| -| **Sponsored Products** | `product` | Anuncios de productos individuales. | -| **Display** | `banner` | Anuncios visuales (imagen estática o video). | -| **Sponsored Brands** | `sponsored_brand` | Anuncios de marca con título, logo y productos. (imagen estática o video) | -| **Digital Signage** | `digital_signage`| Contenido para pantallas y tótems físicos. | - -### Integración de Audiencias - -Dirija anuncios a públicos específicos para aumentar la relevancia. Vea más en [Integración de Audiencias](./5.2-integracion-de-audiencias.md). +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/5.2-integracion-vtex.md b/es/docs/5.2-integracion-vtex.md index 55e04fe..bce084a 100644 --- a/es/docs/5.2-integracion-vtex.md +++ b/es/docs/5.2-integracion-vtex.md @@ -1,32 +1,8 @@ # 5.1 Integración con VTEX (VTEX IO App) -Para tiendas en la plataforma VTEX, Newtail ofrece una aplicación de storefront (`Newtail Media APP VTEX`) que simplifica drásticamente la implementación. La app ya incluye componentes visuales y toda la lógica para la consulta de anuncios y la notificación de eventos. -* **Paso 1: Sincronización del Catálogo** - * La sincronización del catálogo de productos es un prerrequisito. Se puede realizar de dos maneras: - 1. **Vía API:** Proporcionando a Newtail las claves de API para la lectura de su catálogo. - 2. **Vía XML:** Proporcionando un enlace a un feed XML en formato de Google Shopping, que debe contener el campo `SKU` para la identificación del producto. - -* **Paso 2: Instalación de la App** - 1. **Añadir como Dependencia:** En el archivo `manifest.json` de su tema, añada `"newtail.media": "0.x"` a las `peerDependencies`. - 2. **Instalar la App:** Ejecute el comando `vtex install newtail.media@0.x` en su terminal. - -* **Paso 3: Configuración** - 1. **ID del Publisher:** En el admin de su tienda VTEX, acceda a `Configuración de la Tienda > Newtail Media` e ingrese su `Publisher ID` proporcionado por Newtail. - 2. **Política de Seguridad de Contenido (CSP):** Añada las siguientes directivas a su `policies.json`: - ```json - { - "contentSecurityPolicy": { - "default-src": ["'self'", "newtail-media.newtail.com.br"], - "connect-src": ["'self'", "newtail-media.newtail.com.br"] - } - } - ``` - -* **Paso 4: Uso de los Bloques** - * Declare los bloques de la app en las plantillas de su tema para mostrar los anuncios. - - * **Componentes Disponibles:** - * `newtail-media-banner`: Renderiza banners patrocinados. - * `newtail-media-shelf`: Renderiza una estantería de productos patrocinados. - * `newtail-media-search`: Añade sellos "Patrocinado" a los productos en los resultados de búsqueda. - * `newtail-media-conversion`: Componente esencial que gestiona el envío de eventos de conversión. **Debe ser incluido en todas las páginas.** \ No newline at end of file +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/5.3-sincronizacion-de-catalogo.md b/es/docs/5.3-sincronizacion-de-catalogo.md index 761d4a3..c9884d2 100644 --- a/es/docs/5.3-sincronizacion-de-catalogo.md +++ b/es/docs/5.3-sincronizacion-de-catalogo.md @@ -1,193 +1,8 @@ ## 5.2. Sincronización de Catálogo -El primer paso es la sincronización, que ocurre en dos frentes: - -> **Nota para tiendas VTEX:** Para tiendas en la plataforma VTEX, la sincronización del catálogo ocurre de forma transparente, no siendo necesaria ninguna integración adicional para este fin. - -#### **Sincronización de Productos** -Envío de la información de registro de los productos. Requiere autenticación. - -* **Endpoint:** `POST https://api-retail-media.newtail.com.br/product/bulk/products` -* **Límites:** 500 productos por solicitud; 3 solicitudes simultáneas. - -| Campo | Descrição | Tipo | ¿Obligatorio? | -| :--- | :--- | :--- | :--- | -| `product_sku` | ID/SKU único del producto. | String | Sí | -| `parent_sku` | SKU del producto padre (para variaciones). | String | No | -| `name` | Nombre del producto. | String | Sí | -| `url` | URL canónica de la página del producto. | String | Sí | -| `image_url`| URL de la imagen principal del producto. | String | No | -| `categories` | Lista de categorías. | Array[String] | Sí | -| `brand` | Marca del producto. | String | No | -| `gtins` | Códigos de barras (EAN). **Obligatorio para campañas en la VTEX Ads Network.**| Array[String] | No/Sí | -| `tags` | "Etiquetas" para contextualizar búsquedas. Máx. 10 por SKU, 64 caracteres por tag. Solo para campañas de `product`. | Array[String] | No | -| `sellers` | Lista de sellers que venden el producto (en un marketplace). | Array[String] | No | -| `metadata` | Objeto para información adicional (clave-valor). | Object | No | - ---- - -### **Estructuración de Categorías** - -> **Importante:** El campo `categories` es crucial para la segmentación de campañas y la organización de productos. Debe ser estructurado jerárquicamente, representando la ruta completa desde la categoría raíz hasta la categoría específica del producto. - -El campo `categories` debe ser un array de strings, donde cada string es un nivel del árbol de categorías. La jerarquía se construye enviando todas las categorías padre hasta la más específica. - -**Ejemplo Correcto:** - -Para un producto en la categoría de perfumes "Para Mujer", el array `categories` debería ser: - -```json -"categories": [ - "Belleza", - "Belleza > Fragancias", - "Belleza > Fragancias > Perfume", - "Belleza > Fragancias > Perfume > Para Mujer" -] -``` - -Esta estructura permite a la plataforma entender el contexto del producto en todos los niveles, desde el más amplio ("Belleza") hasta el más específico ("Para Mujer"). - ---- - -**Ejemplo de Solicitud:** - -```bash -curl --location 'https://api-retail-media.newtail.com.br/product/bulk/products' \ ---header 'x-app-id: XXXX' \ ---header 'x-api-key: YYYY' \ ---header 'Content-Type: application/json' \ ---data '[ - { - "product_sku": "allan", - "name": "allan", - "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616", - "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629", - "categories": [ - "Belleza", - "Belleza > Fragancias", - "Belleza > Fragancias > Perfume", - "Belleza > Fragancias > Perfume > Para Mujer" - ], - "brand": "SALVADOR DALÍ", - "profit_margin": null, - "gtins": [ - "3331438450103" - ], - "sellers": [], - "skus": [] - }, - { - "product_sku": "allan2", - "name": "allan2", - "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616", - "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629", - "categories": [ - "Belleza", - "Belleza > Fragancias", - "Belleza > Fragancias > Perfume", - "Belleza > Fragancias > Perfume > Para Mujer" - ], - "brand": "SALVADOR DALÍ", - "profit_margin": null, - "gtins": [ - "3331438450103" - ], - "sellers": [], - "skus": [], - "tags": ["Abart", "Mega Maio"] - } -]' -``` - - -**Ejemplo de Respuesta Exitosa:** - -``` -Status: 202 Accepted -Content-Type: application/json - -{ - "messages": [ - "products will be processed soon" - ] -} -``` - ---- - -#### **Sincronización de Inventario** -Envío de la información de precio y stock de los productos. Requiere autenticación. - -* **Endpoint:** `POST https://api-retail-media.newtail.com.br/product/bulk/inventories` -* **Límites:** 500 productos por solicitud; 3 solicitudes simultáneas. - -| Campo | Descripción | Tipo | ¿Obligatorio? | -| :--- | :--- | :--- | :--- | -| `product_sku` | ID/SKU único del producto. | String | Sí | -| `price` | Precio actual del producto. | Float | Sí | -| `promotional_price` | Precio "de" (listado/original). | Float | Sí | -| `is_available` | Producto disponible (en stock). | Boolean | Sí | -| `store_id` | ID de la tienda. Si no se proporciona el ID de la tienda, se interpretará como que esta información de inventario se utilizará para todas las tiendas. | String | No | -| `metadata` | Objeto para información adicional (clave-valor). | Object | No | - -**Ejemplo de Solicitud:** - -```bash -curl --location 'https://api-retail-media.newtail.com.br/product/bulk/inventories' \ ---header 'x-app-id: XXXX' \ ---header 'x-api-key: YYYY' \ ---header 'Content-Type: application/json' \ ---data '[ - { - "product_sku": "120210", - "store_id": "1", - "price": 18.20, - "promotional_price": 16.32, - "is_available": true - }, - { - "product_sku": "120212", - "price": 18.20, - "promotional_price": 0, // Eliminar precio promocional - "is_available": true - } -]' -``` - -**Ejemplo de Respuesta Exitosa:** - -``` -Status: 202 Accepted -Content-Type: application/json - -{ - "messages": [ - "inventory will be processed soon" - ] -} -``` - ---- - -### **Buenas Prácticas para Sincronización** - -1. **Sincronización Inicial Completa:** - * Envíe todo el catálogo en la primera sincronización. - * Divida en lotes de hasta 500 productos para evitar timeouts. - -2. **Actualizaciones Incrementales:** - * Después de la sincronización inicial, envíe solo productos nuevos o modificados. - * Mantenga un registro de la última fecha de modificación de cada producto. - -3. **Frecuencia de Actualización:** - * Precios y stock: Actualice al menos una vez al día, idealmente en tiempo real para cambios significativos. - * Información de registro: Actualice cuando haya cambios. - -4. **Tratamiento de Errores:** - * Implemente reintentos con backoff exponencial para fallos temporales. - * Monitoree las respuestas de la API para identificar problemas persistentes. - -5. **Validación de Datos:** - * Verifique que todos los campos obligatorios estén completos. - * Asegúrese de que las URLs de productos e imágenes sean válidas y accesibles. - * Asegúrese de que las categorías sigan la estructura jerárquica recomendada. \ No newline at end of file +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/5.4-integracion-de-audiencias.md b/es/docs/5.4-integracion-de-audiencias.md index 4fe23f6..9be1985 100644 --- a/es/docs/5.4-integracion-de-audiencias.md +++ b/es/docs/5.4-integracion-de-audiencias.md @@ -1,98 +1,8 @@ ## 5.4. Integración de Audiencias -> **Nota:** La integración de audiencias es opcional, pero muy recomendada para mejorar la segmentación de campañas y la relevancia de los anuncios. - -La integración de audiencias tiene una única forma de integración: **Envío por Lotes (Batch)** al bucket S3 proporcionado por VTEX Ads. - -> **Importante:** La integración vía FTP/SFTP está **deprecated** y solo debe utilizarse en implementaciones legadas. Los nuevos proyectos deben usar exclusivamente el bucket S3. - -> **Alerta:** Si no existe integración de audiencia, es necesario abrir un ticket con el Account Manager solicitando la pre-población de la información de segmentación con datos base (`STATE`, `CITY`, `GENDER` y `AGE`). También es posible enviar una lista de audiencias para su registro, y recomendamos mantener una actualización periódica de esas audiencias. - -### Envio por Lotes (Batch) - Bucket S3 - -La conexión de integración se realiza mediante el envío periódico de audiencias al bucket S3 dedicado al publisher. Las credenciales de acceso (clave/secreto IAM o role para cross-account) y la ruta base del bucket deben solicitarse a su contacto en Newtail. - -* **Formato de Archivo:** `Parquet` con compresión `Snappy`. -* **Patrón de Directorio (clave S3):** Suba los archivos siguiendo el patrón: - `s3://<bucket>/<PREFIJO>/audiences/YYYY/mm/dd/TIMESTAMP.parquet.snappy` - -| Atributo | Descripción | Ejemplo | -| :-------- | :---------------------------------------------------------------------------------------------------------- | :----------- | -| `PREFIJO` | El prefijo será informado por Newtail. | `xyz` | -| `YYYY` | Año de generación con 4 dígitos. | `2023` | -| `mm` | Mes de generación con dos dígitos (Enero = 01 y Diciembre = 12). | `09` | -| `dd` | Día de generación con dos dígitos (del 01 al 31). | `31` | -| `TIMESTAMP`| Timestamp es la cantidad de segundos desde 1970 (el nombre del archivo puede ser cualquiera, el timestamp es solo una sugerencia que nunca se repetirá). | `1694812122` | - -> **Recomendación para el envío:** En la integración inicial, es fundamental que se envíen todos los datos. Y estos datos se pueden enviar en múltiples archivos (dependiendo del tamaño de la base, un buen número es 1 millón de líneas por archivo). Después de la primera integración, lo ideal es que se envíe solo el delta de las filas que tuvieron alguna modificación. - -> **Compatibilidad legada:** Si ya estaba integrado vía SFTP, contacte al equipo de VTEX Ads para planificar la migración al bucket S3. El flujo vía SFTP dejará de recibir nuevas mejoras y puede ser descontinuado. - -### Alternativa sin integración previa (runtime) - -Si decide no integrar audiencias vía batch, todavía puede usar segmentaciones en runtime enviando los datos en el campo `segmentation` de la solicitud de consulta de anuncios. Consulte la sección [5.5. Consulta de Anuncios](5.5-consulta-de-anuncios.md). - -### Atributos del Archivo de Audiencias - -La mayoría de los atributos no son obligatorios, sin embargo, cuanto mayor sea el llenado de toda esta información, mejor será la relevancia. - -> Las columnas son **case sensitive**. Mantenga el nombre de las columnas tal como se presentan. - -| Columna | Tipo | ¿Obligatorio? | Descripción | -| :------------------ | :----- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `CUSTOMER_ID` | String | Sí | Identificador único del cliente. | -| `EMAIL_HASHED` | String | No | PII basado en el correo electrónico del cliente. | -| `PHONE_HASHED` | String | No | PII basado en el número de teléfono principal del cliente. | -| `SOCIAL_ID_HASHED` | String | No | PII basado en el CUIT/CUIL del cliente. | -| `FIRST_NAME_HASHED` | String | No | PII basado en el Nombre del cliente. | -| `LAST_NAME_HASHED` | String | No | PII basado en el Apellido del cliente. | -| `GENDER` | String | No | Indica el sexo del cliente (`F` para femenino, `M` para masculino, `O` para otros, `NULL` para no identificados). | -| `AGE` | Int | No | Indica la edad del cliente. | -| `CEP` | String | No | Indica el código postal de la dirección del cliente. | -| `COUNTRY` | String | No | Indica el país del usuario. | -| `STATE` | String | No | Indica el estado/provincia donde reside el cliente. | -| `CITY` | String | No | Indica la ciudad donde reside el cliente. | -| `NEIGHBORHOOD` | String | No | Indica el barrio donde reside el cliente. | -| `AUDIENCES` | String | No | Una lista de audiencias, separadas por punto y coma (;). | -| `NBO_PRODUCTS` | String | No | Una lista de SKU de productos, separadas por punto y coma (;). | -| `NBO_CATEGORIES` | String | No | Una lista de categorías, separadas por punto y coma (;). La lista puede recibir un árbol de categorías usando " > " como separador (ej: `Tablets;Bebidas > Bebidas No Alcohólicas;Libros > Gastronomía > Guías de Bares y Restaurantes`). | - -### Hash de Campos - -Los datos confidenciales deben ser encriptados antes de ser enviados usando el algoritmo **SHA256**. - -* `EMAIL_HASHED` -* `PHONE_HASHED` -* `SOCIAL_ID_HASHED` -* `FIRST_NAME_HASHED` -* `LAST_NAME_HASHED` - -> Antes de generar el hash de los datos es necesario remover todos los **ESPACIOS** y convertir a **MINÚSCULAS** sus valores. -> Para el atributo `PHONE_HASHED`, será necesario formatearlo al estándar **E.164** e incluir el código de país. - -#### Formato E.164 - -1. Remueva todos los caracteres no numéricos, como espacios, guiones, paréntesis y símbolos. -2. Añada el código del país con el signo de suma (+) al principio. -3. Añada el código de área (si aplica) sin el cero inicial. -4. Incluya el número de teléfono local sin el cero inicial (si aplica). - -**Ejemplo:** - -* Un número de teléfono de Argentina, con código de área 11 y número local 98765-4321, sería formateado como: `+5411987654321` - -#### Creando un HASH en Python - -```python -import re -import hashlib - -hash_obj = hashlib.sha256() - -def create_hash(x): - cleaned = re.sub('\s+', '', x.lower()) - hash_obj.update(cleaned.encode('utf-8')) - return hash_obj.hexdigest() - -create_hash(' Allan ') #=> 8c01ade3cb71d3ac7c718ed5a0c565155a4c05a216d9e59013c5d7b49e916914 -``` +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/5.5-consulta-de-anuncios.md b/es/docs/5.5-consulta-de-anuncios.md index 6b1240c..38675e1 100644 --- a/es/docs/5.5-consulta-de-anuncios.md +++ b/es/docs/5.5-consulta-de-anuncios.md @@ -1,394 +1,8 @@ ## 5.5. Consulta de Anuncios -Con el catálogo sincronizado, su plataforma solicita anuncios para completar los espacios publicitarios (`placements`). La solicitud es un `POST` y el `publisher_id` debe ser informado en la URL. - -* **Endpoint:** `POST https://newtail-media.newtail.com.br/v1/rma/:publisher_id` -* **Content-Type:** Todas las solicitudes deben incluir el encabezado `Content-Type: application/json` - -#### Buenas Prácticas de Solicitud - -- **Persistencia HTTP:** Prefiera conexiones persistentes (`Connection: keep-alive`). -- **Timeout:** Aplique un timeout de 500–600 ms en la consulta (ver 5.6 para eventos). - -#### **Parámetros de la Solicitud** - -| Campo | Descripción | Tipo | Obligatoriedad | -| :--- | :--- | :--- | :--- | -| `session_id` | Identificador persistente del visitante (≥ 14 días). Para aplicaciones móviles, se debe enviar el ID del dispositivo como session_id (GAID en Android e IDFA en iOS), de manera que la sesión se mantenga indefinidamente. | String | Sí | -| `user_id` | ID único del usuario logueado (alfanumérico). | String | No (Recomendado) | -| `store_id` | Filtra anuncios por stock de una tienda específica. | String | No | -| `channel` | Canal de acceso: `site`, `msite`, `app` (para consulta). | String | Sí | -| `context` | Contexto: `home`, `category`, `search`, `product_page`, `brand_page`, `digital_signage`.| String | Sí | -| `term` | Término buscado por el usuario. | String | Solo `context: 'search'` | -| `category_name` | Categoría navegada (breadcrumb completo).| String | Solo `context: 'category'`| -| `product_sku` | SKU del producto que se está visualizando. | String | Solo `context: 'product_page'` | -| `brand_name` | Nombre de la marca que se está visualizando. | String | Solo `context: 'brand_page'` | -| `device_id` | ID único del dispositivo (pantalla, tótem). | String | Solo `context: 'digital_signage'` | -| `store_name` | Nombre de la tienda donde está ubicado el dispositivo. | String | Solo `context: 'digital_signage'` | -| `placements` | Objeto que define los espacios (`placements`) de anuncio. | Object | Sí | -| `placements.{name}.quantity` | Cantidad de anuncios deseada. | Integer | Sí | -| `placements.{name}.size` | Tamaño esperado (Imagen: `desktop`/`mobile`; Video: `1080p`/`720p`/`480p`/`360p`/`320p`). | String | Solo `types: ['banner', 'sponsored_brand']` | -| `placements.{name}.types` | Tipos permitidos (`product`, `banner`, etc.). | Array[String] | Sí | -| `placements.{name}.assets_type`| Medios aceptados (`image`, `video`). Por defecto: `["image"]`. | Array[String] | Solo `types: ['banner', 'sponsored_brand']` | -| `placements.{name}.allow_sku_duplications` | Permite mostrar el mismo SKU más de una vez dentro del mismo placement. | Boolean | No (Default=false) | -| `userAgent` | Identificación del entorno del cliente (campo en el cuerpo, no el header HTTP `User-Agent`). | String | No | -| `segmentation` | Datos para segmentación en tiempo real. | Array[Object] | No | -| `segmentation.#.key` | El tipo de segmentación. | String | No | -| `segmentation.#.values` | Array de valores para la segmentación. | Array[String] | No | -| `tags` | "Etiquetas" para contextualizar búsquedas (principalmente en `search`). Máx. 10 por SKU, 64 caracteres por tag. Solo para campañas de `product`. | Array[String] | No | -| `brand` | Nombre del sitio del publisher. | String | Obligatorio cuando el publisher tiene múltiples sitios | -| `dedup_campaign_ads` | Deduplicar por campaña (máximo 1 anuncio por campaña en la respuesta). | Boolean | No (Default=false) | -| `dedup_ads` | Deduplicar por `ad_id` entre múltiples placements (usar solo al consultar múltiples placements al mismo tiempo). | Boolean | No (Default=false) | -| `skus` | Filtra los resultados de anuncios para retornar solo ads de los SKUs especificados. Compatible solo con Sponsored Products (campañas de producto). | Array[String] | No | - -##### Campos por Contexto - -| Contexto | Campos adicionales obligatorios | -| :--- | :--- | -| `home` | — | -| `search` | `term` | -| `category` | `category_name` | -| `product_page` | `product_sku` | -| `brand_page` | `brand_name` | -| `digital_signage` | `device_id`, `store_name` | - -#### **⚠️ Reglas Importantes de Contexto y Elegibilidad de Anuncios** - -##### Limitaciones de Filtro - -> **Importante:** No es posible hacer filtro por `placement` específico. La selección de anuncios se basa en el `context` y en los parámetros de la solicitud. - -##### Elegibilidad por Contexto - -###### Contexto `home` - -En el contexto **home**, pueden ser retornados: - -- ✅ **Anuncios de Banner/Video/Sponsored Brands** que utilicen **categoría** como criterio de segmentación -- ✅ **Anuncios de Productos (Sponsored Products)** también son elegibles - -**Ejemplo:** -```json -{ - "context": "home", - "placements": { - "site_home_middle_banner": { - "quantity": 3, - "types": ["banner", "sponsored_brand"], - "assets_type": ["image", "video"], - "size": "desktop" - }, - "site_home_shelf_product": { - "quantity": 10, - "types": ["product"] - } - } -} -``` - -###### Contexto `search` - -En el contexto **search**, pueden ser retornados: - -- ✅ **Anuncios de Banner/Video/Sponsored Brands** que sean de **keyword** (palabra clave) -- ✅ **Cualquier campaña de Producto (Sponsored Products)** - -**⚠️ Match Exacto de Keywords:** - -El match de keywords en el contexto `search` es **exacto** (sin stemming/sinónimos). Esto significa que: - -- El anunciante **necesita especificar exactamente** cuáles keywords desea utilizar en la campaña de Banner/Video/Sponsored Brands -- Si el usuario busca "zapatillas nike", el anuncio solo será elegible si el anunciante registró exactamente la keyword "zapatillas nike" -- No hay correspondencia aproximada o por palabras similares - -**Ejemplo:** -```json -{ - "context": "search", - "term": "zapatillas nike", - "placements": { - "site_search_top_banner": { - "quantity": 1, - "types": ["banner", "sponsored_brand"], - "assets_type": ["image"], - "size": "desktop" - }, - "site_search_shelf_product": { - "quantity": 20, - "types": ["product"] - } - } -} -``` - -**Comportamiento esperado:** -- **Banner/Sponsored Brand:** Solo aparecerá si el anunciante registró la keyword exacta "zapatillas nike" en la campaña -- **Sponsored Products:** Productos relacionados al término de búsqueda serán retornados - -###### Contexto `brand_page` - -En el contexto **brand_page**, pueden ser retornados: - -- ✅ **Anuncios de Banner/Video/Sponsored Brands** de la marca -- ✅ **Anuncios de Productos (Sponsored Products)** de la marca - -**Ejemplo:** -```json -{ - "context": "brand_page", - "brand_name": "Nike", - "placements": { - "site_brand_top_banner": { - "quantity": 1, - "types": ["banner", "sponsored_brand"], - "assets_type": ["image"], - "size": "desktop" - }, - "site_brand_shelf_product": { - "quantity": 12, - "types": ["product"] - } - } -} -``` - -###### Contexto `digital_signage` - -En el contexto **digital_signage**, pueden ser retornados anuncios para pantallas/tótems físicos. - -**Ejemplo:** -```json -{ - "context": "digital_signage", - "device_id": "totem-abc-001", - "store_name": "Tienda Centro", - "placements": { - "totem_home_main_video": { - "quantity": 1, - "types": ["banner"], - "assets_type": ["video"], - "size": "720p" - } - } -} -``` -###### Contexto `category` - -En el contexto **category**, pueden ser retornados: - -- ✅ **Anuncios de Banner/Video/Sponsored Brands** que utilicen la **categoría** correspondiente -- ✅ **Anuncios de Productos (Sponsored Products)** de la categoría - -**Ejemplo:** -```json -{ - "context": "category", - "category_name": "Deportes > Calzado > Zapatillas", - "placements": { - "site_category_top_banner": { - "quantity": 1, - "types": ["banner", "sponsored_brand"], - "assets_type": ["image", "video"] - } - } -} -``` - -###### Contexto `product_page` - -En el contexto **product_page**, pueden ser retornados: - -- ✅ **Anuncios de Productos (Sponsored Products)** relacionados al producto visualizado - -**Ejemplo:** -```json -{ - "context": "product_page", - "product_sku": "12345", - "placements": { - "site_product_recommendation": { - "quantity": 5, - "types": ["product"] - } - } -} -``` - -#### **Respuesta de la Consulta** -La respuesta es un JSON donde cada clave es un nombre de `placement`. La estructura de cada anuncio en la respuesta depende de su tipo. - -##### **Campos Comunes de Respuesta para Todos los Tipos de Anuncios** -Estos campos están presentes en todos los tipos de anuncios: - -| Campo | Descripción | -| :--- | :--- | -| `{placementName}.#.ad_id` | ID único del anuncio. | -| `{placementName}.#.type` | Tipo del anuncio (`product`, `banner`, `sponsored_brand`, `digital_signage`). | -| `{placementName}.#.click_url`| **URL para notificar el evento de clic.** | -| `{placementName}.#.impression_url`| **URL para notificar el evento de impresión.**| -| `{placementName}.#.view_url` | **URL para notificar el evento de visualización.** | -| `{placementName}.#.seller_id` | ID del vendedor del producto anunciado (opcional). | - -##### **Campos de Respuesta Específicos por Tipo** - -###### **Anuncios de Producto** -Campos adicionales para anuncios del tipo `product`: - -| Campo | Descripción | -| :--- | :--- | -| `{placementName}.#.product_sku`| SKU del producto anunciado. | - -###### **Anuncios de Banner** -Campos adicionales para anuncios del tipo `banner`: - -| Campo | Descripción | -| :--- | :--- | -| `{placementName}.#.media_url`| URL de la imagen o video a ser exhibido. | - -###### **Anuncios de Marca Patrocinada** -Campos adicionales para anuncios del tipo `sponsored_brand`: - -| Campo | Descripción | -| :--- | :--- | -| `{placementName}.#.media_url`| URL de la imagen o video a ser exhibido. | -| `{placementName}.#.products`| Array de productos asociados a la marca patrocinada. | -| `{placementName}.#.products.#.product_sku`| SKU del producto asociado. | -| `{placementName}.#.products.#.media_url`| URL de la imagen del producto. | - -###### **Anuncios de Digital Signage** -Campos adicionales para anuncios del tipo `digital_signage`: - -| Campo | Descripción | -| :--- | :--- | -| `{placementName}.#.media_url`| URL de la imagen o video a ser exhibido. | -| `{placementName}.#.duration`| Duración de la exhibición del anuncio en segundos. | - -##### Ejemplo de Respuesta (multi-placement) - -```json -{ - "site_home_middle_banner": [ - { - "ad_id": "ad-001", - "type": "banner", - "media_url": "https://cdn.example.com/banner1.jpg", - "impression_url": "https://events.../impression/abc", - "view_url": "https://events.../view/abc", - "click_url": "https://events.../click/abc" - } - ], - "site_home_shelf_product": [ - { - "ad_id": "ad-101", - "type": "product", - "product_sku": "SKU-123", - "seller_id": "SELLER-9", - "impression_url": "https://events.../impression/def", - "view_url": "https://events.../view/def", - "click_url": "https://events.../click/def" - } - ] -} -``` - -### Buenas Prácticas - -#### Nomenclatura de Placements - -Adopte un estándar claro, como `{canal}_{contexto}_{posicion}_{tipo}` (ej: `msite_search_top-shelf_product`). Para recomendaciones detalladas, consulte `es/docs/5.5.1-recomendacion-de-nombres-de-placements.md`. - -| canal | contexto | posición | tipo | ejemplo | -| --- | --- | --- | --- | --- | -| site | home | middle | banner | site_home_middle_banner | -| msite | product | top-shelf | product | msite_product_top-shelf_product | -| app | search | top-shelf | product | app_search_top-shelf_product | -| app | search | top-shelf | banner | app_search_top-shelf_banner | -| site | category | bottom-shelf | banner | site_category_bottom-shelf_banner | -| site | product | filter-bar | product | site_product_filter-bar_product | - -#### Tamaños de Imagen Estándar IAB - -Para anuncios de tipo banner, es importante utilizar imágenes en los formatos estándar definidos por el IAB (Interactive Advertising Bureau). Esto garantiza la compatibilidad y una mejor experiencia visual en diferentes sitios y dispositivos. - -**Formatos Principales:** - -* **Rectángulo Mediano:** 300x250 píxeles -* **Leaderboard:** 728x90 píxeles -* **Skyscraper Ancho:** 160x600 píxeles -* **Leaderboard Móvil:** 320x50 píxeles -* **Billboard:** 970x250 píxeles -* **Media Página:** 300x600 píxeles - -#### Opciones de Tamaño para Videos - -Para solicitudes de anuncios de video, debe especificar el parámetro de tamaño para filtrar por resolución de video. Las opciones disponibles son: - -* **1080p** (1920x1080 pixels) - Recomendado solo para videos en pantalla completa -* **720p** (1280x720 pixels) - Recomendado solo para videos en pantalla completa -* **480p** (854x480 pixels) -* **360p** (640x360 pixels) -* **320p** (568x320 pixels) - Recomendado para dispositivos móviles - -**Importante:** Al solicitar anuncios de video, use solo el identificador de resolución (ej: `"720p"`) en el parámetro size, no las dimensiones completas. Por ejemplo, para filtrar por resolución 1280x720, use `"size": "720p"` en su solicitud de anuncio. - -### Segmentación de Anuncios - -Dirija anuncios a públicos específicos para aumentar la relevancia. - -#### **Segmentación en Tiempo Real** -Envíe datos demográficos o de audiencia directamente en el cuerpo de la **consulta de anuncios**, en el campo `segmentation`. - -El campo `segmentation` es un array de objetos, donde cada objeto contiene: -- `key`: El tipo de segmentación (ej: "STATE", "CITY", "GENDER") -- `values`: Array de valores para la segmentación - -**Ejemplo de Segmentación:** - -```json -[ - { - "key": "STATE", - "values": [ - "CABA" - ] - }, - { - "key": "CITY", - "values": [ - "Buenos Aires" - ] - } -] -``` - -**Tipos de Segmentación Disponibles:** - -| Clave (key) | Descripción | Ejemplos de Valores | -| :--- | :--- | :--- | -| `STATE` | Provincia/Estado del usuario | "CABA", "Buenos Aires", "Córdoba" | -| `CITY` | Ciudad del usuario | "Buenos Aires", "Córdoba", "Rosario" | -| `GENDER` | Género del usuario | "M", "F" | -| `AGE` | Edad del usuario | "22", "35" | -| `AUDIENCES` | Audiencia personalizada | "clientes_alto_valor", "abandonadores_carrito" | -| `NBO_CATEGORIES` | Indica las posibles categorías que el usuario tiene intención de comprar | "Electrónica", "Libros" | - -### Códigos de Respuesta y Errores - -- **200 OK:** Consulta procesada con éxito (retorna JSON por placement). -- **422 Unprocessable Entity:** Error de validación de campos (formato compatible con JSON Schema/Ajv). -- **400 Bad Request / 404 Not Found:** Solicitud inválida o recurso no encontrado. -- **429 Too Many Requests:** Límite de solicitudes excedido. -- **5xx:** Errores internos. - -Ejemplo 422 (parcial): -```json -[ - { - "instancePath": "/context", - "keyword": "enum", - "message": "must be equal to one of the allowed values", - "params": {"allowedValues": ["home","category","search","product_page","brand_page","digital_signage"]}, - "schemaPath": "#/properties/context/enum" - } -] -``` +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/5.5.1-recomendacion-de-nombres-de-placements.md b/es/docs/5.5.1-recomendacion-de-nombres-de-placements.md index c9e18d7..bb61e42 100644 --- a/es/docs/5.5.1-recomendacion-de-nombres-de-placements.md +++ b/es/docs/5.5.1-recomendacion-de-nombres-de-placements.md @@ -1,33 +1,8 @@ # 5.5.1. Recomendación de Nombres de Placements -Usar nombres claros y consistentes para los placements es esencial para medir correctamente el rendimiento de cada área de anuncios del sitio/app, facilitar informes y acelerar diagnósticos. - -Patrón de nomenclatura recomendado: - -``` -{medio}_{contexto}_{posicion}_{tipo} -``` - -Dónde: -- medio: canal de acceso, p. ej.: site, msite (sitio móvil), app -- contexto: página/contexto de navegación, p. ej.: home, category, search, product, brand_page, digital_signage -- posicion: ubicación del bloque en la página, p. ej.: top-vitrine, middle, bottom-vitrine, filter-bar -- tipo: tipo de creativo, p. ej.: product, banner, sponsored_brand - -Buenas prácticas: -- Use minúsculas y sin espacios (use guion para compuestos, p. ej.: top-vitrine). -- Evite abreviaciones poco claras; mantenga consistencia entre páginas y canales. -- El nombre debe ser estable en el tiempo (no incluya fechas, nombres de campañas, etc.). - -Ejemplos: - -| medio | contexto | posición | tipo | ejemplo | -| --- | --- | --- | --- | --- | -| site | home | middle | banner | site_home_middle_banner | -| msite | product | top-vitrine | product | msite_product_top-vitrine_product | -| app | search | top-vitrine | product | app_search_top-vitrine_product | -| app | search | top-vitrine | banner | app_search_top-vitrine_banner | -| site | category | bottom-vitrine | banner | site_category_bottom-vitrine_banner | -| site | product | filter-bar | product | site_product_filter-bar_product | - -Nota: Use los mismos valores de canal y contexto que envía en la Consulta de Anuncios (5.5) para mantener la trazabilidad entre solicitudes y reportes. \ No newline at end of file +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/5.6-eventos.md b/es/docs/5.6-eventos.md index 3a1e750..72e0f84 100644 --- a/es/docs/5.6-eventos.md +++ b/es/docs/5.6-eventos.md @@ -1,365 +1,8 @@ ## 5.6. Eventos -La notificación de eventos es **crucial** para la atribución y la medición. - -#### Buenas Prácticas - -* **Persistencia HTTP:** Utilice conexiones HTTP persistentes (`Connection: keep-alive` en el encabezado) para optimizar la performance. -* **Timeout (consulta de anuncios):** Para llamadas de consulta de anuncios (ver sección 5.5), implemente un timeout de 500–600 ms para no perjudicar la experiencia del usuario. - -#### **Identificación de Usuario y Sesión** - -* **`session_id`:** Identificador persistente del visitante. Obligatorio en todos los eventos. Debe mantenerse consistente durante la navegación y entre sesiones dentro de la ventana de conversión (≥ 14 días). El `session_id` debe ser único por usuario y, idealmente, no expirar en este período. Para aplicaciones móviles, se debe enviar el ID del dispositivo como session_id (GAID en Android e IDFA en iOS), de manera que la sesión se mantenga indefinidamente. -* **`user_id`:** ID único del cliente en la plataforma, consistente entre canales. **Obligatorio en conversión**. **Opcional (recomendado)** para impresión, visualización y clic. El `user_id` debe ser el mismo entre app, sitio web y tienda física. - -Después de identificar al usuario y la sesión, siga estas directrices para el disparo de eventos: - -* **Impresión (`impression_url`):** Dispare el evento inmediatamente después de decidir mostrar los anuncios devueltos por el ad server, incluso si el Anuncio finalmente no se muestra al usuario (por ejemplo, por bloqueos o cambios de diseño). -* **Visualización (`view_url`):** Dispare el evento cuando al menos el 50% del Anuncio permanezca dentro del viewport del usuario durante 1 segundo continuo. -* **Clic (`click_url`):** Dispare el evento siempre que el usuario haga clic en el Anuncio. - -No es necesario mantener el estado de los eventos entre cargas de página, pero asegúrese de que cada evento se envíe solo una vez para el mismo Anuncio y contexto. - -#### **Notificación de Impresión, Visualización y Clic** - -Envíe una solicitud `POST` a la respectiva URL de evento (`impression_url`, `view_url`, `click_url`) proporcionada en la consulta de anuncios, con un cuerpo JSON que contenga `session_id` (**obligatorio**) y `user_id` (**cuando esté disponible**). - -* **Cuándo enviar:** `impression_url` cuando se renderiza el Anuncio; `view_url` cuando el Anuncio esté visible (si usted mide viewability); `click_url` en el clic del usuario. -* **URLs de eventos:** utilice siempre las URLs de evento provistas por la consulta de anuncios; no las derive manualmente. -* **Content-Type:** Todas las solicitudes deben incluir el encabezado `Content-Type: application/json` -* **Método Obligatorio (Navegador):** Es **obligatorio** usar `navigator.sendBeacon()` para garantizar el envío asíncrono sin bloquear la navegación y evitar la pérdida de eventos cuando el usuario navega a otra página o cierra el navegador. -* **Respuesta Exitosa:** `HTTP 202 Accepted`. - -Consulte ejemplos de envío desde el navegador en `examples/EVENTS_IMPRESSIONS_VIEWS_CLICKS_BROWSER.md`. - -**Ejemplo de envío de evento usando Beacon API:** - -```javascript -// Función para enviar evento de impresión -function sendImpressionEvent(impressionUrl, userId, sessionId) { - // Datos del evento - const eventData = { - user_id: userId, - session_id: sessionId - }; - - // Verifica si el navegador soporta la Beacon API - if (navigator.sendBeacon) { - // Convierte los datos a JSON - const blob = new Blob([JSON.stringify(eventData)], {type: 'application/json'}); - - // Envía el evento de forma asíncrona - const success = navigator.sendBeacon(impressionUrl, blob); - - if (!success) { - console.error('Error al enviar evento vía Beacon API'); - // Implementar fallback si es necesario - } - } else { - // Fallback para navegadores que no soportan Beacon API - const xhr = new XMLHttpRequest(); - xhr.open('POST', impressionUrl, true); // true para asíncrono - xhr.setRequestHeader('Content-Type', 'application/json'); - xhr.send(JSON.stringify(eventData)); - } -} - -// Ejemplo de uso -sendImpressionEvent( - 'https://events.newtail-media.newtail.com.br/v1/beacon/impression/123456', - 'user-123', - 'session-456' -); -``` - -> **Importante:** El uso de la Beacon API es obligatorio para garantizar que los eventos se envíen incluso cuando el usuario navega a otra página o cierra el navegador. Esto evita la pérdida de eventos y asegura una medición más precisa. - -#### **Notificación de Conversión** - -Cuando una compra es finalizada, envíe los datos del pedido. - -* **Endpoint:** `POST https://events.newtail-media.newtail.com.br/v1/beacon/conversion` -* **Content-Type:** Todas las solicitudes deben incluir el encabezado `Content-Type: application/json` -* **Cuerpo de la Solicitud:** El objeto debe contener los datos del pedido. El precio del artículo no debe ser multiplicado por la cantidad. - -Consulte ejemplos de conversión en `examples/EVENTS_CONVERSION_BROWSER.md` (Browser) y `examples/EVENTS_CONVERSION_CURL.md` (cURL). - -| Campo del Pedido | Descripción | Tipo | ¿Obligatorio? | -| :--- | :--- | :--- | :--- | -| `publisher_id` | ID del publisher. | String | Sí | -| `user_id` | ID del usuario que realizó la compra. | String | Sí | -| `session_id` | ID de la sesión de la compra. | String | Sí | -| `order_id` | ID del pedido. | String | Sí | -| `created_at` | Fecha/hora del pedido (ISO 8601 en UTC). | String | Sí | -| `items` | Lista de artículos del pedido. | Array[Item] | Sí | -| `channel` | Canal de venta (ej.: ecommerce, app, tienda física). | String | Sí | -| `brand` | Marca/sitio donde ocurrió la venta (necesario cuando existe más de un sitio). | String | No/Sí | -| `gender` | Indica el género del cliente. F: para femenino, M: para masculino, O: para otros, null: para no identificados. | String | No (Recomendado) | -| `uf` | Indica el estado de la compra del pedido. | String | No (Recomendado) | -| `city` | Indica el nombre de la ciudad donde el cliente realizó la compra. | String | No (Recomendado) | -| `is_company` | Indica si la venta fue realizada a una persona jurídica o física. | Boolean | No (Recomendado) | -| `email_hashed` | E-mail del usuario en formato hash (SHA256). | String | Sí | -| `phone_hashed`| Teléfono del usuario en hash (SHA256). | String | No (Recomendado) | -| `social_id_hashed`| ID social/fiscal del usuario (CUIT/CUIL) en hash (SHA256). | String | No (Recomendado) | -| `first_name_hashed` | Nombre del usuario (hash). | String | No (Recomendado) | -| `last_name_hashed` | Apellido del usuario (hash). | String | No (Recomendado) | - -> Normalización recomendada para hashing: -> - `email_hashed`: email en minúsculas y sin espacios (trim); hash SHA-256 en hexadecimal. -> - `phone_hashed`: teléfono en formato E.164 (ej.: +5491112345678), sin máscaras; hash SHA-256 en hexadecimal. -> - `social_id_hashed`: documento fiscal solo con dígitos (sin puntos/guiones); hash SHA-256 en hexadecimal. -> - `first_name_hashed` / `last_name_hashed`: nombres normalizados (trim, sin espacios dobles); hash SHA-256 en hexadecimal. - -#### **Estructura de los Artículos del Pedido** - -##### Campos del Objeto Item - -| Campo | Descripción | Tipo | Obligatoriedad | -|-------|-----------|------|-----------------| -| `sku` | Identificación única del SKU del producto | String | **Obligatorio** | -| `quantity` | Cantidad comprada del producto | Double | **Obligatorio** | -| `price` | Precio original del producto (precio "de") | Double | **Obligatorio** | -| `promotional_price` | Precio promocional del producto (precio "por") | Double | **Obligatorio** | -| `seller_id` | Identificación del vendedor/seller | String | Opcional | -| `product_id` | Identificación única del producto que engloba el SKU | String | Opcional | - -##### ⚠️ Observaciones Importantes - -1. **Valores unitarios**: Los campos `price` y `promotional_price` deben contener el valor **unitario** del producto, **no** multiplicado por la cantidad -2. **Campos obligatorios para medición**: Si `price` y `promotional_price` no se informan correctamente, la conversión **no podrá ser medida** -3. **Formato monetario**: Los valores deben enviarse como números decimales (ej: 1899.00) - -#### **Ejemplos de Utilización** - -##### Ejemplo de Artículo Individual -```json -{ - "sku": "12221", - "seller_id": "1234", - "product_id": "4567", - "quantity": 1, - "price": 2000.00, - "promotional_price": 1899.00 -} -``` - -##### Ejemplo de Solicitud Completa - -```http -POST https://events.newtail-media.newtail.com.br/v1/beacon/conversion HTTP/1.1 -Accept: application/json -Content-Type: application/json -``` - -```json -{ - "channel": "ecommerce", - "publisher_id": "xxx", - "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", - "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", - "order_id": "123", - "email_hashed": "xyz", - "items": [ - { - "sku": "12221", - "seller_id": "1234", - "product_id": "4567", - "quantity": 1, - "price": 2000.00, - "promotional_price": 1899.00 - }, - { - "sku": "12222", - "seller_id": null, - "product_id": "4568", - "quantity": 2, - "price": 500.00, - "promotional_price": 400.00 - } - ], - "created_at": "2023-01-01T09:20:00Z" -} -``` - -**Nota**: En el ejemplo anterior, observe que: -- El primer artículo tiene cantidad 1 con precio unitario de $2.000,00 -- El segundo artículo tiene cantidad 2 con precio unitario de $500,00 (no $1.000,00) - -#### **Respuestas de la API** - -##### ✅ Respuesta Exitosa (HTTP 202) -```json -{ - "messages": [ - "conversion will be processed soon" - ] -} -``` - -##### ❌ Respuesta de Error de Validación (HTTP 422) -La API devuelve errores de validación en un formato compatible con JSON Schema (similar a Ajv). - -Ejemplo de respuesta con errores: -```json -[ - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'user_id'", - "params": { - "missingProperty": "user_id" - }, - "schemaPath": "#/required" - }, - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'order_id'", - "params": { - "missingProperty": "order_id" - }, - "schemaPath": "#/required" - }, - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'publisher_id'", - "params": { - "missingProperty": "publisher_id" - }, - "schemaPath": "#/required" - }, - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'items'", - "params": { - "missingProperty": "items" - }, - "schemaPath": "#/required" - }, - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'created_at'", - "params": { - "missingProperty": "created_at" - }, - "schemaPath": "#/required" - } -] -``` - -#### **🎯 Regla de Match de Productos para Conversiones** - -##### Importante: Correspondencia entre Producto y Campaña - -Las conversiones **solo se computan** para campañas cuando ocurre un **match de producto**. Esto significa que: - -- ✅ **Conversión se mide**: Cuando el producto comprado por el usuario **pertenece** a la campaña en la que el usuario fue impactado -- ❌ **Conversión NO se mide**: Cuando el producto comprado **no pertenece** a la campaña en la que el usuario fue impactado - -##### Ejemplo Práctico: - -**Escenario 1 - Con Match (Conversión Computada)** -- Usuario visualizó anuncio de la Campaña A (productos: SKU-001, SKU-002, SKU-003) -- Usuario compró producto SKU-002 -- ✅ Conversión se atribuye a la Campaña A - -**Escenario 2 - Sin Match (Conversión NO Computada)** -- Usuario visualizó anuncio de la Campaña B (productos: SKU-004, SKU-005) -- Usuario compró producto SKU-999 -- ❌ Conversión NO se atribuye a la Campaña B - -#### **Ejemplo de Código** - -##### JavaScript (Browser) -```javascript -const enviarConversion = async (datosPedido) => { - const payload = { - channel: "ecommerce", - publisher_id: "xxx", - user_id: datosPedido.userId, - session_id: datosPedido.sessionId, - order_id: datosPedido.orderId, - email_hashed: datosPedido.emailHash, - items: datosPedido.items.map(item => ({ - sku: item.sku, - seller_id: item.sellerId || null, - product_id: item.productId || null, - quantity: item.quantity, - price: item.unitPrice, // Valor unitario, no multiplicado - promotional_price: item.unitPromotionalPrice // Valor unitario, no multiplicado - })), - created_at: new Date().toISOString() - }; - - try { - // Convierte los datos a JSON - const blob = new Blob([JSON.stringify(payload)], {type: 'application/json'}); - - // Envía el evento de forma asíncrona usando Beacon API - if (navigator.sendBeacon) { - const success = navigator.sendBeacon( - 'https://events.newtail-media.newtail.com.br/v1/beacon/conversion', - blob - ); - - if (success) { - console.log('Conversión enviada con éxito'); - } else { - console.error('Error al enviar conversión vía Beacon API'); - } - } else { - // Fallback para navegadores que no soportan Beacon API - const response = await fetch('https://events.newtail-media.newtail.com.br/v1/beacon/conversion', { - method: 'POST', - headers: { - 'Accept': 'application/json', - 'Content-Type': 'application/json' - }, - body: JSON.stringify(payload) - }); - - if (response.status === 202) { - console.log('Conversión enviada con éxito'); - } else if (response.status === 422) { - const errors = await response.json(); - console.error('Errores de validación:', errors); - } - } - } catch (error) { - console.error('Error al enviar conversión:', error); - } -}; - -// Ejemplo de uso -const pedido = { - userId: "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", - sessionId: "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", - orderId: "123", - emailHash: "xyz", - items: [ - { - sku: "12221", - sellerId: "1234", - productId: "4567", - quantity: 1, - unitPrice: 2000.00, - unitPromotionalPrice: 1899.00 - } - ] -}; - -enviarConversion(pedido); -``` - -#### **Reglas de Atribución y Deduplicación** - -* **Ventana de Conversión:** Período después de una interacción en el que una venta puede ser atribuida al anuncio. - * **Clic (para `product`):** 14 días. - * **Visualización (para `display`/`video`):** 14 días. -* **Deduplicación de Eventos:** Para el mismo usuario y anuncio, los eventos se ignoran durante un período. - * **Impresiones:** 1 minuto. - * **Clics:** 1 hora. - * **Conversiones:** Idempotentes por `order_id` (reenvíos del mismo `order_id` dentro de 30 días se ignoran). +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/5.7-integracion-transparente.md b/es/docs/5.7-integracion-transparente.md index 566ff12..7ce119b 100644 --- a/es/docs/5.7-integracion-transparente.md +++ b/es/docs/5.7-integracion-transparente.md @@ -1,115 +1,8 @@ # Integración Transparente -> Nota: Esta herramienta solo está apta para servir anuncios de tipo Banner y Video. - -La integración transparente tiene como objetivo reducir la fricción al máximo para iniciar la configuración de la integración de VTEX Ads de la forma más sencilla posible. - -## Requisitos para la Prueba de Concepto (PoC) - -Para que esta Prueba de Concepto funcione, los siguientes requisitos son esenciales: - -1. **Integración de Catálogo:** Es necesario que una integración de catálogo esté en funcionamiento. - -2. **Instalación del Script:** Nuestro script debe ser añadido al sitio web. - -3. **Disparo del Evento de Conversión:** El evento de conversión debe ser disparado desde el lado del cliente. - - -### 1\. Integración del Catálogo - -La sincronización del catálogo sigue el formato ya definido para todas las integraciones. - -### 2\. Instalación del Script - -Añada el siguiente script lo antes posible en la etiqueta `<head>` de la página o en su sitio web/msite: - -``` -<script src="https://cdn.newtail.com.br/retail-media/scripts/vtexads-magic-1.0.0.js"></script> -``` - -#### Requisitos del Script - -Para que el script funcione correctamente, el cliente debe informarnos el origen de dos parámetros importantes: `session_id` y `user_id`. Estos parámetros generalmente se almacenan en cookies, `sessionStorage` o `localStorage`. - -### 3\. Evento de Conversión - -El evento de conversión debe enviarse después de la creación del pedido, sin necesidad de confirmación de pago. - -El siguiente script demuestra cómo enviar datos a un endpoint de API utilizando la interfaz `navigator.sendBeacon`. El método `sendBeacon` es ideal para enviar pequeñas cantidades de datos de forma asíncrona sin afectar el rendimiento de la página. Es particularmente útil para enviar datos de análisis antes de que el usuario abandone la página. - -``` -/** - * Este script demuestra cómo enviar datos a un endpoint de API - * utilizando la interfaz `navigator.sendBeacon`. - * - * El método `sendBeacon` está diseñado para enviar pequeñas cantidades de datos - * de forma asíncrona sin afectar el rendimiento de la página actual - * o el tiempo de carga de la siguiente. - * - * Es particularmente útil para enviar datos de análisis antes de que - * un usuario abandone una página. - */ - -// 1. Defina los datos que desea enviar. -const data = { - "publisher_id": "d4dff0cb-1f21-4a96-9acf-d9426a5ed08c", - "user_id": "26119121", - "order_id": "1758035060", - "channel": "site|msite|app", - "created_at": "2025-09-16T15:04:19.794Z", - "items": [ - { - "price": 12, - "promotional_price": 10, - "quantity": 1, - "sku": "sku1" - }, - { - "price": 15, - "promotional_price": 13, - "quantity": 1, - "sku": "sku2", - "seller_id": "seller1" - }, - { - "price": 19, - "promotional_price": 17, - "quantity": 1, - "sku": "sku3", - "product_id": "prod3" - }, - { - "price": 30, - "promotional_price": 25, - "quantity": 2, - "sku": "sku4", - "product_id": "prod4", - "seller_id": "seller2" - } - ] -}; - -// 2. Convierta el objeto de datos en una cadena JSON. -const rawData = JSON.stringify(data); - -// 3. Cree un Blob a partir de la cadena JSON. -// Esto nos permite definir explícitamente el Content-Type para la solicitud. -const blob = new Blob([rawData], { type: 'application/json' }); - -// 4. Defina la URL del endpoint. -const url = "https://newtail-media.newtail.com.br/v1/beacon/conversion"; - -// 5. Use `navigator.sendBeacon` para enviar los datos. -// El método devuelve `true` si el navegador pone en cola la solicitud -// para su entrega y `false` en caso contrario. -// Tenga en cuenta que `sendBeacon` no devuelve una Promesa, por lo que no hay -// `.then()` o `.catch()`. La entrega no está garantizada, pero es -// muy probable. -const success = navigator.sendBeacon(url, blob); - -if (success) { - console.log("¡Solicitud de beacon encolada con éxito!"); -} else { - console.error("Error al encolar la solicitud de beacon."); -} -``` +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/6-exportacion-de-datos.md b/es/docs/6-exportacion-de-datos.md index 1d3b019..ef65db2 100644 --- a/es/docs/6-exportacion-de-datos.md +++ b/es/docs/6-exportacion-de-datos.md @@ -1,61 +1,8 @@ ## 6. Exportación de Datos -La exportación de datos le permite recibir información detallada sobre eventos y datos agregados de forma sistemática y periódica. La integración se realiza a través de una conexión S3, y los datos se entregan en formatos específicos para cada tipo de exportación. - -### 6.1. Reportes - -Además de la exportación a través de S3, es posible extraer informes a través de la API. Las rutas devuelven JSON por defecto, pero se pueden exportar como archivos XLSX incluyendo el parámetro `download=true` en la consulta. - -* `GET /report/v2/advertisers`: Información de anunciantes (vista del publisher) [[Ejemplo]](../../examples/EXPORT_ADVERTISER_DATA.md) -* `GET /report/v2/publishers`: Información del publisher (vista del anunciante) [[Ejemplo]](../../examples/EXPORT_PUBLISHER_DATA.md) -* `GET /report/network/publishers`: Publishers de la red (para cuentas de tipo Red) [[Ejemplo]](../../examples/EXPORT_NETWORK_PUBLISHERS_DATA.md) -* `GET /campaign/v2`: Informe listado de campañas [[Ejemplo]](../../examples/EXPORT_CAMPAIGNS_LIST_DATA.md) -* `GET /campaign/:id`: Informe detallado de la campaña [[Ejemplo]](../../examples/EXPORT_CAMPAIGN_DATA.md) -* `GET /report/advertisers/campaigns-detailed`: Informe detallado de campañas mixtas para cuentas de anunciante, incluyendo información de subpublisher en campañas de red [[Ejemplo]](../../examples/EXPORT_ADVERTISER_CAMPAIGNS_DETAILED_DATA.md) -* `GET /report/advertisers/ads-detailed`: Informe detallado de anuncios para cuentas de anunciante, incluyendo el desglose por subpublisher en campañas de red [[Ejemplo]](../../examples/EXPORT_ADVERTISER_ADS_DETAILED_DATA.md) -* `GET /ad/results/v2`: Informe de anuncios individuales [[Ejemplo]](../../examples/EXPORT_ADS_DATA.md) - -### 6.2. Exportación de Datos - -La integración siempre se realizará mediante una conexión S3 (o compatible) que deberá ser proporcionada por el receptor de los datos. Las credenciales deben ser entregadas al equipo de Newtail de forma segura. - -La integración es compatible con: - -* **AWS S3:** `Access Key Id` y `Access Key Secret`. -* **Google Cloud Storage:** `Service Account`. -* **Azure Blob Storage**. - -#### Exportación de Eventos - -La exportación de eventos envía datos brutos de las interacciones de los usuarios. - -* **Formato:** `PARQUET` con compresión `Snappy`. -* **Frecuencia:** Diaria (datos de D-1). -* **Estructura de Carpetas:** `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.snappy.parquet` -* **De-duplicación:** Se garantiza que todos los eventos serán enviados, pero no que se enviarán una única vez. Por lo tanto, los eventos siempre deben ser de-duplicados usando el `event_id` o la combinación de `order_id` y `product_sku` para los artículos de conversión. - -##### Tipos de Eventos - -* **Impresiones, Visualizaciones y Clics:** - * **Campos:** `event_id` (clave de de-duplicación), `session_id`, `user_id`, `ad_id`, `campaign_id`, `request_id`, `ad_type`, `placement_name`, `context`, `created_at`, `site`. -* **Conversiones:** - * **Campos:** `event_id`, `session_id`, `user_id`, `order_id` (clave de de-duplicación), `channel`, `placed_at`, `site`. -* **Artículos de Conversión:** - * **Campos:** `event_id`, `session_id`, `user_id`, `order_id` (clave de de-duplicación), `product_sku` (clave de de-duplicación), `ad_id`, `campaign_id`, `request_id`, `ad_size`, `ad_type`, `placement_name`, `context`, `event_created_at`, `price`, `promotional_price`, `quantity`, `total_value`. - -#### Exportación de Datos Agregados - -La exportación de datos agregados envía informes consolidados. - -* **Formato:** `CSV` con codificación `UTF-8`, separado por comas, y números en formato americano (punto decimal). -* **Frecuencia:** Diaria (datos de D-1, con la zona horaria del publisher). -* **Estructura de Carpetas:** `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.csv` - -##### Tipos de Informes - -* **Anunciantes:** - * **Campos:** `advertiser`, `advertiser_id`, `seller_id`, `wallet_balance`, `daily_budget`, `currency`. -* **Campañas:** - * **Campos:** `day`, `name`, `campaign_id`, `campaign_type`, `campaign_status`, `impressions_total`, `clicks_total`, `ctr`, `ad_revenue`, `conversions_total`, `conversion_rate`, `sales_revenue`, `start_date`, `end_date`, `advertiser_id`. -* **Anuncios:** - * **Campos:** `day`, `ad_id`, `campaign_id`, `ad_status`, `ad_media_url`, `cpm`, `cpc`, `impressions_total`, `clicks_total`, `ctr`, `ad_revenue`, `conversions_total`, `conversion_rate`, `sales_revenue`, `product_sku`. +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/7-script-agent.md b/es/docs/7-script-agent.md index 4816aba..12dc9fa 100644 --- a/es/docs/7-script-agent.md +++ b/es/docs/7-script-agent.md @@ -1,77 +1,8 @@ # 7. VTEX Ads - Script Agent -## 7.1. Objetivo - -Este documento detalla el procedimiento para la instalación del script de seguimiento de **VTEX Ads** en todas las páginas de un sitio web (excepto las páginas de checkout) a través de Google Tag Manager (GTM). La correcta implementación de este script es fundamental para la recopilación de datos de navegación que permiten la optimización y el direccionamiento de campañas de Retail Media. - -## 7.2. Datos Recopilados - -El script de VTEX Ads fue desarrollado para recopilar exclusivamente datos de navegación no sensibles, con el objetivo de personalizar la experiencia del usuario y optimizar campañas. - -**Datos Recopilados:** - -- **Para campañas off-site:** - - `session_id`: Identificador anónimo de la sesión de navegación. - - `ad_id`: Identificador del anuncio que originó el tráfico. -- **Para segmentación de audiencia (Page View):** - - `session_id`: Identificador anónimo de la sesión de navegación. - - **Información de la Página:** URL, título (`<title>`) y descripción (`<meta name="description">`). - -> **Importante:** El script **no recopila** ninguna información de identificación personal (PII), como nombre, correo electrónico, CPF, teléfono, dirección o datos de pago. La recopilación de datos cumple con las principales leyes de protección de datos. - -## 7.3. Datos del Script - -El script debe cargarse de forma asíncrona para no afectar el tiempo de carga de la página. - -- **URL del Script:** `https://cdn.newtail.com.br/retail-media/scripts/vtexrma-agent.1.0.0.js` - -## 7.4. Paso a Paso para la Implementación a través de Google Tag Manager (GTM) - -Para garantizar que el script se ejecute lo antes posible en la carga de la página, recomendamos utilizar el activador de **Inicialización (Initialization)**. - -### Paso 7.4.1: Crear la Etiqueta de HTML Personalizado - -1. Acceda a su contenedor de GTM y vaya a la sección **"Etiquetas"**. -2. Haga clic en **"Nueva"** para crear una nueva etiqueta. -3. Dé un nombre claro a la etiqueta, por ejemplo: **"Custom HTML - VTEX Ads Agent"**. -4. Haga clic en **"Configuración de la etiqueta"** y seleccione el tipo de etiqueta **"HTML personalizado"**. -5. En el campo de HTML, inserte el siguiente código: - ```html - <script type="text/javascript" async src="https://cdn.newtail.com.br/retail-media/scripts/vtexrma-agent.1.0.0.js"></script> - ``` - -### Paso 7.4.2: Configurar el Activador Principal - -1. Debajo de la configuración de la etiqueta, haga clic en **"Activación"**. -2. Seleccione el activador **"Initialization - All Pages"** (Inicialización - Todas las Páginas). Este activador garantiza que el script se dispare antes que la mayoría de las otras etiquetas, en todas las páginas. - -### Paso 7.4.3: Crear y Añadir una Excepción de Activación - -Para evitar que el script se ejecute en las páginas de checkout, crearemos una excepción. - -1. Aún en la configuración de la etiqueta, en la sección **"Activación"**, haga clic en **"Añadir excepción"**. -2. Haga clic en el ícono de **"+"** en la esquina superior derecha para crear un nuevo activador de excepción. -3. Dé un nombre al activador, por ejemplo: **"Trigger Exception - Checkout Pages"**. -4. Haga clic en **"Configuración del activador"** y elija el tipo **"Inicialización"**. -5. En **"Este activador se dispara en"**, seleccione **"Algunas inicializaciones"**. -6. Configure la condición para identificar las páginas de checkout. La condición puede variar dependiendo de la estructura de la URL de su sitio. Ejemplos comunes: - - `Page Path` | `contiene` | `/checkout` - - `Page URL` | `coincide con RegEx (sin distinguir mayúsculas y minúsculas)` | `/checkout/|/orderPlaced/` -7. Guarde el nuevo activador de excepción. Se agregará automáticamente a su etiqueta. - -### Paso 7.4.4: Guardar y Publicar - -1. Guarde la etiqueta recién creada. -2. Envíe y publique los cambios en su contenedor de GTM. - -## 7.5. Configuración de la Sesión del Usuario - -Para que la plataforma VTEX Ads pueda correlacionar correctamente las interacciones del usuario, es necesario informar cuál es el identificador de sesión utilizado por su e-commerce. - -**Acción Necesaria:** - -El equipo responsable del e-commerce debe informar al equipo de VTEX Ads cuál es el **nombre del atributo en la `cookie` o `sessionStorage`** que almacena el ID de la sesión del usuario. - -- **Ejemplo:** Si el ID de la sesión se almacena en una cookie llamada `vtex_session`, esta información debe ser comunicada. - -Esta configuración permite que el script lea el identificador correcto y lo asocie a los eventos de navegación. +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/8-repasse.md b/es/docs/8-repasse.md index f49da5b..98bcafb 100644 --- a/es/docs/8-repasse.md +++ b/es/docs/8-repasse.md @@ -1,73 +1,8 @@ ## 7. Transferencia de Créditos -La transferencia de créditos es el flujo que permite al marketplace transferir créditos de publicidad a sus sellers. Esta documentación detalla los endpoints que el marketplace debe implementar y el webhook que debe consumir para realizar la integración con VTEXAds. - -<div align="center"> - <img src="../../diagrams/images/es/credit-transfer.png" alt="Flujo de Transferencia de Créditos" /> -</div> - - * **Endpoints a ser implementados por el Marketplace (Autenticación: Basic Auth):** - 1. **Consulta de Saldo (`GET /checking_account`)** - * **Objetivo:** Verificar el saldo disponible del seller. - * **Parámetros (Query):** `seller_id`, `publisher_id` (opcional, utilizado solo en casos donde una entidad gestiona múltiples publishers). - * **Respuesta Exitosa (200 OK):** - ```json - { "total": "1111.00" } - ``` - - 2. **Solicitud de Transferencia (`POST /checking_account/transfer`)** - * **Objetivo:** Requerir la transferencia de un valor. - * **Cuerpo de la Solicitud:** - ```json - { - "amount": "10.00", - "seller_id": "SELLER_ID", - "publisher_id": "PUBLISHER_ID", - "transfer_identity_id": "uuid" - } - ``` - * **Respuestas:** - - **Síncrona (Éxito):** `201 Created` - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "success" - } - ``` - - **Síncrona (Falla):** `400 Bad Request` - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "failure", - "message": "Motivo del rechazo" - } - ``` - - **Asíncrona:** `202 Accepted` - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "processing" - } - ``` - - * **Webhook a ser consumido por el Marketplace:** - * **Objetivo:** Notificar a VTEXAds sobre el estado final de la transferencia. - * **Endpoint:** `POST https://api-retail-media.newtail.com.br/webhook/marketplace/transfers/:publisher_id` - * **Autenticación:** `x-api-key` y `x-secret-key`. - * **Payload:** - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "success" - } - ``` - o - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "failure", - "message": "Descripción del problema" - } - ``` - * **Lógica de Reintentos:** En caso de falla en la llamada del webhook, el marketplace debe realizar nuevos intentos. - * **Respuesta Esperada:** `204 No Content` \ No newline at end of file +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/es/docs/9-sso.md b/es/docs/9-sso.md index 2975277..5f035d8 100644 --- a/es/docs/9-sso.md +++ b/es/docs/9-sso.md @@ -1,32 +1,8 @@ ## 8. SSO (Single Sign-On) -API para el inicio de sesión unificado del seller. Al llamar a esta API, Newtail genera una URL de redireccionamiento que permite al usuario acceder a la plataforma de Newtail sin necesidad de un nuevo inicio de sesión. - -* **Endpoint:** `POST /sso/marketplace` -* **Cuerpo de la Solicitud:** - -| Campo | Descrição | Tipo | ¿Obligatorio? | -| :--- | :--- | :--- | :--- | -| `sso_token` | Token de identificación del usuario generado por el marketplace. | String | Sí | -| `email` | E-mail del usuario (seller). | String | Sí | -| `user_id` | ID único del usuario en el marketplace. | String | Sí | -| `name` | Nombre del usuario. | String | Sí | -| `marketplace_name` | Nombre del marketplace. | String | Sí | - -* **Ejemplo de Solicitud:** - ```json - { - "sso_token": "token-sso-12345", - "email": "seller@ejemplo.com", - "user_id": "seller123", - "name": "Nombre del Seller", - "marketplace_name": "Mi Marketplace" - } - ``` - -* **Respuesta Exitosa:** `HTTP 200 OK` con la URL de redireccionamiento. - ```json - { - "redirect_url": "https://app.ads.vtex.com/sso/auth?token=TOKEN_GENERADO" - } - ``` \ No newline at end of file +> [!IMPORTANT] +> **Esta página se ha movido.** +> +> La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Actualiza tus marcadores. Esta página ya no recibe mantenimiento. diff --git a/pt/docs/1-resumo.md b/pt/docs/1-resumo.md index dffec7e..5e04599 100644 --- a/pt/docs/1-resumo.md +++ b/pt/docs/1-resumo.md @@ -1,24 +1,8 @@ ---- -layout: default -title: "1. Resumo" ---- - ## 1. Resumo -Esta documentação detalha a integração com a **Retail Media API**, o ponto central de conexão entre a solução VTEX Ads e a plataforma do varejista (publisher). A solução foi desenvolvida sob o conceito **API-first**, garantindo total flexibilidade para que os varejistas integrem e exibam anúncios em qualquer canal digital: e-commerce, marketplace, aplicativo ou até mesmo em totens e telas físicas (Digital Signage). - -Nossa arquitetura é **cookie-less**, o que significa que não dependemos de cookies de terceiros. A identificação e a segmentação são baseadas em identificadores próprios (`user_id`, `session_id`) e dados primários (first-party data), garantindo uma solução robusta, em conformidade com as novas políticas de privacidade e preparada para o futuro do varejo digital. - -Através desta API REST, sua plataforma poderá: -* Sincronizar o catálogo de produtos e inventário. -* Solicitar anúncios relevantes em tempo real para o contexto de navegação do usuário. -* Enviar eventos de interação (impressão, visualização, clique, conversão) para a medição de performance. - -Adotamos o princípio de **Extensibilidade Progressiva** para garantir máxima estabilidade e segurança nas operações dos nossos parceiros. - -Nossa política formal de compatibilidade assegura que: -* **Evolução sem rupturas:** atualizações são sempre incrementais. Novos campos, funcionalidades e opções são adicionados sem alterar ou remover o comportamento dos contratos existentes. -* **Preservação de integrações:** integrações atuais permanecem plenamente funcionais após novos lançamentos, reduzindo retrabalho técnico recorrente. -* **Continuidade de negócio:** ao preservar a integridade dos contratos anteriores, evitamos interrupções operacionais e permitimos a adoção de novas capacidades no ritmo do seu negócio. - -Essa abordagem reforça nosso compromisso com uma plataforma robusta e escalável, em que inovação tecnológica e previsibilidade operacional evoluem juntas. +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/10-janela-atribuicao.md b/pt/docs/10-janela-atribuicao.md index 5acd818..bf5504b 100644 --- a/pt/docs/10-janela-atribuicao.md +++ b/pt/docs/10-janela-atribuicao.md @@ -1,97 +1,8 @@ # Janela de Atribuição e Modelos de Conversão -Este documento detalha as regras, modelos e prazos que regem a atribuição de conversões (vendas) e a cobrança das campanhas de publicidade em nossa plataforma. - -## 1. O que é a Janela de Atribuição? - -A "janela de atribuição" (ou janela de conversão) é o período de tempo _após_ um usuário interagir com um anúncio (seja clicando ou visualizando) durante o qual uma conversão pode ser creditada a esse anúncio. - -- **Janela Padrão:** 14 dias. -- **Flexibilidade:** Este período é o padrão para todas as campanhas, mas pode ser customizado conforme a necessidade estratégica. - -**Exemplo:** Se um usuário clica em um anúncio hoje, qualquer compra que ele fizer do produto associado nos próximos 14 dias poderá ser atribuída a esse anúncio. - -## 2. Medição (Atribuição) vs. Cobrança (Faturamento) - -É fundamental diferenciar o evento que _mede_ a atribuição (o que usamos para contar uma conversão) do evento que _gera a cobrança_ (o que cobramos do anunciante). - -### 2.1. Eventos de Medição (Atribuição) - -Isto define _como_ sabemos que um anúncio "funcionou" para gerar uma venda: - -- **Campanhas de Produto (Product Ads):** - - **Evento:** Clique. - - **Lógica:** A conversão só é contada se o usuário _clicou_ no anúncio antes de comprar. - -- **Demais Campanhas (Banner, Vídeo e Sponsored Brands):** - - **Evento:** Visualização (Impressão). - - **Lógica:** A conversão pode ser contada mesmo que o usuário apenas _tenha visto_ o anúncio (e não necessariamente clicado), seguindo as regras de hierarquia (ver seção 3). - -### 2.2. Modelos de Cobrança (Faturamento) - -Isto define _pelo quê_ o anunciante paga: - -- **CPC (Custo por Clique):** O anunciante paga cada vez que um usuário clica no anúncio. - - _Usado em:_ Campanhas de Produto, Sponsored Brands. - -- **CPM (Custo por Mil Impressões):** O anunciante paga um valor fixo por cada 1.000 vezes que o anúncio é exibido. - - _Usado em:_ Banner, Vídeo, Sponsored Brands. - -- **Modelo Híbrido (CPC + CPM):** - - As campanhas de **Sponsored Brands** são únicas, pois cobram _tanto_ pelos cliques (CPC) quanto pelas impressões (CPM) geradas. - -#### Exemplo de Cálculo de Cobrança (CPM) - -O CPM define o valor para 1.000 impressões, mas a cobrança real é proporcional a cada impressão individual. - -- **Cenário:** Uma campanha de vídeo possui um CPM de **R$ 10,00**. -- **Resultado:** A campanha gera **10 impressões**. - -**Cálculo:** - -1. **Custo por impressão individual:** R$ 10,00 (CPM) / 1.000 (impressões) = **R$ 0,01 por impressão**. -2. **Custo Total:** 10 (impressões geradas) * R$ 0,01 (custo por impressão) = **R$ 0,10**. - -O custo total dessa campanha seria de **dez centavos**. - -## 3. Regras de Atribuição (A Hierarquia de Decisão) - -Quando um usuário interage com múltiplos anúncios antes de comprar, um modelo de atribuição decide qual campanha receberá o crédito pela venda. - -**Princípio Fundamental:** A atribuição é exclusiva. Um pedido vendido **nunca** é atribuído a duas campanhas distintas; o crédito é sempre dado a uma única campanha. - -A decisão segue esta ordem de prioridade: - -1. **Prioridade 1: Campanhas Offsite** - - Se existe uma campanha _offsite_ ativa (trazendo tráfego externo para o site) e ela foi o último ponto de contato do usuário, ela terá preferência total na atribuição da venda. - -2. **Prioridade 2: Último Clique (Last Click)** - - Na ausência de um clique offsite recente, o sistema procura o _último anúncio_ (dentro da plataforma) que o usuário _clicou_ dentro da janela de 14 dias. - -3. **Prioridade 3: Última Visualização (Last View)** - - Se o usuário não clicou em nenhum anúncio no período, o sistema atribui a venda ao _último anúncio_ que ele _visualizou_ (desde que seja um tipo de campanha que meça por visualização, como Banner ou Vídeo). - -**Regra de Tempo:** Para que uma conversão seja válida, o evento de interação (clique ou visualização) deve, obrigatoriamente, ter ocorrido _antes_ do pedido ser finalizado. - -## 4. Mapeamento de Produtos na Atribuição - -Uma campanha só pode receber atribuição por produtos que estão _explicitamente atrelados a ela_. - -### 4.1. Campanhas de Produto (Atribuição 1:1) - -- **Como funciona:** Cada anúncio (AD) dentro da campanha representa um produto específico. -- **Lógica:** A atribuição é direta e 1 para 1. O clique no anúncio do "Produto A" só pode gerar conversão para o "Produto A". - -### 4.2. Demais Campanhas (Banner, Vídeo, etc.) (Atribuição N:1) - -- **Como funciona:** Estas campanhas possuem uma _lista_ de produtos associados (SKUs). -- **Lógica:** A interação (clique ou view) com um único criativo (banner ou vídeo) pode gerar atribuição para _qualquer_ um dos produtos contidos nessa lista da campanha. - -**Observação sobre Criativos:** Dentro de uma campanha (ex: Banner), cada criativo (ex: o "Banner A" e o "Banner B") metrifica suas informações de forma independente. Isso permite analisar a performance individual de cada peça de anúncio. - -## 5. Latência de Dados (Atraso na Atribuição) - -É importante notar que existe um atraso natural entre o momento em que o cliente cria o pedido e o momento em que essa venda é associada (atribuída) à campanha correta nos relatórios. - -- **Integração via API:** Atraso de aproximadamente **30 minutos**. -- **Plataforma VTEX:** Atraso de até **2 horas**. +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/2-glossario.md b/pt/docs/2-glossario.md index 5b37b1c..5bbc945 100644 --- a/pt/docs/2-glossario.md +++ b/pt/docs/2-glossario.md @@ -1,16 +1,8 @@ ## 2. Glossário -| Termo | Descrição | -| :--- | :--- | -| **Advertiser (Anunciante)** | Empresas, sellers ou indivíduos que promovem seus produtos, serviços ou ideias através de campanhas. | -| **Publisher (Varejista)** | A entidade que possui e opera a plataforma digital (site, app) e disponibiliza os espaços para a exibição de anúncios. | -| **Campanha** | Ação criada por um anunciante para promover produtos e gerar conversões (vendas). | -| **Impressão** | Contabilizada cada vez que um anúncio é exibido na tela do usuário. | -| **Visualização (View)**| Contabilizada quando uma impressão se torna visível na tela do usuário por um tempo determinado. | -| **Clique** | Interação do usuário ao clicar em um anúncio para ser direcionado à página de destino. | -| **Conversão** | Ação de valor gerada por um anúncio, tipicamente uma venda. | -| **Receita com Anúncios** | Valor obtido pelos varejistas ao monetizarem seus espaços publicitários. | -| **Receita com Vendas** | Valor total obtido por uma empresa a partir das vendas de produtos ou serviços. | -| **CTR (Click-Through Rate)** | Taxa de Cliques. Fórmula: `(Cliques / Impressões) * 100`. Mede a atratividade de um anúncio. | -| **ROAS (Return on Ad Spend)**| Retorno Sobre o Investimento em Publicidade. Fórmula: `Receita Gerada por Anúncios / Custo da Publicidade`. | -| **Taxa de Conversão** | Percentual de conversões em relação ao total de cliques ou visitas. | +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/3-autenticacao.md b/pt/docs/3-autenticacao.md index 93cf4e8..ed6141c 100644 --- a/pt/docs/3-autenticacao.md +++ b/pt/docs/3-autenticacao.md @@ -1,10 +1,8 @@ ## 3. Autenticação -A autenticação é utilizada para envio de catálogo, consumo de relatórios e gerenciamento. As demais chamadas, como consulta de anúncios e notificação de eventos, são públicas e não exigem autenticação. - -Para os endpoints protegidos, as credenciais devem ser enviadas via header HTTP. Solicite as suas credenciais ao gerente de conta. - -| Atributo | Descrição | -| :--- | :--- | -| `x-app-id` | ID exclusivo da sua aplicação para a integração. | -| `x-api-key` | Chave de API associada à sua aplicação. | +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/4-seguranca-de-dados.md b/pt/docs/4-seguranca-de-dados.md index 1dcdfad..caac53f 100644 --- a/pt/docs/4-seguranca-de-dados.md +++ b/pt/docs/4-seguranca-de-dados.md @@ -1,27 +1,8 @@ # 4. Segurança de Dados -A segurança dos dados é um pilar fundamental da nossa plataforma. Desde o início, nossa arquitetura foi projetada para garantir que nenhuma informação sensível seja coletada e que os dados dos usuários permaneçam sempre protegidos e não identificáveis. - -## Dados Não Identificáveis - -Não coletamos dados sensíveis dos usuários, como nome, e-mail ou documentos. As informações que recebemos, como e-mails ou CPFs (PII - *Personally Identifiable Information*), já chegam em nossa plataforma com um hash criptográfico irreversível. - -Isso significa que o dado original nunca trafega ou é armazenado em nossos sistemas. O resultado é um identificador anônimo que nos permite agrupar comportamentos e audiências sem nunca saber quem é o usuário real. - -**Por que isso é seguro?** - -* **Irreversibilidade:** O processo de hashing é uma via de mão única. Mesmo que alguém tivesse acesso ao hash, não conseguiria descobrir o dado original. -* **Anonimato:** Como não armazenamos o dado original, não temos como identificar o usuário. Para todos os efeitos, os dados são anônimos. - -## Criptografia em Trânsito e em Repouso - -Todos os dados, sejam eles identificadores anônimos ou informações sobre campanhas e anúncios, são tratados com os mais altos padrões de segurança: - -* **Criptografia em Trânsito:** Toda a comunicação entre nossos sistemas e com parceiros é feita utilizando protocolos seguros como TLS 1.2+, garantindo que os dados não possam ser interceptados durante a transferência. -* **Criptografia em Repouso:** Os dados armazenados em nossos bancos de dados e sistemas de arquivos são criptografados. Utilizamos soluções robustas e reconhecidas no mercado, como **Amazon RDS**, **Amazon S3**, **Amazon Redshift** e **Snowflake**, que aplicam criptografia AES-256, um dos algoritmos mais seguros existentes. - -## Acesso Restrito - -O acesso aos dados é rigorosamente controlado e limitado a um grupo seleto de engenheiros e analistas sêniores. Cada acesso é auditado e monitorado, e as permissões são concedidas com base no princípio do menor privilégio, ou seja, cada pessoa tem acesso apenas ao que é estritamente necessário para realizar seu trabalho. - -Essa combinação de dados não identificáveis, criptografia de ponta a ponta e controle de acesso rigoroso garante que a sua informação e a de seus clientes estejam sempre seguras. +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/5-integracao-de-anuncios.md b/pt/docs/5-integracao-de-anuncios.md index d77636b..222a515 100644 --- a/pt/docs/5-integracao-de-anuncios.md +++ b/pt/docs/5-integracao-de-anuncios.md @@ -1,24 +1,8 @@ # 5. Integração de Anúncios -Esta seção fornece informações detalhadas sobre como se integrar à plataforma VTEX Ads para exibir anúncios em seu site. - -## 5.0 Visão Geral do Fluxo de Integração - -<img src="../../diagrams/images/pt/integration-end-to-end.png" alt="Fluxo completo de integração com VTEX Ads" /> - -O fluxo de integração completo é dividido em quatro fases principais que se retroalimentam continuamente: - -1. **Preparação e Onboarding:** Alinhe escopo e cronograma com a equipe da VTEX Ads, receba as credenciais de API e valide acesso a ambientes e webhooks. -2. **Sincronização de Dados Operacionais:** Carregue catálogo (produtos e inventário) e, opcionalmente, audiências. Essa etapa garante que apenas produtos disponíveis e segmentações válidas estejam aptos a aparecer. -3. **Entrega de Anúncios:** Estruture os placements do site, configure convenções de nome e consulte anúncios em tempo real para cada contexto (home, busca, categoria, PDP etc.), exibindo o selo “Patrocinado”. -4. **Mensuração e Otimização:** Dispare os eventos de impressão, visualização, clique e conversão usando `navigator.sendBeacon()`, monitore as métricas de desempenho e ajuste lances, segmentações e posicionamentos de acordo com os resultados. - -As seções seguintes detalham como executar cada uma dessas fases, com exemplos de requisições e boas práticas específicas. - -- [5.1. Integração via API](./5.1-integracao-via-api.md): Para uma integração mais personalizada, use nossa API REST para gerenciar todo o ciclo de vida do anúncio. -- [5.2. Integração VTEX](./5.2-integracao-vtex.md): Se sua loja estiver na plataforma VTEX, use nosso aplicativo VTEX IO para simplificar o processo. -- [5.3. Sincronização de Catálogo](./5.3-sincronizacao-de-catalogo.md): Mantenha seu catálogo de produtos e inventário sincronizados com a VTEX Ads. -- [5.4. Integração de Audiências](5.4-integracao-de-audiencias.md): Envie dados de audiência para melhorar a segmentação e a relevância dos anúncios. -- [5.5. Consulta de Anúncios](5.5-consulta-de-anuncios.md): Requisite à API os anúncios que devem ser exibidos em diferentes páginas e contextos. -- [5.5.1. Recomendação de Nomes de Placements](5.5.1-recomendacao-de-nomes-de-placements.md): Padrão recomendado de nomenclatura de placements para medições precisas. -- [5.6. Eventos](5.6-eventos.md): Notifique a API sobre as interações dos usuários com os anúncios e as conversões. +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/5.1-integracao-via-api.md b/pt/docs/5.1-integracao-via-api.md index e5ce8ae..d60f292 100644 --- a/pt/docs/5.1-integracao-via-api.md +++ b/pt/docs/5.1-integracao-via-api.md @@ -1,22 +1,8 @@ # 5.1 Integração via API -A integração é fundamentada em três pilares que garantem o funcionamento da solução. - -### Pilares da Integração - -1. **[Sincronização de Catálogo](5.3-sincronizacao-de-catalogo.md):** Manter a VTEX Ads sincronizada com seu catálogo de produtos e inventário (preço e estoque). Essencial para anúncios de produto. -2. **[Consulta de Anúncios](5.5-consulta-de-anuncios.md):** Sua plataforma requisita à API os anúncios que devem ser exibidos em diferentes páginas e contextos. -3. **[Eventos](5.6-eventos.md):** Sua plataforma notifica a API sobre todas as interações do usuário com os anúncios e, crucialmente, sobre as conversões (vendas). - -### Tipos de Anúncios - -| Tipo de Anúncio | API Type | Descrição | -| :--- | :--- |:------------------------------------------------| -| **Sponsored Products** | `product` | Anúncios de produtos individuais. | -| **Display** | `banner` | Anúncios visuais (imagem estática ou vídeo). | -| **Sponsored Brands** | `sponsored_brand` | Anúncios de marca com título, logo e produtos. (imagem estática ou vídeo) | -| **Digital Signage** | `digital_signage`| Conteúdo para telas e totens físicos. | - -### Integração de Audiências - -Direcione anúncios para públicos específicos para aumentar a relevância. Veja mais em [Integração de Audiências](5.4-integracao-de-audiencias.md). +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/5.2-integracao-vtex.md b/pt/docs/5.2-integracao-vtex.md index ef60b34..86bf2c0 100644 --- a/pt/docs/5.2-integracao-vtex.md +++ b/pt/docs/5.2-integracao-vtex.md @@ -1,32 +1,8 @@ # 5.2 Integração com VTEX (VTEX IO App) -Para lojas na plataforma VTEX, a Newtail oferece um aplicativo de storefront (`Newtail Media APP VTEX`) que simplifica drasticamente a implementação. O app já inclui componentes visuais e toda a lógica para consulta de anúncios e notificação de eventos. -* **Passo 1: Sincronização do Catálogo** - * A sincronização do catálogo de produtos é um pré-requisito. Ela pode ser feita de duas formas: - 1. **Via API:** Fornecendo à Newtail as chaves de API para leitura do seu catálogo. - 2. **Via XML:** Fornecendo um link para um feed XML no formato do Google Shopping, que deve conter o campo `SKU` para identificação do produto. - -* **Passo 2: Instalação do App** - 1. **Adicionar como Dependência:** No arquivo `manifest.json` do seu tema, adicione `"newtail.media": "0.x"` ao `peerDependencies`. - 2. **Instalar o App:** Execute o comando `vtex install newtail.media@0.x` no seu terminal. - -* **Passo 3: Configuração** - 1. **ID do Publisher:** No admin da sua loja VTEX, acesse `Configurações da Loja > Newtail Media` e insira o seu `Publisher ID` fornecido pela Newtail. - 2. **Política de Conteúdo (CSP):** Adicione as seguintes diretivas ao seu `policies.json`: - ```json - { - "contentSecurityPolicy": { - "default-src": ["'self'", "newtail-media.newtail.com.br"], - "connect-src": ["'self'", "newtail-media.newtail.com.br"] - } - } - ``` - -* **Passo 4: Uso dos Blocos** - * Declare os blocos do app nos templates do seu tema para exibir os anúncios. - - * **Componentes Disponíveis:** - * `newtail-media-banner`: Renderiza banners patrocinados. - * `newtail-media-shelf`: Renderiza uma prateleira de produtos patrocinados. - * `newtail-media-search`: Adiciona selos "Patrocinado" aos produtos nos resultados de busca. - * `newtail-media-conversion`: Componente essencial que gerencia o envio de eventos de conversão. **Deve ser incluído em todas as páginas.** \ No newline at end of file +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/5.3-sincronizacao-de-catalogo.md b/pt/docs/5.3-sincronizacao-de-catalogo.md index a37925c..ccfb70c 100644 --- a/pt/docs/5.3-sincronizacao-de-catalogo.md +++ b/pt/docs/5.3-sincronizacao-de-catalogo.md @@ -1,193 +1,8 @@ ## 5.3. Sincronização de Catálogo -O primeiro passo é a sincronização, que ocorre em duas frentes: - -> **Nota para lojas VTEX:** Para lojas na plataforma VTEX, a sincronização do catálogo ocorre de forma transparente, não sendo necessária nenhuma integração adicional para este fim. - -#### **Sincronização de Produtos** -Envio das informações cadastrais dos produtos. Requer autenticação. - -* **Endpoint:** `POST https://api-retail-media.newtail.com.br/product/bulk/products` -* **Limites:** 500 produtos por requisição; 3 requisições simultâneas. - -| Campo | Descrição | Tipo | Obrigatório? | -| :--- | :--- | :--- | :--- | -| `product_sku` | ID/SKU único do produto. | String | Sim | -| `parent_sku` | SKU do produto pai (para variações). | String | Não | -| `name` | Nome do produto. | String | Sim | -| `url` | URL canônica da página do produto. | String | Sim | -| `image_url`| URL da imagem principal do produto. | String | Não | -| `categories` | Lista de categorias. | Array[String] | Sim | -| `brand` | Marca do produto. | String | Não | -| `gtins` | Códigos de barras (EAN). **Obrigatório para campanhas na VTEX Ads Network.**| Array[String] | Não/Sim | -| `tags` | "Etiquetas" para contextualizar buscas. Máx. 10 por SKU, 64 chars por tag. Apenas para campanhas de `product`. | Array[String] | Não | -| `sellers` | Lista de sellers que vendem o produto (em um marketplace). | Array[String] | Não | -| `metadata` | Objeto para informações adicionais (chave-valor). | Object | Não | - ---- - -### **Estruturação de Categorias** - -> **Importante:** O campo `categories` é crucial para a segmentação de campanhas e a organização de produtos. Ele deve ser estruturado de forma hierárquica, representando o caminho completo desde a categoria raiz até a categoria específica do produto. - -O campo `categories` deve ser um array de strings, onde cada string é um nível da árvore de categorias. A hierarquia é construída enviando todas as categorias pai até a mais específica. - -**Exemplo Correto:** - -Para um produto na categoria de perfumes "Para Mulher", o array `categories` deveria ser: - -```json -"categories": [ - "Beleza", - "Fragrâncias", - "Perfume", - "Para Mulher" -] -``` - -Essa estrutura permite que a plataforma entenda o contexto do produto em todos os níveis, do mais amplo ("Beleza") ao mais específico ("Para Mulher"). - ---- - -**Exemplo de Requisição:** - -```bash -curl --location 'https://api-retail-media.newtail.com.br/product/bulk/products' \ ---header 'x-app-id: XXXX' \ ---header 'x-api-key: YYYY' \ ---header 'Content-Type: application/json' \ ---data '[ - { - "product_sku": "allan", - "name": "allan", - "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616", - "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629", - "categories": [ - "Beleza", - "Fragrâncias", - "Perfume", - "Para Mulher" - ], - "brand": "SALVADOR DALÍ", - "profit_margin": null, - "gtins": [ - "3331438450103" - ], - "sellers": [], - "skus": [] - }, - { - "product_sku": "allan2", - "name": "allan2", - "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616", - "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629", - "categories": [ - "Beleza", - "Fragrâncias", - "Perfume", - "Para Mulher" - ], - "brand": "SALVADOR DALÍ", - "profit_margin": null, - "gtins": [ - "3331438450103" - ], - "sellers": [], - "skus": [], - "tags": ["Abart", "Mega Maio"] - } -]' -``` - - -**Exemplo de Resposta com Sucesso:** - -``` -Status: 202 Accepted -Content-Type: application/json - -{ - "messages": [ - "products will be processed soon" - ] -} -``` - ---- - -#### **Sincronização de Inventário** -Envio das informações de preço e estoque dos produtos. Requer autenticação. - -* **Endpoint:** `POST https://api-retail-media.newtail.com.br/product/bulk/inventories` -* **Limites:** 500 produtos por requisição; 3 requisições simultâneas. - -| Campo | Descrição | Tipo | Obrigatório? | -| :--- | :--- | :--- | :--- | -| `product_sku` | ID/SKU único do produto. | String | Sim | -| `price` | Preço atual do produto. | Float | Sim | -| `promotional_price` | Preço "de" (tabelado/original). | Float | Sim | -| `is_available` | Produto disponível (em estoque). | Boolean | Sim | -| `store_id` | Identificação da loja. Caso não seja enviado o store_id, será interpretado que essa informação de inventário será utilizado para todas as lojas. | String | Não | -| `metadata` | Objeto para informações adicionais (chave-valor). | Object | Não | - -**Exemplo de Requisição:** - -```bash -curl --location 'https://api-retail-media.newtail.com.br/product/bulk/inventories' \ ---header 'x-app-id: XXXX' \ ---header 'x-api-key: YYYY' \ ---header 'Content-Type: application/json' \ ---data '[ - { - "product_sku": "120210", - "store_id": "1", - "price": 18.20, - "promotional_price": 16.32, - "is_available": true - }, - { - "product_sku": "120212", - "price": 18.20, - "promotional_price": 0, // Remove o preço promocional - "is_available": true - } -]' -``` - -**Exemplo de Resposta com Sucesso:** - -``` -Status: 202 Accepted -Content-Type: application/json - -{ - "messages": [ - "inventory will be processed soon" - ] -} -``` - ---- - -### **Boas Práticas para Sincronização** - -1. **Sincronização Inicial Completa:** - * Envie todo o catálogo na primeira sincronização. - * Divida em lotes de até 500 produtos para evitar timeouts. - -2. **Atualizações Incrementais:** - * Após a sincronização inicial, envie apenas produtos novos ou alterados. - * Mantenha um registro da última data de modificação de cada produto. - -3. **Frequência de Atualização:** - * Preços e estoque: Atualize pelo menos uma vez ao dia, idealmente em tempo real para mudanças significativas. - * Informações cadastrais: Atualize quando houver alterações. - -4. **Tratamento de Erros:** - * Implemente retentativas com backoff exponencial para falhas temporárias. - * Monitore as respostas da API para identificar problemas persistentes. - -5. **Validação de Dados:** - * Verifique se todos os campos obrigatórios estão preenchidos. - * Garanta que URLs de produtos e imagens sejam válidas e acessíveis. - * Certifique-se de que as categorias seguem a estrutura hierárquica recomendada. \ No newline at end of file +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/5.4-integracao-de-audiencias.md b/pt/docs/5.4-integracao-de-audiencias.md index 8321d86..16ecb6d 100644 --- a/pt/docs/5.4-integracao-de-audiencias.md +++ b/pt/docs/5.4-integracao-de-audiencias.md @@ -1,98 +1,8 @@ ## 5.4. Integração de Audiências -> **Nota:** A integração de audiências é opcional, mas altamente recomendada para melhorar a segmentação de campanhas e a relevância dos anúncios. - -A integração de audiências possui uma única forma de integração: **Envio em Lote (Batch)** para o bucket S3 fornecido pela VTEX Ads. - -> **Importante:** A integração via FTP/SFTP está **deprecated** e só deve ser utilizada para implantações legadas. Novos projetos devem usar exclusivamente o bucket S3. - -> **Alerta:** Se não existir integração de audiência, é necessário abrir um ticket junto ao Account Manager solicitando a pré-população das informações de segmentação com dados base (`STATE`, `CITY`, `GENDER` e `AGE`). Também é possível enviar uma lista de audiências para cadastro, e recomendamos manter uma atualização periódica dessas audiências. - -### Envio em Lote (Batch) — Bucket S3 - -A conexão de integração ocorre através do envio periódico das audiências para o bucket S3 dedicado ao publisher. As credenciais de acesso (chave/segredo IAM ou role para cross-account) e o caminho base do bucket devem ser solicitados ao seu contato na Newtail. - -* **Formato do Arquivo:** `Parquet` com compressão `Snappy`. -* **Padrão de Diretório (chave S3):** Suba os arquivos seguindo o padrão: - `s3://<bucket>/<PREFIXO>/audiences/YYYY/mm/dd/TIMESTAMP.parquet.snappy` - -| Atributo | Descrição | Exemplo | -| :-------- | :---------------------------------------------------------------------------------------------------- | :----------- | -| `PREFIXO` | O prefixo será informado pela Newtail. | `xyz` | -| `YYYY` | Ano da geração com 4 dígitos. | `2023` | -| `mm` | Mês da geração com dois dígitos (Janeiro = 01 e dezembro = 12). | `09` | -| `dd` | Dia da geração com dois dígitos (de 01 até 31). | `31` | -| `TIMESTAMP`| Timestamp é a quantidade de segundos desde 1970 (o nome do arquivo pode ser qualquer coisa, o timestamp é apenas uma sugestão que nunca irá se repetir). | `1694812122` | - -> **Recomendação para o envio:** Na integração inicial, é fundamental que todos os dados sejam enviados. E esses dados podem ser enviados em múltiplos arquivos (dependendo do tamanho da base, um bom número é 1 milhão de linhas por arquivo). Após a primeira integração, o ideal é que seja enviado, somente o delta das linhas que tiveram alguma modificação. - -> **Compatibilidade legada:** Se você já estava integrado via SFTP, entre em contato com o time VTEX Ads para planejar a migração para o bucket S3. O fluxo via SFTP deixará de receber novos aprimoramentos e poderá ser descontinuado. - -### Alternativa sem integração prévia (runtime) - -Se você optar por não integrar audiências via batch, ainda é possível utilizar segmentações em runtime enviando os dados no campo `segmentation` da requisição de consulta de anúncios. Consulte a seção [5.5. Consulta de Anúncios](5.5-consulta-de-anuncios.md). - -### Atributos do Arquivo de Audiências - -A maioria dos atributos não são obrigatórios, no entanto, quanto maior for o preenchimento de todas essas informações, a relevância será melhor. - -> As colunas são **case sensitive**. Mantenha o nome das colunas da forma como elas estão sendo apresentadas. - -| Coluna | Tipo | Obrigatório? | Descrição | -| :------------------ | :----- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `CUSTOMER_ID` | String | Sim | Identificador único do cliente. | -| `EMAIL_HASHED` | String | Não | PII baseado no e-mail do cliente. | -| `PHONE_HASHED` | String | Não | PII baseado no telefone principal do cliente. | -| `SOCIAL_ID_HASHED` | String | Não | PII baseado no CPF do cliente. | -| `FIRST_NAME_HASHED` | String | Não | PII baseado no Primeiro Nome do cliente. | -| `LAST_NAME_HASHED` | String | Não | PII baseado no Último nome do cliente. | -| `GENDER` | String | Não | Indica qual o sexo do cliente (`F` para feminino, `M` para masculino, `O` para outros, `NULL` para não identificados). | -| `AGE` | Int | Não | Indica a idade do cliente. | -| `CEP` | String | Não | Indica qual o CEP do endereço do cliente. | -| `COUNTRY` | String | Não | Indica qual o país do usuário. | -| `STATE` | String | Não | Indica o estado onde reside o cliente. | -| `CITY` | String | Não | Indica a cidade onde reside o cliente. | -| `NEIGHBORHOOD` | String | Não | Indica o bairro onde reside o cliente. | -| `AUDIENCES` | String | Não | Uma lista de audiências, separadas por ponto e vírgula (;). | -| `NBO_PRODUCTS` | String | Não | Uma lista de SKU de produtos, separadas por ponto e vírgula (;). | -| `NBO_CATEGORIES` | String | Não | Uma lista de categorias, separadas por ponto e vírgula (;). A lista pode receber uma árvore de categorias usando o " > " como separador (ex: `Tablets;Bebidas > Bebidas Não Alcoólicas;Livros > Gastronomia > Guias de Bares e Restaurantes`). | - -### Hash dos Campos - -Dados confidenciais precisam ser criptografados antes de serem enviados usando o algoritmo **SHA256**. - -* `EMAIL_HASHED` -* `PHONE_HASHED` -* `SOCIAL_ID_HASHED` -* `FIRST_NAME_HASHED` -* `LAST_NAME_HASHED` - -> Antes de gerar o hash dos dados é necessário remover todos os **ESPAÇOS** e converter para **MINÚSCULO** os seus valores. -> Para o atributo `PHONE_HASHED`, será necessário formatá-lo no padrão **E.164** e incluir o código de chamada do país. - -#### Formato E.164 - -1. Remova todos os caracteres não numéricos, como espaços, traços, parênteses e símbolos. -2. Adicione o código do país com o sinal de adição (+) no início. -3. Adicione o código de área (se aplicável) sem o zero inicial. -4. Inclua o número de telefone local sem o zero inicial (caso aplicável). - -**Exemplo:** - -* Um número de telefone do Brasil, com código de área 11 e número local 98765-4321, seria formatado como: `+5511987654321` - -#### Criando um HASH em Python - -```python -import re -import hashlib - -hash_obj = hashlib.sha256() - -def create_hash(x): - cleaned = re.sub('\s+', '', x.lower()) - hash_obj.update(cleaned.encode('utf-8')) - return hash_obj.hexdigest() - -create_hash(' Allan ') #=> 8c01ade3cb71d3ac7c718ed5a0c565155a4c05a216d9e59013c5d7b49e916914 -``` +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/5.5-consulta-de-anuncios.md b/pt/docs/5.5-consulta-de-anuncios.md index ca6129a..9638118 100644 --- a/pt/docs/5.5-consulta-de-anuncios.md +++ b/pt/docs/5.5-consulta-de-anuncios.md @@ -1,395 +1,8 @@ ## 5.5. Consulta de Anúncios -Com o catálogo sincronizado, sua plataforma requisita anúncios para preencher os espaços publicitários (`placements`). A requisição é um `POST` e o `publisher_id` deve ser informado na URL. - -* **Endpoint:** `POST https://newtail-media.newtail.com.br/v1/rma/:publisher_id` -* **Content-Type:** Todas as requisições devem incluir o header `Content-Type: application/json` - -#### Boas Práticas de Requisição - -- **Persistência HTTP:** Prefira conexões persistentes (`Connection: keep-alive`). -- **Timeout:** Aplique timeout de 500–600 ms para a consulta (ver 5.6 para eventos). - -#### **Parâmetros da Requisição** - -| Campo | Descrição | Tipo | Obrigatoriedade | -| :--- | :--- | :--- | :--- | -| `session_id` | Identificador persistente do visitante (≥ 14 dias). Para aplicativos móveis, deve-se enviar o ID do dispositivo como session_id (GAID no Android e IDFA no iOS), de forma que a sessão seja mantida indefinidamente. | String | Sim | -| `user_id` | ID único do usuário logado (alfanumérico). | String | Não (Recomendado) | -| `store_id` | Filtra anúncios por estoque de uma loja específica. | String | Não | -| `channel` | Canal de acesso: `site`, `msite`, `app` (para consulta). | String | Sim | -| `context` | Contexto: `home`, `category`, `search`, `product_page`, `brand_page`, `digital_signage`.| String | Sim | -| `term` | Termo buscado pelo usuário. | String | Apenas `context: 'search'` | -| `category_name` | Categoria navegada (breadcrumb completo).| String | Apenas `context: 'category'`| -| `product_sku` | SKU do produto sendo visualizado. | String | Apenas `context: 'product_page'` | -| `brand_name` | Nome da marca sendo visualizada. | String | Apenas `context: 'brand_page'` | -| `device_id` | ID único do dispositivo (tela, totem). | String | Apenas `context: 'digital_signage'` | -| `store_name` | Nome da loja onde o dispositivo está localizado. | String | Apenas `context: 'digital_signage'` | -| `placements` | Objeto que define os espaços (`placements`) de anúncio. | Object | Sim | -| `placements.{name}.quantity` | Quantidade de anúncios desejada. | Integer | Sim | -| `placements.{name}.size` | Tamanho esperado (Imagem: `desktop`/`mobile`; Vídeo: `1080p`/`720p`/`480p`/`360p`/`320p`). | String | Apenas `types: ['banner', 'sponsored_brand']` | -| `placements.{name}.types` | Tipos permitidos (`product`, `banner`, etc.). | Array[String] | Sim | -| `placements.{name}.assets_type`| Mídias aceitas (`image`, `video`). Padrão: `["image"]`. | Array[String] | Apenas `types: ['banner', 'sponsored_brand']` | -| `placements.{name}.allow_sku_duplications` | Permite retornar o mesmo SKU mais de uma vez dentro do mesmo placement. | Boolean | Não (Default=false) | -| `userAgent` | Identificação do ambiente do cliente (campo no corpo, não o header HTTP `User-Agent`). | String | Não | -| `segmentation` | Dados para segmentação em tempo real. | Array[Object] | Não | -| `segmentation.#.key` | O tipo de segmentação. | String | Não | -| `segmentation.#.values` | Array de valores para a segmentação. | Array[String] | Não | -| `tags` | "Etiquetas" para contextualizar buscas (principalmente em `search`). Máx. 10 por SKU, 64 chars por tag. Apenas para campanhas de `product`. | Array[String] | Não | -| `brand` | Nome do site do publisher. | String | Obrigatório quando o publisher possui mais de um site | -| `dedup_campaign_ads` | Deduplica por campanha (no máximo 1 anúncio por campanha na resposta). | Boolean | Não (Default=false) | -| `dedup_ads` | Deduplica por `ad_id` entre múltiplos placements (use apenas ao consultar múltiplos placements ao mesmo tempo). | Boolean | Não (Default=false) | -| `skus` | Filtra os resultados de anúncios para retornar apenas ads dos SKUs especificados. Compatível apenas com Sponsored Products (campanhas de produto). | Array[String] | Não | - -##### Campos por Contexto - -| Contexto | Campos adicionais obrigatórios | -| :--- | :--- | -| `home` | — | -| `search` | `term` | -| `category` | `category_name` | -| `product_page` | `product_sku` | -| `brand_page` | `brand_name` | -| `digital_signage` | `device_id`, `store_name` | - -#### **⚠️ Regras Importantes de Contexto e Elegibilidade de Anúncios** - -##### Limitações de Filtro - -> **Importante:** Não é possível fazer filtro por `placement` específico. A seleção de anúncios é baseada no `context` e nos parâmetros da requisição. - -##### Elegibilidade por Contexto - -###### Contexto `home` - -No contexto **home**, podem ser retornados: - -- ✅ **Anúncios de Banner/Video/Sponsored Brands** que utilizem **categoria** como critério de segmentação -- ✅ **Anúncios de Produtos (Sponsored Products)** também são elegíveis - -**Exemplo:** -```json -{ - "context": "home", - "placements": { - "site_home_middle_banner": { - "quantity": 3, - "types": ["banner", "sponsored_brand"], - "assets_type": ["image", "video"], - "size": "desktop" - }, - "site_home_vitrine_product": { - "quantity": 10, - "types": ["product"] - } - } -} -``` - -###### Contexto `search` - -No contexto **search**, podem ser retornados: - -- ✅ **Anúncios de Banner/Video/Sponsored Brands** que sejam de **keyword** (palavra-chave) -- ✅ **Qualquer campanha de Produto (Sponsored Products)** - -**⚠️ Match Exato de Keywords:** - -O match de keywords no contexto `search` é **exato** (não há stemming/sinônimos). Isso significa que: - -- O anunciante **precisa especificar exatamente** quais keywords deseja utilizar na campanha de Banner/Video/Sponsored Brands -- Se o usuário buscar "tênis nike", o anúncio só será elegível se o anunciante cadastrou exatamente a keyword "tênis nike" -- Não há correspondência aproximada ou por palavras semelhantes - -**Exemplo:** -```json -{ - "context": "search", - "term": "tênis nike", - "placements": { - "site_search_top_banner": { - "quantity": 1, - "types": ["banner", "sponsored_brand"], - "assets_type": ["image"], - "size": "desktop" - }, - "site_search_vitrine_product": { - "quantity": 20, - "types": ["product"] - } - } -} -``` - -**Comportamento esperado:** -- **Banner/Sponsored Brand:** Só aparecerá se o anunciante cadastrou a keyword exata "tênis nike" na campanha -- **Sponsored Products:** Produtos relacionados ao termo de busca serão retornados - -###### Contexto `category` - -No contexto **category**, podem ser retornados: - -- ✅ **Anúncios de Banner/Video/Sponsored Brands** que utilizem a **categoria** correspondente -- ✅ **Anúncios de Produtos (Sponsored Products)** da categoria - -**Exemplo:** -```json -{ - "context": "category", - "category_name": "Esportes > Calçados > Tênis", - "placements": { - "site_category_top_banner": { - "quantity": 1, - "types": ["banner", "sponsored_brand"], - "assets_type": ["image", "video"] - } - } -} -``` - -###### Contexto `product_page` - -No contexto **product_page**, podem ser retornados: - -- ✅ **Anúncios de Produtos (Sponsored Products)** relacionados ao produto visualizado - -**Exemplo:** -```json -{ - "context": "product_page", - "product_sku": "12345", - "placements": { - "site_product_recommendation": { - "quantity": 5, - "types": ["product"] - } - } -} -``` - -###### Contexto `brand_page` - -No contexto **brand_page**, podem ser retornados: - -- ✅ **Anúncios de Banner/Video/Sponsored Brands** da marca -- ✅ **Anúncios de Produtos (Sponsored Products)** da marca - -**Exemplo:** -```json -{ - "context": "brand_page", - "brand_name": "Nike", - "placements": { - "site_brand_top_banner": { - "quantity": 1, - "types": ["banner", "sponsored_brand"], - "assets_type": ["image"], - "size": "desktop" - }, - "site_brand_shelf_product": { - "quantity": 12, - "types": ["product"] - } - } -} -``` - -###### Contexto `digital_signage` - -No contexto **digital_signage**, podem ser retornados anúncios para telas/totens físicos. - -**Exemplo:** -```json -{ - "context": "digital_signage", - "device_id": "totem-abc-001", - "store_name": "Loja Paulista", - "placements": { - "totem_home_main_video": { - "quantity": 1, - "types": ["banner"], - "assets_type": ["video"], - "size": "720p" - } - } -} -``` - -#### **Resposta da Consulta** -A resposta é um JSON onde cada chave é um nome de `placement`. A estrutura de cada anúncio na resposta depende do seu tipo. - -##### **Campos Comuns de Resposta para Todos os Tipos de Anúncios** -Estes campos estão presentes em todos os tipos de anúncios: - -| Campo | Descrição | -| :--- | :--- | -| `{placementName}.#.ad_id` | ID único do anúncio. | -| `{placementName}.#.type` | Tipo do anúncio (`product`, `banner`, `sponsored_brand`, `digital_signage`). | -| `{placementName}.#.click_url`| **URL para notificar o evento de clique.** | -| `{placementName}.#.impression_url`| **URL para notificar o evento de impressão.**| -| `{placementName}.#.view_url` | **URL para notificar o evento de visualização.** | -| `{placementName}.#.seller_id` | ID do vendedor do produto anunciado (opcional). | - -##### **Campos de Resposta Específicos por Tipo** - -###### **Anúncios de Produto** -Campos adicionais para anúncios do tipo `product`: - -| Campo | Descrição | -| :--- | :--- | -| `{placementName}.#.product_sku`| SKU do produto anunciado. | - -###### **Anúncios de Banner** -Campos adicionais para anúncios do tipo `banner`: - -| Campo | Descrição | -| :--- | :--- | -| `{placementName}.#.media_url`| URL da imagem ou vídeo a ser exibido. | - -###### **Anúncios de Marca Patrocinada** -Campos adicionais para anúncios do tipo `sponsored_brand`: - -| Campo | Descrição | -| :--- | :--- | -| `{placementName}.#.media_url`| URL da imagem ou vídeo a ser exibido. | -| `{placementName}.#.products`| Array de produtos associados à marca patrocinada. | -| `{placementName}.#.products.#.product_sku`| SKU do produto associado. | -| `{placementName}.#.products.#.media_url`| URL da imagem do produto. | - -###### **Anúncios de Digital Signage** -Campos adicionais para anúncios do tipo `digital_signage`: - -| Campo | Descrição | -| :--- | :--- | -| `{placementName}.#.media_url`| URL da imagem ou vídeo a ser exibido. | -| `{placementName}.#.duration`| Duração da exibição do anúncio em segundos. | - -##### Exemplo de Resposta (multi-placement) - -```json -{ - "site_home_middle_banner": [ - { - "ad_id": "ad-001", - "type": "banner", - "media_url": "https://cdn.example.com/banner1.jpg", - "impression_url": "https://events.../impression/abc", - "view_url": "https://events.../view/abc", - "click_url": "https://events.../click/abc" - } - ], - "site_home_vitrine_product": [ - { - "ad_id": "ad-101", - "type": "product", - "product_sku": "SKU-123", - "seller_id": "SELLER-9", - "impression_url": "https://events.../impression/def", - "view_url": "https://events.../view/def", - "click_url": "https://events.../click/def" - } - ] -} -``` - -### Boas Práticas - -#### Nomenclatura de Placements - -Adote um padrão claro, como `{canal}_{contexto}_{posicao}_{tipo}` (ex: `msite_search_top-shelf_product`). Para recomendações detalhadas, consulte `pt/docs/5.5.1-recomendacao-de-nomes-de-placements.md`. - -| canal | contexto | posição | tipo | exemplo | -| --- | --- | --- | --- | --- | -| site | home | middle | banner | site_home_middle_banner | -| msite | product | top-vitrine | product | msite_product_top-vitrine_product | -| app | search | top-vitrine | product | app_search_top-vitrine_product | -| app | search | top-vitrine | banner | app_search_top-vitrine_banner | -| site | category | bottom-vitrine | banner | site_category_bottom-vitrine_banner | -| site | product | filter-bar | product | site_product_filter-bar_product | - -#### Tamanhos de Imagem Padrão IAB - -Para anúncios do tipo banner, é importante utilizar imagens nos formatos padrão definidos pelo IAB (Interactive Advertising Bureau). Isso garante a compatibilidade e uma melhor experiência visual em diferentes sites e dispositivos. - -**Formatos Principais:** - -* **Retângulo Médio:** 300x250 pixels -* **Leaderboard:** 728x90 pixels -* **Skyscraper Largo:** 160x600 pixels -* **Leaderboard Móvel:** 320x50 pixels -* **Billboard:** 970x250 pixels -* **Meia Página:** 300x600 pixels - -#### Opções de Tamanho para Vídeos - -Para solicitações de anúncios de vídeo, você deve especificar o parâmetro de tamanho para filtrar por resolução de vídeo. As opções disponíveis são: - -* **1080p** (1920x1080 pixels) - Recomendado apenas para vídeos em tela cheia -* **720p** (1280x720 pixels) - Recomendado apenas para vídeos em tela cheia -* **480p** (854x480 pixels) -* **360p** (640x360 pixels) -* **320p** (568x320 pixels) - Recomendado para dispositivos móveis - -**Importante:** Ao solicitar anúncios de vídeo, use apenas o identificador de resolução (ex: `"720p"`) no parâmetro size, não as dimensões completas. Por exemplo, para filtrar por resolução 1280x720, use `"size": "720p"` na sua solicitação de anúncio. - -### Segmentação de Anúncios - -Direcione anúncios para públicos específicos para aumentar a relevância. - -#### **Segmentação em Tempo Real** -Envie dados demográficos ou de audiência diretamente no corpo da **consulta de anúncios**, no campo `segmentation`. - -O campo `segmentation` é um array de objetos, onde cada objeto contém: -- `key`: O tipo de segmentação (ex: "STATE", "CITY", "GENDER") -- `values`: Array de valores para a segmentação - -**Exemplo de Segmentação:** - -```json -[ - { - "key": "STATE", - "values": [ - "RJ" - ] - }, - { - "key": "CITY", - "values": [ - "Rio de Janeiro" - ] - } -] -``` - -**Tipos de Segmentação Disponíveis:** - -| Chave (key) | Descrição | Exemplo de Valores | -| :--- | :--- | :--- | -| `STATE` | Estado do usuário | "SP", "RJ", "MG" | -| `CITY` | Cidade do usuário | "São Paulo", "Rio de Janeiro" | -| `GENDER` | Gênero do usuário | "M", "F" | -| `AGE` | Idade do usuário | "22", "35" | -| `AUDIENCES` | Audiência personalizada | "high_value_customers", "cart_abandoners" | -| `NBO_CATEGORIES` | Indica quais as possíveis categorias que o usuário tem intenção de comprar | "Eletrônicos", "Livros" | - -### Códigos de Resposta e Erros - -- **200 OK:** Consulta processada com sucesso (retorna JSON por placement). -- **422 Unprocessable Entity:** Erro de validação de campos (formato compatível com JSON Schema/Ajv). -- **400 Bad Request / 404 Not Found:** Requisição inválida ou recurso inexistente. -- **429 Too Many Requests:** Limite de requisições excedido. -- **5xx:** Erros internos. - -Exemplo de 422 (parcial): -```json -[ - { - "instancePath": "/context", - "keyword": "enum", - "message": "must be equal to one of the allowed values", - "params": {"allowedValues": ["home","category","search","product_page","brand_page","digital_signage"]}, - "schemaPath": "#/properties/context/enum" - } -] -``` +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/5.5.1-recomendacao-de-nomes-de-placements.md b/pt/docs/5.5.1-recomendacao-de-nomes-de-placements.md index 3b06c7e..a0d76b3 100644 --- a/pt/docs/5.5.1-recomendacao-de-nomes-de-placements.md +++ b/pt/docs/5.5.1-recomendacao-de-nomes-de-placements.md @@ -1,33 +1,8 @@ # 5.5.1. Recomendação de Nomes de Placements -Ter nomes padronizados e claros para os placements é essencial para medir corretamente o desempenho de cada área de anúncios do site/app, facilitar análises e acelerar diagnósticos. - -Modelo recomendado de nomenclatura: - -``` -{meio}_{contexto}_{posicao}_{tipo} -``` - -Onde: -- meio: canal de acesso, ex.: site, msite (site móvel), app -- contexto: página/região de navegação, ex.: home, category, search, product, brand_page, digital_signage -- posicao: localização do bloco na página, ex.: top-vitrine, middle, bottom-vitrine, filter-bar -- tipo: tipo de criativo, ex.: product, banner, sponsored_brand - -Boas práticas: -- Use letras minúsculas e sem espaços (use hífen para compostos, ex.: top-vitrine). -- Evite abreviações obscuras; mantenha consistência entre páginas e canais. -- O nome deve ser estável ao longo do tempo (não inclua datas, campanhas, etc.). - -Exemplos: - -| meio | contexto | posição | tipo | exemplo | -| --- | --- | --- | --- | --- | -| site | home | middle | banner | site_home_middle_banner | -| msite | product | top-vitrine | product | msite_product_top-vitrine_product | -| app | search | top-vitrine | product | app_search_top-vitrine_product | -| app | search | top-vitrine | banner | app_search_top-vitrine_banner | -| site | category | bottom-vitrine | banner | site_category_bottom-vitrine_banner | -| site | product | filter-bar | product | site_product_filter-bar_product | - -Observação: utilize os mesmos termos de canal e contexto que você envia na Consulta de Anúncios (5.5) para manter a rastreabilidade entre requisições e relatórios. \ No newline at end of file +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/5.6-eventos.md b/pt/docs/5.6-eventos.md index 4331497..ca8a8bc 100644 --- a/pt/docs/5.6-eventos.md +++ b/pt/docs/5.6-eventos.md @@ -1,365 +1,8 @@ ## 5.6. Eventos -A notificação de eventos é **crucial** para a atribuição e mensuração. - -#### Boas Práticas - -* **Persistência HTTP:** Use conexões HTTP persistentes (`Connection: keep-alive` no header) para otimizar a performance. -* **Timeout (consulta de anúncios):** Para chamadas de consulta de anúncios (ver seção 5.5), implemente um timeout de 500–600 ms para não prejudicar a experiência do usuário. - -#### **Identificação de Usuário e Sessão** - -* **`session_id`:** Identificador persistente do visitante. Obrigatório em todos os eventos. Deve ser consistente durante a navegação e entre sessões dentro da janela de conversão (≥ 14 dias). O `session_id` deve ser único por usuário e, idealmente, não expirar nesse período. Para aplicativos móveis, deve-se enviar o ID do dispositivo como session_id (GAID no Android e IDFA no iOS), de forma que a sessão seja mantida indefinidamente. -* **`user_id`:** ID único do cliente na plataforma, consistente entre canais. **Obrigatório na conversão**. **Opcional (recomendado)** para impressão, visualização e clique. O `user_id` deve ser o mesmo entre app, website e loja física. - -Após identificar o usuário e a sessão, siga estas diretrizes para o disparo de eventos: - -* **Impressão (`impression_url`):** Dispare o evento imediatamente após decidir exibir os anúncios retornados pelo ad server, mesmo que o Anúncio acabe não sendo exibido ao usuário (por exemplo, devido a bloqueios ou mudanças de layout). -* **Visualização (`view_url`):** Dispare o evento quando pelo menos 50% do Anúncio permanecer dentro do viewport do usuário por 1 segundo contínuo. -* **Clique (`click_url`):** Dispare o evento sempre que o usuário clicar no Anúncio. - -Não é necessário manter o estado dos eventos entre carregamentos de página, mas garanta que cada evento seja enviado apenas uma única vez para o mesmo Anúncio e contexto. - -#### **Notificação de Impressão, Visualização e Clique** - -Envie uma requisição `POST` para a respectiva URL de evento (`impression_url`, `view_url`, `click_url`) fornecida na consulta de anúncios, com um corpo JSON contendo `session_id` (**obrigatório**) e `user_id` (**quando disponível**). - -* **Quando enviar:** `impression_url` quando o Anúncio for renderizado; `view_url` quando o Anúncio estiver visível (se você medir viewability); `click_url` no clique do usuário. -* **URLs de eventos:** sempre use as URLs retornadas pela consulta de anúncios; não as derive manualmente. -* **Content-Type:** Todas as requisições devem incluir o header `Content-Type: application/json` -* **Método Obrigatório (Navegador):** É **obrigatório** usar `navigator.sendBeacon()` para garantir o envio assíncrono sem bloquear a navegação e evitar a perda de eventos quando o usuário navega para outra página ou fecha o navegador. -* **Resposta de Sucesso:** `HTTP 202 Accepted`. - -Veja exemplos de envio no navegador em `examples/EVENTS_IMPRESSIONS_VIEWS_CLICKS_BROWSER.md`. - -**Exemplo de envio de evento usando Beacon API:** - -```javascript -// Função para enviar evento de impressão -function sendImpressionEvent(impressionUrl, userId, sessionId) { - // Dados do evento - const eventData = { - user_id: userId, - session_id: sessionId - }; - - // Verifica se o navegador suporta a Beacon API - if (navigator.sendBeacon) { - // Converte os dados para JSON - const blob = new Blob([JSON.stringify(eventData)], {type: 'application/json'}); - - // Envia o evento de forma assíncrona - const success = navigator.sendBeacon(impressionUrl, blob); - - if (!success) { - console.error('Falha ao enviar evento via Beacon API'); - // Implementar fallback se necessário - } - } else { - // Fallback para navegadores que não suportam Beacon API - const xhr = new XMLHttpRequest(); - xhr.open('POST', impressionUrl, true); // true para assíncrono - xhr.setRequestHeader('Content-Type', 'application/json'); - xhr.send(JSON.stringify(eventData)); - } -} - -// Exemplo de uso -sendImpressionEvent( - 'https://events.newtail-media.newtail.com.br/v1/beacon/impression/123456', - 'user-123', - 'session-456' -); -``` - -> **Importante:** O uso da Beacon API é obrigatório para garantir que os eventos sejam enviados mesmo quando o usuário navega para outra página ou fecha o navegador. Isso evita a perda de eventos e garante uma medição mais precisa. - -#### **Notificação de Conversão** - -Quando uma compra é finalizada, envie os dados do pedido. - -* **Endpoint:** `POST https://events.newtail-media.newtail.com.br/v1/beacon/conversion` -* **Content-Type:** Todas as requisições devem incluir o header `Content-Type: application/json` -* **Corpo da Requisição:** O objeto deve conter os dados do pedido. O preço do item não deve ser multiplicado pela quantidade. - -Veja exemplos de conversão em `examples/EVENTS_CONVERSION_BROWSER.md` (Browser) e `examples/EVENTS_CONVERSION_CURL.md` (cURL). - -| Campo do Pedido | Descrição | Tipo | Obrigatório? | -| :--- | :--- | :--- | :--- | -| `publisher_id` | ID do publisher. | String | Sim | -| `user_id` | ID do usuário que realizou a compra. | String | Sim | -| `session_id` | ID da sessão da compra. | String | Sim | -| `order_id` | ID do pedido. | String | Sim | -| `created_at` | Data/hora do pedido (ISO 8601 em UTC). | String | Sim | -| `items` | Lista de itens do pedido. | Array[Item] | Sim | -| `channel` | Canal de venda (ex.: ecommerce, app, loja física). | String | Sim | -| `brand` | Marca/site onde ocorreu a venda (necessário quando existe mais de um site). | String | Não/Sim | -| `gender` | Indica qual o sexo do cliente. F: para feminino, M: para masculino, O: para outros, null: para não identificados. | String | Não (Recomendado) | -| `uf` | Indica o estado da compra do pedido. | String | Não (Recomendado) | -| `city` | Indica qual o nome da cidade o cliente comprou. | String | Não (Recomendado) | -| `is_company` | Indica se a venda foi feita para pessoa física ou jurídica. | Boolean | Não (Recomendado) | -| `email_hashed` | E-mail do usuário em formato hash (SHA256). | String | Sim | -| `phone_hashed`| Telefone do usuário em hash (SHA256). | String | Não (Recomendado) | -| `social_id_hashed`| CPF/CNPJ do usuário em hash (SHA256). | String | Não (Recomendado) | -| `first_name_hashed` | Identificação do Primeiro Nome do usuário (hash). | String | Não (Recomendado) | -| `last_name_hashed` | Identificação do Último Nome do usuário (hash). | String | Não (Recomendado) | - -> Normalização recomendada para hashing: -> - `email_hashed`: e-mail em lowercase e trim, sem espaços extras; hash SHA-256 em hexadecimal. -> - `phone_hashed`: telefone em formato E.164 (ex.: +5511999999999), sem máscaras; hash SHA-256 em hexadecimal. -> - `social_id_hashed`: CPF/CNPJ somente dígitos (sem pontos/traços); hash SHA-256 em hexadecimal. -> - `first_name_hashed` / `last_name_hashed`: nomes normalizados (trim, sem espaços duplos); hash SHA-256 em hexadecimal. - -#### **Estrutura dos Itens do Pedido** - -##### Campos do Objeto Item - -| Campo | Descrição | Tipo | Obrigatoriedade | -|-------|-----------|------|-----------------| -| `sku` | Identificação única do SKU do produto | String | **Obrigatório** | -| `quantity` | Quantidade comprada do produto | Double | **Obrigatório** | -| `price` | Preço original do produto (preço "de") | Double | **Obrigatório** | -| `promotional_price` | Preço promocional do produto (preço "por") | Double | **Obrigatório** | -| `seller_id` | Identificação do vendedor/seller | String | Opcional | -| `product_id` | Identificação única do produto que engloba o SKU | String | Opcional | - -##### ⚠️ Observações Importantes - -1. **Valores unitários**: Os campos `price` e `promotional_price` devem conter o valor **unitário** do produto, **não** multiplicado pela quantidade -2. **Campos obrigatórios para mensuração**: Se `price` e `promotional_price` não forem informados corretamente, a conversão **não poderá ser mensurada** -3. **Formato monetário**: Valores devem ser enviados como números decimais (ex: 1899.00) - -#### **Exemplos de Utilização** - -##### Exemplo de Item Individual -```json -{ - "sku": "12221", - "seller_id": "1234", - "product_id": "4567", - "quantity": 1, - "price": 2000.00, - "promotional_price": 1899.00 -} -``` - -##### Exemplo de Requisição Completa - -```http -POST https://events.newtail-media.newtail.com.br/v1/beacon/conversion HTTP/1.1 -Accept: application/json -Content-Type: application/json -``` - -```json -{ - "channel": "ecommerce", - "publisher_id": "xxx", - "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", - "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", - "order_id": "123", - "email_hashed": "xyz", - "items": [ - { - "sku": "12221", - "seller_id": "1234", - "product_id": "4567", - "quantity": 1, - "price": 2000.00, - "promotional_price": 1899.00 - }, - { - "sku": "12222", - "seller_id": null, - "product_id": "4568", - "quantity": 2, - "price": 500.00, - "promotional_price": 400.00 - } - ], - "created_at": "2023-01-01T09:20:00Z" -} -``` - -**Nota**: No exemplo acima, observe que: -- O primeiro item tem quantidade 1 com preço unitário de R$ 2.000,00 -- O segundo item tem quantidade 2 com preço unitário de R$ 500,00 (não R$ 1.000,00) - -#### **Respostas da API** - -##### ✅ Resposta de Sucesso (HTTP 202) -```json -{ - "messages": [ - "conversion will be processed soon" - ] -} -``` - -##### ❌ Resposta de Erro de Validação (HTTP 422) -A API retorna erros de validação em um formato compatível com JSON Schema (semântica similar ao Ajv). - -Exemplo de resposta com erros: -```json -[ - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'user_id'", - "params": { - "missingProperty": "user_id" - }, - "schemaPath": "#/required" - }, - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'order_id'", - "params": { - "missingProperty": "order_id" - }, - "schemaPath": "#/required" - }, - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'publisher_id'", - "params": { - "missingProperty": "publisher_id" - }, - "schemaPath": "#/required" - }, - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'items'", - "params": { - "missingProperty": "items" - }, - "schemaPath": "#/required" - }, - { - "instancePath": "", - "keyword": "required", - "message": "must have required property 'created_at'", - "params": { - "missingProperty": "created_at" - }, - "schemaPath": "#/required" - } -] -``` - -#### **🎯 Regra de Match de Produtos para Conversões** - -##### Importante: Correspondência entre Produto e Campanha - -As conversões **só são computadas** para campanhas quando ocorre um **match de produto**. Isso significa que: - -- ✅ **Conversão é mensurada**: Quando o produto comprado pelo usuário **pertence** à campanha em que o usuário foi impactado -- ❌ **Conversão NÃO é mensurada**: Quando o produto comprado **não pertence** à campanha em que o usuário foi impactado - -##### Exemplo Prático: - -**Cenário 1 - Com Match (Conversão Computada)** -- Usuário visualizou anúncio da Campanha A (produtos: SKU-001, SKU-002, SKU-003) -- Usuário comprou produto SKU-002 -- ✅ Conversão é atribuída à Campanha A - -**Cenário 2 - Sem Match (Conversão NÃO Computada)** -- Usuário visualizou anúncio da Campanha B (produtos: SKU-004, SKU-005) -- Usuário comprou produto SKU-999 -- ❌ Conversão NÃO é atribuída à Campanha B - -#### **Exemplo de Código** - -##### JavaScript (Browser) -```javascript -const enviarConversao = async (dadosPedido) => { - const payload = { - channel: "ecommerce", - publisher_id: "xxx", - user_id: dadosPedido.userId, - session_id: dadosPedido.sessionId, - order_id: dadosPedido.orderId, - email_hashed: dadosPedido.emailHash, - items: dadosPedido.items.map(item => ({ - sku: item.sku, - seller_id: item.sellerId || null, - product_id: item.productId || null, - quantity: item.quantity, - price: item.unitPrice, // Valor unitário, não multiplicado - promotional_price: item.unitPromotionalPrice // Valor unitário, não multiplicado - })), - created_at: new Date().toISOString() - }; - - try { - // Converte os dados para JSON - const blob = new Blob([JSON.stringify(payload)], {type: 'application/json'}); - - // Envia o evento de forma assíncrona usando Beacon API - if (navigator.sendBeacon) { - const success = navigator.sendBeacon( - 'https://events.newtail-media.newtail.com.br/v1/beacon/conversion', - blob - ); - - if (success) { - console.log('Conversão enviada com sucesso'); - } else { - console.error('Falha ao enviar conversão via Beacon API'); - } - } else { - // Fallback para navegadores que não suportam Beacon API - const response = await fetch('https://events.newtail-media.newtail.com.br/v1/beacon/conversion', { - method: 'POST', - headers: { - 'Accept': 'application/json', - 'Content-Type': 'application/json' - }, - body: JSON.stringify(payload) - }); - - if (response.status === 202) { - console.log('Conversão enviada com sucesso'); - } else if (response.status === 422) { - const errors = await response.json(); - console.error('Erros de validação:', errors); - } - } - } catch (error) { - console.error('Erro ao enviar conversão:', error); - } -}; - -// Exemplo de uso -const pedido = { - userId: "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", - sessionId: "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", - orderId: "123", - emailHash: "xyz", - items: [ - { - sku: "12221", - sellerId: "1234", - productId: "4567", - quantity: 1, - unitPrice: 2000.00, - unitPromotionalPrice: 1899.00 - } - ] -}; - -enviarConversao(pedido); -``` - -#### **Regras de Atribuição e Deduplicação** - -* **Janela de Conversão:** Período após uma interação em que uma venda pode ser atribuída ao anúncio. - * **Click (para `product`):** 14 dias. - * **Visualização (para `display`/`video`):** 14 dias. -* **Deduplicação de Eventos:** Para o mesmo usuário e anúncio, eventos são ignorados por um período. - * **Impressões:** 1 minuto. - * **Cliques:** 1 hora. - * **Conversões:** Idempotentes por `order_id` (reenvios do mesmo `order_id` em até 30 dias são ignorados). +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/5.7-integracao-transparente.md b/pt/docs/5.7-integracao-transparente.md index d43f7b3..77384f2 100644 --- a/pt/docs/5.7-integracao-transparente.md +++ b/pt/docs/5.7-integracao-transparente.md @@ -1,115 +1,8 @@ # Integração Transparente -> Atenção: Esta ferramenta está apta apenas a servir anúncios do tipo Banner e Vídeo. - -A integração transparente tem o objetivo de reduzir a fricção ao máximo para iniciar a configuração da integração do VTEX Ads de forma mais simples possível. - -## Requisitos para a Prova de Conceito (PoC) - -Para que esta Prova de Conceito funcione, os seguintes requisitos são essenciais: - -1. **Integração de Catálogo:** Uma integração de catálogo precisa estar em funcionamento. - -2. **Instalação do Script:** O nosso script deve ser adicionado ao site. - -3. **Disparo de Evento de Conversão:** O evento de conversão precisa ser disparado pelo lado do cliente. - - -### 1\. Integração do Catálogo - -A sincronização do catálogo segue o formato já definido para todas as integrações. - -### 2\. Instalação do Script - -Adicione o seguinte script o mais cedo possível na tag `<head>` da página ou em seu site/msite: - -``` -<script src="https://cdn.newtail.com.br/retail-media/scripts/vtexads-magic-1.0.0.js"></script> -``` - -#### Requisitos do Script - -Para que o script funcione corretamente, o cliente deve nos informar a origem de dois parâmetros importantes: `session_id` e `user_id`. Esses parâmetros geralmente são armazenados em cookies, `sessionStorage` ou `localStorage`. - -### 3\. Evento de Conversão - -O evento de conversão deve ser enviado após a criação do pedido, sem a necessidade de confirmação de pagamento. - -O script a seguir demonstra como enviar dados para um endpoint de API usando a interface `navigator.sendBeacon`. O método `sendBeacon` é ideal para enviar pequenas quantidades de dados de forma assíncrona, sem impactar o desempenho da página. É particularmente útil para enviar dados de analytics antes que o usuário saia da página. - -``` -/** - * Este script demonstra como enviar dados para um endpoint de API - * usando a interface `navigator.sendBeacon`. - * - * O método `sendBeacon` é projetado para enviar pequenas quantidades de dados - * de forma assíncrona, sem afetar o desempenho da página atual - * ou o tempo de carregamento da próxima. - * - * É particularmente útil para enviar dados de analytics antes que - * um usuário saia de uma página. - */ - -// 1. Defina os dados que você deseja enviar. -const data = { - "publisher_id": "d4dff0cb-1f21-4a96-9acf-d9426a5ed08c", - "user_id": "26119121", - "order_id": "1758035060", - "channel": "site|msite|app", - "created_at": "2025-09-16T15:04:19.794Z", - "items": [ - { - "price": 12, - "promotional_price": 10, - "quantity": 1, - "sku": "sku1" - }, - { - "price": 15, - "promotional_price": 13, - "quantity": 1, - "sku": "sku2", - "seller_id": "seller1" - }, - { - "price": 19, - "promotional_price": 17, - "quantity": 1, - "sku": "sku3", - "product_id": "prod3" - }, - { - "price": 30, - "promotional_price": 25, - "quantity": 2, - "sku": "sku4", - "product_id": "prod4", - "seller_id": "seller2" - } - ] -}; - -// 2. Converta o objeto de dados em uma string JSON. -const rawData = JSON.stringify(data); - -// 3. Crie um Blob a partir da string JSON. -// Isso nos permite definir explicitamente o Content-Type para a requisição. -const blob = new Blob([rawData], { type: 'application/json' }); - -// 4. Defina a URL do endpoint. -const url = "https://newtail-media.newtail.com.br/v1/beacon/conversion"; - -// 5. Use `navigator.sendBeacon` para enviar os dados. -// O método retorna `true` se o navegador enfileirar a solicitação -// para entrega e `false` caso contrário. -// Note que `sendBeacon` não retorna uma promessa (Promise), então não há -// `.then()` ou `.catch()`. A entrega não é garantida, mas é -// altamente provável. -const success = navigator.sendBeacon(url, blob); - -if (success) { - console.log("Solicitação de beacon enfileirada com sucesso!"); -} else { - console.error("Falha ao enfileirar a solicitação de beacon."); -} -``` +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/6-exportacao-de-dados.md b/pt/docs/6-exportacao-de-dados.md index 33c6d50..37f6432 100644 --- a/pt/docs/6-exportacao-de-dados.md +++ b/pt/docs/6-exportacao-de-dados.md @@ -1,61 +1,8 @@ ## 6. Exportação de Dados -A exportação de dados permite que você receba informações detalhadas sobre eventos e dados agregados de forma sistemática e periódica. A integração ocorre através de uma conexão S3, e os dados são entregues em formatos específicos para cada tipo de exportação. - -### 6.1. Relatórios - -Além da exportação via S3, é possível extrair relatórios via API. As rotas retornam JSON por padrão, mas podem ser exportadas como arquivos XLSX ao incluir o parâmetro `download=true` na query. - -* `GET /report/v2/advertisers`: Informações de anunciantes (visão do publisher) [[Exemplo]](../../examples/EXPORT_ADVERTISER_DATA.md) -* `GET /report/v2/publishers`: Informações do publisher (visão do anunciante) [[Exemplo]](../../examples/EXPORT_PUBLISHER_DATA.md) -* `GET /report/network/publishers`: Publishers da rede (para contas do tipo Rede) [[Exemplo]](../../examples/EXPORT_NETWORK_PUBLISHERS_DATA.md) -* `GET /campaign/v2`: Relatório listagem de campanhas [[Exemplo]](../../examples/EXPORT_CAMPAIGNS_LIST_DATA.md) -* `GET /campaign/:id`: Relatório detalhado da campanha [[Exemplo]](../../examples/EXPORT_CAMPAIGN_DATA.md) -* `GET /report/advertisers/campaigns-detailed`: Relatório detalhado de campanhas mistas para contas de anunciante, incluindo informações de subpublisher em campanhas de rede [[Exemplo]](../../examples/EXPORT_ADVERTISER_CAMPAIGNS_DETAILED_DATA.md) -* `GET /report/advertisers/ads-detailed`: Relatório detalhado de anúncios para contas de anunciante, incluindo quebra por subpublisher em campanhas de rede [[Exemplo]](../../examples/EXPORT_ADVERTISER_ADS_DETAILED_DATA.md) -* `GET /ad/results/v2`: Relatório de anúncios [[Exemplo]](../../examples/EXPORT_ADS_DATA.md) - -### 6.2. Exportação de Dados - -A integração sempre ocorrerá usando uma conexão S3 (ou compatível) que deverá ser disponibilizada pelo receptor dos dados. As credenciais devem ser passadas para o time da Newtail de forma segura. - -A integração é compatível com: - -- **AWS S3:** `Access Key Id` e `Access Key Secret`. -- **Google Cloud Storage:** `Service Account`. -- **Azure Blob Storage**. - -#### Exportação de Eventos - -A exportação de eventos envia dados brutos de interações dos usuários. - -- **Formato:** `PARQUET` com compressão `Snappy`. -- **Frequência:** Diária (dados de D-1). -- **Estrutura de Pastas:** `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.snappy.parquet` -- **De-duplicação:** É garantido que todos os eventos serão enviados, mas não que serão enviados uma única vez. Portanto, os eventos precisam sempre ser de-duplicados usando a `event_id` ou a combinação de `order_id` e `product_sku` para itens de conversão. - -##### Tipos de Eventos - -- **Impressões, Visualizações e Cliques:** - - **Campos:** `event_id` (chave de de-duplicação), `session_id`, `user_id`, `ad_id`, `campaign_id`, `request_id`, `ad_type`, `placement_name`, `context`, `created_at`, `site`. -- **Conversões:** - - **Campos:** `event_id`, `session_id`, `user_id`, `order_id` (chave de de-duplicação), `channel`, `placed_at`, `site`. -- **Itens das Conversões:** - - **Campos:** `event_id`, `session_id`, `user_id`, `order_id` (chave de de-duplicação), `product_sku` (chave de de-duplicação), `ad_id`, `campaign_id`, `request_id`, `ad_size`, `ad_type`, `placement_name`, `context`, `event_created_at`, `price`, `promotional_price`, `quantity`, `total_value`. - -#### Exportação de Dados Agregados - -A exportação de dados agregados envia relatórios consolidados. - -- **Formato:** `CSV` com encoding `UTF-8`, separado por vírgula, e números no formato americano (ponto decimal). -- **Frequência:** Diária (dados de D-1, com o timezone do publisher). -- **Estrutura de Pastas:** `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.csv` - -##### Tipos de Relatórios - -- **Anunciantes:** - - **Campos:** `advertiser`, `advertiser_id`, `seller_id`, `wallet_balance`, `daily_budget`, `currency`. -- **Campanhas:** - - **Campos:** `day`, `name`, `campaign_id`, `campaign_type`, `campaign_status`, `impressions_total`, `clicks_total`, `ctr`, `ad_revenue`, `conversions_total`, `conversion_rate`, `sales_revenue`, `start_date`, `end_date`, `advertiser_id`. -- **Anúncios:** - - **Campos:** `day`, `ad_id`, `campaign_id`, `ad_status`, `ad_media_url`, `cpm`, `cpc`, `impressions_total`, `clicks_total`, `ctr`, `ad_revenue`, `conversions_total`, `conversion_rate`, `sales_revenue`, `product_sku`. +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/7-script-agent.md b/pt/docs/7-script-agent.md index dec5980..a8ca7aa 100644 --- a/pt/docs/7-script-agent.md +++ b/pt/docs/7-script-agent.md @@ -1,104 +1,8 @@ # 7. VTEX Ads - Script Agent -## 7.1. Objetivo - -Este documento detalha o procedimento para a instalação do script de rastreamento da **VTEX Ads** em todas as páginas de um site (exceto as páginas de checkout) através do Google Tag Manager (GTM). A correta implementação deste script é fundamental para a coleta de dados de navegação que permitem a otimização e o direcionamento de campanhas de Retail Media. - -## 7.2. Dados Coletados - -O script da VTEX Ads foi desenvolvido para coletar exclusivamente dados de navegação não sensíveis, com o objetivo de personalizar a experiência do usuário e otimizar campanhas. - -**Dados Coletados:** - -- **Para campanhas off-site:** - - - `session_id`: Identificador anônimo da sessão de navegação. - - - `ad_id`: Identificador do anúncio que originou o tráfego. - -- **Para segmentação de audiência (Page View):** - - - `session_id`: Identificador anônimo da sessão de navegação. - - - **Informações da Página:** URL, título (`<title>`), e descrição (`<meta name="description">`). - - -> **Importante:** O script **não coleta** nenhuma informação pessoalmente identificável (PII), como nome, e-mail, CPF, telefone, endereço ou dados de pagamento. A coleta de dados está em conformidade com as principais leis de proteção de dados. - -## 7.3. Dados do Script - -O script deve ser carregado de forma assíncrona para não impactar o tempo de carregamento da página. - -- **URL do Script:** `https://cdn.newtail.com.br/retail-media/scripts/vtexrma-agent.1.0.0.js` - - -## 7.4. Passo a Passo para Implementação via Google Tag Manager (GTM) - -Para garantir que o script seja executado o mais cedo possível no carregamento da página, recomendamos o uso do acionador de **Inicialização (Initialization)**. - -### Passo 7.4.1: Criar a Tag de HTML Personalizado - -1. Acesse seu contêiner do GTM e vá para a seção **"Tags"**. - -2. Clique em **"Nova"** para criar uma nova tag. - -3. Dê um nome claro para a tag, por exemplo: **"Custom HTML - VTEX Ads Agent"**. - -4. Clique em **"Configuração da tag"** e selecione o tipo de tag **"HTML personalizado"**. - -5. No campo de HTML, insira o seguinte código: - - ``` - <script type="text/javascript" async src="https://cdn.newtail.com.br/retail-media/scripts/vtexrma-agent.1.0.0.js"></script> - ``` - - -### Passo 7.4.2: Configurar o Acionador Principal - -1. Abaixo da configuração da tag, clique em **"Acionamento"**. - -2. Selecione o acionador **"Initialization - All Pages"** (Inicialização - Todas as Páginas). Este acionador garante que o script seja disparado antes da maioria das outras tags, em todas as páginas. - - -### Passo 7.4.3: Criar e Adicionar uma Exceção de Acionamento - -Para evitar que o script seja executado nas páginas de checkout, criaremos uma exceção. - -1. Ainda na configuração da tag, na seção **"Acionamento"**, clique em **"Adicionar exceção"**. - -2. Clique no ícone de **"+"** no canto superior direito para criar um novo acionador de exceção. - -3. Dê um nome para o acionador, por exemplo: **"Trigger Exception - Checkout Pages"**. - -4. Clique em **"Configuração do acionador"** e escolha o tipo **"Inicialização"**. - -5. Em **"Este acionador é disparado em"**, selecione **"Algumas inicializações"**. - -6. Configure a condição para identificar as páginas de checkout. A condição pode variar dependendo da estrutura da URL do seu site. Exemplos comuns: - - - `Page Path` | `contém` | `/checkout` - - - `Page URL` | `corresponde ao RegEx (sem distinção entre maiúsculas e minúsculas)` | `/checkout/|/orderPlaced/` - -7. Salve o novo acionador de exceção. Ele será automaticamente adicionado à sua tag. - - -### Passo 7.4.4: Salvar e Publicar - -1. Salve a tag recém-criada. - -2. Envie e publique as alterações no seu contêiner do GTM. - - -## 7.5. Configuração da Sessão do Usuário - -Para que a plataforma VTEX Ads possa correlacionar corretamente as interações do usuário, é necessário informar qual é o identificador de sessão utilizado pelo seu e-commerce. - -**Ação Necessária:** - -A equipe responsável pelo e-commerce deve informar à equipe da VTEX Ads qual é o **nome do atributo no `cookie` ou `sessionStorage`** que armazena o ID da sessão do usuário. - -- **Exemplo:** Se o ID da sessão estiver armazenado em um cookie chamado `vtex_session`, essa informação deve ser repassada. - - -Esta configuração permite que o script leia o identificador correto e o associe aos eventos de navegação. \ No newline at end of file +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/8-repasse.md b/pt/docs/8-repasse.md index e1ca337..d0826e3 100644 --- a/pt/docs/8-repasse.md +++ b/pt/docs/8-repasse.md @@ -1,73 +1,8 @@ ## 7. Repasse de Créditos -O repasse de créditos é o fluxo que permite ao marketplace transferir créditos de anúncio para seus sellers. Esta documentação detalha os endpoints que o marketplace deve implementar e o webhook que deve consumir para realizar a integração com a VTEXAds. - -<div align="center"> - <img src="../../diagrams/images/pt/credit-transfer.png" alt="Fluxo de Repasse de Créditos" /> -</div> - - * **Endpoints a serem implementados pelo Marketplace (Autenticação: Basic Auth):** - 1. **Consulta de Saldo (`GET /checking_account`)** - * **Objetivo:** Verificar o saldo disponível do seller. - * **Parâmetros (Query):** `seller_id`, `publisher_id` (opcional, utilizado apenas em casos onde uma entidade gerencia múltiplos publishers). - * **Resposta de Sucesso (200 OK):** - ```json - { "total": "1111.00" } - ``` - - 2. **Solicitação de Transferência (`POST /checking_account/transfer`)** - * **Objetivo:** Requisitar a transferência de um valor. - * **Corpo da Requisição:** - ```json - { - "amount": "10.00", - "seller_id": "SELLER_ID", - "publisher_id": "PUBLISHER_ID", - "transfer_identity_id": "uuid" - } - ``` - * **Respostas:** - - **Síncrona (Sucesso):** `201 Created` - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "success" - } - ``` - - **Síncrona (Falha):** `400 Bad Request` - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "failure", - "message": "Motivo da recusa" - } - ``` - - **Assíncrona:** `202 Accepted` - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "processing" - } - ``` - - * **Webhook a ser consumido pelo Marketplace:** - * **Objetivo:** Notificar a VTEXAds sobre o status final da transferência. - * **Endpoint:** `POST https://api-retail-media.newtail.com.br/webhook/marketplace/transfers/:publisher_id` - * **Autenticação:** `x-api-key` e `x-secret-key`. - * **Payload:** - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "success" - } - ``` - ou - ```json - { - "transaction_id": "TRANSACTION_ID", - "status": "failure", - "message": "Descrição do problema" - } - ``` - * **Lógica de Retry:** Em caso de falha na chamada do webhook, o marketplace deve realizar novas tentativas. - * **Resposta Esperada:** `204 No Content` \ No newline at end of file +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. diff --git a/pt/docs/9-sso.md b/pt/docs/9-sso.md index 0457fe4..f5fbc1c 100644 --- a/pt/docs/9-sso.md +++ b/pt/docs/9-sso.md @@ -1,32 +1,8 @@ ## 8. SSO (Single Sign-On) -API para login unificado do seller. Ao chamar esta API, a Newtail gera uma URL de redirecionamento que permite ao usuário acessar a plataforma da Newtail sem a necessidade de um novo login. - -* **Endpoint:** `POST /sso/marketplace` -* **Corpo da Requisição:** - -| Campo | Descrição | Tipo | Obrigatório? | -| :--- | :--- | :--- | :--- | -| `sso_token` | Token de identificação do usuário gerado pelo marketplace. | String | Sim | -| `email` | E-mail do usuário (seller). | String | Sim | -| `user_id` | ID único do usuário no marketplace. | String | Sim | -| `name` | Nome do usuário. | String | Sim | -| `marketplace_name` | Nome do marketplace. | String | Sim | - -* **Exemplo de Requisição:** - ```json - { - "sso_token": "token-sso-12345", - "email": "seller@exemplo.com", - "user_id": "seller123", - "name": "Nome do Seller", - "marketplace_name": "Meu Marketplace" - } - ``` - -* **Resposta de Sucesso:** `HTTP 200 OK` com a URL de redirecionamento. - ```json - { - "redirect_url": "https://app.ads.vtex.com/sso/auth?token=TOKEN_GERADO" - } - ``` \ No newline at end of file +> [!IMPORTANT] +> **Esta página foi movida.** +> +> A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). +> +> Atualize seus favoritos. Esta página não é mais mantida. From c4e8c81bd1713e49bde74646cca7b4536a4d4952 Mon Sep 17 00:00:00 2001 From: Pedro Antunes <47991446+PedroAntunesCosta@users.noreply.github.com> Date: Wed, 20 May 2026 11:20:14 -0300 Subject: [PATCH 2/2] docs: keep original content below redirect callout --- en/docs/1-summary.md | 18 + en/docs/10-attribution-window.md | 96 +++++ en/docs/2-glossary.md | 15 + en/docs/3-authentication.md | 9 + en/docs/4-data-security.md | 26 ++ en/docs/5-ad-integration.md | 23 + en/docs/5.1-api-integration.md | 21 + en/docs/5.2-vtex-integration.md | 32 ++ en/docs/5.3-catalog-synchronization.md | 191 +++++++++ en/docs/5.4-audience-integration.md | 97 +++++ en/docs/5.5-ad-query.md | 394 ++++++++++++++++++ en/docs/5.5.1-placement-naming.md | 32 ++ en/docs/5.6-events.md | 364 ++++++++++++++++ en/docs/5.7-transparent-integration.md | 114 +++++ en/docs/6-data-export.md | 60 +++ en/docs/7-script-agent.md | 76 ++++ en/docs/8-credit-transfer.md | 72 ++++ en/docs/9-sso.md | 31 ++ es/docs/1-resumen.md | 18 + es/docs/10-ventana-atribucion.md | 96 +++++ es/docs/2-glosario.md | 15 + es/docs/3-autenticacion.md | 9 + es/docs/4-seguridad-de-datos.md | 26 ++ es/docs/5-integracion-de-anuncios.md | 23 + es/docs/5.1-integracion-via-api.md | 21 + es/docs/5.2-integracion-vtex.md | 32 ++ es/docs/5.3-sincronizacion-de-catalogo.md | 192 +++++++++ es/docs/5.4-integracion-de-audiencias.md | 97 +++++ es/docs/5.5-consulta-de-anuncios.md | 393 +++++++++++++++++ ...-recomendacion-de-nombres-de-placements.md | 32 ++ es/docs/5.6-eventos.md | 364 ++++++++++++++++ es/docs/5.7-integracion-transparente.md | 114 +++++ es/docs/6-exportacion-de-datos.md | 60 +++ es/docs/7-script-agent.md | 76 ++++ es/docs/8-repasse.md | 72 ++++ es/docs/9-sso.md | 31 ++ pt/docs/1-resumo.md | 23 + pt/docs/10-janela-atribuicao.md | 96 +++++ pt/docs/2-glossario.md | 15 + pt/docs/3-autenticacao.md | 9 + pt/docs/4-seguranca-de-dados.md | 26 ++ pt/docs/5-integracao-de-anuncios.md | 23 + pt/docs/5.1-integracao-via-api.md | 21 + pt/docs/5.2-integracao-vtex.md | 32 ++ pt/docs/5.3-sincronizacao-de-catalogo.md | 192 +++++++++ pt/docs/5.4-integracao-de-audiencias.md | 97 +++++ pt/docs/5.5-consulta-de-anuncios.md | 394 ++++++++++++++++++ ...5.1-recomendacao-de-nomes-de-placements.md | 32 ++ pt/docs/5.6-eventos.md | 364 ++++++++++++++++ pt/docs/5.7-integracao-transparente.md | 114 +++++ pt/docs/6-exportacao-de-dados.md | 60 +++ pt/docs/7-script-agent.md | 103 +++++ pt/docs/8-repasse.md | 72 ++++ pt/docs/9-sso.md | 31 ++ 54 files changed, 5046 insertions(+) diff --git a/en/docs/1-summary.md b/en/docs/1-summary.md index 4514d49..5259532 100644 --- a/en/docs/1-summary.md +++ b/en/docs/1-summary.md @@ -6,3 +6,21 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +This document details the integration with the **Retail Media API**, the central connection point between the VTEX Ads solution and the retailer's (publisher's) platform. The solution was developed under an **API-first** concept, ensuring total flexibility for retailers to integrate and display ads on any digital channel: e-commerce, marketplace, app, or even on physical totems and screens (Digital Signage). + +Our architecture is **cookie-less**, meaning we do not rely on third-party cookies. Identification and targeting are based on proprietary identifiers (`user_id`, `session_id`) and first-party data, ensuring a robust solution that complies with new privacy policies and is prepared for the future of digital retail. + +Through this REST API, your platform will be able to: +* Synchronize the product catalog and inventory. +* Request relevant ads in real-time for the user's Browse context. +* Send interaction events (impression, view, click, conversion) for performance measurement. + +We adopt the **Progressive Extensibility** principle to ensure maximum stability and security for our partners' operations. + +Our formal compatibility policy guarantees: +* **Non-breaking evolution:** all API updates are incremental. New fields, capabilities, and options are added without changing or removing the behavior of existing contracts. +* **Integration preservation:** current integrations remain fully operational after new releases, minimizing recurring technical rework. +* **Business continuity:** by preserving the integrity of previous contracts, we prevent operational disruptions and allow new capabilities to be adopted at your own pace. + +This approach reflects our commitment to a robust, scalable platform where technological innovation and operational predictability evolve together. diff --git a/en/docs/10-attribution-window.md b/en/docs/10-attribution-window.md index 433fc6e..7434c05 100644 --- a/en/docs/10-attribution-window.md +++ b/en/docs/10-attribution-window.md @@ -6,3 +6,99 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +This document details the rules, models, and timelines that govern the attribution of conversions (sales) and the billing of advertising campaigns on our platform. + +## 1. What is the Attribution Window? + +The "attribution window" (or conversion window) is the time period _after_ a user interacts with an ad (either by clicking or viewing) during which a conversion can be credited to that ad. + +- **Default Window:** 14 days. +- **Flexibility:** This period is the default for all campaigns, but can be customized according to strategic needs. + +**Example:** If a user clicks on an ad today, any purchase they make of the associated product in the next 14 days can be attributed to that ad. + +## 2. Measurement (Attribution) vs. Billing (Invoicing) + +It is essential to differentiate the event that _measures_ attribution (what we use to count a conversion) from the event that _generates billing_ (what we charge the advertiser). + +### 2.1. Measurement Events (Attribution) + +This defines _how_ we know that an ad "worked" to generate a sale: + +- **Product Campaigns (Product Ads):** + - **Event:** Click. + - **Logic:** The conversion is only counted if the user _clicked_ on the ad before purchasing. + +- **Other Campaigns (Banner, Video, and Sponsored Brands):** + - **Event:** View (Impression). + - **Logic:** The conversion can be counted even if the user only _saw_ the ad (and did not necessarily click), following the hierarchy rules (see section 3). + +### 2.2. Billing Models (Invoicing) + +This defines _what_ the advertiser pays for: + +- **CPC (Cost Per Click):** The advertiser pays each time a user clicks on the ad. + - _Used in:_ Product Campaigns, Sponsored Brands. + +- **CPM (Cost Per Thousand Impressions):** The advertiser pays a fixed amount for every 1,000 times the ad is displayed. + - _Used in:_ Banner, Video, Sponsored Brands. + +- **Hybrid Model (CPC + CPM):** + - **Sponsored Brands** campaigns are unique, as they charge for _both_ clicks (CPC) and impressions (CPM) generated. + +#### Billing Calculation Example (CPM) + +CPM defines the value for 1,000 impressions, but the actual charge is proportional to each individual impression. + +- **Scenario:** A video campaign has a CPM of **$10.00**. +- **Result:** The campaign generates **10 impressions**. + +**Calculation:** + +1. **Cost per individual impression:** $10.00 (CPM) / 1,000 (impressions) = **$0.01 per impression**. +2. **Total Cost:** 10 (impressions generated) * $0.01 (cost per impression) = **$0.10**. + +The total cost of this campaign would be **ten cents**. + +## 3. Attribution Rules (The Decision Hierarchy) + +When a user interacts with multiple ads before purchasing, an attribution model decides which campaign will receive credit for the sale. + +**Fundamental Principle:** Attribution is exclusive. A sold order is **never** attributed to two different campaigns; credit is always given to a single campaign. + +The decision follows this priority order: + +1. **Priority 1: Offsite Campaigns** + - If there is an active _offsite_ campaign (bringing external traffic to the site) and it was the user's last point of contact, it will have total preference in the sale attribution. + +2. **Priority 2: Last Click** + - In the absence of a recent offsite click, the system looks for the _last ad_ (within the platform) that the user _clicked_ within the 14-day window. + +3. **Priority 3: Last View** + - If the user did not click on any ad during the period, the system attributes the sale to the _last ad_ they _viewed_ (as long as it is a campaign type that measures by view, such as Banner or Video). + +**Time Rule:** For a conversion to be valid, the interaction event (click or view) must have occurred _before_ the order was finalized. + +## 4. Product Mapping in Attribution + +A campaign can only receive attribution for products that are _explicitly linked to it_. + +### 4.1. Product Campaigns (1:1 Attribution) + +- **How it works:** Each ad (AD) within the campaign represents a specific product. +- **Logic:** Attribution is direct and 1-to-1. A click on the "Product A" ad can only generate a conversion for "Product A". + +### 4.2. Other Campaigns (Banner, Video, etc.) (N:1 Attribution) + +- **How it works:** These campaigns have a _list_ of associated products (SKUs). +- **Logic:** Interaction (click or view) with a single creative (banner or video) can generate attribution for _any_ of the products contained in that campaign list. + +**Note on Creatives:** Within a campaign (e.g., Banner), each creative (e.g., "Banner A" and "Banner B") tracks its information independently. This allows analysis of the individual performance of each ad piece. + +## 5. Data Latency (Attribution Delay) + +It is important to note that there is a natural delay between the moment the customer creates the order and the moment that sale is associated (attributed) to the correct campaign in the reports. + +- **API Integration:** Delay of approximately **30 minutes**. +- **VTEX Platform:** Delay of up to **2 hours**. diff --git a/en/docs/2-glossary.md b/en/docs/2-glossary.md index b3c0f0b..dee42c5 100644 --- a/en/docs/2-glossary.md +++ b/en/docs/2-glossary.md @@ -6,3 +6,18 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +| Term | Description | +| :--- | :--- | +| **Advertiser** | Companies, sellers, or individuals who promote their products, services, or ideas through campaigns. | +| **Publisher (Retailer)** | The entity that owns and operates the digital platform (website, app) and makes ad spaces available. | +| **Campaign** | An action created by an advertiser to promote products and generate conversions (sales). | +| **Impression** | Counted each time an ad is displayed on the user's screen. | +| **View** | Counted when an impression becomes visible on the user's screen for a specified time. | +| **Click** | User interaction by clicking on an ad to be redirected to the landing page. | +| **Conversion** | A valuable action generated by an ad, typically a sale. | +| **Ad Revenue** | Revenue earned by retailers from monetizing their ad spaces. | +| **Sales Revenue** | Total revenue a company obtains from the sales of products or services. | +| **CTR (Click-Through Rate)** | Formula: `(Clicks / Impressions) * 100`. Measures the attractiveness of an ad. | +| **ROAS (Return on Ad Spend)**| Return on Advertising Spend. Formula: `Revenue Generated by Ads / Advertising Cost`. | +| **Conversion Rate** | The percentage of conversions relative to the total number of clicks or visits. | diff --git a/en/docs/3-authentication.md b/en/docs/3-authentication.md index 49223ed..e99c4ab 100644 --- a/en/docs/3-authentication.md +++ b/en/docs/3-authentication.md @@ -6,3 +6,12 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +Authentication is required for catalog submission, report consumption, and management. Other calls, such as ad queries and event notifications, are public and do not require authentication. + +For protected endpoints, credentials must be sent via HTTP header. Request your credentials from your account manager. + +| Attribute | Description | +| :--- | :--- | +| `x-app-id` | Your application's unique ID for the integration. | +| `x-api-key` | API key associated with your application. | diff --git a/en/docs/4-data-security.md b/en/docs/4-data-security.md index cfdf405..c376f14 100644 --- a/en/docs/4-data-security.md +++ b/en/docs/4-data-security.md @@ -6,3 +6,29 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +Data security is a fundamental pillar of our platform. From the outset, our architecture was designed to ensure that no sensitive information is collected and that user data remains protected and non-identifiable at all times. + +## Non-Identifiable Data + +We do not collect sensitive user data, such as names, emails, or personal documents. The information we do receive, like emails or identification numbers (PII - Personally Identifiable Information), already arrives on our platform as an irreversible cryptographic hash. + +This means the original data is never transmitted to or stored in our systems. The result is an anonymous identifier that allows us to group behaviors and audiences without ever knowing who the actual user is. + +**Why is this secure?** + +* **Irreversibility:** The hashing process is a one-way street. Even if someone gained access to the hash, they could not uncover the original data. +* **Anonymity:** Since we do not store the original data, we have no way of identifying the user. For all intents and purposes, the data is anonymous. + +## Encryption in Transit and at Rest + +All data, whether they are anonymous identifiers or information about campaigns and ads, is handled with the highest security standards: + +* **Encryption in Transit:** All communication between our systems and with partners is conducted using secure protocols like TLS 1.2+, ensuring that data cannot be intercepted during transfer. +* **Encryption at Rest:** Data stored in our databases and file systems is encrypted. We use robust and market-recognized solutions such as **Amazon RDS**, **Amazon S3**, **Amazon Redshift** and **Snowflake**, which apply AES-256 encryption, one of the most secure algorithms in existence. + +## Restricted Access + +Access to data is strictly controlled and limited to a select group of senior engineers and analysts. Every access is audited and monitored, and permissions are granted based on the principle of least privilege, meaning each person has access only to what is strictly necessary to perform their job. + +This combination of non-identifiable data, end-to-end encryption, and rigorous access control ensures that your information and that of your customers are always secure. diff --git a/en/docs/5-ad-integration.md b/en/docs/5-ad-integration.md index 50483b3..3d5c5a7 100644 --- a/en/docs/5-ad-integration.md +++ b/en/docs/5-ad-integration.md @@ -6,3 +6,26 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +This section provides detailed information on how to integrate with the VTEX Ads platform to display ads on your website. + +## 5.0 Integration Flow Overview + +<img src="../../diagrams/images/en/integration-end-to-end.png" alt="Complete VTEX Ads integration flow" /> + +The complete integration flow is divided into four main phases that continuously feed back into each other: + +1. **Preparation and Onboarding:** Align scope and timeline with the VTEX Ads team, receive API credentials, and validate access to environments and webhooks. +2. **Operational Data Synchronization:** Load catalog (products and inventory) and, optionally, audiences. This step ensures that only available products and valid segmentations are eligible to appear. +3. **Ad Delivery:** Structure site placements, configure naming conventions, and query ads in real-time for each context (home, search, category, PDP, etc.), displaying the "Sponsored" label. +4. **Measurement and Optimization:** Fire impression, view, click, and conversion events using `navigator.sendBeacon()`, monitor performance metrics, and adjust bids, segmentation, and positioning according to results. + +The following sections detail how to execute each of these phases, with request examples and specific best practices. + +- [5.1. API Integration](./5.1-api-integration.md): For a more customized integration, use our REST API to manage the entire ad lifecycle. +- [5.2. VTEX Integration](./5.2-vtex-integration.md): If your store is on the VTEX platform, use our VTEX IO app to simplify the process. +- [5.3. Catalog Synchronization](./5.3-catalog-synchronization.md): Keep your product catalog and inventory synchronized with VTEX Ads. +- [5.4. Audience Integration](./5.4-audience-integration.md): Send audience data to improve targeting and ad relevance. +- [5.5. Ad Query](./5.5-ad-query.md): Request from the API the ads that should be displayed on different pages and contexts. +- [5.5.1. Placement Naming](./5.5.1-placement-naming.md): Recommended standard for naming placements to enable accurate measurement. +- [5.6. Events](./5.6-events.md): Notify the API of user interactions with ads and conversions. diff --git a/en/docs/5.1-api-integration.md b/en/docs/5.1-api-integration.md index 232548a..057e3f1 100644 --- a/en/docs/5.1-api-integration.md +++ b/en/docs/5.1-api-integration.md @@ -6,3 +6,24 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +The integration is based on three pillars that ensure the solution's functionality. + +### Integration Pillars + +1. **[Catalog Synchronization](./5.2-catalog-synchronization.md):** Keep VTEX Ads synchronized with your product catalog and inventory (price and stock). Essential for product ads. +2. **[Ad Query](./5.3-ad-query.md):** Your platform requests from the API the ads that should be displayed on different pages and contexts. +3. **[Events](./5.4-events.md):** Your platform notifies the API of all user interactions with the ads and, crucially, of conversions (sales). + +### Ad Types + +| Ad Type | API Type | Description | +| :--- | :--- |:------------------------------------------------| +| **Sponsored Products** | `product` | Ads for individual products. | +| **Display** | `banner` | Visual ads (static image or video). | +| **Sponsored Brands** | `sponsored_brand` | Brand ads with a title, logo, and products. (static image or video) | +| **Digital Signage** | `digital_signage`| Content for physical screens and totems. | + +### Audience Integration + +Target ads to specific audiences to increase relevance. See more in [Audience Integration](./5.2-audience-integration.md). diff --git a/en/docs/5.2-vtex-integration.md b/en/docs/5.2-vtex-integration.md index 38942b5..6b9e9be 100644 --- a/en/docs/5.2-vtex-integration.md +++ b/en/docs/5.2-vtex-integration.md @@ -6,3 +6,35 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +For stores on the VTEX platform, Newtail offers a storefront app (`Newtail Media APP VTEX`) that drastically simplifies implementation. The app includes visual components and all the logic for ad queries and event notifications. + +* **Step 1: Catalog Synchronization** + * Synchronizing the product catalog is a prerequisite. It can be done in two ways: + 1. **Via API:** By providing Newtail with API keys to read your catalog. + 2. **Via XML:** By providing a link to a Google Shopping format XML feed, which must contain the `SKU` field for product identification. + +* **Step 2: App Installation** + 1. **Add as Dependency:** In your theme's `manifest.json` file, add `"newtail.media": "0.x"` to the `peerDependencies`. + 2. **Install the App:** Run the command `vtex install newtail.media@0.x` in your terminal. + +* **Step 3: Configuration** + 1. **Publisher ID:** In your VTEX store's admin, go to `Store Settings > Newtail Media` and enter your `Publisher ID` provided by Newtail. + 2. **Content Security Policy (CSP):** Add the following directives to your `policies.json`: + ```json + { + "contentSecurityPolicy": { + "default-src": ["'self'", "newtail-media.newtail.com.br"], + "connect-src": ["'self'", "newtail-media.newtail.com.br"] + } + } + ``` + +* **Step 4: Using the Blocks** + * Declare the app's blocks in your theme's templates to display the ads. + + * **Available Components:** + * `newtail-media-banner`: Renders sponsored banners. + * `newtail-media-shelf`: Renders a shelf of sponsored products. + * `newtail-media-search`: Adds "Sponsored" badges to products in search results. + * `newtail-media-conversion`: An essential component that manages the sending of conversion events. **Must be included on all pages.** \ No newline at end of file diff --git a/en/docs/5.3-catalog-synchronization.md b/en/docs/5.3-catalog-synchronization.md index 5d47602..9d7b47b 100644 --- a/en/docs/5.3-catalog-synchronization.md +++ b/en/docs/5.3-catalog-synchronization.md @@ -6,3 +6,194 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +The first step is synchronization, which occurs on two fronts: + +> **Note for VTEX stores:** For stores on the VTEX platform, catalog synchronization occurs transparently, with no additional integration required for this purpose. + +#### **Product Synchronization** +Sends product registration information. Requires authentication. + +* **Endpoint:** `POST https://api-retail-media.newtail.com.br/product/bulk/products` +* **Limits:** 500 products per request; 3 simultaneous requests. + +| Field | Description | Type | Required? | +| :--- | :--- | :--- | :--- | +| `product_sku` | Unique product ID/SKU. | String | Yes | +| `parent_sku` | Parent product SKU (for variations). | String | No | +| `name` | Product name. | String | Yes | +| `url` | Canonical URL of the product page. | String | Yes | +| `image_url`| URL of the main product image. | String | No | +| `categories` | List of categories. | Array[String] | Yes | +| `brand` | Product brand. | String | No | +| `gtins` | Barcodes (EAN). **Required for campaigns on the VTEX Ads Network.**| Array[String] | No/Yes | +| `tags` | "Tags" to contextualize searches. Max 10 per SKU, 64 chars per tag. Only for `product` campaigns. | Array[String] | No | +| `sellers` | List of sellers who sell the product (in a marketplace). | Array[String] | No | +| `metadata` | Object for additional information (key-value). | Object | No | + +--- + +### **Structuring Categories** + +> **Important:** The `categories` field is crucial for campaign targeting and product organization. It must be structured hierarchically, representing the full path from the root category to the product's specific category. + +The `categories` field must be an array of strings, where each string is a level of the category tree. The hierarchy is built by sending all parent categories up to the most specific one. + +**Correct Example:** + +For a product in the "For Women" perfume category, the `categories` array should be: + +```json +"categories": [ + "Beauty", + "Beauty > Fragrances", + "Beauty > Fragrances > Perfume", + "Beauty > Fragrances > Perfume > For Women" +] +``` + +This structure allows the platform to understand the product's context at all levels, from the broadest ("Beauty") to the most specific ("For Women"). + +--- + +**Request Example:** + +```bash +curl --location 'https://api-retail-media.newtail.com.br/product/bulk/products' \ +--header 'x-app-id: XXXX' \ +--header 'x-api-key: YYYY' \ +--header 'Content-Type: application/json' \ +--data '[ + { + "product_sku": "allan", + "name": "allan", + "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616", + "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629", + "categories": [ + "Beauty", + "Beauty > Fragrances", + "Beauty > Fragrances > Perfume", + "Beauty > Fragrances > Perfume > For Women" + ], + "brand": "SALVADOR DALÍ", + "profit_margin": null, + "gtins": [ + "3331438450103" + ], + "sellers": [], + "skus": [] + }, + { + "product_sku": "allan2", + "name": "allan2", + "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616", + "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629", + "categories": [ + "Beauty", + "Beauty > Fragrances", + "Beauty > Fragrances > Perfume", + "Beauty > Fragrances > Perfume > For Women" + ], + "brand": "SALVADOR DALÍ", + "profit_margin": null, + "gtins": [ + "3331438450103" + ], + "sellers": [], + "skus": [], + "tags": ["Abart", "Mega Maio"] + } +]' +``` + +**Success Response Example:** + +``` +Status: 202 Accepted +Content-Type: application/json + +{ + "messages": [ + "products will be processed soon" + ] +} +``` + +--- + +#### **Inventory Synchronization** +Sends price and stock information for products. Requires authentication. + +* **Endpoint:** `POST https://api-retail-media.newtail.com.br/product/bulk/inventories` +* **Limits:** 500 products per request; 3 simultaneous requests. + +| Field | Description | Type | Required? | +| :--- | :--- | :--- | :--- | +| `product_sku` | Unique product ID/SKU. | String | Yes | +| `price` | Current product price. | Float | Yes | +| `promotional_price` | "From" price (list/original). | Float | Yes | +| `is_available` | Available product (in stock). | Boolean | Yes | +| `store_id` | Store ID. If store_id is not provided, it will be interpreted as meaning this inventory information will be used for all stores. | String | No | +| `metadata` | Object for additional information (key-value). | Object | No | + +**Request Example:** + +```bash +curl --location 'https://api-retail-media.newtail.com.br/product/bulk/inventories' \ +--header 'x-app-id: XXXX' \ +--header 'x-api-key: YYYY' \ +--header 'Content-Type: application/json' \ +--data '[ + { + "product_sku": "120210", + "store_id": "1", + "price": 18.20, + "promotional_price": 16.32, + "is_available": true + }, + { + "product_sku": "120212", + "price": 18.20, + "promotional_price": 0, // Remove promotional price + "is_available": true + } +]' +``` + +**Success Response Example:** + +``` +Status: 202 Accepted +Content-Type: application/json + +{ + "messages": [ + "inventory will be processed soon" + ] +} +``` + +--- + +### **Best Practices for Synchronization** + +1. **Complete Initial Synchronization:** + * Send the entire catalog in the first synchronization. + * Divide into batches of up to 500 products to avoid timeouts. + +2. **Incremental Updates:** + * After the initial synchronization, send only new or changed products. + * Keep a record of the last modification date of each product. + +3. **Update Frequency:** + * Prices and stock: Update at least once a day, ideally in real-time for significant changes. + * Registration information: Update when there are changes. + +4. **Error Handling:** + * Implement retries with exponential backoff for temporary failures. + * Monitor API responses to identify persistent problems. + +5. **Data Validation:** + * Verify that all required fields are filled in. + * Ensure that product and image URLs are valid and accessible. + * Make sure categories follow the recommended hierarchical structure. \ No newline at end of file diff --git a/en/docs/5.4-audience-integration.md b/en/docs/5.4-audience-integration.md index c08c952..6e6a2e9 100644 --- a/en/docs/5.4-audience-integration.md +++ b/en/docs/5.4-audience-integration.md @@ -6,3 +6,100 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +> **Note:** Audience integration is optional, but highly recommended to improve campaign targeting and ad relevance. + +Audience integration has a single integration method: **Batch Submission** to the S3 bucket provided by VTEX Ads. + +> **Important:** FTP/SFTP integration is **deprecated** and should only be used for legacy implementations. New projects must use the S3 bucket exclusively. + +> **Warning:** If there is no audience integration, you must open a ticket with your Account Manager requesting pre-population of segmentation information with base data (`STATE`, `CITY`, `GENDER`, and `AGE`). You can also provide a list of audiences to be registered, and we recommend keeping these audiences updated periodically. + +### Batch Submission - S3 Bucket + +The integration connection occurs through periodic audience uploads to the publisher's dedicated S3 bucket. Access credentials (IAM key/secret or cross-account role) and the bucket base path must be requested from your Newtail contact. + +* **File Format:** `Parquet` with `Snappy` compression. +* **Directory Pattern (S3 key):** Upload files using: + `s3://<bucket>/<PREFIX>/audiences/YYYY/mm/dd/TIMESTAMP.parquet.snappy` + +| Attribute | Description | Example | +| :--- | :--- | :--- | +| `PREFIX` | The prefix will be provided by Newtail. | `xyz` | +| `YYYY` | 4-digit year of generation. | `2023` | +| `mm` | Two-digit month of generation (January = 01 and December = 12). | `09` | +| `dd` | Two-digit day of generation (from 01 to 31). | `31` | +| `TIMESTAMP`| Timestamp is the number of seconds since 1970 (the file name can be anything, the timestamp is just a suggestion that will never be repeated). | `1694812122` | + +> **Recommendation for submission:** In the initial integration, it is essential that all data be sent. This data can be sent in multiple files (depending on the size of the base, a good number is 1 million lines per file). After the first integration, the ideal is to send only the delta of the rows that had any modification. + +> **Legacy compatibility:** If you are already integrated via SFTP, contact the VTEX Ads team to plan the migration to the S3 bucket. The SFTP flow will no longer receive new enhancements and may be discontinued. + +### Runtime Alternative Without Prior Integration + +If you choose not to integrate audiences via batch, you can still use segmentation at runtime by sending the data in the `segmentation` field of the ad query request. See [5.5. Ad Query](5.5-ad-query.md). + +### Audience File Attributes + +Most attributes are not mandatory, however, the more complete this information is, the better the relevance will be. + +> The columns are **case-sensitive**. Keep the column names as they are presented. + +| Column | Type | Required? | Description | +| :--- | :--- | :--- | :--- | +| `CUSTOMER_ID` | String | Yes | Unique customer identifier. | +| `EMAIL_HASHED` | String | No | PII based on the customer's email. | +| `PHONE_HASHED` | String | No | PII based on the customer's primary phone number. | +| `SOCIAL_ID_HASHED` | String | No | PII based on the customer's CPF. | +| `FIRST_NAME_HASHED` | String | No | PII based on the customer's First Name. | +| `LAST_NAME_HASHED` | String | No | PII based on the customer's Last Name. | +| `GENDER` | String | No | Indicates the customer's gender (`F` for female, `M` for male, `O` for others, `NULL` for unidentified). | +| `AGE` | Int | No | Indicates the customer's age. | +| `CEP` | String | No | Indicates the customer's postal code. | +| `COUNTRY` | String | No | Indicates the user's country. | +| `STATE` | String | No | Indicates the state where the customer resides. | +| `CITY` | String | No | Indicates the city where the customer resides. | +| `NEIGHBORHOOD` | String | No | Indicates the neighborhood where the customer resides. | +| `AUDIENCES` | String | No | A list of audiences, separated by a semicolon (;). | +| `NBO_PRODUCTS` | String | No | A list of product SKUs, separated by a semicolon (;). | +| `NBO_CATEGORIES` | String | No | A list of categories, separated by a semicolon (;). The list can receive a category tree using " > " as a separator (e.g., `Tablets;Beverages > Non-Alcoholic Beverages;Books > Gastronomy > Bar and Restaurant Guides`). | + +### Field Hashing + +Confidential data must be encrypted before being sent using the **SHA256** algorithm. + +* `EMAIL_HASHED` +* `PHONE_HASHED` +* `SOCIAL_ID_HASHED` +* `FIRST_NAME_HASHED` +* `LAST_NAME_HASHED` + +> Before generating the hash of the data, it is necessary to remove all **SPACES** and convert its values to **LOWERCASE**. +> For the `PHONE_HASHED` attribute, it will be necessary to format it in the **E.164** standard and include the country calling code. + +#### E.164 Format + +1. Remove all non-numeric characters, such as spaces, hyphens, parentheses, and symbols. +2. Add the country code with the plus sign (+) at the beginning. +3. Add the area code (if applicable) without the leading zero. +4. Include the local phone number without the leading zero (if applicable). + +**Example:** + +* A phone number from the United States, with area code 212 and local number 555-1234, would be formatted as: `+12125551234` + +#### Creating a HASH in Python + +```python +import re +import hashlib + +hash_obj = hashlib.sha256() + +def create_hash(x): + cleaned = re.sub('\s+', '', x.lower()) + hash_obj.update(cleaned.encode('utf-8')) + return hash_obj.hexdigest() + +create_hash(' Allan ') #=> 8c01ade3cb71d3ac7c718ed5a0c565155a4c05a216d9e59013c5d7b49e916914 +``` diff --git a/en/docs/5.5-ad-query.md b/en/docs/5.5-ad-query.md index b2eabdf..881772c 100644 --- a/en/docs/5.5-ad-query.md +++ b/en/docs/5.5-ad-query.md @@ -6,3 +6,397 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +With the catalog synchronized, your platform requests ads to fill the ad spaces (`placements`). The request is a `POST` and the `publisher_id` must be provided in the URL. + +* **Endpoint:** `POST https://newtail-media.newtail.com.br/v1/rma/:publisher_id` +* **Content-Type:** All requests must include the `Content-Type: application/json` header. + +#### Request Best Practices + +- **HTTP persistence:** Prefer persistent connections (`Connection: keep-alive`). +- **Timeout:** Apply a 500–600 ms timeout to the ad query (see 5.6 for events guidance). + +#### **Request Parameters** + +| Field | Description | Type | Required? | +| :--- | :--- | :--- | :--- | +| `session_id` | Persistent visitor identifier (≥ 14 days). For mobile applications, the device ID should be sent as the session_id (GAID on Android and IDFA on iOS), so that the session is maintained indefinitely. | String | Yes | +| `user_id` | Unique ID of the logged-in user (alphanumeric). | String | No (Recommended) | +| `store_id` | Filters ads by a specific store's stock. | String | No | +| `channel` | Access channel: `site`, `msite`, `app` (for ad query). | String | Yes | +| `context` | Context: `home`, `category`, `search`, `product_page`, `brand_page`, `digital_signage`.| String | Yes | +| `term` | Term searched by the user. | String | Only `context: 'search'` | +| `category_name` | Browsed category (full breadcrumb).| String | Only `context: 'category'`| +| `product_sku` | SKU of the product being viewed. | String | Only `context: 'product_page'` | +| `brand_name` | Name of the brand being viewed. | String | Only `context: 'brand_page'` | +| `device_id` | Unique device ID (screen, totem). | String | Only `context: 'digital_signage'` | +| `store_name` | Name of the store where the device is located. | String | Only `context: 'digital_signage'` | +| `placements` | Object defining the ad `placements`. | Object | Yes | +| `placements.{name}.quantity` | Desired number of ads. | Integer | Yes | +| `placements.{name}.size` | Expected size (Image: `desktop`/`mobile`; Video: `1080p`/`720p`/`480p`/`360p`/`320p`). | String | Only `types: ['banner', 'sponsored_brand']` | +| `placements.{name}.types` | Allowed types (`product`, `banner`, etc.). | Array[String] | Yes | +| `placements.{name}.assets_type`| Accepted media (`image`, `video`). Default: `["image"]`. | Array[String] | Only `types: ['banner', 'sponsored_brand']` | +| `placements.{name}.allow_sku_duplications` | Allows the same SKU to appear more than once within the same placement. | Boolean | No (Default=false) | +| `userAgent` | Client environment identification (body field, not the HTTP `User-Agent` header). | String | No | +| `segmentation` | Data for real-time targeting. | Array[Object] | No | +| `segmentation.#.key` | The type of segmentation. | String | No | +| `segmentation.#.values` | Array of values for the segmentation. | Array[String] | No | +| `tags` | "Tags" to contextualize searches (primarily for `search`). Max 10 per SKU, 64 chars per tag. Only for `product` campaigns. | Array[String] | No | +| `brand` | Publisher's site name. | String | Required when the publisher has multiple sites | +| `dedup_campaign_ads` | Deduplicate by campaign (response contains at most one ad per campaign). | Boolean | No (Default=false) | +| `dedup_ads` | Deduplicate by `ad_id` across multiple placements (use only when querying multiple placements at the same time). | Boolean | No (Default=false) | +| `skus` | Filters ad results to return only ads for the specified SKUs. Only compatible with Sponsored Products (product campaigns). | Array[String] | No | + +##### Fields by Context + +| Context | Additional required fields | +| :--- | :--- | +| `home` | — | +| `search` | `term` | +| `category` | `category_name` | +| `product_page` | `product_sku` | +| `brand_page` | `brand_name` | +| `digital_signage` | `device_id`, `store_name` | + +#### **⚠️ Important Context and Ad Eligibility Rules** + +##### Filter Limitations + +> **Important:** It is not possible to filter by specific `placement`. Ad selection is based on `context` and request parameters. + +##### Eligibility by Context + +###### `home` Context + +In the **home** context, the following can be returned: + +- ✅ **Banner/Video/Sponsored Brands Ads** that use **category** as a targeting criterion +- ✅ **Product Ads (Sponsored Products)** are also eligible + +**Example:** +```json +{ + "context": "home", + "placements": { + "site_home_middle_banner": { + "quantity": 3, + "types": ["banner", "sponsored_brand"], + "assets_type": ["image", "video"], + "size": "desktop" + }, + "site_home_shelf_product": { + "quantity": 10, + "types": ["product"] + } + } +} +``` + +###### `brand_page` Context + +In the **brand_page** context, the following can be returned: + +- ✅ **Banner/Video/Sponsored Brands Ads** for the brand +- ✅ **Product Ads (Sponsored Products)** from the brand + +**Example:** +```json +{ + "context": "brand_page", + "brand_name": "Nike", + "placements": { + "site_brand_top_banner": { + "quantity": 1, + "types": ["banner", "sponsored_brand"], + "assets_type": ["image"], + "size": "desktop" + }, + "site_brand_shelf_product": { + "quantity": 12, + "types": ["product"] + } + } +} +``` + +###### `digital_signage` Context + +In the **digital_signage** context, ads can be returned for physical screens/totems. + +**Example:** +```json +{ + "context": "digital_signage", + "device_id": "totem-abc-001", + "store_name": "Downtown Store", + "placements": { + "totem_home_main_video": { + "quantity": 1, + "types": ["banner"], + "assets_type": ["video"], + "size": "720p" + } + } +} +``` + +###### `search` Context + +In the **search** context, the following can be returned: + +- ✅ **Banner/Video/Sponsored Brands Ads** that are **keyword-based** +- ✅ **Any Product Campaign (Sponsored Products)** + +**⚠️ Exact Keyword Matching:** + +Keyword matching in the `search` context is **exact** (no stemming/synonyms). This means: + +- The advertiser **must specify exactly** which keywords they want to use in the Banner/Video/Sponsored Brands campaign +- If a user searches for "nike shoes", the ad will only be eligible if the advertiser registered exactly the keyword "nike shoes" +- There is no approximate matching or similar words matching + +**Example:** +```json +{ + "context": "search", + "term": "nike shoes", + "placements": { + "site_search_top_banner": { + "quantity": 1, + "types": ["banner", "sponsored_brand"], + "assets_type": ["image"], + "size": "desktop" + }, + "site_search_shelf_product": { + "quantity": 20, + "types": ["product"] + } + } +} +``` + +**Expected behavior:** +- **Banner/Sponsored Brand:** Will only appear if the advertiser registered the exact keyword "nike shoes" in the campaign +- **Sponsored Products:** Products related to the search term will be returned + +###### `category` Context + +In the **category** context, the following can be returned: + +- ✅ **Banner/Video/Sponsored Brands Ads** that use the corresponding **category** +- ✅ **Product Ads (Sponsored Products)** from the category + +**Example:** +```json +{ + "context": "category", + "category_name": "Sports > Shoes > Sneakers", + "placements": { + "site_category_top_banner": { + "quantity": 1, + "types": ["banner", "sponsored_brand"], + "assets_type": ["image", "video"] + } + } +} +``` + +###### `product_page` Context + +In the **product_page** context, the following can be returned: + +- ✅ **Product Ads (Sponsored Products)** related to the viewed product + +**Example:** +```json +{ + "context": "product_page", + "product_sku": "12345", + "placements": { + "site_product_recommendation": { + "quantity": 5, + "types": ["product"] + } + } +} +``` + +#### **Query Response** +The response is a JSON where each key is a `placement` name. The structure of each ad in the response depends on its type. + +##### **Common Response Fields for All Ad Types** +These fields are present in all ad types: + +| Field | Description | +| :--- | :--- | +| `{placementName}.#.ad_id` | Unique ad ID. | +| `{placementName}.#.type` | Ad type (`product`, `banner`, `sponsored_brand`, `digital_signage`). | +| `{placementName}.#.click_url`| **URL to notify the click event.** | +| `{placementName}.#.impression_url`| **URL to notify the impression event.**| +| `{placementName}.#.view_url` | **URL to notify the view event.** | +| `{placementName}.#.seller_id` | ID of the seller of the advertised product (optional). | + +##### **Type-Specific Response Fields** + +###### **Product Ads** +Additional fields for ads of type `product`: + +| Field | Description | +| :--- | :--- | +| `{placementName}.#.product_sku`| SKU of the product being advertised. | + +###### **Banner Ads** +Additional fields for ads of type `banner`: + +| Field | Description | +| :--- | :--- | +| `{placementName}.#.media_url`| URL of the image or video to be displayed. | + +###### **Sponsored Brand Ads** +Additional fields for ads of type `sponsored_brand`: + +| Field | Description | +| :--- | :--- | +| `{placementName}.#.media_url`| URL of the image or video to be displayed. | +| `{placementName}.#.products`| Array of products associated with the sponsored brand. | +| `{placementName}.#.products.#.product_sku`| SKU of the associated product. | +| `{placementName}.#.products.#.media_url`| URL of the product image. | + +###### **Digital Signage Ads** +Additional fields for ads of type `digital_signage`: + +| Field | Description | +| :--- | :--- | +| `{placementName}.#.media_url`| URL of the image or video to be displayed. | +| `{placementName}.#.duration`| Duration of the ad display in seconds. | + +##### Example Response (multi-placement) + +```json +{ + "site_home_middle_banner": [ + { + "ad_id": "ad-001", + "type": "banner", + "media_url": "https://cdn.example.com/banner1.jpg", + "impression_url": "https://events.../impression/abc", + "view_url": "https://events.../view/abc", + "click_url": "https://events.../click/abc" + } + ], + "site_home_shelf_product": [ + { + "ad_id": "ad-101", + "type": "product", + "product_sku": "SKU-123", + "seller_id": "SELLER-9", + "impression_url": "https://events.../impression/def", + "view_url": "https://events.../view/def", + "click_url": "https://events.../click/def" + } + ] +} +``` + +### Best Practices + +#### Placement Naming + +Adopt a clear standard, such as `{channel}_{context}_{position}_{type}` (e.g., `msite_search_top-shelf_product`). For detailed recommendations, see `en/docs/5.5.1-placement-naming.md`. + +| channel | context | position | type | example | +| --- | --- | --- | --- | --- | +| site | home | middle | banner | site_home_middle_banner | +| msite | product | top-shelf | product | msite_product_top-shelf_product | +| app | search | top-shelf | product | app_search_top-shelf_product | +| app | search | top-shelf | banner | app_search_top-shelf_banner | +| site | category | bottom-shelf | banner | site_category_bottom-shelf_banner | +| site | product | filter-bar | product | site_product_filter-bar_product | + +#### IAB Standard Image Sizes + +For banner-type ads, it is important to use images in the standard formats defined by the IAB (Interactive Advertising Bureau). This ensures compatibility and a better visual experience across different sites and devices. + +**Main Formats:** + +* **Medium Rectangle:** 300x250 pixels +* **Leaderboard:** 728x90 pixels +* **Wide Skyscraper:** 160x600 pixels +* **Mobile Leaderboard:** 320x50 pixels +* **Billboard:** 970x250 pixels +* **Half Page:** 300x600 pixels + +#### Video Size Options + +For video ad requests, you should specify the size parameter to filter by video resolution. The available options are: + +* **1080p** (1920x1080 pixels) - Recommended only for full-screen videos +* **720p** (1280x720 pixels) - Recommended only for full-screen videos +* **480p** (854x480 pixels) +* **360p** (640x360 pixels) +* **320p** (568x320 pixels) - Recommended for mobile devices + +**Important:** When requesting video ads, use only the resolution identifier (e.g., `"720p"`) in the size parameter, not the full dimensions. For example, to filter by 1280x720 resolution, use `"size": "720p"` in your ad request. + +### Ad Targeting + +Target ads to specific audiences to increase relevance. + +#### **Real-Time Targeting** +Send demographic or audience data directly in the body of the **ad query**, in the `segmentation` field. + +The `segmentation` field is an array of objects, where each object contains: +- `key`: The type of segmentation (e.g., "STATE", "CITY", "GENDER") +- `values`: Array of values for the segmentation + +**Segmentation Example:** + +```json +[ + { + "key": "STATE", + "values": [ + "CA" + ] + }, + { + "key": "CITY", + "values": [ + "San Francisco" + ] + } +] +``` + +**Available Segmentation Types:** + +| Key | Description | Example Values | +| :--- | :--- | :--- | +| `STATE` | User's state | "CA", "NY", "TX" | +| `CITY` | User's city | "San Francisco", "New York" | +| `GENDER` | User's gender | "M", "F" | +| `AGE` | User's age | "22", "35" | +| `AUDIENCES` | Custom audience | "high_value_customers", "cart_abandoners" | +| `NBO_CATEGORIES` | Indicates the possible categories that the user intends to buy | "Electronics", "Books" | + +### Response Codes and Errors + +- **200 OK:** Query processed successfully (returns JSON per placement). +- **422 Unprocessable Entity:** Field validation error (JSON Schema/Ajv-like format). +- **400 Bad Request / 404 Not Found:** Invalid request or resource not found. +- **429 Too Many Requests:** Rate limit exceeded. +- **5xx:** Internal errors. + +Example 422 (partial): +```json +[ + { + "instancePath": "/context", + "keyword": "enum", + "message": "must be equal to one of the allowed values", + "params": {"allowedValues": ["home","category","search","product_page","brand_page","digital_signage"]}, + "schemaPath": "#/properties/context/enum" + } +] +``` diff --git a/en/docs/5.5.1-placement-naming.md b/en/docs/5.5.1-placement-naming.md index 96097a4..6df5d5e 100644 --- a/en/docs/5.5.1-placement-naming.md +++ b/en/docs/5.5.1-placement-naming.md @@ -6,3 +6,35 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +Using clear, consistent placement names is essential to correctly measure the performance of each ad area on your site/app, make reporting easier, and speed up troubleshooting. + +Recommended naming pattern: + +``` +{channel}_{context}_{position}_{type} +``` + +Where: +- channel: access channel, e.g., site, msite (mobile site), app +- context: page/navigation context, e.g., home, category, search, product, brand_page, digital_signage +- position: block location on the page, e.g., top-vitrine, middle, bottom-vitrine, filter-bar +- type: creative type, e.g., product, banner, sponsored_brand + +Best practices: +- Use lowercase and no spaces (use hyphen for compounds, e.g., top-vitrine). +- Avoid obscure abbreviations; keep consistency across pages and channels. +- The name should be stable over time (do not include dates, campaign names, etc.). + +Examples: + +| channel | context | position | type | example | +| --- | --- | --- | --- | --- | +| site | home | middle | banner | site_home_middle_banner | +| msite | product | top-vitrine | product | msite_product_top-vitrine_product | +| app | search | top-vitrine | product | app_search_top-vitrine_product | +| app | search | top-vitrine | banner | app_search_top-vitrine_banner | +| site | category | bottom-vitrine | banner | site_category_bottom-vitrine_banner | +| site | product | filter-bar | product | site_product_filter-bar_product | + +Note: Use the same channel and context values you send in Ad Query (5.5) to keep traceability between requests and reports. \ No newline at end of file diff --git a/en/docs/5.6-events.md b/en/docs/5.6-events.md index f616e35..4efd876 100644 --- a/en/docs/5.6-events.md +++ b/en/docs/5.6-events.md @@ -6,3 +6,367 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +Event notification is **crucial** for attribution and measurement. + +#### Best Practices + +* **HTTP Persistence:** Use persistent HTTP connections (`Connection: keep-alive` in the header) to optimize performance. +* **Timeout (ad query):** For ad query calls (see section 5.5), implement a 500–600 ms timeout to avoid harming the user experience. + +#### **User and Session Identification** + +* **`session_id`:** Persistent visitor identifier. Required in all events. Must remain consistent during browsing and across sessions within the conversion window (≥ 14 days). The `session_id` should be unique per user and ideally not expire during this period. For mobile applications, the device ID should be sent as the session_id (GAID on Android and IDFA on iOS), so that the session is maintained indefinitely. +* **`user_id`:** Unique customer ID on the platform, consistent across channels. **Required in conversion**. **Optional (recommended)** for impression, view, and click. The `user_id` must be the same across app, website, and physical store. + +After identifying the user and the session, follow these guidelines when firing events: + +* **Impression (`impression_url`):** Fire the event as soon as you decide to display the Ads returned by the ad server, even if the Ad ultimately is not shown to the user (e.g., due to layout changes or blocking). +* **View (`view_url`):** Fire the event when at least 50% of the Ad stays within the user's viewport for a continuous 1 second. +* **Click (`click_url`):** Fire the event every time the user clicks the Ad. + +There is no need to persist event state across page loads, but make sure each event is sent only once for the same Ad and context. + +#### **Impression, View, and Click Notification** + +Send a `POST` request to the respective event URL (`impression_url`, `view_url`, `click_url`) provided in the ad query, with a JSON body containing `session_id` (**required**) and `user_id` (**when available**). + +* **When to send:** `impression_url` when the Ad is rendered; `view_url` when the Ad is visible (if you measure viewability); `click_url` on user click. +* **Event URLs:** always use the event URLs returned in the ad query; do not derive them manually. +* **Content-Type:** All requests must include the `Content-Type: application/json` header. +* **Required Method (Browser):** It is **mandatory** to use `navigator.sendBeacon()` to ensure asynchronous sending without blocking navigation and prevent loss of events when the user navigates to another page or closes the browser. +* **Success Response:** `HTTP 202 Accepted`. + +See browser event sending examples in `examples/EVENTS_IMPRESSIONS_VIEWS_CLICKS_BROWSER.md`. + +**Example of sending an event using Beacon API:** + +```javascript +// Function to send impression event +function sendImpressionEvent(impressionUrl, userId, sessionId) { + // Event data + const eventData = { + user_id: userId, + session_id: sessionId + }; + + // Check if browser supports Beacon API + if (navigator.sendBeacon) { + // Convert data to JSON + const blob = new Blob([JSON.stringify(eventData)], {type: 'application/json'}); + + // Send event asynchronously + const success = navigator.sendBeacon(impressionUrl, blob); + + if (!success) { + console.error('Failed to send event via Beacon API'); + // Implement fallback if needed + } + } else { + // Fallback for browsers that don't support Beacon API + const xhr = new XMLHttpRequest(); + xhr.open('POST', impressionUrl, true); // true for asynchronous + xhr.setRequestHeader('Content-Type', 'application/json'); + xhr.send(JSON.stringify(eventData)); + } +} + +// Example usage +sendImpressionEvent( + 'https://events.newtail-media.newtail.com.br/v1/beacon/impression/123456', + 'user-123', + 'session-456' +); +``` + +> **Important:** Using the Beacon API is mandatory to ensure that events are sent even when the user navigates to another page or closes the browser. This prevents loss of events and ensures more accurate measurement. + +#### **Conversion Notification** + +When a purchase is completed, send the order data. + +* **Endpoint:** `POST https://events.newtail-media.newtail.com.br/v1/beacon/conversion` +* **Content-Type:** All requests must include the `Content-Type: application/json` header. +* **Request Body:** The object must contain the order data. The item price should not be multiplied by the quantity. + +See conversion examples in `examples/EVENTS_CONVERSION_BROWSER.md` (Browser) and `examples/EVENTS_CONVERSION_CURL.md` (cURL). + +| Order Field | Description | Type | Required? | +| :--- | :--- | :--- | :--- | +| `publisher_id` | Publisher ID. | String | Yes | +| `user_id` | ID of the user who made the purchase. | String | Yes | +| `session_id` | Session ID of the purchase. | String | Yes | +| `order_id` | Order ID. | String | Yes | +| `created_at` | Order date/time (ISO 8601 in UTC). | String | Yes | +| `items` | List of order items. | Array[Item] | Yes | +| `channel` | Sales channel (e.g., ecommerce, app, physical store). | String | Yes | +| `brand` | Brand/site where the sale occurred (required when there is more than one site). | String | No/Yes | +| `gender` | Indicates the customer's gender. F: for female, M: for male, O: for others, null: for unidentified. | String | No (Recommended) | +| `uf` | Indicates the state of the order purchase. | String | No (Recommended) | +| `city` | Indicates the city where the customer made the purchase. | String | No (Recommended) | +| `is_company` | Indicates if the sale was made to a company or individual. | Boolean | No (Recommended) | +| `email_hashed` | User's email in hash format (SHA256). | String | Yes | +| `phone_hashed`| User's phone in hash (SHA256). | String | No (Recommended) | +| `social_id_hashed`| User's Tax ID (CPF/CNPJ) in hash (SHA256). | String | No (Recommended) | +| `first_name_hashed` | User's First Name (hashed). | String | No (Recommended) | +| `last_name_hashed` | User's Last Name (hashed). | String | No (Recommended) | + +> Recommended normalization for hashing: +> - `email_hashed`: lowercase and trim the email; SHA-256 hash in hexadecimal. +> - `phone_hashed`: phone in E.164 format (e.g., +15551234567), no masks; SHA-256 hash in hexadecimal. +> - `social_id_hashed`: tax ID digits only (no punctuation); SHA-256 hash in hexadecimal. +> - `first_name_hashed` / `last_name_hashed`: names normalized (trim, no double spaces); SHA-256 hash in hexadecimal. + +#### **Order Items Structure** + +##### Item Object Fields + +| Field | Description | Type | Required | +|-------|-----------|------|-----------------| +| `sku` | Unique product SKU identifier | String | **Required** | +| `quantity` | Quantity of product purchased | Double | **Required** | +| `price` | Original product price (list price) | Double | **Required** | +| `promotional_price` | Promotional product price (sale price) | Double | **Required** | +| `seller_id` | Seller identifier | String | Optional | +| `product_id` | Unique product identifier that encompasses the SKU | String | Optional | + +##### ⚠️ Important Notes + +1. **Unit values**: The `price` and `promotional_price` fields must contain the **unit** value of the product, **not** multiplied by quantity +2. **Required fields for measurement**: If `price` and `promotional_price` are not provided correctly, the conversion **cannot be measured** +3. **Monetary format**: Values must be sent as decimal numbers (e.g., 1899.00) + +#### **Usage Examples** + +##### Individual Item Example +```json +{ + "sku": "12221", + "seller_id": "1234", + "product_id": "4567", + "quantity": 1, + "price": 2000.00, + "promotional_price": 1899.00 +} +``` + +##### Complete Request Example + +```http +POST https://events.newtail-media.newtail.com.br/v1/beacon/conversion HTTP/1.1 +Accept: application/json +Content-Type: application/json +``` + +```json +{ + "channel": "ecommerce", + "publisher_id": "xxx", + "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", + "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", + "order_id": "123", + "email_hashed": "xyz", + "items": [ + { + "sku": "12221", + "seller_id": "1234", + "product_id": "4567", + "quantity": 1, + "price": 2000.00, + "promotional_price": 1899.00 + }, + { + "sku": "12222", + "seller_id": null, + "product_id": "4568", + "quantity": 2, + "price": 500.00, + "promotional_price": 400.00 + } + ], + "created_at": "2023-01-01T09:20:00Z" +} +``` + +**Note**: In the example above, observe that: +- The first item has quantity 1 with unit price of $2,000.00 +- The second item has quantity 2 with unit price of $500.00 (not $1,000.00) + +#### **API Responses** + +##### ✅ Success Response (HTTP 202) +```json +{ + "messages": [ + "conversion will be processed soon" + ] +} +``` + +##### ❌ Validation Error Response (HTTP 422) +The API returns validation errors in a JSON Schema–compatible (Ajv-like) format. + +Example error response: +```json +[ + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'user_id'", + "params": { + "missingProperty": "user_id" + }, + "schemaPath": "#/required" + }, + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'order_id'", + "params": { + "missingProperty": "order_id" + }, + "schemaPath": "#/required" + }, + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'publisher_id'", + "params": { + "missingProperty": "publisher_id" + }, + "schemaPath": "#/required" + }, + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'items'", + "params": { + "missingProperty": "items" + }, + "schemaPath": "#/required" + }, + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'created_at'", + "params": { + "missingProperty": "created_at" + }, + "schemaPath": "#/required" + } +] +``` + +#### **🎯 Product Match Rule for Conversions** + +##### Important: Product and Campaign Matching + +Conversions are **only computed** for campaigns when a **product match** occurs. This means: + +- ✅ **Conversion is measured**: When the product purchased by the user **belongs** to the campaign in which the user was impacted +- ❌ **Conversion is NOT measured**: When the purchased product **does not belong** to the campaign in which the user was impacted + +##### Practical Example: + +**Scenario 1 - With Match (Conversion Computed)** +- User viewed ad from Campaign A (products: SKU-001, SKU-002, SKU-003) +- User purchased product SKU-002 +- ✅ Conversion is attributed to Campaign A + +**Scenario 2 - Without Match (Conversion NOT Computed)** +- User viewed ad from Campaign B (products: SKU-004, SKU-005) +- User purchased product SKU-999 +- ❌ Conversion is NOT attributed to Campaign B + +#### **Code Example** + +##### JavaScript (Browser) +```javascript +const sendConversion = async (orderData) => { + const payload = { + channel: "ecommerce", + publisher_id: "xxx", + user_id: orderData.userId, + session_id: orderData.sessionId, + order_id: orderData.orderId, + email_hashed: orderData.emailHash, + items: orderData.items.map(item => ({ + sku: item.sku, + seller_id: item.sellerId || null, + product_id: item.productId || null, + quantity: item.quantity, + price: item.unitPrice, // Unit value, not multiplied + promotional_price: item.unitPromotionalPrice // Unit value, not multiplied + })), + created_at: new Date().toISOString() + }; + + try { + // Convert data to JSON + const blob = new Blob([JSON.stringify(payload)], {type: 'application/json'}); + + // Send event asynchronously using Beacon API + if (navigator.sendBeacon) { + const success = navigator.sendBeacon( + 'https://events.newtail-media.newtail.com.br/v1/beacon/conversion', + blob + ); + + if (success) { + console.log('Conversion sent successfully'); + } else { + console.error('Failed to send conversion via Beacon API'); + } + } else { + // Fallback for browsers that don't support Beacon API + const response = await fetch('https://events.newtail-media.newtail.com.br/v1/beacon/conversion', { + method: 'POST', + headers: { + 'Accept': 'application/json', + 'Content-Type': 'application/json' + }, + body: JSON.stringify(payload) + }); + + if (response.status === 202) { + console.log('Conversion sent successfully'); + } else if (response.status === 422) { + const errors = await response.json(); + console.error('Validation errors:', errors); + } + } + } catch (error) { + console.error('Error sending conversion:', error); + } +}; + +// Example usage +const order = { + userId: "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", + sessionId: "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", + orderId: "123", + emailHash: "xyz", + items: [ + { + sku: "12221", + sellerId: "1234", + productId: "4567", + quantity: 1, + unitPrice: 2000.00, + unitPromotionalPrice: 1899.00 + } + ] +}; + +sendConversion(order); +``` + +#### **Attribution and Deduplication Rules** + +* **Conversion Window:** The period after an interaction during which a sale can be attributed to the ad. + * **Click (for `product`):** 14 days. + * **View (for `display`/`video`):** 14 days. +* **Event Deduplication:** For the same user and ad, events are ignored for a period. + * **Impressions:** 1 minute. + * **Clicks:** 1 hour. + * **Conversions:** Idempotent by `order_id` (re-sending the same `order_id` within 30 days is ignored). diff --git a/en/docs/5.7-transparent-integration.md b/en/docs/5.7-transparent-integration.md index 3aa1280..d01901c 100644 --- a/en/docs/5.7-transparent-integration.md +++ b/en/docs/5.7-transparent-integration.md @@ -6,3 +6,117 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +> Note: This tool is only able to serve Banner and Video ads. + +The goal of transparent integration is to reduce friction as much as possible to start the VTEX Ads integration setup in the simplest way possible. + +## Requirements for the Proof of Concept (PoC) + +For this Proof of Concept to work, the following requirements are essential: + +1. **Catalog Integration:** A catalog integration needs to be up and running. + +2. **Script Installation:** Our script must be added to the website. + +3. **Conversion Event Trigger:** The conversion event needs to be triggered on the client side. + + +### 1\. Catalog Integration + +The catalog synchronization follows the format already defined for all integrations. + +### 2\. Script Installation + +Add the following script as early as possible in the page's `<head>` tag or on your website/msite: + +``` +<script src="https://cdn.newtail.com.br/retail-media/scripts/vtexads-magic-1.0.0.js"></script> +``` + +#### Script Requirements + +For the script to work correctly, the client must inform us of the origin of two important parameters: `session_id` and `user_id`. These parameters are usually stored in cookies, `sessionStorage`, or `localStorage`. + +### 3\. Conversion Event + +The conversion event must be sent after the order is created, without the need for payment confirmation. + +The following script demonstrates how to send data to an API endpoint using the `navigator.sendBeacon` interface. The `sendBeacon` method is ideal for sending small amounts of data asynchronously without impacting the page's performance. It is particularly useful for sending analytics data before the user navigates away from the page. + +``` +/** + * This script demonstrates how to send data to an API endpoint + * using the `navigator.sendBeacon` interface. + * + * The `sendBeacon` method is designed to send small amounts of data + * asynchronously without affecting the performance of the current page + * or the load time of the next one. + * + * It is particularly useful for sending analytics data before + * a user navigates away from a page. + */ + +// 1. Define the data you want to send. +const data = { + "publisher_id": "d4dff0cb-1f21-4a96-9acf-d9426a5ed08c", + "user_id": "26119121", + "order_id": "1758035060", + "channel": "site|msite|app", + "created_at": "2025-09-16T15:04:19.794Z", + "items": [ + { + "price": 12, + "promotional_price": 10, + "quantity": 1, + "sku": "sku1" + }, + { + "price": 15, + "promotional_price": 13, + "quantity": 1, + "sku": "sku2", + "seller_id": "seller1" + }, + { + "price": 19, + "promotional_price": 17, + "quantity": 1, + "sku": "sku3", + "product_id": "prod3" + }, + { + "price": 30, + "promotional_price": 25, + "quantity": 2, + "sku": "sku4", + "product_id": "prod4", + "seller_id": "seller2" + } + ] +}; + +// 2. Convert the data object into a JSON string. +const rawData = JSON.stringify(data); + +// 3. Create a Blob from the JSON string. +// This allows us to explicitly set the Content-Type for the request. +const blob = new Blob([rawData], { type: 'application/json' }); + +// 4. Define the endpoint URL. +const url = "https://newtail-media.newtail.com.br/v1/beacon/conversion"; + +// 5. Use `navigator.sendBeacon` to send the data. +// The method returns `true` if the browser queues the request +// for delivery and `false` otherwise. +// Note that `sendBeacon` does not return a Promise, so there is no +// `.then()` or `.catch()`. Delivery is not guaranteed, but it is +// highly likely. +const success = navigator.sendBeacon(url, blob); + +if (success) { + console.log("Beacon request successfully queued!"); +} else { + console.error("Failed to queue beacon request."); +} +``` diff --git a/en/docs/6-data-export.md b/en/docs/6-data-export.md index ca14021..b644881 100644 --- a/en/docs/6-data-export.md +++ b/en/docs/6-data-export.md @@ -6,3 +6,63 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +Data export allows you to receive detailed information about events and aggregated data systematically and periodically. The integration occurs through an S3 connection, and the data is delivered in specific formats for each type of export. + +### 6.1. Reports + +In addition to exporting via S3, it is possible to extract reports via the API. The routes return JSON by default, but can be exported as XLSX files by including the `download=true` parameter in the query. + +* `GET /report/v2/advertisers`: Advertiser information (publisher view) [[Example]](../../examples/EXPORT_ADVERTISER_DATA.md) +* `GET /report/v2/publishers`: Publisher information (advertiser view) [[Example]](../../examples/EXPORT_PUBLISHER_DATA.md) +* `GET /report/network/publishers`: Network publishers (for Network type accounts) [[Example]](../../examples/EXPORT_NETWORK_PUBLISHERS_DATA.md) +* `GET /campaign/v2`: Campaign listing report [[Example]](../../examples/EXPORT_CAMPAIGNS_LIST_DATA.md) +* `GET /campaign/:id`: Detailed campaign report [[Example]](../../examples/EXPORT_CAMPAIGN_DATA.md) +* `GET /report/advertisers/campaigns-detailed`: Detailed mixed campaign report for advertiser accounts, including subpublisher information for network campaigns [[Example]](../../examples/EXPORT_ADVERTISER_CAMPAIGNS_DETAILED_DATA.md) +* `GET /report/advertisers/ads-detailed`: Detailed ad report for advertiser accounts, including subpublisher breakdown for network campaigns [[Example]](../../examples/EXPORT_ADVERTISER_ADS_DETAILED_DATA.md) +* `GET /ad/results/v2`: Performance report for individual ads [[Example]](../../examples/EXPORT_ADS_DATA.md) + +### 6.2. Data Export + +The integration will always occur using an S3 (or compatible) connection that must be provided by the data recipient. The credentials must be passed to the Newtail team securely. + +The integration is compatible with: + +* **AWS S3:** `Access Key Id` and `Access Key Secret`. +* **Google Cloud Storage:** `Service Account`. +* **Azure Blob Storage**. + +#### Event Export + +Event export sends raw data of user interactions. + +* **Format:** `PARQUET` with `Snappy` compression. +* **Frequency:** Daily (D-1 data). +* **Folder Structure:** `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.snappy.parquet` +* **De-duplication:** It is guaranteed that all events will be sent, but not that they will be sent only once. Therefore, events must always be de-duplicated using the `event_id` or the combination of `order_id` and `product_sku` for conversion items. + +##### Event Types + +* **Impressions, Views, and Clicks:** + * **Fields:** `event_id` (de-duplication key), `session_id`, `user_id`, `ad_id`, `campaign_id`, `request_id`, `ad_type`, `placement_name`, `context`, `created_at`, `site`. +* **Conversions:** + * **Fields:** `event_id`, `session_id`, `user_id`, `order_id` (de-duplication key), `channel`, `placed_at`, `site`. +* **Conversion Items:** + * **Fields:** `event_id`, `session_id`, `user_id`, `order_id` (de-duplication key), `product_sku` (de-duplication key), `ad_id`, `campaign_id`, `request_id`, `ad_size`, `ad_type`, `placement_name`, `context`, `event_created_at`, `price`, `promotional_price`, `quantity`, `total_value`. + +#### Aggregated Data Export + +Aggregated data export sends consolidated reports. + +* **Format:** `CSV` with `UTF-8` encoding, comma-separated, and numbers in American format (decimal point). +* **Frequency:** Daily (D-1 data, with the publisher's timezone). +* **Folder Structure:** `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.csv` + +##### Report Types + +* **Advertisers:** + * **Fields:** `advertiser`, `advertiser_id`, `seller_id`, `wallet_balance`, `daily_budget`, `currency`. +* **Campaigns:** + * **Fields:** `day`, `name`, `campaign_id`, `campaign_type`, `campaign_status`, `impressions_total`, `clicks_total`, `ctr`, `ad_revenue`, `conversions_total`, `conversion_rate`, `sales_revenue`, `start_date`, `end_date`, `advertiser_id`. +* **Ads:** + * **Fields:** `day`, `ad_id`, `campaign_id`, `ad_status`, `ad_media_url`, `cpm`, `cpc`, `impressions_total`, `clicks_total`, `ctr`, `ad_revenue`, `conversions_total`, `conversion_rate`, `sales_revenue`, `product_sku`. diff --git a/en/docs/7-script-agent.md b/en/docs/7-script-agent.md index d61832d..5e8db9c 100644 --- a/en/docs/7-script-agent.md +++ b/en/docs/7-script-agent.md @@ -6,3 +6,79 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +## 7.1. Objective + +This document details the procedure for installing the **VTEX Ads** tracking script on all pages of a website (except for checkout pages) using Google Tag Manager (GTM). The correct implementation of this script is essential for collecting browsing data that allows for the optimization and targeting of Retail Media campaigns. + +## 7.2. Data Collected + +The VTEX Ads script was developed to exclusively collect non-sensitive browsing data, with the aim of personalizing the user experience and optimizing campaigns. + +**Data Collected:** + +- **For off-site campaigns:** + - `session_id`: Anonymous identifier for the browsing session. + - `ad_id`: Identifier of the ad that originated the traffic. +- **For audience segmentation (Page View):** + - `session_id`: Anonymous identifier for the browsing session. + - **Page Information:** URL, title (`<title>`), and description (`<meta name="description">`). + +> **Important:** The script **does not collect** any personally identifiable information (PII), such as name, email, CPF, phone number, address, or payment data. Data collection complies with major data protection laws. + +## 7.3. Script Details + +The script should be loaded asynchronously so as not to impact the page load time. + +- **Script URL:** `https://cdn.newtail.com.br/retail-media/scripts/vtexrma-agent.1.0.0.js` + +## 7.4. Step-by-Step Guide for Implementation via Google Tag Manager (GTM) + +To ensure the script runs as early as possible during page load, we recommend using the **Initialization** trigger. + +### Step 7.4.1: Create the Custom HTML Tag + +1. Access your GTM container and go to the **"Tags"** section. +2. Click **"New"** to create a new tag. +3. Give the tag a clear name, for example: **"Custom HTML - VTEX Ads Agent"**. +4. Click on **"Tag Configuration"** and select the **"Custom HTML"** tag type. +5. In the HTML field, insert the following code: + ```html + <script type="text/javascript" async src="https://cdn.newtail.com.br/retail-media/scripts/vtexrma-agent.1.0.0.js"></script> + ``` + +### Step 7.4.2: Configure the Main Trigger + +1. Below the tag configuration, click on **"Triggering"**. +2. Select the **"Initialization - All Pages"** trigger. This trigger ensures that the script is fired before most other tags on all pages. + +### Step 7.4.3: Create and Add a Trigger Exception + +To prevent the script from running on checkout pages, we will create an exception. + +1. Still in the tag configuration, in the **"Triggering"** section, click **"Add Exception"**. +2. Click the **"+"** icon in the upper right corner to create a new exception trigger. +3. Give the trigger a name, for example: **"Trigger Exception - Checkout Pages"**. +4. Click on **"Trigger Configuration"** and choose the **"Initialization"** type. +5. Under **"This trigger fires on"**, select **"Some Initializations"**. +6. Configure the condition to identify the checkout pages. The condition may vary depending on your site's URL structure. Common examples: + - `Page Path` | `contains` | `/checkout` + - `Page URL` | `matches RegEx (ignore case)` | `/checkout/|/orderPlaced/` +7. Save the new exception trigger. It will be automatically added to your tag. + +### Step 7.4.4: Save and Publish + +1. Save the newly created tag. +2. Submit and publish the changes in your GTM container. + +## 7.5. User Session Configuration + +For the VTEX Ads platform to correctly correlate user interactions, it is necessary to inform which session identifier is used by your e-commerce. + +**Action Required:** + +The team responsible for the e-commerce must inform the VTEX Ads team of the **name of the attribute in the `cookie` or `sessionStorage`** that stores the user's session ID. + +- **Example:** If the session ID is stored in a cookie named `vtex_session`, this information must be passed on. + +This configuration allows the script to read the correct identifier and associate it with browsing events. diff --git a/en/docs/8-credit-transfer.md b/en/docs/8-credit-transfer.md index 448af60..bb21022 100644 --- a/en/docs/8-credit-transfer.md +++ b/en/docs/8-credit-transfer.md @@ -6,3 +6,75 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +Credit transfer is the flow that allows the marketplace to transfer advertising credits to its sellers. This documentation details the endpoints that the marketplace must implement and the webhook it must consume to integrate with VTEXAds. + +<div align="center"> + <img src="../../diagrams/images/en/credit-transfer.png" alt="Credit Transfer Flow" /> +</div> + + * **Endpoints to be implemented by the Marketplace (Authentication: Basic Auth):** + 1. **Check Balance (`GET /checking_account`)** + * **Objective:** Check the seller's available balance. + * **Query Parameters:** `seller_id`, `publisher_id` (optional, only applies to cases where an entity manages multiple publishers). + * **Success Response (200 OK):** + ```json + { "total": "1111.00" } + ``` + + 2. **Request Transfer (`POST /checking_account/transfer`)** + * **Objective:** Request the transfer of a specific amount. + * **Request Body:** + ```json + { + "amount": "10.00", + "seller_id": "SELLER_ID", + "publisher_id": "PUBLISHER_ID", + "transfer_identity_id": "uuid" + } + ``` + * **Responses:** + - **Synchronous (Success):** `201 Created` + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "success" + } + ``` + - **Synchronous (Failure):** `400 Bad Request` + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "failure", + "message": "Reason for refusal" + } + ``` + - **Asynchronous:** `202 Accepted` + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "processing" + } + ``` + + * **Webhook to be consumed by the Marketplace:** + * **Objective:** Notify VTEXAds about the final status of the transfer. + * **Endpoint:** `POST https://api-retail-media.newtail.com.br/webhook/marketplace/transfers/:publisher_id` + * **Authentication:** `x-api-key` and `x-secret-key`. + * **Payload:** + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "success" + } + ``` + or + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "failure", + "message": "Problem description" + } + ``` + * **Retry Logic:** In case of a webhook call failure, the marketplace must retry. + * **Expected Response:** `204 No Content` \ No newline at end of file diff --git a/en/docs/9-sso.md b/en/docs/9-sso.md index d564653..789d304 100644 --- a/en/docs/9-sso.md +++ b/en/docs/9-sso.md @@ -6,3 +6,34 @@ > The VTEX Ads API documentation is now part of the official VTEX Developers Portal: [VTEX Ads API on developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Please update your bookmarks. This page is no longer maintained. + +API for unified seller login. When calling this API, Newtail generates a redirect URL that allows the user to access the Newtail platform without needing to log in again. + +* **Endpoint:** `POST /sso/marketplace` +* **Request Body:** + +| Field | Description | Type | Required? | +| :--- | :--- | :--- | :--- | +| `sso_token` | User identification token generated by the marketplace. | String | Yes | +| `email` | User's (seller's) email. | String | Yes | +| `user_id` | Unique user ID in the marketplace. | String | Yes | +| `name` | User's name. | String | Yes | +| `marketplace_name` | Name of the marketplace. | String | Yes | + +* **Request Example:** + ```json + { + "sso_token": "sso-token-12345", + "email": "seller@example.com", + "user_id": "seller123", + "name": "Seller Name", + "marketplace_name": "My Marketplace" + } + ``` + +* **Success Response:** `HTTP 200 OK` with the redirect URL. + ```json + { + "redirect_url": "https://app.ads.vtex.com/sso/auth?token=GENERATED_TOKEN" + } + ``` \ No newline at end of file diff --git a/es/docs/1-resumen.md b/es/docs/1-resumen.md index 51dad11..922d050 100644 --- a/es/docs/1-resumen.md +++ b/es/docs/1-resumen.md @@ -6,3 +6,21 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +Esta documentación detalla la integración con la **Retail Media API**, el punto central de conexión entre la solución de VTEX Ads y la plataforma del minorista (publisher). La solución fue desarrollada bajo el concepto **API-first**, garantizando flexibilidad total para que los minoristas integren y exhiban anuncios en cualquier canal digital: e-commerce, marketplace, aplicación o incluso en tótems y pantallas físicas (Digital Signage). + +Nuestra arquitectura es **cookie-less**, lo que significa que no dependemos de cookies de terceros. La identificación y segmentación se basan en identificadores propios (`user_id`, `session_id`) y datos primarios (first-party data), garantizando una solución robusta, en conformidad con las nuevas políticas de privacidad y preparada para el futuro del retail digital. + +A través de esta API REST, su plataforma podrá: +* Sincronizar el catálogo de productos e inventario. +* Solicitar anuncios relevantes en tiempo real para el contexto de navegación del usuario. +* Enviar eventos de interacción (impresión, visualización, clic, conversión) para la medición de performance. + +Adoptamos el principio de **Extensibilidad Progresiva** para garantizar la máxima estabilidad y seguridad en las operaciones de nuestros socios. + +Nuestra política formal de compatibilidad garantiza: +* **Evolución sin rupturas:** todas las actualizaciones de API se realizan de forma incremental. Se agregan nuevos campos, funcionalidades y opciones sin alterar ni eliminar el comportamiento de los contratos existentes. +* **Preservación de integraciones:** las integraciones actuales permanecen plenamente operativas tras nuevos lanzamientos, reduciendo el retrabajo técnico recurrente. +* **Continuidad del negocio:** al preservar la integridad de los contratos anteriores, evitamos interrupciones operativas y permitimos adoptar nuevas capacidades al ritmo de su negocio. + +Este enfoque refleja nuestro compromiso con una plataforma robusta y escalable, donde la innovación tecnológica y la previsibilidad operativa evolucionan juntas. diff --git a/es/docs/10-ventana-atribucion.md b/es/docs/10-ventana-atribucion.md index 47f5ade..a6dfea2 100644 --- a/es/docs/10-ventana-atribucion.md +++ b/es/docs/10-ventana-atribucion.md @@ -6,3 +6,99 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +Este documento detalla las reglas, modelos y plazos que rigen la atribución de conversiones (ventas) y la facturación de las campañas publicitarias en nuestra plataforma. + +## 1. ¿Qué es la Ventana de Atribución? + +La "ventana de atribución" (o ventana de conversión) es el período de tiempo _después_ de que un usuario interactúa con un anuncio (ya sea haciendo clic o visualizándolo) durante el cual una conversión puede ser acreditada a ese anuncio. + +- **Ventana Predeterminada:** 14 días. +- **Flexibilidad:** Este período es el predeterminado para todas las campañas, pero puede personalizarse según las necesidades estratégicas. + +**Ejemplo:** Si un usuario hace clic en un anuncio hoy, cualquier compra que realice del producto asociado en los próximos 14 días podrá atribuirse a ese anuncio. + +## 2. Medición (Atribución) vs. Facturación + +Es fundamental diferenciar el evento que _mide_ la atribución (lo que usamos para contar una conversión) del evento que _genera la facturación_ (lo que cobramos al anunciante). + +### 2.1. Eventos de Medición (Atribución) + +Esto define _cómo_ sabemos que un anuncio "funcionó" para generar una venta: + +- **Campañas de Producto (Product Ads):** + - **Evento:** Clic. + - **Lógica:** La conversión solo se cuenta si el usuario _hizo clic_ en el anuncio antes de comprar. + +- **Otras Campañas (Banner, Video y Sponsored Brands):** + - **Evento:** Visualización (Impresión). + - **Lógica:** La conversión puede contarse incluso si el usuario solo _vio_ el anuncio (y no necesariamente hizo clic), siguiendo las reglas de jerarquía (ver sección 3). + +### 2.2. Modelos de Facturación + +Esto define _por qué_ paga el anunciante: + +- **CPC (Costo Por Clic):** El anunciante paga cada vez que un usuario hace clic en el anuncio. + - _Usado en:_ Campañas de Producto, Sponsored Brands. + +- **CPM (Costo Por Mil Impresiones):** El anunciante paga un valor fijo por cada 1.000 veces que se muestra el anuncio. + - _Usado en:_ Banner, Video, Sponsored Brands. + +- **Modelo Híbrido (CPC + CPM):** + - Las campañas de **Sponsored Brands** son únicas, ya que cobran _tanto_ por los clics (CPC) como por las impresiones (CPM) generadas. + +#### Ejemplo de Cálculo de Facturación (CPM) + +El CPM define el valor para 1.000 impresiones, pero el cargo real es proporcional a cada impresión individual. + +- **Escenario:** Una campaña de video tiene un CPM de **$10,00**. +- **Resultado:** La campaña genera **10 impresiones**. + +**Cálculo:** + +1. **Costo por impresión individual:** $10,00 (CPM) / 1.000 (impresiones) = **$0,01 por impresión**. +2. **Costo Total:** 10 (impresiones generadas) * $0,01 (costo por impresión) = **$0,10**. + +El costo total de esta campaña sería de **diez centavos**. + +## 3. Reglas de Atribución (La Jerarquía de Decisión) + +Cuando un usuario interactúa con múltiples anuncios antes de comprar, un modelo de atribución decide qué campaña recibirá el crédito por la venta. + +**Principio Fundamental:** La atribución es exclusiva. Un pedido vendido **nunca** se atribuye a dos campañas distintas; el crédito siempre se otorga a una sola campaña. + +La decisión sigue este orden de prioridad: + +1. **Prioridad 1: Campañas Offsite** + - Si existe una campaña _offsite_ activa (trayendo tráfico externo al sitio) y fue el último punto de contacto del usuario, tendrá preferencia total en la atribución de la venta. + +2. **Prioridad 2: Último Clic (Last Click)** + - En ausencia de un clic offsite reciente, el sistema busca el _último anuncio_ (dentro de la plataforma) en el que el usuario _hizo clic_ dentro de la ventana de 14 días. + +3. **Prioridad 3: Última Visualización (Last View)** + - Si el usuario no hizo clic en ningún anuncio durante el período, el sistema atribuye la venta al _último anuncio_ que _visualizó_ (siempre que sea un tipo de campaña que mida por visualización, como Banner o Video). + +**Regla de Tiempo:** Para que una conversión sea válida, el evento de interacción (clic o visualización) debe haber ocurrido _antes_ de que se finalizara el pedido. + +## 4. Mapeo de Productos en la Atribución + +Una campaña solo puede recibir atribución por productos que están _explícitamente vinculados a ella_. + +### 4.1. Campañas de Producto (Atribución 1:1) + +- **Cómo funciona:** Cada anuncio (AD) dentro de la campaña representa un producto específico. +- **Lógica:** La atribución es directa y 1 a 1. El clic en el anuncio del "Producto A" solo puede generar conversión para el "Producto A". + +### 4.2. Otras Campañas (Banner, Video, etc.) (Atribución N:1) + +- **Cómo funciona:** Estas campañas tienen una _lista_ de productos asociados (SKUs). +- **Lógica:** La interacción (clic o visualización) con un solo creativo (banner o video) puede generar atribución para _cualquiera_ de los productos contenidos en esa lista de la campaña. + +**Observación sobre Creativos:** Dentro de una campaña (ej: Banner), cada creativo (ej: el "Banner A" y el "Banner B") mide su información de forma independiente. Esto permite analizar el rendimiento individual de cada pieza publicitaria. + +## 5. Latencia de Datos (Retraso en la Atribución) + +Es importante notar que existe un retraso natural entre el momento en que el cliente crea el pedido y el momento en que esa venta es asociada (atribuida) a la campaña correcta en los informes. + +- **Integración vía API:** Retraso de aproximadamente **30 minutos**. +- **Plataforma VTEX:** Retraso de hasta **2 horas**. diff --git a/es/docs/2-glosario.md b/es/docs/2-glosario.md index 0717406..2ed0982 100644 --- a/es/docs/2-glosario.md +++ b/es/docs/2-glosario.md @@ -6,3 +6,18 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +| Término | Descripción | +| :--- | :--- | +| **Advertiser (Anunciante)** | Empresas, sellers o individuos que promocionan sus productos, servicios o ideas a través de campañas. | +| **Publisher (Minorista)** | La entidad que posee y opera la plataforma digital (sitio, app) y pone a disposición los espacios para la exhibición de anuncios. | +| **Campaña** | Acción creada por un anunciante para promocionar productos y generar conversiones (ventas). | +| **Impresión** | Se contabiliza cada vez que un anuncio se exhibe en la pantalla del usuario. | +| **Visualización (View)**| Se contabiliza cuando una impresión se vuelve visible en la pantalla del usuario por un tiempo determinado. | +| **Clic** | Interacción del usuario al hacer clic en un anuncio para ser dirigido a la página de destino. | +| **Conversión** | Acción de valor generada por un anuncio, típicamente una venta. | +| **Ingresos por Anuncios** | Valor obtenido por los minoristas al monetizar sus espacios publicitarios. | +| **Ingresos por Ventas** | Valor total obtenido por una empresa a partir de las ventas de productos o servicios. | +| **CTR (Click-Through Rate)** | Tasa de Clics. Fórmula: `(Clics / Impresiones) * 100`. Mide el atractivo de un anuncio. | +| **ROAS (Return on Ad Spend)**| Retorno de la Inversión Publicitaria. Fórmula: `Ingresos Generados por Anuncios / Costo de la Publicidad`. | +| **Tasa de Conversión** | Porcentaje de conversiones en relación con el total de clics o visitas. | diff --git a/es/docs/3-autenticacion.md b/es/docs/3-autenticacion.md index 3df2c72..b40352f 100644 --- a/es/docs/3-autenticacion.md +++ b/es/docs/3-autenticacion.md @@ -6,3 +6,12 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +La autenticación es necesaria para el envío de catálogos, el consumo de informes y la gestión. Las demás llamadas, como consulta de anuncios y notificación de eventos, son públicas y no requieren autenticación. + +Para los endpoints protegidos, las credenciales deben ser enviadas vía encabezado (header) HTTP. Solicite sus credenciales al gerente de cuenta. + +| Atributo | Descripción | +| :--- | :--- | +| `x-app-id` | ID exclusivo de su aplicación para la integración. | +| `x-api-key` | Clave de API asociada a su aplicación. | diff --git a/es/docs/4-seguridad-de-datos.md b/es/docs/4-seguridad-de-datos.md index 1fac336..abd83ac 100644 --- a/es/docs/4-seguridad-de-datos.md +++ b/es/docs/4-seguridad-de-datos.md @@ -6,3 +6,29 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +La seguridad de los datos es un pilar fundamental de nuestra plataforma. Desde el principio, nuestra arquitectura fue diseñada para garantizar que no se recopile información sensible y que los datos de los usuarios permanezcan siempre protegidos y no identificables. + +## Datos No Identificables + +No recopilamos datos sensibles de los usuarios, como nombre, correo electrónico o documentos. La información que recibimos, como correos electrónicos o números de identificación (PII - *Personally Identifiable Information*), ya llega a nuestra plataforma con un hash criptográfico irreversible. + +Esto significa que el dato original nunca viaja o se almacena en nuestros sistemas. El resultado es un identificador anónimo que nos permite agrupar comportamientos y audiencias sin saber nunca quién es el usuario real. + +**¿Por qué es esto seguro?** + +* **Irreversibilidad:** El proceso de hashing es de una sola vía. Incluso si alguien tuviera acceso al hash, no podría descubrir el dato original. +* **Anonimato:** Como no almacenamos el dato original, no tenemos forma de identificar al usuario. A todos los efectos, los datos son anónimos. + +## Cifrado en Tránsito y en Reposo + +Todos los datos, ya sean identificadores anónimos o información sobre campañas y anuncios, se tratan con los más altos estándares de seguridad: + +* **Cifrado en Tránsito:** Toda la comunicación entre nuestros sistemas y con socios se realiza utilizando protocolos seguros como TLS 1.2+, garantizando que los datos no puedan ser interceptados durante la transferencia. +* **Cifrado en Reposo:** Los datos almacenados en nuestras bases de datos y sistemas de archivos están cifrados. Utilizamos soluciones robustas y reconocidas en el mercado, como **Amazon RDS**, **Amazon S3**, **Amazon Redshift** y **Snowflake**, que aplican cifrado AES-256, uno de los algoritmos más seguros que existen. + +## Acceso Restringido + +El acceso a los datos está rigurosamente controlado y limitado a un grupo selecto de ingenieros y analistas senior. Cada acceso es auditado y monitoreado, y los permisos se conceden con base en el principio del menor privilegio, es decir, cada persona tiene acceso solo a lo estrictamente necesario para realizar su trabajo. + +Esta combinación de datos no identificables, cifrado de extremo a extremo y control de acceso riguroso garantiza que su información y la de sus clientes estén siempre seguras. diff --git a/es/docs/5-integracion-de-anuncios.md b/es/docs/5-integracion-de-anuncios.md index f83014a..8b18148 100644 --- a/es/docs/5-integracion-de-anuncios.md +++ b/es/docs/5-integracion-de-anuncios.md @@ -6,3 +6,26 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +Esta sección proporciona información detallada sobre cómo integrarse con la plataforma de VTEX Ads para mostrar anuncios en su sitio web. + +## 5.0 Visión General del Flujo de Integración + +<img src="../../diagrams/images/es/integration-end-to-end.png" alt="Flujo completo de integración con VTEX Ads" /> + +El flujo de integración completo se divide en cuatro fases principales que se retroalimentan continuamente: + +1. **Preparación y Onboarding:** Alinee el alcance y cronograma con el equipo de VTEX Ads, reciba las credenciales de API y valide el acceso a ambientes y webhooks. +2. **Sincronización de Datos Operacionales:** Cargue el catálogo (productos e inventario) y, opcionalmente, audiencias. Este paso garantiza que solo los productos disponibles y segmentaciones válidas estén aptos para aparecer. +3. **Entrega de Anuncios:** Estructure los placements del sitio, configure convenciones de nombre y consulte anuncios en tiempo real para cada contexto (home, búsqueda, categoría, PDP, etc.), mostrando el sello "Patrocinado". +4. **Medición y Optimización:** Dispare los eventos de impresión, visualización, clic y conversión usando `navigator.sendBeacon()`, monitoree las métricas de desempeño y ajuste pujas, segmentaciones y posicionamientos de acuerdo con los resultados. + +Las siguientes secciones detallan cómo ejecutar cada una de estas fases, con ejemplos de solicitudes y mejores prácticas específicas. + +- [5.1. Integración vía API](./5.1-integracion-via-api.md): Para una integración más personalizada, utilice nuestra API REST para gestionar todo el ciclo de vida de los anuncios. +- [5.2. Integración VTEX](./5.2-integracion-vtex.md): Si su tienda está en la plataforma VTEX, utilice nuestra aplicación VTEX IO para simplificar el proceso. +- [5.3. Sincronización de Catálogo](./5.3-sincronizacion-de-catalogo.md): Mantenga su catálogo de productos e inventario sincronizado con VTEX Ads. +- [5.4. Integración de Audiencias](./5.4-integracion-de-audiencias.md): Envíe datos de audiencia para mejorar la segmentación y la relevancia de los anuncios. +- [5.5. Consulta de Anuncios](./5.5-consulta-de-anuncios.md): Solicite a la API los anuncios que deben ser exhibidos en diferentes páginas y contextos. +- [5.5.1. Recomendación de Nombres de Placements](./5.5.1-recomendacion-de-nombres-de-placements.md): Estándar recomendado de nombres de placements para una medición precisa. +- [5.6. Eventos](./5.6-eventos.md): Notifique a la API sobre todas las interacciones del usuario con los anuncios y las conversiones. diff --git a/es/docs/5.1-integracion-via-api.md b/es/docs/5.1-integracion-via-api.md index 475e00f..ecbd126 100644 --- a/es/docs/5.1-integracion-via-api.md +++ b/es/docs/5.1-integracion-via-api.md @@ -6,3 +6,24 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +La integración se fundamenta en tres pilares que garantizan el funcionamiento de la solución. + +### Pilares de la Integración + +1. **[Sincronización de Catálogo](./5.2-sincronizacion-de-catalogo.md):** Mantener a VTEX Ads sincronizado con su catálogo de productos e inventario (precio y stock). Esencial para anuncios de producto. +2. **[Consulta de Anuncios](./5.3-consulta-de-anuncios.md):** Su plataforma solicita a la API los anuncios que deben ser exhibidos en diferentes páginas y contextos. +3. **[Eventos](./5.4-eventos.md):** Su plataforma notifica a la API sobre todas las interacciones del usuario con los anuncios y, crucialmente, sobre las conversiones (ventas). + +### Tipos de Anuncios + +| Tipo de Anuncio | API Type | Descripción | +| :--- | :--- |:------------------------------------------------| +| **Sponsored Products** | `product` | Anuncios de productos individuales. | +| **Display** | `banner` | Anuncios visuales (imagen estática o video). | +| **Sponsored Brands** | `sponsored_brand` | Anuncios de marca con título, logo y productos. (imagen estática o video) | +| **Digital Signage** | `digital_signage`| Contenido para pantallas y tótems físicos. | + +### Integración de Audiencias + +Dirija anuncios a públicos específicos para aumentar la relevancia. Vea más en [Integración de Audiencias](./5.2-integracion-de-audiencias.md). diff --git a/es/docs/5.2-integracion-vtex.md b/es/docs/5.2-integracion-vtex.md index bce084a..4183da3 100644 --- a/es/docs/5.2-integracion-vtex.md +++ b/es/docs/5.2-integracion-vtex.md @@ -6,3 +6,35 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +Para tiendas en la plataforma VTEX, Newtail ofrece una aplicación de storefront (`Newtail Media APP VTEX`) que simplifica drásticamente la implementación. La app ya incluye componentes visuales y toda la lógica para la consulta de anuncios y la notificación de eventos. + +* **Paso 1: Sincronización del Catálogo** + * La sincronización del catálogo de productos es un prerrequisito. Se puede realizar de dos maneras: + 1. **Vía API:** Proporcionando a Newtail las claves de API para la lectura de su catálogo. + 2. **Vía XML:** Proporcionando un enlace a un feed XML en formato de Google Shopping, que debe contener el campo `SKU` para la identificación del producto. + +* **Paso 2: Instalación de la App** + 1. **Añadir como Dependencia:** En el archivo `manifest.json` de su tema, añada `"newtail.media": "0.x"` a las `peerDependencies`. + 2. **Instalar la App:** Ejecute el comando `vtex install newtail.media@0.x` en su terminal. + +* **Paso 3: Configuración** + 1. **ID del Publisher:** En el admin de su tienda VTEX, acceda a `Configuración de la Tienda > Newtail Media` e ingrese su `Publisher ID` proporcionado por Newtail. + 2. **Política de Seguridad de Contenido (CSP):** Añada las siguientes directivas a su `policies.json`: + ```json + { + "contentSecurityPolicy": { + "default-src": ["'self'", "newtail-media.newtail.com.br"], + "connect-src": ["'self'", "newtail-media.newtail.com.br"] + } + } + ``` + +* **Paso 4: Uso de los Bloques** + * Declare los bloques de la app en las plantillas de su tema para mostrar los anuncios. + + * **Componentes Disponibles:** + * `newtail-media-banner`: Renderiza banners patrocinados. + * `newtail-media-shelf`: Renderiza una estantería de productos patrocinados. + * `newtail-media-search`: Añade sellos "Patrocinado" a los productos en los resultados de búsqueda. + * `newtail-media-conversion`: Componente esencial que gestiona el envío de eventos de conversión. **Debe ser incluido en todas las páginas.** \ No newline at end of file diff --git a/es/docs/5.3-sincronizacion-de-catalogo.md b/es/docs/5.3-sincronizacion-de-catalogo.md index c9884d2..5f1c5b2 100644 --- a/es/docs/5.3-sincronizacion-de-catalogo.md +++ b/es/docs/5.3-sincronizacion-de-catalogo.md @@ -6,3 +6,195 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +El primer paso es la sincronización, que ocurre en dos frentes: + +> **Nota para tiendas VTEX:** Para tiendas en la plataforma VTEX, la sincronización del catálogo ocurre de forma transparente, no siendo necesaria ninguna integración adicional para este fin. + +#### **Sincronización de Productos** +Envío de la información de registro de los productos. Requiere autenticación. + +* **Endpoint:** `POST https://api-retail-media.newtail.com.br/product/bulk/products` +* **Límites:** 500 productos por solicitud; 3 solicitudes simultáneas. + +| Campo | Descrição | Tipo | ¿Obligatorio? | +| :--- | :--- | :--- | :--- | +| `product_sku` | ID/SKU único del producto. | String | Sí | +| `parent_sku` | SKU del producto padre (para variaciones). | String | No | +| `name` | Nombre del producto. | String | Sí | +| `url` | URL canónica de la página del producto. | String | Sí | +| `image_url`| URL de la imagen principal del producto. | String | No | +| `categories` | Lista de categorías. | Array[String] | Sí | +| `brand` | Marca del producto. | String | No | +| `gtins` | Códigos de barras (EAN). **Obligatorio para campañas en la VTEX Ads Network.**| Array[String] | No/Sí | +| `tags` | "Etiquetas" para contextualizar búsquedas. Máx. 10 por SKU, 64 caracteres por tag. Solo para campañas de `product`. | Array[String] | No | +| `sellers` | Lista de sellers que venden el producto (en un marketplace). | Array[String] | No | +| `metadata` | Objeto para información adicional (clave-valor). | Object | No | + +--- + +### **Estructuración de Categorías** + +> **Importante:** El campo `categories` es crucial para la segmentación de campañas y la organización de productos. Debe ser estructurado jerárquicamente, representando la ruta completa desde la categoría raíz hasta la categoría específica del producto. + +El campo `categories` debe ser un array de strings, donde cada string es un nivel del árbol de categorías. La jerarquía se construye enviando todas las categorías padre hasta la más específica. + +**Ejemplo Correcto:** + +Para un producto en la categoría de perfumes "Para Mujer", el array `categories` debería ser: + +```json +"categories": [ + "Belleza", + "Belleza > Fragancias", + "Belleza > Fragancias > Perfume", + "Belleza > Fragancias > Perfume > Para Mujer" +] +``` + +Esta estructura permite a la plataforma entender el contexto del producto en todos los niveles, desde el más amplio ("Belleza") hasta el más específico ("Para Mujer"). + +--- + +**Ejemplo de Solicitud:** + +```bash +curl --location 'https://api-retail-media.newtail.com.br/product/bulk/products' \ +--header 'x-app-id: XXXX' \ +--header 'x-api-key: YYYY' \ +--header 'Content-Type: application/json' \ +--data '[ + { + "product_sku": "allan", + "name": "allan", + "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616", + "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629", + "categories": [ + "Belleza", + "Belleza > Fragancias", + "Belleza > Fragancias > Perfume", + "Belleza > Fragancias > Perfume > Para Mujer" + ], + "brand": "SALVADOR DALÍ", + "profit_margin": null, + "gtins": [ + "3331438450103" + ], + "sellers": [], + "skus": [] + }, + { + "product_sku": "allan2", + "name": "allan2", + "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616", + "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629", + "categories": [ + "Belleza", + "Belleza > Fragancias", + "Belleza > Fragancias > Perfume", + "Belleza > Fragancias > Perfume > Para Mujer" + ], + "brand": "SALVADOR DALÍ", + "profit_margin": null, + "gtins": [ + "3331438450103" + ], + "sellers": [], + "skus": [], + "tags": ["Abart", "Mega Maio"] + } +]' +``` + + +**Ejemplo de Respuesta Exitosa:** + +``` +Status: 202 Accepted +Content-Type: application/json + +{ + "messages": [ + "products will be processed soon" + ] +} +``` + +--- + +#### **Sincronización de Inventario** +Envío de la información de precio y stock de los productos. Requiere autenticación. + +* **Endpoint:** `POST https://api-retail-media.newtail.com.br/product/bulk/inventories` +* **Límites:** 500 productos por solicitud; 3 solicitudes simultáneas. + +| Campo | Descripción | Tipo | ¿Obligatorio? | +| :--- | :--- | :--- | :--- | +| `product_sku` | ID/SKU único del producto. | String | Sí | +| `price` | Precio actual del producto. | Float | Sí | +| `promotional_price` | Precio "de" (listado/original). | Float | Sí | +| `is_available` | Producto disponible (en stock). | Boolean | Sí | +| `store_id` | ID de la tienda. Si no se proporciona el ID de la tienda, se interpretará como que esta información de inventario se utilizará para todas las tiendas. | String | No | +| `metadata` | Objeto para información adicional (clave-valor). | Object | No | + +**Ejemplo de Solicitud:** + +```bash +curl --location 'https://api-retail-media.newtail.com.br/product/bulk/inventories' \ +--header 'x-app-id: XXXX' \ +--header 'x-api-key: YYYY' \ +--header 'Content-Type: application/json' \ +--data '[ + { + "product_sku": "120210", + "store_id": "1", + "price": 18.20, + "promotional_price": 16.32, + "is_available": true + }, + { + "product_sku": "120212", + "price": 18.20, + "promotional_price": 0, // Eliminar precio promocional + "is_available": true + } +]' +``` + +**Ejemplo de Respuesta Exitosa:** + +``` +Status: 202 Accepted +Content-Type: application/json + +{ + "messages": [ + "inventory will be processed soon" + ] +} +``` + +--- + +### **Buenas Prácticas para Sincronización** + +1. **Sincronización Inicial Completa:** + * Envíe todo el catálogo en la primera sincronización. + * Divida en lotes de hasta 500 productos para evitar timeouts. + +2. **Actualizaciones Incrementales:** + * Después de la sincronización inicial, envíe solo productos nuevos o modificados. + * Mantenga un registro de la última fecha de modificación de cada producto. + +3. **Frecuencia de Actualización:** + * Precios y stock: Actualice al menos una vez al día, idealmente en tiempo real para cambios significativos. + * Información de registro: Actualice cuando haya cambios. + +4. **Tratamiento de Errores:** + * Implemente reintentos con backoff exponencial para fallos temporales. + * Monitoree las respuestas de la API para identificar problemas persistentes. + +5. **Validación de Datos:** + * Verifique que todos los campos obligatorios estén completos. + * Asegúrese de que las URLs de productos e imágenes sean válidas y accesibles. + * Asegúrese de que las categorías sigan la estructura jerárquica recomendada. \ No newline at end of file diff --git a/es/docs/5.4-integracion-de-audiencias.md b/es/docs/5.4-integracion-de-audiencias.md index 9be1985..1ea4229 100644 --- a/es/docs/5.4-integracion-de-audiencias.md +++ b/es/docs/5.4-integracion-de-audiencias.md @@ -6,3 +6,100 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +> **Nota:** La integración de audiencias es opcional, pero muy recomendada para mejorar la segmentación de campañas y la relevancia de los anuncios. + +La integración de audiencias tiene una única forma de integración: **Envío por Lotes (Batch)** al bucket S3 proporcionado por VTEX Ads. + +> **Importante:** La integración vía FTP/SFTP está **deprecated** y solo debe utilizarse en implementaciones legadas. Los nuevos proyectos deben usar exclusivamente el bucket S3. + +> **Alerta:** Si no existe integración de audiencia, es necesario abrir un ticket con el Account Manager solicitando la pre-población de la información de segmentación con datos base (`STATE`, `CITY`, `GENDER` y `AGE`). También es posible enviar una lista de audiencias para su registro, y recomendamos mantener una actualización periódica de esas audiencias. + +### Envio por Lotes (Batch) - Bucket S3 + +La conexión de integración se realiza mediante el envío periódico de audiencias al bucket S3 dedicado al publisher. Las credenciales de acceso (clave/secreto IAM o role para cross-account) y la ruta base del bucket deben solicitarse a su contacto en Newtail. + +* **Formato de Archivo:** `Parquet` con compresión `Snappy`. +* **Patrón de Directorio (clave S3):** Suba los archivos siguiendo el patrón: + `s3://<bucket>/<PREFIJO>/audiences/YYYY/mm/dd/TIMESTAMP.parquet.snappy` + +| Atributo | Descripción | Ejemplo | +| :-------- | :---------------------------------------------------------------------------------------------------------- | :----------- | +| `PREFIJO` | El prefijo será informado por Newtail. | `xyz` | +| `YYYY` | Año de generación con 4 dígitos. | `2023` | +| `mm` | Mes de generación con dos dígitos (Enero = 01 y Diciembre = 12). | `09` | +| `dd` | Día de generación con dos dígitos (del 01 al 31). | `31` | +| `TIMESTAMP`| Timestamp es la cantidad de segundos desde 1970 (el nombre del archivo puede ser cualquiera, el timestamp es solo una sugerencia que nunca se repetirá). | `1694812122` | + +> **Recomendación para el envío:** En la integración inicial, es fundamental que se envíen todos los datos. Y estos datos se pueden enviar en múltiples archivos (dependiendo del tamaño de la base, un buen número es 1 millón de líneas por archivo). Después de la primera integración, lo ideal es que se envíe solo el delta de las filas que tuvieron alguna modificación. + +> **Compatibilidad legada:** Si ya estaba integrado vía SFTP, contacte al equipo de VTEX Ads para planificar la migración al bucket S3. El flujo vía SFTP dejará de recibir nuevas mejoras y puede ser descontinuado. + +### Alternativa sin integración previa (runtime) + +Si decide no integrar audiencias vía batch, todavía puede usar segmentaciones en runtime enviando los datos en el campo `segmentation` de la solicitud de consulta de anuncios. Consulte la sección [5.5. Consulta de Anuncios](5.5-consulta-de-anuncios.md). + +### Atributos del Archivo de Audiencias + +La mayoría de los atributos no son obligatorios, sin embargo, cuanto mayor sea el llenado de toda esta información, mejor será la relevancia. + +> Las columnas son **case sensitive**. Mantenga el nombre de las columnas tal como se presentan. + +| Columna | Tipo | ¿Obligatorio? | Descripción | +| :------------------ | :----- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `CUSTOMER_ID` | String | Sí | Identificador único del cliente. | +| `EMAIL_HASHED` | String | No | PII basado en el correo electrónico del cliente. | +| `PHONE_HASHED` | String | No | PII basado en el número de teléfono principal del cliente. | +| `SOCIAL_ID_HASHED` | String | No | PII basado en el CUIT/CUIL del cliente. | +| `FIRST_NAME_HASHED` | String | No | PII basado en el Nombre del cliente. | +| `LAST_NAME_HASHED` | String | No | PII basado en el Apellido del cliente. | +| `GENDER` | String | No | Indica el sexo del cliente (`F` para femenino, `M` para masculino, `O` para otros, `NULL` para no identificados). | +| `AGE` | Int | No | Indica la edad del cliente. | +| `CEP` | String | No | Indica el código postal de la dirección del cliente. | +| `COUNTRY` | String | No | Indica el país del usuario. | +| `STATE` | String | No | Indica el estado/provincia donde reside el cliente. | +| `CITY` | String | No | Indica la ciudad donde reside el cliente. | +| `NEIGHBORHOOD` | String | No | Indica el barrio donde reside el cliente. | +| `AUDIENCES` | String | No | Una lista de audiencias, separadas por punto y coma (;). | +| `NBO_PRODUCTS` | String | No | Una lista de SKU de productos, separadas por punto y coma (;). | +| `NBO_CATEGORIES` | String | No | Una lista de categorías, separadas por punto y coma (;). La lista puede recibir un árbol de categorías usando " > " como separador (ej: `Tablets;Bebidas > Bebidas No Alcohólicas;Libros > Gastronomía > Guías de Bares y Restaurantes`). | + +### Hash de Campos + +Los datos confidenciales deben ser encriptados antes de ser enviados usando el algoritmo **SHA256**. + +* `EMAIL_HASHED` +* `PHONE_HASHED` +* `SOCIAL_ID_HASHED` +* `FIRST_NAME_HASHED` +* `LAST_NAME_HASHED` + +> Antes de generar el hash de los datos es necesario remover todos los **ESPACIOS** y convertir a **MINÚSCULAS** sus valores. +> Para el atributo `PHONE_HASHED`, será necesario formatearlo al estándar **E.164** e incluir el código de país. + +#### Formato E.164 + +1. Remueva todos los caracteres no numéricos, como espacios, guiones, paréntesis y símbolos. +2. Añada el código del país con el signo de suma (+) al principio. +3. Añada el código de área (si aplica) sin el cero inicial. +4. Incluya el número de teléfono local sin el cero inicial (si aplica). + +**Ejemplo:** + +* Un número de teléfono de Argentina, con código de área 11 y número local 98765-4321, sería formateado como: `+5411987654321` + +#### Creando un HASH en Python + +```python +import re +import hashlib + +hash_obj = hashlib.sha256() + +def create_hash(x): + cleaned = re.sub('\s+', '', x.lower()) + hash_obj.update(cleaned.encode('utf-8')) + return hash_obj.hexdigest() + +create_hash(' Allan ') #=> 8c01ade3cb71d3ac7c718ed5a0c565155a4c05a216d9e59013c5d7b49e916914 +``` diff --git a/es/docs/5.5-consulta-de-anuncios.md b/es/docs/5.5-consulta-de-anuncios.md index 38675e1..85d99f0 100644 --- a/es/docs/5.5-consulta-de-anuncios.md +++ b/es/docs/5.5-consulta-de-anuncios.md @@ -6,3 +6,396 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +Con el catálogo sincronizado, su plataforma solicita anuncios para completar los espacios publicitarios (`placements`). La solicitud es un `POST` y el `publisher_id` debe ser informado en la URL. + +* **Endpoint:** `POST https://newtail-media.newtail.com.br/v1/rma/:publisher_id` +* **Content-Type:** Todas las solicitudes deben incluir el encabezado `Content-Type: application/json` + +#### Buenas Prácticas de Solicitud + +- **Persistencia HTTP:** Prefiera conexiones persistentes (`Connection: keep-alive`). +- **Timeout:** Aplique un timeout de 500–600 ms en la consulta (ver 5.6 para eventos). + +#### **Parámetros de la Solicitud** + +| Campo | Descripción | Tipo | Obligatoriedad | +| :--- | :--- | :--- | :--- | +| `session_id` | Identificador persistente del visitante (≥ 14 días). Para aplicaciones móviles, se debe enviar el ID del dispositivo como session_id (GAID en Android e IDFA en iOS), de manera que la sesión se mantenga indefinidamente. | String | Sí | +| `user_id` | ID único del usuario logueado (alfanumérico). | String | No (Recomendado) | +| `store_id` | Filtra anuncios por stock de una tienda específica. | String | No | +| `channel` | Canal de acceso: `site`, `msite`, `app` (para consulta). | String | Sí | +| `context` | Contexto: `home`, `category`, `search`, `product_page`, `brand_page`, `digital_signage`.| String | Sí | +| `term` | Término buscado por el usuario. | String | Solo `context: 'search'` | +| `category_name` | Categoría navegada (breadcrumb completo).| String | Solo `context: 'category'`| +| `product_sku` | SKU del producto que se está visualizando. | String | Solo `context: 'product_page'` | +| `brand_name` | Nombre de la marca que se está visualizando. | String | Solo `context: 'brand_page'` | +| `device_id` | ID único del dispositivo (pantalla, tótem). | String | Solo `context: 'digital_signage'` | +| `store_name` | Nombre de la tienda donde está ubicado el dispositivo. | String | Solo `context: 'digital_signage'` | +| `placements` | Objeto que define los espacios (`placements`) de anuncio. | Object | Sí | +| `placements.{name}.quantity` | Cantidad de anuncios deseada. | Integer | Sí | +| `placements.{name}.size` | Tamaño esperado (Imagen: `desktop`/`mobile`; Video: `1080p`/`720p`/`480p`/`360p`/`320p`). | String | Solo `types: ['banner', 'sponsored_brand']` | +| `placements.{name}.types` | Tipos permitidos (`product`, `banner`, etc.). | Array[String] | Sí | +| `placements.{name}.assets_type`| Medios aceptados (`image`, `video`). Por defecto: `["image"]`. | Array[String] | Solo `types: ['banner', 'sponsored_brand']` | +| `placements.{name}.allow_sku_duplications` | Permite mostrar el mismo SKU más de una vez dentro del mismo placement. | Boolean | No (Default=false) | +| `userAgent` | Identificación del entorno del cliente (campo en el cuerpo, no el header HTTP `User-Agent`). | String | No | +| `segmentation` | Datos para segmentación en tiempo real. | Array[Object] | No | +| `segmentation.#.key` | El tipo de segmentación. | String | No | +| `segmentation.#.values` | Array de valores para la segmentación. | Array[String] | No | +| `tags` | "Etiquetas" para contextualizar búsquedas (principalmente en `search`). Máx. 10 por SKU, 64 caracteres por tag. Solo para campañas de `product`. | Array[String] | No | +| `brand` | Nombre del sitio del publisher. | String | Obligatorio cuando el publisher tiene múltiples sitios | +| `dedup_campaign_ads` | Deduplicar por campaña (máximo 1 anuncio por campaña en la respuesta). | Boolean | No (Default=false) | +| `dedup_ads` | Deduplicar por `ad_id` entre múltiples placements (usar solo al consultar múltiples placements al mismo tiempo). | Boolean | No (Default=false) | +| `skus` | Filtra los resultados de anuncios para retornar solo ads de los SKUs especificados. Compatible solo con Sponsored Products (campañas de producto). | Array[String] | No | + +##### Campos por Contexto + +| Contexto | Campos adicionales obligatorios | +| :--- | :--- | +| `home` | — | +| `search` | `term` | +| `category` | `category_name` | +| `product_page` | `product_sku` | +| `brand_page` | `brand_name` | +| `digital_signage` | `device_id`, `store_name` | + +#### **⚠️ Reglas Importantes de Contexto y Elegibilidad de Anuncios** + +##### Limitaciones de Filtro + +> **Importante:** No es posible hacer filtro por `placement` específico. La selección de anuncios se basa en el `context` y en los parámetros de la solicitud. + +##### Elegibilidad por Contexto + +###### Contexto `home` + +En el contexto **home**, pueden ser retornados: + +- ✅ **Anuncios de Banner/Video/Sponsored Brands** que utilicen **categoría** como criterio de segmentación +- ✅ **Anuncios de Productos (Sponsored Products)** también son elegibles + +**Ejemplo:** +```json +{ + "context": "home", + "placements": { + "site_home_middle_banner": { + "quantity": 3, + "types": ["banner", "sponsored_brand"], + "assets_type": ["image", "video"], + "size": "desktop" + }, + "site_home_shelf_product": { + "quantity": 10, + "types": ["product"] + } + } +} +``` + +###### Contexto `search` + +En el contexto **search**, pueden ser retornados: + +- ✅ **Anuncios de Banner/Video/Sponsored Brands** que sean de **keyword** (palabra clave) +- ✅ **Cualquier campaña de Producto (Sponsored Products)** + +**⚠️ Match Exacto de Keywords:** + +El match de keywords en el contexto `search` es **exacto** (sin stemming/sinónimos). Esto significa que: + +- El anunciante **necesita especificar exactamente** cuáles keywords desea utilizar en la campaña de Banner/Video/Sponsored Brands +- Si el usuario busca "zapatillas nike", el anuncio solo será elegible si el anunciante registró exactamente la keyword "zapatillas nike" +- No hay correspondencia aproximada o por palabras similares + +**Ejemplo:** +```json +{ + "context": "search", + "term": "zapatillas nike", + "placements": { + "site_search_top_banner": { + "quantity": 1, + "types": ["banner", "sponsored_brand"], + "assets_type": ["image"], + "size": "desktop" + }, + "site_search_shelf_product": { + "quantity": 20, + "types": ["product"] + } + } +} +``` + +**Comportamiento esperado:** +- **Banner/Sponsored Brand:** Solo aparecerá si el anunciante registró la keyword exacta "zapatillas nike" en la campaña +- **Sponsored Products:** Productos relacionados al término de búsqueda serán retornados + +###### Contexto `brand_page` + +En el contexto **brand_page**, pueden ser retornados: + +- ✅ **Anuncios de Banner/Video/Sponsored Brands** de la marca +- ✅ **Anuncios de Productos (Sponsored Products)** de la marca + +**Ejemplo:** +```json +{ + "context": "brand_page", + "brand_name": "Nike", + "placements": { + "site_brand_top_banner": { + "quantity": 1, + "types": ["banner", "sponsored_brand"], + "assets_type": ["image"], + "size": "desktop" + }, + "site_brand_shelf_product": { + "quantity": 12, + "types": ["product"] + } + } +} +``` + +###### Contexto `digital_signage` + +En el contexto **digital_signage**, pueden ser retornados anuncios para pantallas/tótems físicos. + +**Ejemplo:** +```json +{ + "context": "digital_signage", + "device_id": "totem-abc-001", + "store_name": "Tienda Centro", + "placements": { + "totem_home_main_video": { + "quantity": 1, + "types": ["banner"], + "assets_type": ["video"], + "size": "720p" + } + } +} +``` +###### Contexto `category` + +En el contexto **category**, pueden ser retornados: + +- ✅ **Anuncios de Banner/Video/Sponsored Brands** que utilicen la **categoría** correspondiente +- ✅ **Anuncios de Productos (Sponsored Products)** de la categoría + +**Ejemplo:** +```json +{ + "context": "category", + "category_name": "Deportes > Calzado > Zapatillas", + "placements": { + "site_category_top_banner": { + "quantity": 1, + "types": ["banner", "sponsored_brand"], + "assets_type": ["image", "video"] + } + } +} +``` + +###### Contexto `product_page` + +En el contexto **product_page**, pueden ser retornados: + +- ✅ **Anuncios de Productos (Sponsored Products)** relacionados al producto visualizado + +**Ejemplo:** +```json +{ + "context": "product_page", + "product_sku": "12345", + "placements": { + "site_product_recommendation": { + "quantity": 5, + "types": ["product"] + } + } +} +``` + +#### **Respuesta de la Consulta** +La respuesta es un JSON donde cada clave es un nombre de `placement`. La estructura de cada anuncio en la respuesta depende de su tipo. + +##### **Campos Comunes de Respuesta para Todos los Tipos de Anuncios** +Estos campos están presentes en todos los tipos de anuncios: + +| Campo | Descripción | +| :--- | :--- | +| `{placementName}.#.ad_id` | ID único del anuncio. | +| `{placementName}.#.type` | Tipo del anuncio (`product`, `banner`, `sponsored_brand`, `digital_signage`). | +| `{placementName}.#.click_url`| **URL para notificar el evento de clic.** | +| `{placementName}.#.impression_url`| **URL para notificar el evento de impresión.**| +| `{placementName}.#.view_url` | **URL para notificar el evento de visualización.** | +| `{placementName}.#.seller_id` | ID del vendedor del producto anunciado (opcional). | + +##### **Campos de Respuesta Específicos por Tipo** + +###### **Anuncios de Producto** +Campos adicionales para anuncios del tipo `product`: + +| Campo | Descripción | +| :--- | :--- | +| `{placementName}.#.product_sku`| SKU del producto anunciado. | + +###### **Anuncios de Banner** +Campos adicionales para anuncios del tipo `banner`: + +| Campo | Descripción | +| :--- | :--- | +| `{placementName}.#.media_url`| URL de la imagen o video a ser exhibido. | + +###### **Anuncios de Marca Patrocinada** +Campos adicionales para anuncios del tipo `sponsored_brand`: + +| Campo | Descripción | +| :--- | :--- | +| `{placementName}.#.media_url`| URL de la imagen o video a ser exhibido. | +| `{placementName}.#.products`| Array de productos asociados a la marca patrocinada. | +| `{placementName}.#.products.#.product_sku`| SKU del producto asociado. | +| `{placementName}.#.products.#.media_url`| URL de la imagen del producto. | + +###### **Anuncios de Digital Signage** +Campos adicionales para anuncios del tipo `digital_signage`: + +| Campo | Descripción | +| :--- | :--- | +| `{placementName}.#.media_url`| URL de la imagen o video a ser exhibido. | +| `{placementName}.#.duration`| Duración de la exhibición del anuncio en segundos. | + +##### Ejemplo de Respuesta (multi-placement) + +```json +{ + "site_home_middle_banner": [ + { + "ad_id": "ad-001", + "type": "banner", + "media_url": "https://cdn.example.com/banner1.jpg", + "impression_url": "https://events.../impression/abc", + "view_url": "https://events.../view/abc", + "click_url": "https://events.../click/abc" + } + ], + "site_home_shelf_product": [ + { + "ad_id": "ad-101", + "type": "product", + "product_sku": "SKU-123", + "seller_id": "SELLER-9", + "impression_url": "https://events.../impression/def", + "view_url": "https://events.../view/def", + "click_url": "https://events.../click/def" + } + ] +} +``` + +### Buenas Prácticas + +#### Nomenclatura de Placements + +Adopte un estándar claro, como `{canal}_{contexto}_{posicion}_{tipo}` (ej: `msite_search_top-shelf_product`). Para recomendaciones detalladas, consulte `es/docs/5.5.1-recomendacion-de-nombres-de-placements.md`. + +| canal | contexto | posición | tipo | ejemplo | +| --- | --- | --- | --- | --- | +| site | home | middle | banner | site_home_middle_banner | +| msite | product | top-shelf | product | msite_product_top-shelf_product | +| app | search | top-shelf | product | app_search_top-shelf_product | +| app | search | top-shelf | banner | app_search_top-shelf_banner | +| site | category | bottom-shelf | banner | site_category_bottom-shelf_banner | +| site | product | filter-bar | product | site_product_filter-bar_product | + +#### Tamaños de Imagen Estándar IAB + +Para anuncios de tipo banner, es importante utilizar imágenes en los formatos estándar definidos por el IAB (Interactive Advertising Bureau). Esto garantiza la compatibilidad y una mejor experiencia visual en diferentes sitios y dispositivos. + +**Formatos Principales:** + +* **Rectángulo Mediano:** 300x250 píxeles +* **Leaderboard:** 728x90 píxeles +* **Skyscraper Ancho:** 160x600 píxeles +* **Leaderboard Móvil:** 320x50 píxeles +* **Billboard:** 970x250 píxeles +* **Media Página:** 300x600 píxeles + +#### Opciones de Tamaño para Videos + +Para solicitudes de anuncios de video, debe especificar el parámetro de tamaño para filtrar por resolución de video. Las opciones disponibles son: + +* **1080p** (1920x1080 pixels) - Recomendado solo para videos en pantalla completa +* **720p** (1280x720 pixels) - Recomendado solo para videos en pantalla completa +* **480p** (854x480 pixels) +* **360p** (640x360 pixels) +* **320p** (568x320 pixels) - Recomendado para dispositivos móviles + +**Importante:** Al solicitar anuncios de video, use solo el identificador de resolución (ej: `"720p"`) en el parámetro size, no las dimensiones completas. Por ejemplo, para filtrar por resolución 1280x720, use `"size": "720p"` en su solicitud de anuncio. + +### Segmentación de Anuncios + +Dirija anuncios a públicos específicos para aumentar la relevancia. + +#### **Segmentación en Tiempo Real** +Envíe datos demográficos o de audiencia directamente en el cuerpo de la **consulta de anuncios**, en el campo `segmentation`. + +El campo `segmentation` es un array de objetos, donde cada objeto contiene: +- `key`: El tipo de segmentación (ej: "STATE", "CITY", "GENDER") +- `values`: Array de valores para la segmentación + +**Ejemplo de Segmentación:** + +```json +[ + { + "key": "STATE", + "values": [ + "CABA" + ] + }, + { + "key": "CITY", + "values": [ + "Buenos Aires" + ] + } +] +``` + +**Tipos de Segmentación Disponibles:** + +| Clave (key) | Descripción | Ejemplos de Valores | +| :--- | :--- | :--- | +| `STATE` | Provincia/Estado del usuario | "CABA", "Buenos Aires", "Córdoba" | +| `CITY` | Ciudad del usuario | "Buenos Aires", "Córdoba", "Rosario" | +| `GENDER` | Género del usuario | "M", "F" | +| `AGE` | Edad del usuario | "22", "35" | +| `AUDIENCES` | Audiencia personalizada | "clientes_alto_valor", "abandonadores_carrito" | +| `NBO_CATEGORIES` | Indica las posibles categorías que el usuario tiene intención de comprar | "Electrónica", "Libros" | + +### Códigos de Respuesta y Errores + +- **200 OK:** Consulta procesada con éxito (retorna JSON por placement). +- **422 Unprocessable Entity:** Error de validación de campos (formato compatible con JSON Schema/Ajv). +- **400 Bad Request / 404 Not Found:** Solicitud inválida o recurso no encontrado. +- **429 Too Many Requests:** Límite de solicitudes excedido. +- **5xx:** Errores internos. + +Ejemplo 422 (parcial): +```json +[ + { + "instancePath": "/context", + "keyword": "enum", + "message": "must be equal to one of the allowed values", + "params": {"allowedValues": ["home","category","search","product_page","brand_page","digital_signage"]}, + "schemaPath": "#/properties/context/enum" + } +] +``` diff --git a/es/docs/5.5.1-recomendacion-de-nombres-de-placements.md b/es/docs/5.5.1-recomendacion-de-nombres-de-placements.md index bb61e42..342de11 100644 --- a/es/docs/5.5.1-recomendacion-de-nombres-de-placements.md +++ b/es/docs/5.5.1-recomendacion-de-nombres-de-placements.md @@ -6,3 +6,35 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +Usar nombres claros y consistentes para los placements es esencial para medir correctamente el rendimiento de cada área de anuncios del sitio/app, facilitar informes y acelerar diagnósticos. + +Patrón de nomenclatura recomendado: + +``` +{medio}_{contexto}_{posicion}_{tipo} +``` + +Dónde: +- medio: canal de acceso, p. ej.: site, msite (sitio móvil), app +- contexto: página/contexto de navegación, p. ej.: home, category, search, product, brand_page, digital_signage +- posicion: ubicación del bloque en la página, p. ej.: top-vitrine, middle, bottom-vitrine, filter-bar +- tipo: tipo de creativo, p. ej.: product, banner, sponsored_brand + +Buenas prácticas: +- Use minúsculas y sin espacios (use guion para compuestos, p. ej.: top-vitrine). +- Evite abreviaciones poco claras; mantenga consistencia entre páginas y canales. +- El nombre debe ser estable en el tiempo (no incluya fechas, nombres de campañas, etc.). + +Ejemplos: + +| medio | contexto | posición | tipo | ejemplo | +| --- | --- | --- | --- | --- | +| site | home | middle | banner | site_home_middle_banner | +| msite | product | top-vitrine | product | msite_product_top-vitrine_product | +| app | search | top-vitrine | product | app_search_top-vitrine_product | +| app | search | top-vitrine | banner | app_search_top-vitrine_banner | +| site | category | bottom-vitrine | banner | site_category_bottom-vitrine_banner | +| site | product | filter-bar | product | site_product_filter-bar_product | + +Nota: Use los mismos valores de canal y contexto que envía en la Consulta de Anuncios (5.5) para mantener la trazabilidad entre solicitudes y reportes. \ No newline at end of file diff --git a/es/docs/5.6-eventos.md b/es/docs/5.6-eventos.md index 72e0f84..7660ed0 100644 --- a/es/docs/5.6-eventos.md +++ b/es/docs/5.6-eventos.md @@ -6,3 +6,367 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +La notificación de eventos es **crucial** para la atribución y la medición. + +#### Buenas Prácticas + +* **Persistencia HTTP:** Utilice conexiones HTTP persistentes (`Connection: keep-alive` en el encabezado) para optimizar la performance. +* **Timeout (consulta de anuncios):** Para llamadas de consulta de anuncios (ver sección 5.5), implemente un timeout de 500–600 ms para no perjudicar la experiencia del usuario. + +#### **Identificación de Usuario y Sesión** + +* **`session_id`:** Identificador persistente del visitante. Obligatorio en todos los eventos. Debe mantenerse consistente durante la navegación y entre sesiones dentro de la ventana de conversión (≥ 14 días). El `session_id` debe ser único por usuario y, idealmente, no expirar en este período. Para aplicaciones móviles, se debe enviar el ID del dispositivo como session_id (GAID en Android e IDFA en iOS), de manera que la sesión se mantenga indefinidamente. +* **`user_id`:** ID único del cliente en la plataforma, consistente entre canales. **Obligatorio en conversión**. **Opcional (recomendado)** para impresión, visualización y clic. El `user_id` debe ser el mismo entre app, sitio web y tienda física. + +Después de identificar al usuario y la sesión, siga estas directrices para el disparo de eventos: + +* **Impresión (`impression_url`):** Dispare el evento inmediatamente después de decidir mostrar los anuncios devueltos por el ad server, incluso si el Anuncio finalmente no se muestra al usuario (por ejemplo, por bloqueos o cambios de diseño). +* **Visualización (`view_url`):** Dispare el evento cuando al menos el 50% del Anuncio permanezca dentro del viewport del usuario durante 1 segundo continuo. +* **Clic (`click_url`):** Dispare el evento siempre que el usuario haga clic en el Anuncio. + +No es necesario mantener el estado de los eventos entre cargas de página, pero asegúrese de que cada evento se envíe solo una vez para el mismo Anuncio y contexto. + +#### **Notificación de Impresión, Visualización y Clic** + +Envíe una solicitud `POST` a la respectiva URL de evento (`impression_url`, `view_url`, `click_url`) proporcionada en la consulta de anuncios, con un cuerpo JSON que contenga `session_id` (**obligatorio**) y `user_id` (**cuando esté disponible**). + +* **Cuándo enviar:** `impression_url` cuando se renderiza el Anuncio; `view_url` cuando el Anuncio esté visible (si usted mide viewability); `click_url` en el clic del usuario. +* **URLs de eventos:** utilice siempre las URLs de evento provistas por la consulta de anuncios; no las derive manualmente. +* **Content-Type:** Todas las solicitudes deben incluir el encabezado `Content-Type: application/json` +* **Método Obligatorio (Navegador):** Es **obligatorio** usar `navigator.sendBeacon()` para garantizar el envío asíncrono sin bloquear la navegación y evitar la pérdida de eventos cuando el usuario navega a otra página o cierra el navegador. +* **Respuesta Exitosa:** `HTTP 202 Accepted`. + +Consulte ejemplos de envío desde el navegador en `examples/EVENTS_IMPRESSIONS_VIEWS_CLICKS_BROWSER.md`. + +**Ejemplo de envío de evento usando Beacon API:** + +```javascript +// Función para enviar evento de impresión +function sendImpressionEvent(impressionUrl, userId, sessionId) { + // Datos del evento + const eventData = { + user_id: userId, + session_id: sessionId + }; + + // Verifica si el navegador soporta la Beacon API + if (navigator.sendBeacon) { + // Convierte los datos a JSON + const blob = new Blob([JSON.stringify(eventData)], {type: 'application/json'}); + + // Envía el evento de forma asíncrona + const success = navigator.sendBeacon(impressionUrl, blob); + + if (!success) { + console.error('Error al enviar evento vía Beacon API'); + // Implementar fallback si es necesario + } + } else { + // Fallback para navegadores que no soportan Beacon API + const xhr = new XMLHttpRequest(); + xhr.open('POST', impressionUrl, true); // true para asíncrono + xhr.setRequestHeader('Content-Type', 'application/json'); + xhr.send(JSON.stringify(eventData)); + } +} + +// Ejemplo de uso +sendImpressionEvent( + 'https://events.newtail-media.newtail.com.br/v1/beacon/impression/123456', + 'user-123', + 'session-456' +); +``` + +> **Importante:** El uso de la Beacon API es obligatorio para garantizar que los eventos se envíen incluso cuando el usuario navega a otra página o cierra el navegador. Esto evita la pérdida de eventos y asegura una medición más precisa. + +#### **Notificación de Conversión** + +Cuando una compra es finalizada, envíe los datos del pedido. + +* **Endpoint:** `POST https://events.newtail-media.newtail.com.br/v1/beacon/conversion` +* **Content-Type:** Todas las solicitudes deben incluir el encabezado `Content-Type: application/json` +* **Cuerpo de la Solicitud:** El objeto debe contener los datos del pedido. El precio del artículo no debe ser multiplicado por la cantidad. + +Consulte ejemplos de conversión en `examples/EVENTS_CONVERSION_BROWSER.md` (Browser) y `examples/EVENTS_CONVERSION_CURL.md` (cURL). + +| Campo del Pedido | Descripción | Tipo | ¿Obligatorio? | +| :--- | :--- | :--- | :--- | +| `publisher_id` | ID del publisher. | String | Sí | +| `user_id` | ID del usuario que realizó la compra. | String | Sí | +| `session_id` | ID de la sesión de la compra. | String | Sí | +| `order_id` | ID del pedido. | String | Sí | +| `created_at` | Fecha/hora del pedido (ISO 8601 en UTC). | String | Sí | +| `items` | Lista de artículos del pedido. | Array[Item] | Sí | +| `channel` | Canal de venta (ej.: ecommerce, app, tienda física). | String | Sí | +| `brand` | Marca/sitio donde ocurrió la venta (necesario cuando existe más de un sitio). | String | No/Sí | +| `gender` | Indica el género del cliente. F: para femenino, M: para masculino, O: para otros, null: para no identificados. | String | No (Recomendado) | +| `uf` | Indica el estado de la compra del pedido. | String | No (Recomendado) | +| `city` | Indica el nombre de la ciudad donde el cliente realizó la compra. | String | No (Recomendado) | +| `is_company` | Indica si la venta fue realizada a una persona jurídica o física. | Boolean | No (Recomendado) | +| `email_hashed` | E-mail del usuario en formato hash (SHA256). | String | Sí | +| `phone_hashed`| Teléfono del usuario en hash (SHA256). | String | No (Recomendado) | +| `social_id_hashed`| ID social/fiscal del usuario (CUIT/CUIL) en hash (SHA256). | String | No (Recomendado) | +| `first_name_hashed` | Nombre del usuario (hash). | String | No (Recomendado) | +| `last_name_hashed` | Apellido del usuario (hash). | String | No (Recomendado) | + +> Normalización recomendada para hashing: +> - `email_hashed`: email en minúsculas y sin espacios (trim); hash SHA-256 en hexadecimal. +> - `phone_hashed`: teléfono en formato E.164 (ej.: +5491112345678), sin máscaras; hash SHA-256 en hexadecimal. +> - `social_id_hashed`: documento fiscal solo con dígitos (sin puntos/guiones); hash SHA-256 en hexadecimal. +> - `first_name_hashed` / `last_name_hashed`: nombres normalizados (trim, sin espacios dobles); hash SHA-256 en hexadecimal. + +#### **Estructura de los Artículos del Pedido** + +##### Campos del Objeto Item + +| Campo | Descripción | Tipo | Obligatoriedad | +|-------|-----------|------|-----------------| +| `sku` | Identificación única del SKU del producto | String | **Obligatorio** | +| `quantity` | Cantidad comprada del producto | Double | **Obligatorio** | +| `price` | Precio original del producto (precio "de") | Double | **Obligatorio** | +| `promotional_price` | Precio promocional del producto (precio "por") | Double | **Obligatorio** | +| `seller_id` | Identificación del vendedor/seller | String | Opcional | +| `product_id` | Identificación única del producto que engloba el SKU | String | Opcional | + +##### ⚠️ Observaciones Importantes + +1. **Valores unitarios**: Los campos `price` y `promotional_price` deben contener el valor **unitario** del producto, **no** multiplicado por la cantidad +2. **Campos obligatorios para medición**: Si `price` y `promotional_price` no se informan correctamente, la conversión **no podrá ser medida** +3. **Formato monetario**: Los valores deben enviarse como números decimales (ej: 1899.00) + +#### **Ejemplos de Utilización** + +##### Ejemplo de Artículo Individual +```json +{ + "sku": "12221", + "seller_id": "1234", + "product_id": "4567", + "quantity": 1, + "price": 2000.00, + "promotional_price": 1899.00 +} +``` + +##### Ejemplo de Solicitud Completa + +```http +POST https://events.newtail-media.newtail.com.br/v1/beacon/conversion HTTP/1.1 +Accept: application/json +Content-Type: application/json +``` + +```json +{ + "channel": "ecommerce", + "publisher_id": "xxx", + "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", + "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", + "order_id": "123", + "email_hashed": "xyz", + "items": [ + { + "sku": "12221", + "seller_id": "1234", + "product_id": "4567", + "quantity": 1, + "price": 2000.00, + "promotional_price": 1899.00 + }, + { + "sku": "12222", + "seller_id": null, + "product_id": "4568", + "quantity": 2, + "price": 500.00, + "promotional_price": 400.00 + } + ], + "created_at": "2023-01-01T09:20:00Z" +} +``` + +**Nota**: En el ejemplo anterior, observe que: +- El primer artículo tiene cantidad 1 con precio unitario de $2.000,00 +- El segundo artículo tiene cantidad 2 con precio unitario de $500,00 (no $1.000,00) + +#### **Respuestas de la API** + +##### ✅ Respuesta Exitosa (HTTP 202) +```json +{ + "messages": [ + "conversion will be processed soon" + ] +} +``` + +##### ❌ Respuesta de Error de Validación (HTTP 422) +La API devuelve errores de validación en un formato compatible con JSON Schema (similar a Ajv). + +Ejemplo de respuesta con errores: +```json +[ + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'user_id'", + "params": { + "missingProperty": "user_id" + }, + "schemaPath": "#/required" + }, + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'order_id'", + "params": { + "missingProperty": "order_id" + }, + "schemaPath": "#/required" + }, + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'publisher_id'", + "params": { + "missingProperty": "publisher_id" + }, + "schemaPath": "#/required" + }, + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'items'", + "params": { + "missingProperty": "items" + }, + "schemaPath": "#/required" + }, + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'created_at'", + "params": { + "missingProperty": "created_at" + }, + "schemaPath": "#/required" + } +] +``` + +#### **🎯 Regla de Match de Productos para Conversiones** + +##### Importante: Correspondencia entre Producto y Campaña + +Las conversiones **solo se computan** para campañas cuando ocurre un **match de producto**. Esto significa que: + +- ✅ **Conversión se mide**: Cuando el producto comprado por el usuario **pertenece** a la campaña en la que el usuario fue impactado +- ❌ **Conversión NO se mide**: Cuando el producto comprado **no pertenece** a la campaña en la que el usuario fue impactado + +##### Ejemplo Práctico: + +**Escenario 1 - Con Match (Conversión Computada)** +- Usuario visualizó anuncio de la Campaña A (productos: SKU-001, SKU-002, SKU-003) +- Usuario compró producto SKU-002 +- ✅ Conversión se atribuye a la Campaña A + +**Escenario 2 - Sin Match (Conversión NO Computada)** +- Usuario visualizó anuncio de la Campaña B (productos: SKU-004, SKU-005) +- Usuario compró producto SKU-999 +- ❌ Conversión NO se atribuye a la Campaña B + +#### **Ejemplo de Código** + +##### JavaScript (Browser) +```javascript +const enviarConversion = async (datosPedido) => { + const payload = { + channel: "ecommerce", + publisher_id: "xxx", + user_id: datosPedido.userId, + session_id: datosPedido.sessionId, + order_id: datosPedido.orderId, + email_hashed: datosPedido.emailHash, + items: datosPedido.items.map(item => ({ + sku: item.sku, + seller_id: item.sellerId || null, + product_id: item.productId || null, + quantity: item.quantity, + price: item.unitPrice, // Valor unitario, no multiplicado + promotional_price: item.unitPromotionalPrice // Valor unitario, no multiplicado + })), + created_at: new Date().toISOString() + }; + + try { + // Convierte los datos a JSON + const blob = new Blob([JSON.stringify(payload)], {type: 'application/json'}); + + // Envía el evento de forma asíncrona usando Beacon API + if (navigator.sendBeacon) { + const success = navigator.sendBeacon( + 'https://events.newtail-media.newtail.com.br/v1/beacon/conversion', + blob + ); + + if (success) { + console.log('Conversión enviada con éxito'); + } else { + console.error('Error al enviar conversión vía Beacon API'); + } + } else { + // Fallback para navegadores que no soportan Beacon API + const response = await fetch('https://events.newtail-media.newtail.com.br/v1/beacon/conversion', { + method: 'POST', + headers: { + 'Accept': 'application/json', + 'Content-Type': 'application/json' + }, + body: JSON.stringify(payload) + }); + + if (response.status === 202) { + console.log('Conversión enviada con éxito'); + } else if (response.status === 422) { + const errors = await response.json(); + console.error('Errores de validación:', errors); + } + } + } catch (error) { + console.error('Error al enviar conversión:', error); + } +}; + +// Ejemplo de uso +const pedido = { + userId: "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", + sessionId: "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", + orderId: "123", + emailHash: "xyz", + items: [ + { + sku: "12221", + sellerId: "1234", + productId: "4567", + quantity: 1, + unitPrice: 2000.00, + unitPromotionalPrice: 1899.00 + } + ] +}; + +enviarConversion(pedido); +``` + +#### **Reglas de Atribución y Deduplicación** + +* **Ventana de Conversión:** Período después de una interacción en el que una venta puede ser atribuida al anuncio. + * **Clic (para `product`):** 14 días. + * **Visualización (para `display`/`video`):** 14 días. +* **Deduplicación de Eventos:** Para el mismo usuario y anuncio, los eventos se ignoran durante un período. + * **Impresiones:** 1 minuto. + * **Clics:** 1 hora. + * **Conversiones:** Idempotentes por `order_id` (reenvíos del mismo `order_id` dentro de 30 días se ignoran). diff --git a/es/docs/5.7-integracion-transparente.md b/es/docs/5.7-integracion-transparente.md index 7ce119b..2104dfe 100644 --- a/es/docs/5.7-integracion-transparente.md +++ b/es/docs/5.7-integracion-transparente.md @@ -6,3 +6,117 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +> Nota: Esta herramienta solo está apta para servir anuncios de tipo Banner y Video. + +La integración transparente tiene como objetivo reducir la fricción al máximo para iniciar la configuración de la integración de VTEX Ads de la forma más sencilla posible. + +## Requisitos para la Prueba de Concepto (PoC) + +Para que esta Prueba de Concepto funcione, los siguientes requisitos son esenciales: + +1. **Integración de Catálogo:** Es necesario que una integración de catálogo esté en funcionamiento. + +2. **Instalación del Script:** Nuestro script debe ser añadido al sitio web. + +3. **Disparo del Evento de Conversión:** El evento de conversión debe ser disparado desde el lado del cliente. + + +### 1\. Integración del Catálogo + +La sincronización del catálogo sigue el formato ya definido para todas las integraciones. + +### 2\. Instalación del Script + +Añada el siguiente script lo antes posible en la etiqueta `<head>` de la página o en su sitio web/msite: + +``` +<script src="https://cdn.newtail.com.br/retail-media/scripts/vtexads-magic-1.0.0.js"></script> +``` + +#### Requisitos del Script + +Para que el script funcione correctamente, el cliente debe informarnos el origen de dos parámetros importantes: `session_id` y `user_id`. Estos parámetros generalmente se almacenan en cookies, `sessionStorage` o `localStorage`. + +### 3\. Evento de Conversión + +El evento de conversión debe enviarse después de la creación del pedido, sin necesidad de confirmación de pago. + +El siguiente script demuestra cómo enviar datos a un endpoint de API utilizando la interfaz `navigator.sendBeacon`. El método `sendBeacon` es ideal para enviar pequeñas cantidades de datos de forma asíncrona sin afectar el rendimiento de la página. Es particularmente útil para enviar datos de análisis antes de que el usuario abandone la página. + +``` +/** + * Este script demuestra cómo enviar datos a un endpoint de API + * utilizando la interfaz `navigator.sendBeacon`. + * + * El método `sendBeacon` está diseñado para enviar pequeñas cantidades de datos + * de forma asíncrona sin afectar el rendimiento de la página actual + * o el tiempo de carga de la siguiente. + * + * Es particularmente útil para enviar datos de análisis antes de que + * un usuario abandone una página. + */ + +// 1. Defina los datos que desea enviar. +const data = { + "publisher_id": "d4dff0cb-1f21-4a96-9acf-d9426a5ed08c", + "user_id": "26119121", + "order_id": "1758035060", + "channel": "site|msite|app", + "created_at": "2025-09-16T15:04:19.794Z", + "items": [ + { + "price": 12, + "promotional_price": 10, + "quantity": 1, + "sku": "sku1" + }, + { + "price": 15, + "promotional_price": 13, + "quantity": 1, + "sku": "sku2", + "seller_id": "seller1" + }, + { + "price": 19, + "promotional_price": 17, + "quantity": 1, + "sku": "sku3", + "product_id": "prod3" + }, + { + "price": 30, + "promotional_price": 25, + "quantity": 2, + "sku": "sku4", + "product_id": "prod4", + "seller_id": "seller2" + } + ] +}; + +// 2. Convierta el objeto de datos en una cadena JSON. +const rawData = JSON.stringify(data); + +// 3. Cree un Blob a partir de la cadena JSON. +// Esto nos permite definir explícitamente el Content-Type para la solicitud. +const blob = new Blob([rawData], { type: 'application/json' }); + +// 4. Defina la URL del endpoint. +const url = "https://newtail-media.newtail.com.br/v1/beacon/conversion"; + +// 5. Use `navigator.sendBeacon` para enviar los datos. +// El método devuelve `true` si el navegador pone en cola la solicitud +// para su entrega y `false` en caso contrario. +// Tenga en cuenta que `sendBeacon` no devuelve una Promesa, por lo que no hay +// `.then()` o `.catch()`. La entrega no está garantizada, pero es +// muy probable. +const success = navigator.sendBeacon(url, blob); + +if (success) { + console.log("¡Solicitud de beacon encolada con éxito!"); +} else { + console.error("Error al encolar la solicitud de beacon."); +} +``` diff --git a/es/docs/6-exportacion-de-datos.md b/es/docs/6-exportacion-de-datos.md index ef65db2..be0d7eb 100644 --- a/es/docs/6-exportacion-de-datos.md +++ b/es/docs/6-exportacion-de-datos.md @@ -6,3 +6,63 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +La exportación de datos le permite recibir información detallada sobre eventos y datos agregados de forma sistemática y periódica. La integración se realiza a través de una conexión S3, y los datos se entregan en formatos específicos para cada tipo de exportación. + +### 6.1. Reportes + +Además de la exportación a través de S3, es posible extraer informes a través de la API. Las rutas devuelven JSON por defecto, pero se pueden exportar como archivos XLSX incluyendo el parámetro `download=true` en la consulta. + +* `GET /report/v2/advertisers`: Información de anunciantes (vista del publisher) [[Ejemplo]](../../examples/EXPORT_ADVERTISER_DATA.md) +* `GET /report/v2/publishers`: Información del publisher (vista del anunciante) [[Ejemplo]](../../examples/EXPORT_PUBLISHER_DATA.md) +* `GET /report/network/publishers`: Publishers de la red (para cuentas de tipo Red) [[Ejemplo]](../../examples/EXPORT_NETWORK_PUBLISHERS_DATA.md) +* `GET /campaign/v2`: Informe listado de campañas [[Ejemplo]](../../examples/EXPORT_CAMPAIGNS_LIST_DATA.md) +* `GET /campaign/:id`: Informe detallado de la campaña [[Ejemplo]](../../examples/EXPORT_CAMPAIGN_DATA.md) +* `GET /report/advertisers/campaigns-detailed`: Informe detallado de campañas mixtas para cuentas de anunciante, incluyendo información de subpublisher en campañas de red [[Ejemplo]](../../examples/EXPORT_ADVERTISER_CAMPAIGNS_DETAILED_DATA.md) +* `GET /report/advertisers/ads-detailed`: Informe detallado de anuncios para cuentas de anunciante, incluyendo el desglose por subpublisher en campañas de red [[Ejemplo]](../../examples/EXPORT_ADVERTISER_ADS_DETAILED_DATA.md) +* `GET /ad/results/v2`: Informe de anuncios individuales [[Ejemplo]](../../examples/EXPORT_ADS_DATA.md) + +### 6.2. Exportación de Datos + +La integración siempre se realizará mediante una conexión S3 (o compatible) que deberá ser proporcionada por el receptor de los datos. Las credenciales deben ser entregadas al equipo de Newtail de forma segura. + +La integración es compatible con: + +* **AWS S3:** `Access Key Id` y `Access Key Secret`. +* **Google Cloud Storage:** `Service Account`. +* **Azure Blob Storage**. + +#### Exportación de Eventos + +La exportación de eventos envía datos brutos de las interacciones de los usuarios. + +* **Formato:** `PARQUET` con compresión `Snappy`. +* **Frecuencia:** Diaria (datos de D-1). +* **Estructura de Carpetas:** `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.snappy.parquet` +* **De-duplicación:** Se garantiza que todos los eventos serán enviados, pero no que se enviarán una única vez. Por lo tanto, los eventos siempre deben ser de-duplicados usando el `event_id` o la combinación de `order_id` y `product_sku` para los artículos de conversión. + +##### Tipos de Eventos + +* **Impresiones, Visualizaciones y Clics:** + * **Campos:** `event_id` (clave de de-duplicación), `session_id`, `user_id`, `ad_id`, `campaign_id`, `request_id`, `ad_type`, `placement_name`, `context`, `created_at`, `site`. +* **Conversiones:** + * **Campos:** `event_id`, `session_id`, `user_id`, `order_id` (clave de de-duplicación), `channel`, `placed_at`, `site`. +* **Artículos de Conversión:** + * **Campos:** `event_id`, `session_id`, `user_id`, `order_id` (clave de de-duplicación), `product_sku` (clave de de-duplicación), `ad_id`, `campaign_id`, `request_id`, `ad_size`, `ad_type`, `placement_name`, `context`, `event_created_at`, `price`, `promotional_price`, `quantity`, `total_value`. + +#### Exportación de Datos Agregados + +La exportación de datos agregados envía informes consolidados. + +* **Formato:** `CSV` con codificación `UTF-8`, separado por comas, y números en formato americano (punto decimal). +* **Frecuencia:** Diaria (datos de D-1, con la zona horaria del publisher). +* **Estructura de Carpetas:** `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.csv` + +##### Tipos de Informes + +* **Anunciantes:** + * **Campos:** `advertiser`, `advertiser_id`, `seller_id`, `wallet_balance`, `daily_budget`, `currency`. +* **Campañas:** + * **Campos:** `day`, `name`, `campaign_id`, `campaign_type`, `campaign_status`, `impressions_total`, `clicks_total`, `ctr`, `ad_revenue`, `conversions_total`, `conversion_rate`, `sales_revenue`, `start_date`, `end_date`, `advertiser_id`. +* **Anuncios:** + * **Campos:** `day`, `ad_id`, `campaign_id`, `ad_status`, `ad_media_url`, `cpm`, `cpc`, `impressions_total`, `clicks_total`, `ctr`, `ad_revenue`, `conversions_total`, `conversion_rate`, `sales_revenue`, `product_sku`. diff --git a/es/docs/7-script-agent.md b/es/docs/7-script-agent.md index 12dc9fa..380c524 100644 --- a/es/docs/7-script-agent.md +++ b/es/docs/7-script-agent.md @@ -6,3 +6,79 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +## 7.1. Objetivo + +Este documento detalla el procedimiento para la instalación del script de seguimiento de **VTEX Ads** en todas las páginas de un sitio web (excepto las páginas de checkout) a través de Google Tag Manager (GTM). La correcta implementación de este script es fundamental para la recopilación de datos de navegación que permiten la optimización y el direccionamiento de campañas de Retail Media. + +## 7.2. Datos Recopilados + +El script de VTEX Ads fue desarrollado para recopilar exclusivamente datos de navegación no sensibles, con el objetivo de personalizar la experiencia del usuario y optimizar campañas. + +**Datos Recopilados:** + +- **Para campañas off-site:** + - `session_id`: Identificador anónimo de la sesión de navegación. + - `ad_id`: Identificador del anuncio que originó el tráfico. +- **Para segmentación de audiencia (Page View):** + - `session_id`: Identificador anónimo de la sesión de navegación. + - **Información de la Página:** URL, título (`<title>`) y descripción (`<meta name="description">`). + +> **Importante:** El script **no recopila** ninguna información de identificación personal (PII), como nombre, correo electrónico, CPF, teléfono, dirección o datos de pago. La recopilación de datos cumple con las principales leyes de protección de datos. + +## 7.3. Datos del Script + +El script debe cargarse de forma asíncrona para no afectar el tiempo de carga de la página. + +- **URL del Script:** `https://cdn.newtail.com.br/retail-media/scripts/vtexrma-agent.1.0.0.js` + +## 7.4. Paso a Paso para la Implementación a través de Google Tag Manager (GTM) + +Para garantizar que el script se ejecute lo antes posible en la carga de la página, recomendamos utilizar el activador de **Inicialización (Initialization)**. + +### Paso 7.4.1: Crear la Etiqueta de HTML Personalizado + +1. Acceda a su contenedor de GTM y vaya a la sección **"Etiquetas"**. +2. Haga clic en **"Nueva"** para crear una nueva etiqueta. +3. Dé un nombre claro a la etiqueta, por ejemplo: **"Custom HTML - VTEX Ads Agent"**. +4. Haga clic en **"Configuración de la etiqueta"** y seleccione el tipo de etiqueta **"HTML personalizado"**. +5. En el campo de HTML, inserte el siguiente código: + ```html + <script type="text/javascript" async src="https://cdn.newtail.com.br/retail-media/scripts/vtexrma-agent.1.0.0.js"></script> + ``` + +### Paso 7.4.2: Configurar el Activador Principal + +1. Debajo de la configuración de la etiqueta, haga clic en **"Activación"**. +2. Seleccione el activador **"Initialization - All Pages"** (Inicialización - Todas las Páginas). Este activador garantiza que el script se dispare antes que la mayoría de las otras etiquetas, en todas las páginas. + +### Paso 7.4.3: Crear y Añadir una Excepción de Activación + +Para evitar que el script se ejecute en las páginas de checkout, crearemos una excepción. + +1. Aún en la configuración de la etiqueta, en la sección **"Activación"**, haga clic en **"Añadir excepción"**. +2. Haga clic en el ícono de **"+"** en la esquina superior derecha para crear un nuevo activador de excepción. +3. Dé un nombre al activador, por ejemplo: **"Trigger Exception - Checkout Pages"**. +4. Haga clic en **"Configuración del activador"** y elija el tipo **"Inicialización"**. +5. En **"Este activador se dispara en"**, seleccione **"Algunas inicializaciones"**. +6. Configure la condición para identificar las páginas de checkout. La condición puede variar dependiendo de la estructura de la URL de su sitio. Ejemplos comunes: + - `Page Path` | `contiene` | `/checkout` + - `Page URL` | `coincide con RegEx (sin distinguir mayúsculas y minúsculas)` | `/checkout/|/orderPlaced/` +7. Guarde el nuevo activador de excepción. Se agregará automáticamente a su etiqueta. + +### Paso 7.4.4: Guardar y Publicar + +1. Guarde la etiqueta recién creada. +2. Envíe y publique los cambios en su contenedor de GTM. + +## 7.5. Configuración de la Sesión del Usuario + +Para que la plataforma VTEX Ads pueda correlacionar correctamente las interacciones del usuario, es necesario informar cuál es el identificador de sesión utilizado por su e-commerce. + +**Acción Necesaria:** + +El equipo responsable del e-commerce debe informar al equipo de VTEX Ads cuál es el **nombre del atributo en la `cookie` o `sessionStorage`** que almacena el ID de la sesión del usuario. + +- **Ejemplo:** Si el ID de la sesión se almacena en una cookie llamada `vtex_session`, esta información debe ser comunicada. + +Esta configuración permite que el script lea el identificador correcto y lo asocie a los eventos de navegación. diff --git a/es/docs/8-repasse.md b/es/docs/8-repasse.md index 98bcafb..36b8068 100644 --- a/es/docs/8-repasse.md +++ b/es/docs/8-repasse.md @@ -6,3 +6,75 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +La transferencia de créditos es el flujo que permite al marketplace transferir créditos de publicidad a sus sellers. Esta documentación detalla los endpoints que el marketplace debe implementar y el webhook que debe consumir para realizar la integración con VTEXAds. + +<div align="center"> + <img src="../../diagrams/images/es/credit-transfer.png" alt="Flujo de Transferencia de Créditos" /> +</div> + + * **Endpoints a ser implementados por el Marketplace (Autenticación: Basic Auth):** + 1. **Consulta de Saldo (`GET /checking_account`)** + * **Objetivo:** Verificar el saldo disponible del seller. + * **Parámetros (Query):** `seller_id`, `publisher_id` (opcional, utilizado solo en casos donde una entidad gestiona múltiples publishers). + * **Respuesta Exitosa (200 OK):** + ```json + { "total": "1111.00" } + ``` + + 2. **Solicitud de Transferencia (`POST /checking_account/transfer`)** + * **Objetivo:** Requerir la transferencia de un valor. + * **Cuerpo de la Solicitud:** + ```json + { + "amount": "10.00", + "seller_id": "SELLER_ID", + "publisher_id": "PUBLISHER_ID", + "transfer_identity_id": "uuid" + } + ``` + * **Respuestas:** + - **Síncrona (Éxito):** `201 Created` + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "success" + } + ``` + - **Síncrona (Falla):** `400 Bad Request` + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "failure", + "message": "Motivo del rechazo" + } + ``` + - **Asíncrona:** `202 Accepted` + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "processing" + } + ``` + + * **Webhook a ser consumido por el Marketplace:** + * **Objetivo:** Notificar a VTEXAds sobre el estado final de la transferencia. + * **Endpoint:** `POST https://api-retail-media.newtail.com.br/webhook/marketplace/transfers/:publisher_id` + * **Autenticación:** `x-api-key` y `x-secret-key`. + * **Payload:** + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "success" + } + ``` + o + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "failure", + "message": "Descripción del problema" + } + ``` + * **Lógica de Reintentos:** En caso de falla en la llamada del webhook, el marketplace debe realizar nuevos intentos. + * **Respuesta Esperada:** `204 No Content` \ No newline at end of file diff --git a/es/docs/9-sso.md b/es/docs/9-sso.md index 5f035d8..f8f499a 100644 --- a/es/docs/9-sso.md +++ b/es/docs/9-sso.md @@ -6,3 +6,34 @@ > La documentación de la API de VTEX Ads ahora forma parte del Portal de Desarrolladores oficial de VTEX: [VTEX Ads API en developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Actualiza tus marcadores. Esta página ya no recibe mantenimiento. + +API para el inicio de sesión unificado del seller. Al llamar a esta API, Newtail genera una URL de redireccionamiento que permite al usuario acceder a la plataforma de Newtail sin necesidad de un nuevo inicio de sesión. + +* **Endpoint:** `POST /sso/marketplace` +* **Cuerpo de la Solicitud:** + +| Campo | Descrição | Tipo | ¿Obligatorio? | +| :--- | :--- | :--- | :--- | +| `sso_token` | Token de identificación del usuario generado por el marketplace. | String | Sí | +| `email` | E-mail del usuario (seller). | String | Sí | +| `user_id` | ID único del usuario en el marketplace. | String | Sí | +| `name` | Nombre del usuario. | String | Sí | +| `marketplace_name` | Nombre del marketplace. | String | Sí | + +* **Ejemplo de Solicitud:** + ```json + { + "sso_token": "token-sso-12345", + "email": "seller@ejemplo.com", + "user_id": "seller123", + "name": "Nombre del Seller", + "marketplace_name": "Mi Marketplace" + } + ``` + +* **Respuesta Exitosa:** `HTTP 200 OK` con la URL de redireccionamiento. + ```json + { + "redirect_url": "https://app.ads.vtex.com/sso/auth?token=TOKEN_GENERADO" + } + ``` \ No newline at end of file diff --git a/pt/docs/1-resumo.md b/pt/docs/1-resumo.md index 5e04599..ae8526d 100644 --- a/pt/docs/1-resumo.md +++ b/pt/docs/1-resumo.md @@ -1,3 +1,8 @@ +--- +layout: default +title: "1. Resumo" +--- + ## 1. Resumo > [!IMPORTANT] @@ -6,3 +11,21 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +Esta documentação detalha a integração com a **Retail Media API**, o ponto central de conexão entre a solução VTEX Ads e a plataforma do varejista (publisher). A solução foi desenvolvida sob o conceito **API-first**, garantindo total flexibilidade para que os varejistas integrem e exibam anúncios em qualquer canal digital: e-commerce, marketplace, aplicativo ou até mesmo em totens e telas físicas (Digital Signage). + +Nossa arquitetura é **cookie-less**, o que significa que não dependemos de cookies de terceiros. A identificação e a segmentação são baseadas em identificadores próprios (`user_id`, `session_id`) e dados primários (first-party data), garantindo uma solução robusta, em conformidade com as novas políticas de privacidade e preparada para o futuro do varejo digital. + +Através desta API REST, sua plataforma poderá: +* Sincronizar o catálogo de produtos e inventário. +* Solicitar anúncios relevantes em tempo real para o contexto de navegação do usuário. +* Enviar eventos de interação (impressão, visualização, clique, conversão) para a medição de performance. + +Adotamos o princípio de **Extensibilidade Progressiva** para garantir máxima estabilidade e segurança nas operações dos nossos parceiros. + +Nossa política formal de compatibilidade assegura que: +* **Evolução sem rupturas:** atualizações são sempre incrementais. Novos campos, funcionalidades e opções são adicionados sem alterar ou remover o comportamento dos contratos existentes. +* **Preservação de integrações:** integrações atuais permanecem plenamente funcionais após novos lançamentos, reduzindo retrabalho técnico recorrente. +* **Continuidade de negócio:** ao preservar a integridade dos contratos anteriores, evitamos interrupções operacionais e permitimos a adoção de novas capacidades no ritmo do seu negócio. + +Essa abordagem reforça nosso compromisso com uma plataforma robusta e escalável, em que inovação tecnológica e previsibilidade operacional evoluem juntas. diff --git a/pt/docs/10-janela-atribuicao.md b/pt/docs/10-janela-atribuicao.md index bf5504b..5aa7de9 100644 --- a/pt/docs/10-janela-atribuicao.md +++ b/pt/docs/10-janela-atribuicao.md @@ -6,3 +6,99 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +Este documento detalha as regras, modelos e prazos que regem a atribuição de conversões (vendas) e a cobrança das campanhas de publicidade em nossa plataforma. + +## 1. O que é a Janela de Atribuição? + +A "janela de atribuição" (ou janela de conversão) é o período de tempo _após_ um usuário interagir com um anúncio (seja clicando ou visualizando) durante o qual uma conversão pode ser creditada a esse anúncio. + +- **Janela Padrão:** 14 dias. +- **Flexibilidade:** Este período é o padrão para todas as campanhas, mas pode ser customizado conforme a necessidade estratégica. + +**Exemplo:** Se um usuário clica em um anúncio hoje, qualquer compra que ele fizer do produto associado nos próximos 14 dias poderá ser atribuída a esse anúncio. + +## 2. Medição (Atribuição) vs. Cobrança (Faturamento) + +É fundamental diferenciar o evento que _mede_ a atribuição (o que usamos para contar uma conversão) do evento que _gera a cobrança_ (o que cobramos do anunciante). + +### 2.1. Eventos de Medição (Atribuição) + +Isto define _como_ sabemos que um anúncio "funcionou" para gerar uma venda: + +- **Campanhas de Produto (Product Ads):** + - **Evento:** Clique. + - **Lógica:** A conversão só é contada se o usuário _clicou_ no anúncio antes de comprar. + +- **Demais Campanhas (Banner, Vídeo e Sponsored Brands):** + - **Evento:** Visualização (Impressão). + - **Lógica:** A conversão pode ser contada mesmo que o usuário apenas _tenha visto_ o anúncio (e não necessariamente clicado), seguindo as regras de hierarquia (ver seção 3). + +### 2.2. Modelos de Cobrança (Faturamento) + +Isto define _pelo quê_ o anunciante paga: + +- **CPC (Custo por Clique):** O anunciante paga cada vez que um usuário clica no anúncio. + - _Usado em:_ Campanhas de Produto, Sponsored Brands. + +- **CPM (Custo por Mil Impressões):** O anunciante paga um valor fixo por cada 1.000 vezes que o anúncio é exibido. + - _Usado em:_ Banner, Vídeo, Sponsored Brands. + +- **Modelo Híbrido (CPC + CPM):** + - As campanhas de **Sponsored Brands** são únicas, pois cobram _tanto_ pelos cliques (CPC) quanto pelas impressões (CPM) geradas. + +#### Exemplo de Cálculo de Cobrança (CPM) + +O CPM define o valor para 1.000 impressões, mas a cobrança real é proporcional a cada impressão individual. + +- **Cenário:** Uma campanha de vídeo possui um CPM de **R$ 10,00**. +- **Resultado:** A campanha gera **10 impressões**. + +**Cálculo:** + +1. **Custo por impressão individual:** R$ 10,00 (CPM) / 1.000 (impressões) = **R$ 0,01 por impressão**. +2. **Custo Total:** 10 (impressões geradas) * R$ 0,01 (custo por impressão) = **R$ 0,10**. + +O custo total dessa campanha seria de **dez centavos**. + +## 3. Regras de Atribuição (A Hierarquia de Decisão) + +Quando um usuário interage com múltiplos anúncios antes de comprar, um modelo de atribuição decide qual campanha receberá o crédito pela venda. + +**Princípio Fundamental:** A atribuição é exclusiva. Um pedido vendido **nunca** é atribuído a duas campanhas distintas; o crédito é sempre dado a uma única campanha. + +A decisão segue esta ordem de prioridade: + +1. **Prioridade 1: Campanhas Offsite** + - Se existe uma campanha _offsite_ ativa (trazendo tráfego externo para o site) e ela foi o último ponto de contato do usuário, ela terá preferência total na atribuição da venda. + +2. **Prioridade 2: Último Clique (Last Click)** + - Na ausência de um clique offsite recente, o sistema procura o _último anúncio_ (dentro da plataforma) que o usuário _clicou_ dentro da janela de 14 dias. + +3. **Prioridade 3: Última Visualização (Last View)** + - Se o usuário não clicou em nenhum anúncio no período, o sistema atribui a venda ao _último anúncio_ que ele _visualizou_ (desde que seja um tipo de campanha que meça por visualização, como Banner ou Vídeo). + +**Regra de Tempo:** Para que uma conversão seja válida, o evento de interação (clique ou visualização) deve, obrigatoriamente, ter ocorrido _antes_ do pedido ser finalizado. + +## 4. Mapeamento de Produtos na Atribuição + +Uma campanha só pode receber atribuição por produtos que estão _explicitamente atrelados a ela_. + +### 4.1. Campanhas de Produto (Atribuição 1:1) + +- **Como funciona:** Cada anúncio (AD) dentro da campanha representa um produto específico. +- **Lógica:** A atribuição é direta e 1 para 1. O clique no anúncio do "Produto A" só pode gerar conversão para o "Produto A". + +### 4.2. Demais Campanhas (Banner, Vídeo, etc.) (Atribuição N:1) + +- **Como funciona:** Estas campanhas possuem uma _lista_ de produtos associados (SKUs). +- **Lógica:** A interação (clique ou view) com um único criativo (banner ou vídeo) pode gerar atribuição para _qualquer_ um dos produtos contidos nessa lista da campanha. + +**Observação sobre Criativos:** Dentro de uma campanha (ex: Banner), cada criativo (ex: o "Banner A" e o "Banner B") metrifica suas informações de forma independente. Isso permite analisar a performance individual de cada peça de anúncio. + +## 5. Latência de Dados (Atraso na Atribuição) + +É importante notar que existe um atraso natural entre o momento em que o cliente cria o pedido e o momento em que essa venda é associada (atribuída) à campanha correta nos relatórios. + +- **Integração via API:** Atraso de aproximadamente **30 minutos**. +- **Plataforma VTEX:** Atraso de até **2 horas**. diff --git a/pt/docs/2-glossario.md b/pt/docs/2-glossario.md index 5bbc945..338e116 100644 --- a/pt/docs/2-glossario.md +++ b/pt/docs/2-glossario.md @@ -6,3 +6,18 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +| Termo | Descrição | +| :--- | :--- | +| **Advertiser (Anunciante)** | Empresas, sellers ou indivíduos que promovem seus produtos, serviços ou ideias através de campanhas. | +| **Publisher (Varejista)** | A entidade que possui e opera a plataforma digital (site, app) e disponibiliza os espaços para a exibição de anúncios. | +| **Campanha** | Ação criada por um anunciante para promover produtos e gerar conversões (vendas). | +| **Impressão** | Contabilizada cada vez que um anúncio é exibido na tela do usuário. | +| **Visualização (View)**| Contabilizada quando uma impressão se torna visível na tela do usuário por um tempo determinado. | +| **Clique** | Interação do usuário ao clicar em um anúncio para ser direcionado à página de destino. | +| **Conversão** | Ação de valor gerada por um anúncio, tipicamente uma venda. | +| **Receita com Anúncios** | Valor obtido pelos varejistas ao monetizarem seus espaços publicitários. | +| **Receita com Vendas** | Valor total obtido por uma empresa a partir das vendas de produtos ou serviços. | +| **CTR (Click-Through Rate)** | Taxa de Cliques. Fórmula: `(Cliques / Impressões) * 100`. Mede a atratividade de um anúncio. | +| **ROAS (Return on Ad Spend)**| Retorno Sobre o Investimento em Publicidade. Fórmula: `Receita Gerada por Anúncios / Custo da Publicidade`. | +| **Taxa de Conversão** | Percentual de conversões em relação ao total de cliques ou visitas. | diff --git a/pt/docs/3-autenticacao.md b/pt/docs/3-autenticacao.md index ed6141c..6cbf808 100644 --- a/pt/docs/3-autenticacao.md +++ b/pt/docs/3-autenticacao.md @@ -6,3 +6,12 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +A autenticação é utilizada para envio de catálogo, consumo de relatórios e gerenciamento. As demais chamadas, como consulta de anúncios e notificação de eventos, são públicas e não exigem autenticação. + +Para os endpoints protegidos, as credenciais devem ser enviadas via header HTTP. Solicite as suas credenciais ao gerente de conta. + +| Atributo | Descrição | +| :--- | :--- | +| `x-app-id` | ID exclusivo da sua aplicação para a integração. | +| `x-api-key` | Chave de API associada à sua aplicação. | diff --git a/pt/docs/4-seguranca-de-dados.md b/pt/docs/4-seguranca-de-dados.md index caac53f..712b0f2 100644 --- a/pt/docs/4-seguranca-de-dados.md +++ b/pt/docs/4-seguranca-de-dados.md @@ -6,3 +6,29 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +A segurança dos dados é um pilar fundamental da nossa plataforma. Desde o início, nossa arquitetura foi projetada para garantir que nenhuma informação sensível seja coletada e que os dados dos usuários permaneçam sempre protegidos e não identificáveis. + +## Dados Não Identificáveis + +Não coletamos dados sensíveis dos usuários, como nome, e-mail ou documentos. As informações que recebemos, como e-mails ou CPFs (PII - *Personally Identifiable Information*), já chegam em nossa plataforma com um hash criptográfico irreversível. + +Isso significa que o dado original nunca trafega ou é armazenado em nossos sistemas. O resultado é um identificador anônimo que nos permite agrupar comportamentos e audiências sem nunca saber quem é o usuário real. + +**Por que isso é seguro?** + +* **Irreversibilidade:** O processo de hashing é uma via de mão única. Mesmo que alguém tivesse acesso ao hash, não conseguiria descobrir o dado original. +* **Anonimato:** Como não armazenamos o dado original, não temos como identificar o usuário. Para todos os efeitos, os dados são anônimos. + +## Criptografia em Trânsito e em Repouso + +Todos os dados, sejam eles identificadores anônimos ou informações sobre campanhas e anúncios, são tratados com os mais altos padrões de segurança: + +* **Criptografia em Trânsito:** Toda a comunicação entre nossos sistemas e com parceiros é feita utilizando protocolos seguros como TLS 1.2+, garantindo que os dados não possam ser interceptados durante a transferência. +* **Criptografia em Repouso:** Os dados armazenados em nossos bancos de dados e sistemas de arquivos são criptografados. Utilizamos soluções robustas e reconhecidas no mercado, como **Amazon RDS**, **Amazon S3**, **Amazon Redshift** e **Snowflake**, que aplicam criptografia AES-256, um dos algoritmos mais seguros existentes. + +## Acesso Restrito + +O acesso aos dados é rigorosamente controlado e limitado a um grupo seleto de engenheiros e analistas sêniores. Cada acesso é auditado e monitorado, e as permissões são concedidas com base no princípio do menor privilégio, ou seja, cada pessoa tem acesso apenas ao que é estritamente necessário para realizar seu trabalho. + +Essa combinação de dados não identificáveis, criptografia de ponta a ponta e controle de acesso rigoroso garante que a sua informação e a de seus clientes estejam sempre seguras. diff --git a/pt/docs/5-integracao-de-anuncios.md b/pt/docs/5-integracao-de-anuncios.md index 222a515..c93654a 100644 --- a/pt/docs/5-integracao-de-anuncios.md +++ b/pt/docs/5-integracao-de-anuncios.md @@ -6,3 +6,26 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +Esta seção fornece informações detalhadas sobre como se integrar à plataforma VTEX Ads para exibir anúncios em seu site. + +## 5.0 Visão Geral do Fluxo de Integração + +<img src="../../diagrams/images/pt/integration-end-to-end.png" alt="Fluxo completo de integração com VTEX Ads" /> + +O fluxo de integração completo é dividido em quatro fases principais que se retroalimentam continuamente: + +1. **Preparação e Onboarding:** Alinhe escopo e cronograma com a equipe da VTEX Ads, receba as credenciais de API e valide acesso a ambientes e webhooks. +2. **Sincronização de Dados Operacionais:** Carregue catálogo (produtos e inventário) e, opcionalmente, audiências. Essa etapa garante que apenas produtos disponíveis e segmentações válidas estejam aptos a aparecer. +3. **Entrega de Anúncios:** Estruture os placements do site, configure convenções de nome e consulte anúncios em tempo real para cada contexto (home, busca, categoria, PDP etc.), exibindo o selo “Patrocinado”. +4. **Mensuração e Otimização:** Dispare os eventos de impressão, visualização, clique e conversão usando `navigator.sendBeacon()`, monitore as métricas de desempenho e ajuste lances, segmentações e posicionamentos de acordo com os resultados. + +As seções seguintes detalham como executar cada uma dessas fases, com exemplos de requisições e boas práticas específicas. + +- [5.1. Integração via API](./5.1-integracao-via-api.md): Para uma integração mais personalizada, use nossa API REST para gerenciar todo o ciclo de vida do anúncio. +- [5.2. Integração VTEX](./5.2-integracao-vtex.md): Se sua loja estiver na plataforma VTEX, use nosso aplicativo VTEX IO para simplificar o processo. +- [5.3. Sincronização de Catálogo](./5.3-sincronizacao-de-catalogo.md): Mantenha seu catálogo de produtos e inventário sincronizados com a VTEX Ads. +- [5.4. Integração de Audiências](5.4-integracao-de-audiencias.md): Envie dados de audiência para melhorar a segmentação e a relevância dos anúncios. +- [5.5. Consulta de Anúncios](5.5-consulta-de-anuncios.md): Requisite à API os anúncios que devem ser exibidos em diferentes páginas e contextos. +- [5.5.1. Recomendação de Nomes de Placements](5.5.1-recomendacao-de-nomes-de-placements.md): Padrão recomendado de nomenclatura de placements para medições precisas. +- [5.6. Eventos](5.6-eventos.md): Notifique a API sobre as interações dos usuários com os anúncios e as conversões. diff --git a/pt/docs/5.1-integracao-via-api.md b/pt/docs/5.1-integracao-via-api.md index d60f292..597f744 100644 --- a/pt/docs/5.1-integracao-via-api.md +++ b/pt/docs/5.1-integracao-via-api.md @@ -6,3 +6,24 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +A integração é fundamentada em três pilares que garantem o funcionamento da solução. + +### Pilares da Integração + +1. **[Sincronização de Catálogo](5.3-sincronizacao-de-catalogo.md):** Manter a VTEX Ads sincronizada com seu catálogo de produtos e inventário (preço e estoque). Essencial para anúncios de produto. +2. **[Consulta de Anúncios](5.5-consulta-de-anuncios.md):** Sua plataforma requisita à API os anúncios que devem ser exibidos em diferentes páginas e contextos. +3. **[Eventos](5.6-eventos.md):** Sua plataforma notifica a API sobre todas as interações do usuário com os anúncios e, crucialmente, sobre as conversões (vendas). + +### Tipos de Anúncios + +| Tipo de Anúncio | API Type | Descrição | +| :--- | :--- |:------------------------------------------------| +| **Sponsored Products** | `product` | Anúncios de produtos individuais. | +| **Display** | `banner` | Anúncios visuais (imagem estática ou vídeo). | +| **Sponsored Brands** | `sponsored_brand` | Anúncios de marca com título, logo e produtos. (imagem estática ou vídeo) | +| **Digital Signage** | `digital_signage`| Conteúdo para telas e totens físicos. | + +### Integração de Audiências + +Direcione anúncios para públicos específicos para aumentar a relevância. Veja mais em [Integração de Audiências](5.4-integracao-de-audiencias.md). diff --git a/pt/docs/5.2-integracao-vtex.md b/pt/docs/5.2-integracao-vtex.md index 86bf2c0..cfdeeed 100644 --- a/pt/docs/5.2-integracao-vtex.md +++ b/pt/docs/5.2-integracao-vtex.md @@ -6,3 +6,35 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +Para lojas na plataforma VTEX, a Newtail oferece um aplicativo de storefront (`Newtail Media APP VTEX`) que simplifica drasticamente a implementação. O app já inclui componentes visuais e toda a lógica para consulta de anúncios e notificação de eventos. + +* **Passo 1: Sincronização do Catálogo** + * A sincronização do catálogo de produtos é um pré-requisito. Ela pode ser feita de duas formas: + 1. **Via API:** Fornecendo à Newtail as chaves de API para leitura do seu catálogo. + 2. **Via XML:** Fornecendo um link para um feed XML no formato do Google Shopping, que deve conter o campo `SKU` para identificação do produto. + +* **Passo 2: Instalação do App** + 1. **Adicionar como Dependência:** No arquivo `manifest.json` do seu tema, adicione `"newtail.media": "0.x"` ao `peerDependencies`. + 2. **Instalar o App:** Execute o comando `vtex install newtail.media@0.x` no seu terminal. + +* **Passo 3: Configuração** + 1. **ID do Publisher:** No admin da sua loja VTEX, acesse `Configurações da Loja > Newtail Media` e insira o seu `Publisher ID` fornecido pela Newtail. + 2. **Política de Conteúdo (CSP):** Adicione as seguintes diretivas ao seu `policies.json`: + ```json + { + "contentSecurityPolicy": { + "default-src": ["'self'", "newtail-media.newtail.com.br"], + "connect-src": ["'self'", "newtail-media.newtail.com.br"] + } + } + ``` + +* **Passo 4: Uso dos Blocos** + * Declare os blocos do app nos templates do seu tema para exibir os anúncios. + + * **Componentes Disponíveis:** + * `newtail-media-banner`: Renderiza banners patrocinados. + * `newtail-media-shelf`: Renderiza uma prateleira de produtos patrocinados. + * `newtail-media-search`: Adiciona selos "Patrocinado" aos produtos nos resultados de busca. + * `newtail-media-conversion`: Componente essencial que gerencia o envio de eventos de conversão. **Deve ser incluído em todas as páginas.** \ No newline at end of file diff --git a/pt/docs/5.3-sincronizacao-de-catalogo.md b/pt/docs/5.3-sincronizacao-de-catalogo.md index ccfb70c..cb68d74 100644 --- a/pt/docs/5.3-sincronizacao-de-catalogo.md +++ b/pt/docs/5.3-sincronizacao-de-catalogo.md @@ -6,3 +6,195 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +O primeiro passo é a sincronização, que ocorre em duas frentes: + +> **Nota para lojas VTEX:** Para lojas na plataforma VTEX, a sincronização do catálogo ocorre de forma transparente, não sendo necessária nenhuma integração adicional para este fim. + +#### **Sincronização de Produtos** +Envio das informações cadastrais dos produtos. Requer autenticação. + +* **Endpoint:** `POST https://api-retail-media.newtail.com.br/product/bulk/products` +* **Limites:** 500 produtos por requisição; 3 requisições simultâneas. + +| Campo | Descrição | Tipo | Obrigatório? | +| :--- | :--- | :--- | :--- | +| `product_sku` | ID/SKU único do produto. | String | Sim | +| `parent_sku` | SKU do produto pai (para variações). | String | Não | +| `name` | Nome do produto. | String | Sim | +| `url` | URL canônica da página do produto. | String | Sim | +| `image_url`| URL da imagem principal do produto. | String | Não | +| `categories` | Lista de categorias. | Array[String] | Sim | +| `brand` | Marca do produto. | String | Não | +| `gtins` | Códigos de barras (EAN). **Obrigatório para campanhas na VTEX Ads Network.**| Array[String] | Não/Sim | +| `tags` | "Etiquetas" para contextualizar buscas. Máx. 10 por SKU, 64 chars por tag. Apenas para campanhas de `product`. | Array[String] | Não | +| `sellers` | Lista de sellers que vendem o produto (em um marketplace). | Array[String] | Não | +| `metadata` | Objeto para informações adicionais (chave-valor). | Object | Não | + +--- + +### **Estruturação de Categorias** + +> **Importante:** O campo `categories` é crucial para a segmentação de campanhas e a organização de produtos. Ele deve ser estruturado de forma hierárquica, representando o caminho completo desde a categoria raiz até a categoria específica do produto. + +O campo `categories` deve ser um array de strings, onde cada string é um nível da árvore de categorias. A hierarquia é construída enviando todas as categorias pai até a mais específica. + +**Exemplo Correto:** + +Para um produto na categoria de perfumes "Para Mulher", o array `categories` deveria ser: + +```json +"categories": [ + "Beleza", + "Fragrâncias", + "Perfume", + "Para Mulher" +] +``` + +Essa estrutura permite que a plataforma entenda o contexto do produto em todos os níveis, do mais amplo ("Beleza") ao mais específico ("Para Mulher"). + +--- + +**Exemplo de Requisição:** + +```bash +curl --location 'https://api-retail-media.newtail.com.br/product/bulk/products' \ +--header 'x-app-id: XXXX' \ +--header 'x-api-key: YYYY' \ +--header 'Content-Type: application/json' \ +--data '[ + { + "product_sku": "allan", + "name": "allan", + "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616", + "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629", + "categories": [ + "Beleza", + "Fragrâncias", + "Perfume", + "Para Mulher" + ], + "brand": "SALVADOR DALÍ", + "profit_margin": null, + "gtins": [ + "3331438450103" + ], + "sellers": [], + "skus": [] + }, + { + "product_sku": "allan2", + "name": "allan2", + "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616", + "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629", + "categories": [ + "Beleza", + "Fragrâncias", + "Perfume", + "Para Mulher" + ], + "brand": "SALVADOR DALÍ", + "profit_margin": null, + "gtins": [ + "3331438450103" + ], + "sellers": [], + "skus": [], + "tags": ["Abart", "Mega Maio"] + } +]' +``` + + +**Exemplo de Resposta com Sucesso:** + +``` +Status: 202 Accepted +Content-Type: application/json + +{ + "messages": [ + "products will be processed soon" + ] +} +``` + +--- + +#### **Sincronização de Inventário** +Envio das informações de preço e estoque dos produtos. Requer autenticação. + +* **Endpoint:** `POST https://api-retail-media.newtail.com.br/product/bulk/inventories` +* **Limites:** 500 produtos por requisição; 3 requisições simultâneas. + +| Campo | Descrição | Tipo | Obrigatório? | +| :--- | :--- | :--- | :--- | +| `product_sku` | ID/SKU único do produto. | String | Sim | +| `price` | Preço atual do produto. | Float | Sim | +| `promotional_price` | Preço "de" (tabelado/original). | Float | Sim | +| `is_available` | Produto disponível (em estoque). | Boolean | Sim | +| `store_id` | Identificação da loja. Caso não seja enviado o store_id, será interpretado que essa informação de inventário será utilizado para todas as lojas. | String | Não | +| `metadata` | Objeto para informações adicionais (chave-valor). | Object | Não | + +**Exemplo de Requisição:** + +```bash +curl --location 'https://api-retail-media.newtail.com.br/product/bulk/inventories' \ +--header 'x-app-id: XXXX' \ +--header 'x-api-key: YYYY' \ +--header 'Content-Type: application/json' \ +--data '[ + { + "product_sku": "120210", + "store_id": "1", + "price": 18.20, + "promotional_price": 16.32, + "is_available": true + }, + { + "product_sku": "120212", + "price": 18.20, + "promotional_price": 0, // Remove o preço promocional + "is_available": true + } +]' +``` + +**Exemplo de Resposta com Sucesso:** + +``` +Status: 202 Accepted +Content-Type: application/json + +{ + "messages": [ + "inventory will be processed soon" + ] +} +``` + +--- + +### **Boas Práticas para Sincronização** + +1. **Sincronização Inicial Completa:** + * Envie todo o catálogo na primeira sincronização. + * Divida em lotes de até 500 produtos para evitar timeouts. + +2. **Atualizações Incrementais:** + * Após a sincronização inicial, envie apenas produtos novos ou alterados. + * Mantenha um registro da última data de modificação de cada produto. + +3. **Frequência de Atualização:** + * Preços e estoque: Atualize pelo menos uma vez ao dia, idealmente em tempo real para mudanças significativas. + * Informações cadastrais: Atualize quando houver alterações. + +4. **Tratamento de Erros:** + * Implemente retentativas com backoff exponencial para falhas temporárias. + * Monitore as respostas da API para identificar problemas persistentes. + +5. **Validação de Dados:** + * Verifique se todos os campos obrigatórios estão preenchidos. + * Garanta que URLs de produtos e imagens sejam válidas e acessíveis. + * Certifique-se de que as categorias seguem a estrutura hierárquica recomendada. \ No newline at end of file diff --git a/pt/docs/5.4-integracao-de-audiencias.md b/pt/docs/5.4-integracao-de-audiencias.md index 16ecb6d..e098d3a 100644 --- a/pt/docs/5.4-integracao-de-audiencias.md +++ b/pt/docs/5.4-integracao-de-audiencias.md @@ -6,3 +6,100 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +> **Nota:** A integração de audiências é opcional, mas altamente recomendada para melhorar a segmentação de campanhas e a relevância dos anúncios. + +A integração de audiências possui uma única forma de integração: **Envio em Lote (Batch)** para o bucket S3 fornecido pela VTEX Ads. + +> **Importante:** A integração via FTP/SFTP está **deprecated** e só deve ser utilizada para implantações legadas. Novos projetos devem usar exclusivamente o bucket S3. + +> **Alerta:** Se não existir integração de audiência, é necessário abrir um ticket junto ao Account Manager solicitando a pré-população das informações de segmentação com dados base (`STATE`, `CITY`, `GENDER` e `AGE`). Também é possível enviar uma lista de audiências para cadastro, e recomendamos manter uma atualização periódica dessas audiências. + +### Envio em Lote (Batch) — Bucket S3 + +A conexão de integração ocorre através do envio periódico das audiências para o bucket S3 dedicado ao publisher. As credenciais de acesso (chave/segredo IAM ou role para cross-account) e o caminho base do bucket devem ser solicitados ao seu contato na Newtail. + +* **Formato do Arquivo:** `Parquet` com compressão `Snappy`. +* **Padrão de Diretório (chave S3):** Suba os arquivos seguindo o padrão: + `s3://<bucket>/<PREFIXO>/audiences/YYYY/mm/dd/TIMESTAMP.parquet.snappy` + +| Atributo | Descrição | Exemplo | +| :-------- | :---------------------------------------------------------------------------------------------------- | :----------- | +| `PREFIXO` | O prefixo será informado pela Newtail. | `xyz` | +| `YYYY` | Ano da geração com 4 dígitos. | `2023` | +| `mm` | Mês da geração com dois dígitos (Janeiro = 01 e dezembro = 12). | `09` | +| `dd` | Dia da geração com dois dígitos (de 01 até 31). | `31` | +| `TIMESTAMP`| Timestamp é a quantidade de segundos desde 1970 (o nome do arquivo pode ser qualquer coisa, o timestamp é apenas uma sugestão que nunca irá se repetir). | `1694812122` | + +> **Recomendação para o envio:** Na integração inicial, é fundamental que todos os dados sejam enviados. E esses dados podem ser enviados em múltiplos arquivos (dependendo do tamanho da base, um bom número é 1 milhão de linhas por arquivo). Após a primeira integração, o ideal é que seja enviado, somente o delta das linhas que tiveram alguma modificação. + +> **Compatibilidade legada:** Se você já estava integrado via SFTP, entre em contato com o time VTEX Ads para planejar a migração para o bucket S3. O fluxo via SFTP deixará de receber novos aprimoramentos e poderá ser descontinuado. + +### Alternativa sem integração prévia (runtime) + +Se você optar por não integrar audiências via batch, ainda é possível utilizar segmentações em runtime enviando os dados no campo `segmentation` da requisição de consulta de anúncios. Consulte a seção [5.5. Consulta de Anúncios](5.5-consulta-de-anuncios.md). + +### Atributos do Arquivo de Audiências + +A maioria dos atributos não são obrigatórios, no entanto, quanto maior for o preenchimento de todas essas informações, a relevância será melhor. + +> As colunas são **case sensitive**. Mantenha o nome das colunas da forma como elas estão sendo apresentadas. + +| Coluna | Tipo | Obrigatório? | Descrição | +| :------------------ | :----- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `CUSTOMER_ID` | String | Sim | Identificador único do cliente. | +| `EMAIL_HASHED` | String | Não | PII baseado no e-mail do cliente. | +| `PHONE_HASHED` | String | Não | PII baseado no telefone principal do cliente. | +| `SOCIAL_ID_HASHED` | String | Não | PII baseado no CPF do cliente. | +| `FIRST_NAME_HASHED` | String | Não | PII baseado no Primeiro Nome do cliente. | +| `LAST_NAME_HASHED` | String | Não | PII baseado no Último nome do cliente. | +| `GENDER` | String | Não | Indica qual o sexo do cliente (`F` para feminino, `M` para masculino, `O` para outros, `NULL` para não identificados). | +| `AGE` | Int | Não | Indica a idade do cliente. | +| `CEP` | String | Não | Indica qual o CEP do endereço do cliente. | +| `COUNTRY` | String | Não | Indica qual o país do usuário. | +| `STATE` | String | Não | Indica o estado onde reside o cliente. | +| `CITY` | String | Não | Indica a cidade onde reside o cliente. | +| `NEIGHBORHOOD` | String | Não | Indica o bairro onde reside o cliente. | +| `AUDIENCES` | String | Não | Uma lista de audiências, separadas por ponto e vírgula (;). | +| `NBO_PRODUCTS` | String | Não | Uma lista de SKU de produtos, separadas por ponto e vírgula (;). | +| `NBO_CATEGORIES` | String | Não | Uma lista de categorias, separadas por ponto e vírgula (;). A lista pode receber uma árvore de categorias usando o " > " como separador (ex: `Tablets;Bebidas > Bebidas Não Alcoólicas;Livros > Gastronomia > Guias de Bares e Restaurantes`). | + +### Hash dos Campos + +Dados confidenciais precisam ser criptografados antes de serem enviados usando o algoritmo **SHA256**. + +* `EMAIL_HASHED` +* `PHONE_HASHED` +* `SOCIAL_ID_HASHED` +* `FIRST_NAME_HASHED` +* `LAST_NAME_HASHED` + +> Antes de gerar o hash dos dados é necessário remover todos os **ESPAÇOS** e converter para **MINÚSCULO** os seus valores. +> Para o atributo `PHONE_HASHED`, será necessário formatá-lo no padrão **E.164** e incluir o código de chamada do país. + +#### Formato E.164 + +1. Remova todos os caracteres não numéricos, como espaços, traços, parênteses e símbolos. +2. Adicione o código do país com o sinal de adição (+) no início. +3. Adicione o código de área (se aplicável) sem o zero inicial. +4. Inclua o número de telefone local sem o zero inicial (caso aplicável). + +**Exemplo:** + +* Um número de telefone do Brasil, com código de área 11 e número local 98765-4321, seria formatado como: `+5511987654321` + +#### Criando um HASH em Python + +```python +import re +import hashlib + +hash_obj = hashlib.sha256() + +def create_hash(x): + cleaned = re.sub('\s+', '', x.lower()) + hash_obj.update(cleaned.encode('utf-8')) + return hash_obj.hexdigest() + +create_hash(' Allan ') #=> 8c01ade3cb71d3ac7c718ed5a0c565155a4c05a216d9e59013c5d7b49e916914 +``` diff --git a/pt/docs/5.5-consulta-de-anuncios.md b/pt/docs/5.5-consulta-de-anuncios.md index 9638118..bd139bf 100644 --- a/pt/docs/5.5-consulta-de-anuncios.md +++ b/pt/docs/5.5-consulta-de-anuncios.md @@ -6,3 +6,397 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +Com o catálogo sincronizado, sua plataforma requisita anúncios para preencher os espaços publicitários (`placements`). A requisição é um `POST` e o `publisher_id` deve ser informado na URL. + +* **Endpoint:** `POST https://newtail-media.newtail.com.br/v1/rma/:publisher_id` +* **Content-Type:** Todas as requisições devem incluir o header `Content-Type: application/json` + +#### Boas Práticas de Requisição + +- **Persistência HTTP:** Prefira conexões persistentes (`Connection: keep-alive`). +- **Timeout:** Aplique timeout de 500–600 ms para a consulta (ver 5.6 para eventos). + +#### **Parâmetros da Requisição** + +| Campo | Descrição | Tipo | Obrigatoriedade | +| :--- | :--- | :--- | :--- | +| `session_id` | Identificador persistente do visitante (≥ 14 dias). Para aplicativos móveis, deve-se enviar o ID do dispositivo como session_id (GAID no Android e IDFA no iOS), de forma que a sessão seja mantida indefinidamente. | String | Sim | +| `user_id` | ID único do usuário logado (alfanumérico). | String | Não (Recomendado) | +| `store_id` | Filtra anúncios por estoque de uma loja específica. | String | Não | +| `channel` | Canal de acesso: `site`, `msite`, `app` (para consulta). | String | Sim | +| `context` | Contexto: `home`, `category`, `search`, `product_page`, `brand_page`, `digital_signage`.| String | Sim | +| `term` | Termo buscado pelo usuário. | String | Apenas `context: 'search'` | +| `category_name` | Categoria navegada (breadcrumb completo).| String | Apenas `context: 'category'`| +| `product_sku` | SKU do produto sendo visualizado. | String | Apenas `context: 'product_page'` | +| `brand_name` | Nome da marca sendo visualizada. | String | Apenas `context: 'brand_page'` | +| `device_id` | ID único do dispositivo (tela, totem). | String | Apenas `context: 'digital_signage'` | +| `store_name` | Nome da loja onde o dispositivo está localizado. | String | Apenas `context: 'digital_signage'` | +| `placements` | Objeto que define os espaços (`placements`) de anúncio. | Object | Sim | +| `placements.{name}.quantity` | Quantidade de anúncios desejada. | Integer | Sim | +| `placements.{name}.size` | Tamanho esperado (Imagem: `desktop`/`mobile`; Vídeo: `1080p`/`720p`/`480p`/`360p`/`320p`). | String | Apenas `types: ['banner', 'sponsored_brand']` | +| `placements.{name}.types` | Tipos permitidos (`product`, `banner`, etc.). | Array[String] | Sim | +| `placements.{name}.assets_type`| Mídias aceitas (`image`, `video`). Padrão: `["image"]`. | Array[String] | Apenas `types: ['banner', 'sponsored_brand']` | +| `placements.{name}.allow_sku_duplications` | Permite retornar o mesmo SKU mais de uma vez dentro do mesmo placement. | Boolean | Não (Default=false) | +| `userAgent` | Identificação do ambiente do cliente (campo no corpo, não o header HTTP `User-Agent`). | String | Não | +| `segmentation` | Dados para segmentação em tempo real. | Array[Object] | Não | +| `segmentation.#.key` | O tipo de segmentação. | String | Não | +| `segmentation.#.values` | Array de valores para a segmentação. | Array[String] | Não | +| `tags` | "Etiquetas" para contextualizar buscas (principalmente em `search`). Máx. 10 por SKU, 64 chars por tag. Apenas para campanhas de `product`. | Array[String] | Não | +| `brand` | Nome do site do publisher. | String | Obrigatório quando o publisher possui mais de um site | +| `dedup_campaign_ads` | Deduplica por campanha (no máximo 1 anúncio por campanha na resposta). | Boolean | Não (Default=false) | +| `dedup_ads` | Deduplica por `ad_id` entre múltiplos placements (use apenas ao consultar múltiplos placements ao mesmo tempo). | Boolean | Não (Default=false) | +| `skus` | Filtra os resultados de anúncios para retornar apenas ads dos SKUs especificados. Compatível apenas com Sponsored Products (campanhas de produto). | Array[String] | Não | + +##### Campos por Contexto + +| Contexto | Campos adicionais obrigatórios | +| :--- | :--- | +| `home` | — | +| `search` | `term` | +| `category` | `category_name` | +| `product_page` | `product_sku` | +| `brand_page` | `brand_name` | +| `digital_signage` | `device_id`, `store_name` | + +#### **⚠️ Regras Importantes de Contexto e Elegibilidade de Anúncios** + +##### Limitações de Filtro + +> **Importante:** Não é possível fazer filtro por `placement` específico. A seleção de anúncios é baseada no `context` e nos parâmetros da requisição. + +##### Elegibilidade por Contexto + +###### Contexto `home` + +No contexto **home**, podem ser retornados: + +- ✅ **Anúncios de Banner/Video/Sponsored Brands** que utilizem **categoria** como critério de segmentação +- ✅ **Anúncios de Produtos (Sponsored Products)** também são elegíveis + +**Exemplo:** +```json +{ + "context": "home", + "placements": { + "site_home_middle_banner": { + "quantity": 3, + "types": ["banner", "sponsored_brand"], + "assets_type": ["image", "video"], + "size": "desktop" + }, + "site_home_vitrine_product": { + "quantity": 10, + "types": ["product"] + } + } +} +``` + +###### Contexto `search` + +No contexto **search**, podem ser retornados: + +- ✅ **Anúncios de Banner/Video/Sponsored Brands** que sejam de **keyword** (palavra-chave) +- ✅ **Qualquer campanha de Produto (Sponsored Products)** + +**⚠️ Match Exato de Keywords:** + +O match de keywords no contexto `search` é **exato** (não há stemming/sinônimos). Isso significa que: + +- O anunciante **precisa especificar exatamente** quais keywords deseja utilizar na campanha de Banner/Video/Sponsored Brands +- Se o usuário buscar "tênis nike", o anúncio só será elegível se o anunciante cadastrou exatamente a keyword "tênis nike" +- Não há correspondência aproximada ou por palavras semelhantes + +**Exemplo:** +```json +{ + "context": "search", + "term": "tênis nike", + "placements": { + "site_search_top_banner": { + "quantity": 1, + "types": ["banner", "sponsored_brand"], + "assets_type": ["image"], + "size": "desktop" + }, + "site_search_vitrine_product": { + "quantity": 20, + "types": ["product"] + } + } +} +``` + +**Comportamento esperado:** +- **Banner/Sponsored Brand:** Só aparecerá se o anunciante cadastrou a keyword exata "tênis nike" na campanha +- **Sponsored Products:** Produtos relacionados ao termo de busca serão retornados + +###### Contexto `category` + +No contexto **category**, podem ser retornados: + +- ✅ **Anúncios de Banner/Video/Sponsored Brands** que utilizem a **categoria** correspondente +- ✅ **Anúncios de Produtos (Sponsored Products)** da categoria + +**Exemplo:** +```json +{ + "context": "category", + "category_name": "Esportes > Calçados > Tênis", + "placements": { + "site_category_top_banner": { + "quantity": 1, + "types": ["banner", "sponsored_brand"], + "assets_type": ["image", "video"] + } + } +} +``` + +###### Contexto `product_page` + +No contexto **product_page**, podem ser retornados: + +- ✅ **Anúncios de Produtos (Sponsored Products)** relacionados ao produto visualizado + +**Exemplo:** +```json +{ + "context": "product_page", + "product_sku": "12345", + "placements": { + "site_product_recommendation": { + "quantity": 5, + "types": ["product"] + } + } +} +``` + +###### Contexto `brand_page` + +No contexto **brand_page**, podem ser retornados: + +- ✅ **Anúncios de Banner/Video/Sponsored Brands** da marca +- ✅ **Anúncios de Produtos (Sponsored Products)** da marca + +**Exemplo:** +```json +{ + "context": "brand_page", + "brand_name": "Nike", + "placements": { + "site_brand_top_banner": { + "quantity": 1, + "types": ["banner", "sponsored_brand"], + "assets_type": ["image"], + "size": "desktop" + }, + "site_brand_shelf_product": { + "quantity": 12, + "types": ["product"] + } + } +} +``` + +###### Contexto `digital_signage` + +No contexto **digital_signage**, podem ser retornados anúncios para telas/totens físicos. + +**Exemplo:** +```json +{ + "context": "digital_signage", + "device_id": "totem-abc-001", + "store_name": "Loja Paulista", + "placements": { + "totem_home_main_video": { + "quantity": 1, + "types": ["banner"], + "assets_type": ["video"], + "size": "720p" + } + } +} +``` + +#### **Resposta da Consulta** +A resposta é um JSON onde cada chave é um nome de `placement`. A estrutura de cada anúncio na resposta depende do seu tipo. + +##### **Campos Comuns de Resposta para Todos os Tipos de Anúncios** +Estes campos estão presentes em todos os tipos de anúncios: + +| Campo | Descrição | +| :--- | :--- | +| `{placementName}.#.ad_id` | ID único do anúncio. | +| `{placementName}.#.type` | Tipo do anúncio (`product`, `banner`, `sponsored_brand`, `digital_signage`). | +| `{placementName}.#.click_url`| **URL para notificar o evento de clique.** | +| `{placementName}.#.impression_url`| **URL para notificar o evento de impressão.**| +| `{placementName}.#.view_url` | **URL para notificar o evento de visualização.** | +| `{placementName}.#.seller_id` | ID do vendedor do produto anunciado (opcional). | + +##### **Campos de Resposta Específicos por Tipo** + +###### **Anúncios de Produto** +Campos adicionais para anúncios do tipo `product`: + +| Campo | Descrição | +| :--- | :--- | +| `{placementName}.#.product_sku`| SKU do produto anunciado. | + +###### **Anúncios de Banner** +Campos adicionais para anúncios do tipo `banner`: + +| Campo | Descrição | +| :--- | :--- | +| `{placementName}.#.media_url`| URL da imagem ou vídeo a ser exibido. | + +###### **Anúncios de Marca Patrocinada** +Campos adicionais para anúncios do tipo `sponsored_brand`: + +| Campo | Descrição | +| :--- | :--- | +| `{placementName}.#.media_url`| URL da imagem ou vídeo a ser exibido. | +| `{placementName}.#.products`| Array de produtos associados à marca patrocinada. | +| `{placementName}.#.products.#.product_sku`| SKU do produto associado. | +| `{placementName}.#.products.#.media_url`| URL da imagem do produto. | + +###### **Anúncios de Digital Signage** +Campos adicionais para anúncios do tipo `digital_signage`: + +| Campo | Descrição | +| :--- | :--- | +| `{placementName}.#.media_url`| URL da imagem ou vídeo a ser exibido. | +| `{placementName}.#.duration`| Duração da exibição do anúncio em segundos. | + +##### Exemplo de Resposta (multi-placement) + +```json +{ + "site_home_middle_banner": [ + { + "ad_id": "ad-001", + "type": "banner", + "media_url": "https://cdn.example.com/banner1.jpg", + "impression_url": "https://events.../impression/abc", + "view_url": "https://events.../view/abc", + "click_url": "https://events.../click/abc" + } + ], + "site_home_vitrine_product": [ + { + "ad_id": "ad-101", + "type": "product", + "product_sku": "SKU-123", + "seller_id": "SELLER-9", + "impression_url": "https://events.../impression/def", + "view_url": "https://events.../view/def", + "click_url": "https://events.../click/def" + } + ] +} +``` + +### Boas Práticas + +#### Nomenclatura de Placements + +Adote um padrão claro, como `{canal}_{contexto}_{posicao}_{tipo}` (ex: `msite_search_top-shelf_product`). Para recomendações detalhadas, consulte `pt/docs/5.5.1-recomendacao-de-nomes-de-placements.md`. + +| canal | contexto | posição | tipo | exemplo | +| --- | --- | --- | --- | --- | +| site | home | middle | banner | site_home_middle_banner | +| msite | product | top-vitrine | product | msite_product_top-vitrine_product | +| app | search | top-vitrine | product | app_search_top-vitrine_product | +| app | search | top-vitrine | banner | app_search_top-vitrine_banner | +| site | category | bottom-vitrine | banner | site_category_bottom-vitrine_banner | +| site | product | filter-bar | product | site_product_filter-bar_product | + +#### Tamanhos de Imagem Padrão IAB + +Para anúncios do tipo banner, é importante utilizar imagens nos formatos padrão definidos pelo IAB (Interactive Advertising Bureau). Isso garante a compatibilidade e uma melhor experiência visual em diferentes sites e dispositivos. + +**Formatos Principais:** + +* **Retângulo Médio:** 300x250 pixels +* **Leaderboard:** 728x90 pixels +* **Skyscraper Largo:** 160x600 pixels +* **Leaderboard Móvel:** 320x50 pixels +* **Billboard:** 970x250 pixels +* **Meia Página:** 300x600 pixels + +#### Opções de Tamanho para Vídeos + +Para solicitações de anúncios de vídeo, você deve especificar o parâmetro de tamanho para filtrar por resolução de vídeo. As opções disponíveis são: + +* **1080p** (1920x1080 pixels) - Recomendado apenas para vídeos em tela cheia +* **720p** (1280x720 pixels) - Recomendado apenas para vídeos em tela cheia +* **480p** (854x480 pixels) +* **360p** (640x360 pixels) +* **320p** (568x320 pixels) - Recomendado para dispositivos móveis + +**Importante:** Ao solicitar anúncios de vídeo, use apenas o identificador de resolução (ex: `"720p"`) no parâmetro size, não as dimensões completas. Por exemplo, para filtrar por resolução 1280x720, use `"size": "720p"` na sua solicitação de anúncio. + +### Segmentação de Anúncios + +Direcione anúncios para públicos específicos para aumentar a relevância. + +#### **Segmentação em Tempo Real** +Envie dados demográficos ou de audiência diretamente no corpo da **consulta de anúncios**, no campo `segmentation`. + +O campo `segmentation` é um array de objetos, onde cada objeto contém: +- `key`: O tipo de segmentação (ex: "STATE", "CITY", "GENDER") +- `values`: Array de valores para a segmentação + +**Exemplo de Segmentação:** + +```json +[ + { + "key": "STATE", + "values": [ + "RJ" + ] + }, + { + "key": "CITY", + "values": [ + "Rio de Janeiro" + ] + } +] +``` + +**Tipos de Segmentação Disponíveis:** + +| Chave (key) | Descrição | Exemplo de Valores | +| :--- | :--- | :--- | +| `STATE` | Estado do usuário | "SP", "RJ", "MG" | +| `CITY` | Cidade do usuário | "São Paulo", "Rio de Janeiro" | +| `GENDER` | Gênero do usuário | "M", "F" | +| `AGE` | Idade do usuário | "22", "35" | +| `AUDIENCES` | Audiência personalizada | "high_value_customers", "cart_abandoners" | +| `NBO_CATEGORIES` | Indica quais as possíveis categorias que o usuário tem intenção de comprar | "Eletrônicos", "Livros" | + +### Códigos de Resposta e Erros + +- **200 OK:** Consulta processada com sucesso (retorna JSON por placement). +- **422 Unprocessable Entity:** Erro de validação de campos (formato compatível com JSON Schema/Ajv). +- **400 Bad Request / 404 Not Found:** Requisição inválida ou recurso inexistente. +- **429 Too Many Requests:** Limite de requisições excedido. +- **5xx:** Erros internos. + +Exemplo de 422 (parcial): +```json +[ + { + "instancePath": "/context", + "keyword": "enum", + "message": "must be equal to one of the allowed values", + "params": {"allowedValues": ["home","category","search","product_page","brand_page","digital_signage"]}, + "schemaPath": "#/properties/context/enum" + } +] +``` diff --git a/pt/docs/5.5.1-recomendacao-de-nomes-de-placements.md b/pt/docs/5.5.1-recomendacao-de-nomes-de-placements.md index a0d76b3..db14b18 100644 --- a/pt/docs/5.5.1-recomendacao-de-nomes-de-placements.md +++ b/pt/docs/5.5.1-recomendacao-de-nomes-de-placements.md @@ -6,3 +6,35 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +Ter nomes padronizados e claros para os placements é essencial para medir corretamente o desempenho de cada área de anúncios do site/app, facilitar análises e acelerar diagnósticos. + +Modelo recomendado de nomenclatura: + +``` +{meio}_{contexto}_{posicao}_{tipo} +``` + +Onde: +- meio: canal de acesso, ex.: site, msite (site móvel), app +- contexto: página/região de navegação, ex.: home, category, search, product, brand_page, digital_signage +- posicao: localização do bloco na página, ex.: top-vitrine, middle, bottom-vitrine, filter-bar +- tipo: tipo de criativo, ex.: product, banner, sponsored_brand + +Boas práticas: +- Use letras minúsculas e sem espaços (use hífen para compostos, ex.: top-vitrine). +- Evite abreviações obscuras; mantenha consistência entre páginas e canais. +- O nome deve ser estável ao longo do tempo (não inclua datas, campanhas, etc.). + +Exemplos: + +| meio | contexto | posição | tipo | exemplo | +| --- | --- | --- | --- | --- | +| site | home | middle | banner | site_home_middle_banner | +| msite | product | top-vitrine | product | msite_product_top-vitrine_product | +| app | search | top-vitrine | product | app_search_top-vitrine_product | +| app | search | top-vitrine | banner | app_search_top-vitrine_banner | +| site | category | bottom-vitrine | banner | site_category_bottom-vitrine_banner | +| site | product | filter-bar | product | site_product_filter-bar_product | + +Observação: utilize os mesmos termos de canal e contexto que você envia na Consulta de Anúncios (5.5) para manter a rastreabilidade entre requisições e relatórios. \ No newline at end of file diff --git a/pt/docs/5.6-eventos.md b/pt/docs/5.6-eventos.md index ca8a8bc..8f479fb 100644 --- a/pt/docs/5.6-eventos.md +++ b/pt/docs/5.6-eventos.md @@ -6,3 +6,367 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +A notificação de eventos é **crucial** para a atribuição e mensuração. + +#### Boas Práticas + +* **Persistência HTTP:** Use conexões HTTP persistentes (`Connection: keep-alive` no header) para otimizar a performance. +* **Timeout (consulta de anúncios):** Para chamadas de consulta de anúncios (ver seção 5.5), implemente um timeout de 500–600 ms para não prejudicar a experiência do usuário. + +#### **Identificação de Usuário e Sessão** + +* **`session_id`:** Identificador persistente do visitante. Obrigatório em todos os eventos. Deve ser consistente durante a navegação e entre sessões dentro da janela de conversão (≥ 14 dias). O `session_id` deve ser único por usuário e, idealmente, não expirar nesse período. Para aplicativos móveis, deve-se enviar o ID do dispositivo como session_id (GAID no Android e IDFA no iOS), de forma que a sessão seja mantida indefinidamente. +* **`user_id`:** ID único do cliente na plataforma, consistente entre canais. **Obrigatório na conversão**. **Opcional (recomendado)** para impressão, visualização e clique. O `user_id` deve ser o mesmo entre app, website e loja física. + +Após identificar o usuário e a sessão, siga estas diretrizes para o disparo de eventos: + +* **Impressão (`impression_url`):** Dispare o evento imediatamente após decidir exibir os anúncios retornados pelo ad server, mesmo que o Anúncio acabe não sendo exibido ao usuário (por exemplo, devido a bloqueios ou mudanças de layout). +* **Visualização (`view_url`):** Dispare o evento quando pelo menos 50% do Anúncio permanecer dentro do viewport do usuário por 1 segundo contínuo. +* **Clique (`click_url`):** Dispare o evento sempre que o usuário clicar no Anúncio. + +Não é necessário manter o estado dos eventos entre carregamentos de página, mas garanta que cada evento seja enviado apenas uma única vez para o mesmo Anúncio e contexto. + +#### **Notificação de Impressão, Visualização e Clique** + +Envie uma requisição `POST` para a respectiva URL de evento (`impression_url`, `view_url`, `click_url`) fornecida na consulta de anúncios, com um corpo JSON contendo `session_id` (**obrigatório**) e `user_id` (**quando disponível**). + +* **Quando enviar:** `impression_url` quando o Anúncio for renderizado; `view_url` quando o Anúncio estiver visível (se você medir viewability); `click_url` no clique do usuário. +* **URLs de eventos:** sempre use as URLs retornadas pela consulta de anúncios; não as derive manualmente. +* **Content-Type:** Todas as requisições devem incluir o header `Content-Type: application/json` +* **Método Obrigatório (Navegador):** É **obrigatório** usar `navigator.sendBeacon()` para garantir o envio assíncrono sem bloquear a navegação e evitar a perda de eventos quando o usuário navega para outra página ou fecha o navegador. +* **Resposta de Sucesso:** `HTTP 202 Accepted`. + +Veja exemplos de envio no navegador em `examples/EVENTS_IMPRESSIONS_VIEWS_CLICKS_BROWSER.md`. + +**Exemplo de envio de evento usando Beacon API:** + +```javascript +// Função para enviar evento de impressão +function sendImpressionEvent(impressionUrl, userId, sessionId) { + // Dados do evento + const eventData = { + user_id: userId, + session_id: sessionId + }; + + // Verifica se o navegador suporta a Beacon API + if (navigator.sendBeacon) { + // Converte os dados para JSON + const blob = new Blob([JSON.stringify(eventData)], {type: 'application/json'}); + + // Envia o evento de forma assíncrona + const success = navigator.sendBeacon(impressionUrl, blob); + + if (!success) { + console.error('Falha ao enviar evento via Beacon API'); + // Implementar fallback se necessário + } + } else { + // Fallback para navegadores que não suportam Beacon API + const xhr = new XMLHttpRequest(); + xhr.open('POST', impressionUrl, true); // true para assíncrono + xhr.setRequestHeader('Content-Type', 'application/json'); + xhr.send(JSON.stringify(eventData)); + } +} + +// Exemplo de uso +sendImpressionEvent( + 'https://events.newtail-media.newtail.com.br/v1/beacon/impression/123456', + 'user-123', + 'session-456' +); +``` + +> **Importante:** O uso da Beacon API é obrigatório para garantir que os eventos sejam enviados mesmo quando o usuário navega para outra página ou fecha o navegador. Isso evita a perda de eventos e garante uma medição mais precisa. + +#### **Notificação de Conversão** + +Quando uma compra é finalizada, envie os dados do pedido. + +* **Endpoint:** `POST https://events.newtail-media.newtail.com.br/v1/beacon/conversion` +* **Content-Type:** Todas as requisições devem incluir o header `Content-Type: application/json` +* **Corpo da Requisição:** O objeto deve conter os dados do pedido. O preço do item não deve ser multiplicado pela quantidade. + +Veja exemplos de conversão em `examples/EVENTS_CONVERSION_BROWSER.md` (Browser) e `examples/EVENTS_CONVERSION_CURL.md` (cURL). + +| Campo do Pedido | Descrição | Tipo | Obrigatório? | +| :--- | :--- | :--- | :--- | +| `publisher_id` | ID do publisher. | String | Sim | +| `user_id` | ID do usuário que realizou a compra. | String | Sim | +| `session_id` | ID da sessão da compra. | String | Sim | +| `order_id` | ID do pedido. | String | Sim | +| `created_at` | Data/hora do pedido (ISO 8601 em UTC). | String | Sim | +| `items` | Lista de itens do pedido. | Array[Item] | Sim | +| `channel` | Canal de venda (ex.: ecommerce, app, loja física). | String | Sim | +| `brand` | Marca/site onde ocorreu a venda (necessário quando existe mais de um site). | String | Não/Sim | +| `gender` | Indica qual o sexo do cliente. F: para feminino, M: para masculino, O: para outros, null: para não identificados. | String | Não (Recomendado) | +| `uf` | Indica o estado da compra do pedido. | String | Não (Recomendado) | +| `city` | Indica qual o nome da cidade o cliente comprou. | String | Não (Recomendado) | +| `is_company` | Indica se a venda foi feita para pessoa física ou jurídica. | Boolean | Não (Recomendado) | +| `email_hashed` | E-mail do usuário em formato hash (SHA256). | String | Sim | +| `phone_hashed`| Telefone do usuário em hash (SHA256). | String | Não (Recomendado) | +| `social_id_hashed`| CPF/CNPJ do usuário em hash (SHA256). | String | Não (Recomendado) | +| `first_name_hashed` | Identificação do Primeiro Nome do usuário (hash). | String | Não (Recomendado) | +| `last_name_hashed` | Identificação do Último Nome do usuário (hash). | String | Não (Recomendado) | + +> Normalização recomendada para hashing: +> - `email_hashed`: e-mail em lowercase e trim, sem espaços extras; hash SHA-256 em hexadecimal. +> - `phone_hashed`: telefone em formato E.164 (ex.: +5511999999999), sem máscaras; hash SHA-256 em hexadecimal. +> - `social_id_hashed`: CPF/CNPJ somente dígitos (sem pontos/traços); hash SHA-256 em hexadecimal. +> - `first_name_hashed` / `last_name_hashed`: nomes normalizados (trim, sem espaços duplos); hash SHA-256 em hexadecimal. + +#### **Estrutura dos Itens do Pedido** + +##### Campos do Objeto Item + +| Campo | Descrição | Tipo | Obrigatoriedade | +|-------|-----------|------|-----------------| +| `sku` | Identificação única do SKU do produto | String | **Obrigatório** | +| `quantity` | Quantidade comprada do produto | Double | **Obrigatório** | +| `price` | Preço original do produto (preço "de") | Double | **Obrigatório** | +| `promotional_price` | Preço promocional do produto (preço "por") | Double | **Obrigatório** | +| `seller_id` | Identificação do vendedor/seller | String | Opcional | +| `product_id` | Identificação única do produto que engloba o SKU | String | Opcional | + +##### ⚠️ Observações Importantes + +1. **Valores unitários**: Os campos `price` e `promotional_price` devem conter o valor **unitário** do produto, **não** multiplicado pela quantidade +2. **Campos obrigatórios para mensuração**: Se `price` e `promotional_price` não forem informados corretamente, a conversão **não poderá ser mensurada** +3. **Formato monetário**: Valores devem ser enviados como números decimais (ex: 1899.00) + +#### **Exemplos de Utilização** + +##### Exemplo de Item Individual +```json +{ + "sku": "12221", + "seller_id": "1234", + "product_id": "4567", + "quantity": 1, + "price": 2000.00, + "promotional_price": 1899.00 +} +``` + +##### Exemplo de Requisição Completa + +```http +POST https://events.newtail-media.newtail.com.br/v1/beacon/conversion HTTP/1.1 +Accept: application/json +Content-Type: application/json +``` + +```json +{ + "channel": "ecommerce", + "publisher_id": "xxx", + "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", + "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", + "order_id": "123", + "email_hashed": "xyz", + "items": [ + { + "sku": "12221", + "seller_id": "1234", + "product_id": "4567", + "quantity": 1, + "price": 2000.00, + "promotional_price": 1899.00 + }, + { + "sku": "12222", + "seller_id": null, + "product_id": "4568", + "quantity": 2, + "price": 500.00, + "promotional_price": 400.00 + } + ], + "created_at": "2023-01-01T09:20:00Z" +} +``` + +**Nota**: No exemplo acima, observe que: +- O primeiro item tem quantidade 1 com preço unitário de R$ 2.000,00 +- O segundo item tem quantidade 2 com preço unitário de R$ 500,00 (não R$ 1.000,00) + +#### **Respostas da API** + +##### ✅ Resposta de Sucesso (HTTP 202) +```json +{ + "messages": [ + "conversion will be processed soon" + ] +} +``` + +##### ❌ Resposta de Erro de Validação (HTTP 422) +A API retorna erros de validação em um formato compatível com JSON Schema (semântica similar ao Ajv). + +Exemplo de resposta com erros: +```json +[ + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'user_id'", + "params": { + "missingProperty": "user_id" + }, + "schemaPath": "#/required" + }, + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'order_id'", + "params": { + "missingProperty": "order_id" + }, + "schemaPath": "#/required" + }, + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'publisher_id'", + "params": { + "missingProperty": "publisher_id" + }, + "schemaPath": "#/required" + }, + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'items'", + "params": { + "missingProperty": "items" + }, + "schemaPath": "#/required" + }, + { + "instancePath": "", + "keyword": "required", + "message": "must have required property 'created_at'", + "params": { + "missingProperty": "created_at" + }, + "schemaPath": "#/required" + } +] +``` + +#### **🎯 Regra de Match de Produtos para Conversões** + +##### Importante: Correspondência entre Produto e Campanha + +As conversões **só são computadas** para campanhas quando ocorre um **match de produto**. Isso significa que: + +- ✅ **Conversão é mensurada**: Quando o produto comprado pelo usuário **pertence** à campanha em que o usuário foi impactado +- ❌ **Conversão NÃO é mensurada**: Quando o produto comprado **não pertence** à campanha em que o usuário foi impactado + +##### Exemplo Prático: + +**Cenário 1 - Com Match (Conversão Computada)** +- Usuário visualizou anúncio da Campanha A (produtos: SKU-001, SKU-002, SKU-003) +- Usuário comprou produto SKU-002 +- ✅ Conversão é atribuída à Campanha A + +**Cenário 2 - Sem Match (Conversão NÃO Computada)** +- Usuário visualizou anúncio da Campanha B (produtos: SKU-004, SKU-005) +- Usuário comprou produto SKU-999 +- ❌ Conversão NÃO é atribuída à Campanha B + +#### **Exemplo de Código** + +##### JavaScript (Browser) +```javascript +const enviarConversao = async (dadosPedido) => { + const payload = { + channel: "ecommerce", + publisher_id: "xxx", + user_id: dadosPedido.userId, + session_id: dadosPedido.sessionId, + order_id: dadosPedido.orderId, + email_hashed: dadosPedido.emailHash, + items: dadosPedido.items.map(item => ({ + sku: item.sku, + seller_id: item.sellerId || null, + product_id: item.productId || null, + quantity: item.quantity, + price: item.unitPrice, // Valor unitário, não multiplicado + promotional_price: item.unitPromotionalPrice // Valor unitário, não multiplicado + })), + created_at: new Date().toISOString() + }; + + try { + // Converte os dados para JSON + const blob = new Blob([JSON.stringify(payload)], {type: 'application/json'}); + + // Envia o evento de forma assíncrona usando Beacon API + if (navigator.sendBeacon) { + const success = navigator.sendBeacon( + 'https://events.newtail-media.newtail.com.br/v1/beacon/conversion', + blob + ); + + if (success) { + console.log('Conversão enviada com sucesso'); + } else { + console.error('Falha ao enviar conversão via Beacon API'); + } + } else { + // Fallback para navegadores que não suportam Beacon API + const response = await fetch('https://events.newtail-media.newtail.com.br/v1/beacon/conversion', { + method: 'POST', + headers: { + 'Accept': 'application/json', + 'Content-Type': 'application/json' + }, + body: JSON.stringify(payload) + }); + + if (response.status === 202) { + console.log('Conversão enviada com sucesso'); + } else if (response.status === 422) { + const errors = await response.json(); + console.error('Erros de validação:', errors); + } + } + } catch (error) { + console.error('Erro ao enviar conversão:', error); + } +}; + +// Exemplo de uso +const pedido = { + userId: "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", + sessionId: "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", + orderId: "123", + emailHash: "xyz", + items: [ + { + sku: "12221", + sellerId: "1234", + productId: "4567", + quantity: 1, + unitPrice: 2000.00, + unitPromotionalPrice: 1899.00 + } + ] +}; + +enviarConversao(pedido); +``` + +#### **Regras de Atribuição e Deduplicação** + +* **Janela de Conversão:** Período após uma interação em que uma venda pode ser atribuída ao anúncio. + * **Click (para `product`):** 14 dias. + * **Visualização (para `display`/`video`):** 14 dias. +* **Deduplicação de Eventos:** Para o mesmo usuário e anúncio, eventos são ignorados por um período. + * **Impressões:** 1 minuto. + * **Cliques:** 1 hora. + * **Conversões:** Idempotentes por `order_id` (reenvios do mesmo `order_id` em até 30 dias são ignorados). diff --git a/pt/docs/5.7-integracao-transparente.md b/pt/docs/5.7-integracao-transparente.md index 77384f2..f1ec8bb 100644 --- a/pt/docs/5.7-integracao-transparente.md +++ b/pt/docs/5.7-integracao-transparente.md @@ -6,3 +6,117 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +> Atenção: Esta ferramenta está apta apenas a servir anúncios do tipo Banner e Vídeo. + +A integração transparente tem o objetivo de reduzir a fricção ao máximo para iniciar a configuração da integração do VTEX Ads de forma mais simples possível. + +## Requisitos para a Prova de Conceito (PoC) + +Para que esta Prova de Conceito funcione, os seguintes requisitos são essenciais: + +1. **Integração de Catálogo:** Uma integração de catálogo precisa estar em funcionamento. + +2. **Instalação do Script:** O nosso script deve ser adicionado ao site. + +3. **Disparo de Evento de Conversão:** O evento de conversão precisa ser disparado pelo lado do cliente. + + +### 1\. Integração do Catálogo + +A sincronização do catálogo segue o formato já definido para todas as integrações. + +### 2\. Instalação do Script + +Adicione o seguinte script o mais cedo possível na tag `<head>` da página ou em seu site/msite: + +``` +<script src="https://cdn.newtail.com.br/retail-media/scripts/vtexads-magic-1.0.0.js"></script> +``` + +#### Requisitos do Script + +Para que o script funcione corretamente, o cliente deve nos informar a origem de dois parâmetros importantes: `session_id` e `user_id`. Esses parâmetros geralmente são armazenados em cookies, `sessionStorage` ou `localStorage`. + +### 3\. Evento de Conversão + +O evento de conversão deve ser enviado após a criação do pedido, sem a necessidade de confirmação de pagamento. + +O script a seguir demonstra como enviar dados para um endpoint de API usando a interface `navigator.sendBeacon`. O método `sendBeacon` é ideal para enviar pequenas quantidades de dados de forma assíncrona, sem impactar o desempenho da página. É particularmente útil para enviar dados de analytics antes que o usuário saia da página. + +``` +/** + * Este script demonstra como enviar dados para um endpoint de API + * usando a interface `navigator.sendBeacon`. + * + * O método `sendBeacon` é projetado para enviar pequenas quantidades de dados + * de forma assíncrona, sem afetar o desempenho da página atual + * ou o tempo de carregamento da próxima. + * + * É particularmente útil para enviar dados de analytics antes que + * um usuário saia de uma página. + */ + +// 1. Defina os dados que você deseja enviar. +const data = { + "publisher_id": "d4dff0cb-1f21-4a96-9acf-d9426a5ed08c", + "user_id": "26119121", + "order_id": "1758035060", + "channel": "site|msite|app", + "created_at": "2025-09-16T15:04:19.794Z", + "items": [ + { + "price": 12, + "promotional_price": 10, + "quantity": 1, + "sku": "sku1" + }, + { + "price": 15, + "promotional_price": 13, + "quantity": 1, + "sku": "sku2", + "seller_id": "seller1" + }, + { + "price": 19, + "promotional_price": 17, + "quantity": 1, + "sku": "sku3", + "product_id": "prod3" + }, + { + "price": 30, + "promotional_price": 25, + "quantity": 2, + "sku": "sku4", + "product_id": "prod4", + "seller_id": "seller2" + } + ] +}; + +// 2. Converta o objeto de dados em uma string JSON. +const rawData = JSON.stringify(data); + +// 3. Crie um Blob a partir da string JSON. +// Isso nos permite definir explicitamente o Content-Type para a requisição. +const blob = new Blob([rawData], { type: 'application/json' }); + +// 4. Defina a URL do endpoint. +const url = "https://newtail-media.newtail.com.br/v1/beacon/conversion"; + +// 5. Use `navigator.sendBeacon` para enviar os dados. +// O método retorna `true` se o navegador enfileirar a solicitação +// para entrega e `false` caso contrário. +// Note que `sendBeacon` não retorna uma promessa (Promise), então não há +// `.then()` ou `.catch()`. A entrega não é garantida, mas é +// altamente provável. +const success = navigator.sendBeacon(url, blob); + +if (success) { + console.log("Solicitação de beacon enfileirada com sucesso!"); +} else { + console.error("Falha ao enfileirar a solicitação de beacon."); +} +``` diff --git a/pt/docs/6-exportacao-de-dados.md b/pt/docs/6-exportacao-de-dados.md index 37f6432..d83cffb 100644 --- a/pt/docs/6-exportacao-de-dados.md +++ b/pt/docs/6-exportacao-de-dados.md @@ -6,3 +6,63 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +A exportação de dados permite que você receba informações detalhadas sobre eventos e dados agregados de forma sistemática e periódica. A integração ocorre através de uma conexão S3, e os dados são entregues em formatos específicos para cada tipo de exportação. + +### 6.1. Relatórios + +Além da exportação via S3, é possível extrair relatórios via API. As rotas retornam JSON por padrão, mas podem ser exportadas como arquivos XLSX ao incluir o parâmetro `download=true` na query. + +* `GET /report/v2/advertisers`: Informações de anunciantes (visão do publisher) [[Exemplo]](../../examples/EXPORT_ADVERTISER_DATA.md) +* `GET /report/v2/publishers`: Informações do publisher (visão do anunciante) [[Exemplo]](../../examples/EXPORT_PUBLISHER_DATA.md) +* `GET /report/network/publishers`: Publishers da rede (para contas do tipo Rede) [[Exemplo]](../../examples/EXPORT_NETWORK_PUBLISHERS_DATA.md) +* `GET /campaign/v2`: Relatório listagem de campanhas [[Exemplo]](../../examples/EXPORT_CAMPAIGNS_LIST_DATA.md) +* `GET /campaign/:id`: Relatório detalhado da campanha [[Exemplo]](../../examples/EXPORT_CAMPAIGN_DATA.md) +* `GET /report/advertisers/campaigns-detailed`: Relatório detalhado de campanhas mistas para contas de anunciante, incluindo informações de subpublisher em campanhas de rede [[Exemplo]](../../examples/EXPORT_ADVERTISER_CAMPAIGNS_DETAILED_DATA.md) +* `GET /report/advertisers/ads-detailed`: Relatório detalhado de anúncios para contas de anunciante, incluindo quebra por subpublisher em campanhas de rede [[Exemplo]](../../examples/EXPORT_ADVERTISER_ADS_DETAILED_DATA.md) +* `GET /ad/results/v2`: Relatório de anúncios [[Exemplo]](../../examples/EXPORT_ADS_DATA.md) + +### 6.2. Exportação de Dados + +A integração sempre ocorrerá usando uma conexão S3 (ou compatível) que deverá ser disponibilizada pelo receptor dos dados. As credenciais devem ser passadas para o time da Newtail de forma segura. + +A integração é compatível com: + +- **AWS S3:** `Access Key Id` e `Access Key Secret`. +- **Google Cloud Storage:** `Service Account`. +- **Azure Blob Storage**. + +#### Exportação de Eventos + +A exportação de eventos envia dados brutos de interações dos usuários. + +- **Formato:** `PARQUET` com compressão `Snappy`. +- **Frequência:** Diária (dados de D-1). +- **Estrutura de Pastas:** `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.snappy.parquet` +- **De-duplicação:** É garantido que todos os eventos serão enviados, mas não que serão enviados uma única vez. Portanto, os eventos precisam sempre ser de-duplicados usando a `event_id` ou a combinação de `order_id` e `product_sku` para itens de conversão. + +##### Tipos de Eventos + +- **Impressões, Visualizações e Cliques:** + - **Campos:** `event_id` (chave de de-duplicação), `session_id`, `user_id`, `ad_id`, `campaign_id`, `request_id`, `ad_type`, `placement_name`, `context`, `created_at`, `site`. +- **Conversões:** + - **Campos:** `event_id`, `session_id`, `user_id`, `order_id` (chave de de-duplicação), `channel`, `placed_at`, `site`. +- **Itens das Conversões:** + - **Campos:** `event_id`, `session_id`, `user_id`, `order_id` (chave de de-duplicação), `product_sku` (chave de de-duplicação), `ad_id`, `campaign_id`, `request_id`, `ad_size`, `ad_type`, `placement_name`, `context`, `event_created_at`, `price`, `promotional_price`, `quantity`, `total_value`. + +#### Exportação de Dados Agregados + +A exportação de dados agregados envia relatórios consolidados. + +- **Formato:** `CSV` com encoding `UTF-8`, separado por vírgula, e números no formato americano (ponto decimal). +- **Frequência:** Diária (dados de D-1, com o timezone do publisher). +- **Estrutura de Pastas:** `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.csv` + +##### Tipos de Relatórios + +- **Anunciantes:** + - **Campos:** `advertiser`, `advertiser_id`, `seller_id`, `wallet_balance`, `daily_budget`, `currency`. +- **Campanhas:** + - **Campos:** `day`, `name`, `campaign_id`, `campaign_type`, `campaign_status`, `impressions_total`, `clicks_total`, `ctr`, `ad_revenue`, `conversions_total`, `conversion_rate`, `sales_revenue`, `start_date`, `end_date`, `advertiser_id`. +- **Anúncios:** + - **Campos:** `day`, `ad_id`, `campaign_id`, `ad_status`, `ad_media_url`, `cpm`, `cpc`, `impressions_total`, `clicks_total`, `ctr`, `ad_revenue`, `conversions_total`, `conversion_rate`, `sales_revenue`, `product_sku`. diff --git a/pt/docs/7-script-agent.md b/pt/docs/7-script-agent.md index a8ca7aa..fdcec0a 100644 --- a/pt/docs/7-script-agent.md +++ b/pt/docs/7-script-agent.md @@ -6,3 +6,106 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +## 7.1. Objetivo + +Este documento detalha o procedimento para a instalação do script de rastreamento da **VTEX Ads** em todas as páginas de um site (exceto as páginas de checkout) através do Google Tag Manager (GTM). A correta implementação deste script é fundamental para a coleta de dados de navegação que permitem a otimização e o direcionamento de campanhas de Retail Media. + +## 7.2. Dados Coletados + +O script da VTEX Ads foi desenvolvido para coletar exclusivamente dados de navegação não sensíveis, com o objetivo de personalizar a experiência do usuário e otimizar campanhas. + +**Dados Coletados:** + +- **Para campanhas off-site:** + + - `session_id`: Identificador anônimo da sessão de navegação. + + - `ad_id`: Identificador do anúncio que originou o tráfego. + +- **Para segmentação de audiência (Page View):** + + - `session_id`: Identificador anônimo da sessão de navegação. + + - **Informações da Página:** URL, título (`<title>`), e descrição (`<meta name="description">`). + + +> **Importante:** O script **não coleta** nenhuma informação pessoalmente identificável (PII), como nome, e-mail, CPF, telefone, endereço ou dados de pagamento. A coleta de dados está em conformidade com as principais leis de proteção de dados. + +## 7.3. Dados do Script + +O script deve ser carregado de forma assíncrona para não impactar o tempo de carregamento da página. + +- **URL do Script:** `https://cdn.newtail.com.br/retail-media/scripts/vtexrma-agent.1.0.0.js` + + +## 7.4. Passo a Passo para Implementação via Google Tag Manager (GTM) + +Para garantir que o script seja executado o mais cedo possível no carregamento da página, recomendamos o uso do acionador de **Inicialização (Initialization)**. + +### Passo 7.4.1: Criar a Tag de HTML Personalizado + +1. Acesse seu contêiner do GTM e vá para a seção **"Tags"**. + +2. Clique em **"Nova"** para criar uma nova tag. + +3. Dê um nome claro para a tag, por exemplo: **"Custom HTML - VTEX Ads Agent"**. + +4. Clique em **"Configuração da tag"** e selecione o tipo de tag **"HTML personalizado"**. + +5. No campo de HTML, insira o seguinte código: + + ``` + <script type="text/javascript" async src="https://cdn.newtail.com.br/retail-media/scripts/vtexrma-agent.1.0.0.js"></script> + ``` + + +### Passo 7.4.2: Configurar o Acionador Principal + +1. Abaixo da configuração da tag, clique em **"Acionamento"**. + +2. Selecione o acionador **"Initialization - All Pages"** (Inicialização - Todas as Páginas). Este acionador garante que o script seja disparado antes da maioria das outras tags, em todas as páginas. + + +### Passo 7.4.3: Criar e Adicionar uma Exceção de Acionamento + +Para evitar que o script seja executado nas páginas de checkout, criaremos uma exceção. + +1. Ainda na configuração da tag, na seção **"Acionamento"**, clique em **"Adicionar exceção"**. + +2. Clique no ícone de **"+"** no canto superior direito para criar um novo acionador de exceção. + +3. Dê um nome para o acionador, por exemplo: **"Trigger Exception - Checkout Pages"**. + +4. Clique em **"Configuração do acionador"** e escolha o tipo **"Inicialização"**. + +5. Em **"Este acionador é disparado em"**, selecione **"Algumas inicializações"**. + +6. Configure a condição para identificar as páginas de checkout. A condição pode variar dependendo da estrutura da URL do seu site. Exemplos comuns: + + - `Page Path` | `contém` | `/checkout` + + - `Page URL` | `corresponde ao RegEx (sem distinção entre maiúsculas e minúsculas)` | `/checkout/|/orderPlaced/` + +7. Salve o novo acionador de exceção. Ele será automaticamente adicionado à sua tag. + + +### Passo 7.4.4: Salvar e Publicar + +1. Salve a tag recém-criada. + +2. Envie e publique as alterações no seu contêiner do GTM. + + +## 7.5. Configuração da Sessão do Usuário + +Para que a plataforma VTEX Ads possa correlacionar corretamente as interações do usuário, é necessário informar qual é o identificador de sessão utilizado pelo seu e-commerce. + +**Ação Necessária:** + +A equipe responsável pelo e-commerce deve informar à equipe da VTEX Ads qual é o **nome do atributo no `cookie` ou `sessionStorage`** que armazena o ID da sessão do usuário. + +- **Exemplo:** Se o ID da sessão estiver armazenado em um cookie chamado `vtex_session`, essa informação deve ser repassada. + + +Esta configuração permite que o script leia o identificador correto e o associe aos eventos de navegação. \ No newline at end of file diff --git a/pt/docs/8-repasse.md b/pt/docs/8-repasse.md index d0826e3..bdaf093 100644 --- a/pt/docs/8-repasse.md +++ b/pt/docs/8-repasse.md @@ -6,3 +6,75 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +O repasse de créditos é o fluxo que permite ao marketplace transferir créditos de anúncio para seus sellers. Esta documentação detalha os endpoints que o marketplace deve implementar e o webhook que deve consumir para realizar a integração com a VTEXAds. + +<div align="center"> + <img src="../../diagrams/images/pt/credit-transfer.png" alt="Fluxo de Repasse de Créditos" /> +</div> + + * **Endpoints a serem implementados pelo Marketplace (Autenticação: Basic Auth):** + 1. **Consulta de Saldo (`GET /checking_account`)** + * **Objetivo:** Verificar o saldo disponível do seller. + * **Parâmetros (Query):** `seller_id`, `publisher_id` (opcional, utilizado apenas em casos onde uma entidade gerencia múltiplos publishers). + * **Resposta de Sucesso (200 OK):** + ```json + { "total": "1111.00" } + ``` + + 2. **Solicitação de Transferência (`POST /checking_account/transfer`)** + * **Objetivo:** Requisitar a transferência de um valor. + * **Corpo da Requisição:** + ```json + { + "amount": "10.00", + "seller_id": "SELLER_ID", + "publisher_id": "PUBLISHER_ID", + "transfer_identity_id": "uuid" + } + ``` + * **Respostas:** + - **Síncrona (Sucesso):** `201 Created` + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "success" + } + ``` + - **Síncrona (Falha):** `400 Bad Request` + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "failure", + "message": "Motivo da recusa" + } + ``` + - **Assíncrona:** `202 Accepted` + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "processing" + } + ``` + + * **Webhook a ser consumido pelo Marketplace:** + * **Objetivo:** Notificar a VTEXAds sobre o status final da transferência. + * **Endpoint:** `POST https://api-retail-media.newtail.com.br/webhook/marketplace/transfers/:publisher_id` + * **Autenticação:** `x-api-key` e `x-secret-key`. + * **Payload:** + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "success" + } + ``` + ou + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "failure", + "message": "Descrição do problema" + } + ``` + * **Lógica de Retry:** Em caso de falha na chamada do webhook, o marketplace deve realizar novas tentativas. + * **Resposta Esperada:** `204 No Content` \ No newline at end of file diff --git a/pt/docs/9-sso.md b/pt/docs/9-sso.md index f5fbc1c..4bdda9f 100644 --- a/pt/docs/9-sso.md +++ b/pt/docs/9-sso.md @@ -6,3 +6,34 @@ > A documentação da API do VTEX Ads agora faz parte do Portal do Desenvolvedor oficial da VTEX: [VTEX Ads API em developers.vtex.com](https://developers.vtex.com/docs/api-reference/vtex-ads-api). > > Atualize seus favoritos. Esta página não é mais mantida. + +API para login unificado do seller. Ao chamar esta API, a Newtail gera uma URL de redirecionamento que permite ao usuário acessar a plataforma da Newtail sem a necessidade de um novo login. + +* **Endpoint:** `POST /sso/marketplace` +* **Corpo da Requisição:** + +| Campo | Descrição | Tipo | Obrigatório? | +| :--- | :--- | :--- | :--- | +| `sso_token` | Token de identificação do usuário gerado pelo marketplace. | String | Sim | +| `email` | E-mail do usuário (seller). | String | Sim | +| `user_id` | ID único do usuário no marketplace. | String | Sim | +| `name` | Nome do usuário. | String | Sim | +| `marketplace_name` | Nome do marketplace. | String | Sim | + +* **Exemplo de Requisição:** + ```json + { + "sso_token": "token-sso-12345", + "email": "seller@exemplo.com", + "user_id": "seller123", + "name": "Nome do Seller", + "marketplace_name": "Meu Marketplace" + } + ``` + +* **Resposta de Sucesso:** `HTTP 200 OK` com a URL de redirecionamento. + ```json + { + "redirect_url": "https://app.ads.vtex.com/sso/auth?token=TOKEN_GERADO" + } + ``` \ No newline at end of file