diff --git a/docs/guides/Subscriptions/enabling-manual-prices-for-subscriptions-v3.md b/docs/guides/Subscriptions/enabling-manual-prices-for-subscriptions-v3.md index 999b1affa1..4a0d187319 100644 --- a/docs/guides/Subscriptions/enabling-manual-prices-for-subscriptions-v3.md +++ b/docs/guides/Subscriptions/enabling-manual-prices-for-subscriptions-v3.md @@ -79,7 +79,7 @@ You can manually modify the price when: Read the following sections for details on the endpoints you must use and their request body examples. -> 🚧 You can only apply a manual price to a subscription item if the `manualPriceAllowed` configuration is set to `true`, as described in the [Configuration](#configuration) section. +> ⚠️ You can only apply a manual price to a subscription item if the `manualPriceAllowed` configuration is set to `true`, as described in the [Configuration](#configuration) section. ### Adding an item to a subscription diff --git a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/ads-events-notification.md b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/ads-events-notification.md index f9991f0b6b..c0a2759c62 100644 --- a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/ads-events-notification.md +++ b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/ads-events-notification.md @@ -12,7 +12,7 @@ This guide explains how to send event notifications to VTEX Ads. You can send ev - Through a web browser using the `sendBeacon()` API - Server-side or through native apps using REST endpoints -> 🚧 Don't construct event URLs manually. Always use the URL provided from the `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) request. +> ⚠️ Don't construct event URLs manually. Always use the URL provided from the `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) request. > > This is extremely important to ensure long-term stability of the integration, because the parameters of the event URL may change over time, but the integration itself does not. diff --git a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/clicks.md b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/clicks.md index 80ecb5bbca..72e5759c3c 100644 --- a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/clicks.md +++ b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/clicks.md @@ -16,7 +16,7 @@ Click tracking is essential for measuring ad performance in VTEX Ads. This guide - Click events require both `user_id` and `session_id` for proper attribution. - Click URLs are unique to each ad and should be obtained from the [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) response. -> 🚧 Don't construct event URLs manually. Always use the URL provided from the `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) request. +> ⚠️ Don't construct event URLs manually. Always use the URL provided from the `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) request. > > This is extremely important to ensure long-term stability of the integration, because the parameters of the event URL may change over time, but the integration itself does not. diff --git a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/conversion.md b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/conversion.md index e9a85df038..46a90a3d65 100644 --- a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/conversion.md +++ b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/conversion.md @@ -17,7 +17,7 @@ Conversion tracking is crucial for measuring ad campaign effectiveness in VTEX A - Prices must be sent per unit. Don't multiply the `price` or `promotional_price` by the `quantity`. - All customer identifiers (email, phone, etc.) must be hashed for privacy. -> 🚧 Don't construct event URLs manually. Always use the URL provided from the `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) request. +> ⚠️ Don't construct event URLs manually. Always use the URL provided from the `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) request. > > This is extremely important to ensure long-term stability of the integration, because the parameters of the event URL may change over time, but the integration itself does not. diff --git a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/impressions.md b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/impressions.md index 51d2a283cb..4d127070d2 100644 --- a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/impressions.md +++ b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/impressions.md @@ -16,7 +16,7 @@ Impression tracking is fundamental for measuring ad visibility in VTEX Ads. This - Impression events require both `user_id` and `session_id` for proper attribution. - Impression URLs are unique to each ad and should be obtained from the [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) response. -> 🚧 Don't construct event URLs manually. Always use the URL provided from the `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) request. +> ⚠️ Don't construct event URLs manually. Always use the URL provided from the `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) request. > > This is extremely important to ensure long-term stability of the integration, because the parameters of the event URL may change over time, but the integration itself does not. diff --git a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/views.md b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/views.md index a7aa6d9106..ba50119e99 100644 --- a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/views.md +++ b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/ads-events/views.md @@ -15,7 +15,7 @@ VTEX Ads uses view tracking to measure when banner advertisements are effectivel - View events require both `user_id` and `session_id` for proper attribution. - View URLs are unique to each ad and should be obtained from the [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) response. -> 🚧 Don't construct event URLs manually. Always use the URL provided from the `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) request. +> ⚠️ Don't construct event URLs manually. Always use the URL provided from the `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-) request. > > This is extremely important to ensure long-term stability of the integration, because the parameters of the event URL may change over time, but the integration itself does not. diff --git a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/retrieving-ads.md b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/retrieving-ads.md index fde9bb9b2f..e7f7d63324 100644 --- a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/retrieving-ads.md +++ b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/retrieving-ads.md @@ -146,7 +146,7 @@ The response is a dictionary where: Sponsored brands campaigns have a different response format that includes brand information and related products. -> 🚧 All events must be triggered for both the ad and its products. +> ⚠️ All events must be triggered for both the ad and its products. Request example: diff --git a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/retrieving-ads/digital-signage.md b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/retrieving-ads/digital-signage.md index 2db9940f07..585995de67 100644 --- a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/retrieving-ads/digital-signage.md +++ b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/retrieving-ads/digital-signage.md @@ -13,7 +13,7 @@ The Digital Signage integration uses the `POST` [Get ads](https://developers.vte All ads that should be displayed will be returned. Once all ads have been displayed, the API must be called again to retrieve the next batch of items to be shown. ->🚧 Don't display the same items twice, as display metrics will only be counted once. +> ⚠️ Don't display the same items twice, as display metrics will only be counted once. Request example: @@ -60,7 +60,7 @@ In some cases, it is possible to identify the user making a purchase, typically Once the user is identified, you can request a personalized ad for that user. ->🚧 For segmented campaigns, an audience integration is required. +> ⚠️ For segmented campaigns, an audience integration is required. Request example: diff --git a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/retrieving-ads/segmenting-campaigns.md b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/retrieving-ads/segmenting-campaigns.md index 3c126b56a8..206eee96c0 100644 --- a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/retrieving-ads/segmenting-campaigns.md +++ b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/retrieving-ads/segmenting-campaigns.md @@ -9,7 +9,7 @@ updatedAt: "2025-05-21T22:18:24.684Z" Campaign targeting allows meta-information to be provided during an ad query, which can be used in real time to prioritize campaigns aimed at that specific audience. -> 🚧 Campaigns with targeting will have higher priority during the query process, meaning they are considered more relevant to the audience they were directed to. However, the presence of targeting does not prevent non-targeted campaigns from also being displayed. +> ⚠️ Campaigns with targeting will have higher priority during the query process, meaning they are considered more relevant to the audience they were directed to. However, the presence of targeting does not prevent non-targeted campaigns from also being displayed. ## Targeting attributes @@ -56,7 +56,7 @@ Content-Type: application/json In this approach, targeting information is obtained based on the audiences associated with the `user_id`. These audiences must have been previously imported into the system. -> 🚧 When using this approach, don't send data in the `segmentation` field, since this field would take priority over `user_id`. The system will automatically fetch the audiences associated with the `user_id`. +> ⚠️ When using this approach, don't send data in the `segmentation` field, since this field would take priority over `user_id`. The system will automatically fetch the audiences associated with the `user_id`. Request example: diff --git a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/synchronizing-the-catalog-with-vtex-ads/synchronizing-inventory-information.md b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/synchronizing-the-catalog-with-vtex-ads/synchronizing-inventory-information.md index a85f75ab7a..e62f345348 100644 --- a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/synchronizing-the-catalog-with-vtex-ads/synchronizing-inventory-information.md +++ b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/synchronizing-the-catalog-with-vtex-ads/synchronizing-inventory-information.md @@ -11,7 +11,7 @@ Inventory information defines the price, promotional price, and "stock." Regardi Learn more about each field on `POST` [Synchronize inventory information](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/product/bulk/inventories). -> 🚧 Batch Insert / Update +> ⚠️ Batch Insert / Update > > For each batch insert/update, a maximum of 500 objects per request and 3 simultaneous requests are allowed. > diff --git a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/synchronizing-the-catalog-with-vtex-ads/synchronizing-product-information.md b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/synchronizing-the-catalog-with-vtex-ads/synchronizing-product-information.md index 5d8a5ff798..b8542384c9 100644 --- a/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/synchronizing-the-catalog-with-vtex-ads/synchronizing-product-information.md +++ b/docs/guides/VTEX Ads/getting-started-with-vtex-ads-api/synchronizing-the-catalog-with-vtex-ads/synchronizing-product-information.md @@ -15,7 +15,7 @@ Learn more about each field on `POST` [Synchronize product information](https:// To update the basic product data, the following endpoint must be used: -> 🚧 Batch Insert / Update +> ⚠️ Batch Insert / Update > > For each batch insert/update, a maximum of 500 objects per request and 3 simultaneous requests are allowed. > diff --git a/docs/localization/exporting-ads-events.md b/docs/localization/exporting-ads-events.md new file mode 100644 index 0000000000..9ca5d7aaac --- /dev/null +++ b/docs/localization/exporting-ads-events.md @@ -0,0 +1,107 @@ +--- +title: "Exporting ads events" +slug: "exporting-ads-events" +excerpt: "Export raw advertising event data including impressions, clicks, views, and conversions for detailed analysis." +hidden: false +createdAt: "2025-10-13T00:00:00.000Z" +updatedAt: "2025-10-14T00:00:00.000Z" +--- +Event data export enables systematic and periodic integration of raw advertising events for detailed analysis and custom reporting. + +## Integration connection + +See more about the connection in [Exporting data from VTEX Ads](https://developers.vtex.com/docs/guides/exporting-data-from-vtex-ads). + +## Integration format + +- Data sent is always D-1 (previous day) +- Files are in [Parquet](https://parquet.apache.org/docs/overview/) format with [Snappy](https://parquet.apache.org/docs/file-format/data-pages/compression/) compression +- Files are always sent in a daily path format: `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.snappy.parquet` (one or more files may be sent) + +> ⚠️ Event deduplication +> +> All events are guaranteed to be sent, but there is no guarantee that an event will be sent only once. Therefore, events must always be deduplicated. + +## Event data + +### Impressions + +| Attribute | Type | Description | +| :------------- | :------------ | :-------------------------------------------------------------- | +| event_id | String | Unique event identifier **(deduplication key)** | +| session_id | String | Unique user session identifier | +| user_id | String | Unique user identifier | +| ad_id | String | Advertisement identifier | +| campaign_id | String | Unique campaign identifier | +| request_id | String | Unique ad query request identifier | +| ad_type | String | Type of advertisement that generated the event | +| placement_name | String | Name of the placement where the ad was displayed | +| context | String | Context in which the ad was displayed | +| created_at | Timestamp UTC | Timestamp of when the event occurred | +| site | String | Site brand identifier | + +### Views + +| Attribute | Type | Description | +| :------------- | :------------ | :-------------------------------------------------------------- | +| event_id | String | Unique event identifier **(deduplication key)** | +| session_id | String | Unique user session identifier | +| user_id | String | Unique user identifier | +| ad_id | String | Advertisement identifier | +| campaign_id | String | Unique campaign identifier | +| request_id | String | Unique ad query request identifier | +| ad_type | String | Type of advertisement that generated the event | +| placement_name | String | Name of the placement where the ad was displayed | +| context | String | Context in which the ad was displayed | +| created_at | Timestamp UTC | Timestamp of when the event occurred | +| site | String | Site brand identifier | + +### Clicks + +| Attribute | Type | Description | +| :------------- | :------------ | :-------------------------------------------------------------- | +| event_id | String | Unique event identifier **(deduplication key)** | +| session_id | String | Unique user session identifier | +| user_id | String | Unique user identifier | +| ad_id | String | Advertisement identifier | +| campaign_id | String | Unique campaign identifier | +| request_id | String | Unique ad query request identifier | +| ad_type | String | Type of advertisement that generated the event | +| placement_name | String | Name of the placement where the ad was displayed | +| context | String | Context in which the ad was displayed | +| created_at | Timestamp UTC | Timestamp of when the event occurred | +| site | String | Site brand identifier | + +### Conversions + +| Attribute | Type | Description | +| :--------- | :------------ | :----------------------------------------------------- | +| event_id | String | Unique conversion event identifier | +| session_id | String | Unique user session identifier | +| user_id | String | Unique user identifier | +| order_id | String | Unique retail order identifier **(deduplication key)** | +| channel | String | Channel identifier | +| placed_at | Timestamp UTC | Order timestamp | +| site | String | Site brand identifier | + +### Conversion items + +| Attribute | Type | Description | +| :---------------- | :-------- | :-------------------------------------------------------------- | +| event_id | String | Unique identifier of the event that generated the conversion (view or click) | +| session_id | String | Unique user session identifier | +| user_id | String | Unique user identifier | +| order_id | String | Unique retail order identifier **(deduplication key)** | +| product_sku | String | Product identifier **(deduplication key)** | +| ad_id | String | Unique advertisement identifier | +| campaign_id | String | Unique campaign identifier | +| request_id | String | Unique ad query request identifier | +| ad_size | String | Size of the media used in the advertisement | +| ad_type | String | Type of advertisement that generated the conversion | +| placement_name | String | Name of the placement where the ad was displayed | +| context | String | Context in which the ad was displayed | +| event_created_at | Timestamp | Timestamp of when the event occurred | +| price | Float | Product price (regular) | +| promotional_price | Float | Product promotional price | +| quantity | Int | Quantity of items sold | +| total_value | Float | Total item value (quantity * min(price, promotional_price)) | diff --git a/docs/localization/exporting-ads-reports.md b/docs/localization/exporting-ads-reports.md new file mode 100644 index 0000000000..20b4fd2c40 --- /dev/null +++ b/docs/localization/exporting-ads-reports.md @@ -0,0 +1,177 @@ +--- +title: "Exporting ads reports" +slug: "exporting-ads-reports" +excerpt: "Access and download platform data automatically through API endpoints with JSON or XLSX export options." +hidden: false +createdAt: "2025-10-13T00:00:00.000Z" +updatedAt: "2025-10-14T00:00:00.000Z" +--- +Report export allows you to access and download platform information automatically, without the need for manual extraction through the interface. All report routes return data in JSON format by default, but can be exported as XLSX files by including the `download=true` parameter in the query. + +> ℹ️ API Authentication +> +> To access the routes, users must be authenticated. See the [authentication documentation](https://newtail-media.readme.io/reference/autenticacao) for more details. + +> ⚠️ Limited availability of some reports +> +> Export of certain reports may be restricted based on the account type associated with the authentication. Not all users will have access to all available reports. + +## Reports + +### Advertisers + +This endpoint allows you to search for information from all advertisers associated with a publisher account. Data is returned in JSON format by default, but can be exported as XLSX by adding the `download=true` parameter to the query string. + +> ℹ️ Only available in publisher view. + +#### Request + +``` +GET https://api-retail-media.newtail.com.br/report/v2/advertisers?start_date=2025-01-01&end_date=2025-01-01 HTTP/1.1 +accept: application/json +content-type: application/json +x-app-id: +x-api-key: +``` + +#### Query parameters + +| Parameter | Required | Description | +| :----------- | :------- | :-------------------------------------------------------------------------------- | +| start_date | Yes | Metrics start date in `YYYY-MM-DD` format | +| end_date | Yes | Metrics end date in `YYYY-MM-DD` format | +| account_info | No | If true, includes detailed account information in the result. Default is `false` | +| page | No | Page number of results. Default is `1` | +| quantity | No | Number of items per page. Default is `100` | +| count | No | If `true`, returns the total number of available records. Default is `false` | +| download | No | If `true`, returns an XLSX file buffer ready for download instead of JSON | + +### Publishers + +This endpoint allows you to search for publisher information. Data is returned in JSON format by default, but can be exported as XLSX by including the `download=true` parameter in the query string. + +> ℹ️ Only available in advertiser view. + +#### Request + +``` +GET https://api-retail-media.newtail.com.br/report/v2/publishers?start_date=2025-01-01&end_date=2025-01-01 HTTP/1.1 +accept: application/json +content-type: application/json +x-app-id: +x-api-key: +``` + +#### Query parameters + +| Parameter | Required | Description | +| :-------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| start_date | Yes | Metrics start date in `YYYY-MM-DD` format | +| end_date | Yes | Metrics end date in `YYYY-MM-DD` format | +| publisher_name | No | Filters results by publisher name | +| account_info | No | If true, includes detailed account information in the result. Default is `false` | +| page | No | Page number of results. Default is `1` | +| quantity | No | Number of items per page. Default is `100` | +| count | No | If `true`, returns the total number of available records. Default is `false` | +| order_by | No | Defines the field for sorting results. Possible values: `name, balance, total_daily_budget, total_campaigns, impressions, clicks, ctr, total_spent, conversions, conversion_rate, income, roas` | +| order_direction | No | Defines the sorting direction. Possible values: `asc` (ascending) or `desc` (descending) | +| download | No | If `true`, returns an XLSX file buffer ready for download instead of JSON | + +### Network publishers + +This endpoint allows you to search for information about publishers associated with a **Network** type Publisher account. Data is returned in JSON format by default, but can be exported as XLSX by including the `download=true` parameter in the query string. + +> ℹ️ Only publishers operating in Network format have permission to access this report. + +#### Request + +``` +GET https://api-retail-media.newtail.com.br/report/network/publishers?start_date=2025-01-01&end_date=2025-01-01 HTTP/1.1 +accept: application/json +content-type: application/json +x-app-id: +x-api-key: +``` + +#### Query parameters + +| Parameter | Required | Description | +| :-------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | +| start_date | Yes | Metrics start date in `YYYY-MM-DD` format | +| end_date | Yes | Metrics end date in `YYYY-MM-DD` format | +| publisher_name | No | Filters results by publisher name | +| account_info | No | If true, includes detailed account information in the result. Default is `false` | +| page | No | Page number of results. Default is `1` | +| quantity | No | Number of items per page. Default is `100` | +| count | No | If `true`, returns the total number of available records. Default is `false` | +| order_by | No | Defines the field for sorting results. Possible values: `name, impressions, clicks, ctr, conversions, conversion_rate, income, roas, requests` | +| order_direction | No | Defines the sorting direction. Possible values: `asc` (ascending) or `desc` (descending) | +| download | No | If `true`, returns an XLSX file buffer ready for download instead of JSON | + +### Campaigns + +This endpoint allows you to search for all available campaigns, applying filters as needed. Data is returned in JSON format by default, but can be exported as XLSX by including the `download=true` parameter in the query string. + +#### Request + +``` +GET https://api-retail-media.newtail.com.br/campaign/v2?start_date=2025-01-01&end_date=2025-01-01 HTTP/1.1 +accept: application/json +content-type: application/json +x-app-id: +x-api-key: +``` + +#### Query parameters + +| Parameter | Required | Description | +| :-------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| start_date | Yes | Metrics start date in `YYYY-MM-DD` format | +| end_date | Yes | Metrics end date in `YYYY-MM-DD` format | +| status | No | Filters by campaign status | +| advertiser_id | No | Filters campaigns by advertiser ID | +| ad_type | No | Filters by ad type | +| name | No | Searches campaigns by name | +| account_info | No | If true, includes detailed account information in the result. Default is `false` | +| page | No | Page number of results. Default is `1` | +| quantity | No | Number of items per page. Default is `100` | +| count | No | If `true`, returns the total number of available records. Default is `false` | +| order_by | No | Defines the field for sorting results. Possible values: `name, impressions, clicks, ctr, conversions, conversion_rate, income, roas, created_at, start_at, daily_budget, ad_type, advertiser_name, status` | +| order_direction | No | Defines the sorting direction. Possible values: `asc` (ascending) or `desc` (descending) | +| download | No | If `true`, returns an XLSX file buffer ready for download instead of JSON | + +### Ads + +This endpoint allows you to search for all available ads, applying filters as needed. Data is returned in JSON format by default, but can be exported as XLSX by including the `download=true` parameter in the query string. + +#### Request + +``` +GET https://api-retail-media.newtail.com.br/ad/results/v2?start_date=2025-01-01&end_date=2025-01-01 HTTP/1.1 +accept: application/json +content-type: application/json +x-app-id: +x-api-key: +``` + +#### Query parameters + +| Parameter | Required | Description | +| :-------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| start_date | Yes | Metrics start date in `YYYY-MM-DD` format | +| end_date | Yes | Metrics end date in `YYYY-MM-DD` format | +| campaign_name | No | Filters ads by campaign name | +| campaign_id | No | Filters ads by campaign ID | +| advertiser_id | No | Filters ads by advertiser ID | +| product_sku | No | Filters ads by product SKU | +| ad_status | No | Filters ads by status | +| ad_type | No | Filters by ad type | +| targeting_type | No | Filters by targeting type | +| show_inactive | No | If `true`, includes paused ads | +| account_info | No | If `true`, includes detailed account information in the result. Default is `false` | +| page | No | Page number of results. Default is `1` | +| quantity | No | Number of items per page. Default is `100` | +| count | No | If `true`, returns the total number of available records. Default is `false` | +| order_by | No | Defines the field for sorting results. Possible values: `ad_type, ad_status, impressions, conversion_rate, ctr, income, total_spent, roas, conversions, total_conversions_item_quantity` | +| order_direction | No | Defines the sorting direction. Possible values: `asc` (ascending) or `desc` (descending) | +| download | No | If `true`, returns an XLSX file buffer ready for download instead of JSON | diff --git a/docs/localization/exporting-aggregated-data-from-vtex-ads.md b/docs/localization/exporting-aggregated-data-from-vtex-ads.md new file mode 100644 index 0000000000..9cf6a3e6cd --- /dev/null +++ b/docs/localization/exporting-aggregated-data-from-vtex-ads.md @@ -0,0 +1,124 @@ +--- +title: "Exporting aggregated data from VTEX Ads" +slug: "exporting-aggregated-data-from-vtex-ads" +excerpt: "Export pre-processed performance metrics and campaign statistics for business intelligence and reporting purposes." +hidden: false +createdAt: "2025-10-13T00:00:00.000Z" +updatedAt: "2025-10-14T00:00:00.000Z" +--- +Aggregated data export enables systematic and periodic integration of pre-processed advertising performance metrics for business intelligence and reporting purposes. + +## Integration connection + +See more about the connection in [Exporting data from VTEX Ads](https://developers.vtex.com/docs/guides/exporting-data-from-vtex-ads). + +## Integration format + +- Data sent is always D-1 (previous day) +- Data is always sent D-1 with the publisher's timezone +- Files are sent in CSV format: + - UTF-8 encoding + - Comma-separated values + - All numbers follow American format with decimal point (".") +- Files are always sent in a daily path format: `TYPE_REPORT/YYYY/MM/DD/TIMESTAMP_NS/RANDOM_FILE_NAMES.csv` (one or more files may be sent) + +## Data to be exported + +> ℹ️ File examples +> +> Examples of files that will be sent: +> +> +> +> + +### Advertisers + +`advertisers/YYYY/MM/DD/CURRENT_DELIVERY_TIME/RANDOM_FILE_NAME.csv` + +| Column | Type | Description | +| :------------- | :----- | :------------------------------------------------------- | +| advertiser | String | Advertiser name | +| advertiser_id | String | Unique advertiser identifier | +| seller_id | String | Seller identifier | +| wallet_balance | Float | Current balance in the advertiser's wallet | +| daily_budget | Float | Total daily budget sum of all active campaigns | +| currency | String | Currency format the advertiser is operating in (e.g., BRL, USD) | + +### Campaigns + +`campaigns/YYYY/MM/DD/CURRENT_DELIVERY_TIME/RANDOM_FILE_NAME.csv` + +| Column | Type | Description | +| :---------------- | :---------------- | :------------------------------------------------------- | +| day | date YYYY-DD-MM | Day is always sent in the publisher's timezone | +| name | String | Campaign name | +| campaign_id | String | Unique campaign identifier | +| campaign_type | String | Campaign type: `product`, `banner`, `sponsored_brands`, `video` | +| campaign_status | String | Campaign operating status | +| impressions_total | int | Total impressions | +| clicks_total | int | Total clicks | +| ctr | float | Campaign CTR | +| ad_revenue | Float | Ad revenue | +| conversions_total | int | Total conversions | +| conversion_rate | float | Order conversion rate | +| sales_revenue | float | Revenue from sold items | +| start_date | date YYYY-DD-MM | Campaign start date | +| end_date | date YYYY-DD-MM | Campaign end date | +| advertiser_id | String | Unique advertiser identifier | + +### Ads + +`ads/YYYY/MM/DD/CURRENT_DELIVERY_TIME/RANDOM_FILE_NAME.csv` + +| Column | Type | Description | +| :---------------- | :---------------- | :------------------------------------------------------- | +| day | date YYYY-DD-MM | Day is always sent in the publisher's timezone | +| ad_id | String | Unique ad identifier | +| campaign_id | String | Unique campaign identifier | +| ad_status | String | Ad operating status | +| ad_media_url | String | Ad media URL | +| cpm | float | CPM value | +| cpc | float | CPC value | +| impressions_total | int | Total impressions | +| clicks_total | int | Total clicks | +| ctr | float | Ad CTR | +| ad_revenue | float | Ad revenue | +| conversions_total | int | Total conversions generated by the ad | +| conversion_rate | float | Conversion rate | +| sales_revenue | float | Revenue from product sales | +| product_sku | String | List of SKUs separated by semicolon. Note: Product campaigns always have only 1 product per ad | + +### Product ads + +`product_ads/YYYY/MM/DD/CURRENT_DELIVERY_TIME/RANDOM_FILE_NAME.csv` + +| Column | Type | Description | +| :---------------- | :---------------- | :------------------------------------------------------- | +| day | date YYYY-DD-MM | Day is always sent in the publisher's timezone | +| ad_id | String | Unique ad identifier | +| campaign_id | String | Unique campaign identifier | +| advertiser_id | String | Unique advertiser identifier | +| product_sku | String | Product SKU | +| ad_type | String | Ad type | +| ad_media_url | String | Ad media URL | +| cpm | float | CPM value | +| cpc | float | CPC value | +| impressions_total | int | Total impressions | +| clicks_total | int | Total clicks | +| ctr | float | Ad CTR | +| ad_revenue | float | Ad revenue | +| conversions_total | int | Total conversions generated by the ad | +| conversion_rate | float | Conversion rate | +| sales_revenue | float | Revenue from product sales | + +### Catalog + +`catalog/YYYY/MM/DD/CURRENT_DELIVERY_TIME/RANDOM_FILE_NAME.csv` + +| Column | Type | Description | +| :---------- | :----- | :------------------------------------------------------- | +| product_sku | String | Product SKU | +| name | String | Product name | +| categories | String | List of product categories separated by semicolon (e.g., Cat1 > Cat2; ...) | +| image_url | String | Product image URL | diff --git a/docs/localization/exporting-data-from-vtex-ads.md b/docs/localization/exporting-data-from-vtex-ads.md new file mode 100644 index 0000000000..3dc5fa5978 --- /dev/null +++ b/docs/localization/exporting-data-from-vtex-ads.md @@ -0,0 +1,37 @@ +--- +title: "Exporting data from VTEX Ads" +slug: "exporting-data-from-vtex-ads" +excerpt: "Learn how to export data from VTEX Ads using S3-compatible connections for events and aggregated data." +hidden: false +createdAt: "2025-10-13T00:00:00.000Z" +updatedAt: "2025-10-13T00:00:00.000Z" +--- +VTEX Ads provides data export capabilities that allow you to extract campaign events and aggregated performance data. Integration always occurs using an S3-compatible connection that must be provided by the data receiver. + +## Prerequisites + +Before setting up data export, ensure you have: + +- An S3-compatible storage solution configured. +- Proper access credentials for your chosen storage provider. +- Network connectivity between VTEX Ads and your storage endpoint. + +## Credentials + +Credentials must be securely shared with the VTEX team through agreed-upon secure channels. The integration supports the following cloud storage providers: + +- **AWS S3**: Requires `Access Key ID` and `Access Key Secret` +- **Google Cloud Storage**: Requires `Service Account` credentials +- **Azure Blob Storage**: Requires connection string or account key + +> ⚠️ **Security**: Never share credentials through unsecured channels. Use encrypted communication methods as agreed between parties. + +## Export Types + +VTEX Ads supports three types of data export: + +- **[Event Export](https://developers.vtex.com/docs/guides/exporting-ads-events)**: Export raw event data including clicks, impressions, and conversions for detailed analysis and custom reporting. + +- **[Aggregated Data Export](https://developers.vtex.com/docs/guides/exporting-aggregated-data-from-vtex-ads)**: Export pre-processed performance metrics and campaign statistics for business intelligence and reporting purposes. + +- **[Ads Reports Export](https://developers.vtex.com/docs/guides/exporting-ads-reports)**: Export comprehensive advertising reports with campaign performance data, conversion metrics, and ROI analysis. diff --git a/docs/localization/integrating-audiences.md b/docs/localization/integrating-audiences.md new file mode 100644 index 0000000000..5e1a2b0ae4 --- /dev/null +++ b/docs/localization/integrating-audiences.md @@ -0,0 +1,169 @@ +--- +title: "Integrating audiences" +slug: "integrating-audiences" +excerpt: "Integrate customer audience data with VTEX Ads using a presigned S3 upload and PII hashing." +hidden: false +createdAt: "2025-10-13T00:00:00.000Z" +updatedAt: "2026-06-03T00:00:00.000Z" +--- + +Audience integration lets you enrich **VTEX Ads** targeting with your own customer data, improving campaign segmentation and ad relevance. It is optional but highly recommended. + +You deliver an audience file through a short-lived presigned Amazon S3 upload. First you request an upload URL from the VTEX Ads API, then you upload the file directly to Amazon S3 using the signed fields returned in the response. The backend builds the destination path from your authenticated publisher, so no per-publisher credentials or manual paths are required. + +> ℹ️ If you do not integrate audiences, open a ticket with your account manager to request 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 keep them updated periodically. + +## Before you begin + +- **Authentication:** the upload URL request requires the `X-App-Id` and `X-Api-Key` headers. Contact [VTEX support](https://help.vtex.com/en/tutorial/how-does-vtex-support-work--2eAT5EyOvaLoHdIWDVaxC3) to obtain credentials. +- **File format:** `Parquet` with `Snappy` compression. Column names are case-sensitive (see [Audience file](#audience-file)). + +> ℹ️ Delivery recommendation +> +> On the first integration, send all data. You can split it across multiple files (a good size is around 1 million rows per file). After the first integration, send only the delta of rows that changed. + +> ℹ️ FTP/SFTP integration is no longer supported for new projects. If you have a legacy SFTP integration, contact the VTEX Ads team to plan the migration to this flow. + +## 1. Request an upload URL + +Send an authenticated `POST` request to the `/audience/upload-url` endpoint. The endpoint returns a presigned Amazon S3 `POST` that is valid for `expires_in` seconds (900 by default, around 15 minutes). + +Request example: + +```bash +curl -X POST "https://api-retail-media.newtail.com.br/audience/upload-url" \ + -H "X-App-Id: {your_app_id}" \ + -H "X-Api-Key: {your_api_key}" \ + -H "Accept: application/json" +``` + +Response example: + +```json +{ + "url": "https://newtail-data-clean-room.s3.amazonaws.com/", + "fields": { + "key": "0d675bf6-03f6-4b81-9617-e79dffddc3ab/audiences/2026/06/03/14/1780495200.parquet.snappy", + "Content-Type": "application/octet-stream", + "Policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0wNi0wM1QxNDoxNTowMFoiLCJjb25kaXRpb25zIjpbXX0=", + "X-Amz-Signature": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" + }, + "key": "0d675bf6-03f6-4b81-9617-e79dffddc3ab/audiences/2026/06/03/14/1780495200.parquet.snappy", + "bucket": "newtail-data-clean-room", + "expires_in": 900, + "max_bytes": 2147483648, + "upload": { + "method": "POST", + "enctype": "multipart/form-data" + } +} +``` + +See the `POST` [Generate audience upload URL](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/audience/upload-url) endpoint for the full response schema. The following table describes the response fields: + +| Field | Description | +| :--- | :--- | +| `url` | Amazon S3 endpoint to send the upload request to. | +| `fields` | Signed Amazon S3 form fields that must be sent with the upload, before the `file` field. | +| `key` | Object key the file will be stored under. Built by the backend from your authenticated publisher. | +| `bucket` | Amazon S3 bucket that receives the upload. | +| `expires_in` | Number of seconds the presigned `POST` remains valid. Defaults to `900`. | +| `max_bytes` | Maximum file size, in bytes, accepted by Amazon S3. Defaults to `2147483648` (2 GB). | +| `upload` | HTTP `method` and `enctype` to use for the upload request. | + +## 2. Upload the file to Amazon S3 + +Upload the audience file with a multipart `POST` request directly to the `url` returned in the previous step. Send every entry from `fields` first and the `file` field last. + +```bash +curl -X POST "{url}" \ + -F key={fields.key} \ + -F Content-Type=application/octet-stream \ + -F Policy={fields.Policy} \ + -F X-Amz-Signature={fields.X-Amz-Signature} \ + -F \ + -F file=@my-audience.parquet.snappy +``` + +> ⚠️ The presigned `POST` expires after `expires_in` seconds. If it expires before the upload completes, request a new upload URL. Amazon S3 rejects files larger than `max_bytes` (2 GB by default). + +## Audience file + +### Attributes + +Most attributes are not required. However, the more complete this information is, the better the relevance will be. + +> ℹ️ Columns are case-sensitive +> +> Keep the column names exactly as they are presented. + +| Column | Type | Required | Description | +| :---------------- | :----- | :------- | :------------------------------------------------------- | +| `CUSTOMER_ID` | String | Yes | Unique customer identifier | +| `EMAIL_HASHED` | String | No | PII based on customer email | +| `PHONE_HASHED` | String | No | PII based on customer primary phone number | +| `SOCIAL_ID_HASHED` | String | No | PII based on customer CPF (tax ID) | +| `FIRST_NAME_HASHED` | String | No | PII based on customer first name | +| `LAST_NAME_HASHED` | String | No | PII based on customer last name | +| `GENDER` | String | No | Customer gender: `F` (female), `M` (male), `O` (other), `NULL` (not identified) | +| `AGE` | Int | No | Customer age | +| `CEP` | String | No | Customer address postal code | +| `COUNTRY` | String | No | Customer country | +| `STATE` | String | No | Customer state of residence | +| `CITY` | String | No | Customer city of residence | +| `NEIGHBORHOOD` | String | No | Customer neighborhood of residence | +| `AUDIENCES` | String | No | List of audiences using `;` as the separator | +| `NBO_PRODUCTS` | String | No | List of product SKUs using `;` as the separator | +| `NBO_CATEGORIES` | String | No | List of categories using `;` as the separator. Category lists can include category trees using ` > ` as separator. Example: `Tablets;Beverages > Non-Alcoholic Beverages;Books > Gastronomy > Bar and Restaurant Guides` | + + +### Field hashing + +Confidential data must be encrypted before being sent using the SHA-256 algorithm. + +- `EMAIL_HASHED` +- `PHONE_HASHED` +- `SOCIAL_ID_HASHED` +- `FIRST_NAME_HASHED` +- `LAST_NAME_HASHED` + +> ℹ️ Before generating the data hash, you must remove all SPACES and convert values to **LOWERCASE**. + +> ⚠️ For the `PHONE_HASHED` attribute, you must format it to the E.164 standard and include the country calling code. + +#### E.164 format + +1. Remove all non-numeric characters, such as spaces, dashes, parentheses, and symbols. +2. Add the country code with a plus sign (+) at the beginning. The country code is a 1 to 3-digit code that identifies the country of the phone number. You can find a list of country codes in the ISO 3166-1 standard. +3. Add the area code (if applicable) without the leading zero. For example, in the United States, the area code consists of three digits and should not start with zero. +4. Include the local phone number without the leading zero (if applicable). + +Examples: + +- A United States phone number with area code 212 and local number 555-1234 would be formatted as: +12125551234 +- A Brazilian phone number with area code 11 and local number 98765-4321 would be formatted as: +5511987654321 + +#### Creating a hash of a formatted attribute using 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 +``` + +## Runtime alternative + +If you choose not to integrate audiences through file upload, you can still apply segmentation at query time by sending the data in the `segmentation` field of the ad query request. For more details, see [Segmenting campaigns](https://developers.vtex.com/docs/guides/segmenting-campaigns). + +## Next steps + +- [Segmenting campaigns](https://developers.vtex.com/docs/guides/segmenting-campaigns) +- `POST` [Generate audience upload URL](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/audience/upload-url) diff --git a/docs/localization/integrating-vtex-ads-with-external-marketplaces.md b/docs/localization/integrating-vtex-ads-with-external-marketplaces.md new file mode 100644 index 0000000000..57b76dad17 --- /dev/null +++ b/docs/localization/integrating-vtex-ads-with-external-marketplaces.md @@ -0,0 +1,246 @@ +--- +title: "Integrating VTEX Ads with external marketplaces" +slug: "integrating-vtex-ads-with-external-marketplaces" +excerpt: "Learn how to integrate VTEX Ads with external marketplaces through authentication, catalog management, campaign operations, and SSO implementation." +hidden: false +createdAt: "2025-10-13T00:00:00.000Z" +updatedAt: "2025-10-13T00:00:00.000Z" +--- + +This document describes how to integrate VTEX Ads with external marketplaces through bidirectional authentication, catalog synchronization, and unified campaign management. + +## Authentication + +Authentication occurs bidirectionally, both from the marketplace to VTEX Ads and from VTEX Ads to the marketplace. + +### Marketplace to VTEX Ads + +The connection requires adding two parameters in the request headers sent to VTEX Ads. + +| Header | Description | +| --- | --- | +| `x-app-id` | The App ID identifies the API user | +| `x-api-key` | The API Key identifies the API "password" | + +>ℹ️ Access credentials must be requested from our [Support](https://support.vtex.com/hc/en-us/requests) team. + +### VTEX Ads to marketplace + +In this scenario, the connection will be from VTEX Ads to the marketplace. To standardize this integration, we will use **Basic Authentication** format in the request. + +| Authentication | Description | +| --- | --- | +| `username` | Username for authentication | +| `password` | User password | + +>ℹ️ For more information about Basic Authentication functionality, see the [RFC 7617 specification](https://datatracker.ietf.org/doc/html/rfc7617). + +## Catalog + +The catalog API enables product synchronization between marketplaces and VTEX Ads. All product data must include the following attributes: + +| Attribute | Description | Type | Required | +| --- | --- | --- | --- | +| `product_sku` | Unique identifier of the parent product | String | Yes | +| `name` | Product title | String | Yes | +| `image_url` | Public product image URL, can be just a thumbnail | String | No | +| `categories` | List of categories | String | Yes | +| `brand` | Product brand name | String | Yes | +| `gtins` | List of EANs | Array | No | +| `urls` | Product URL information | Array | Yes | +| `urls.site` | Site brand name | String | No | +| `urls.url` | Product URL | String | Yes | +| `stocks` | Product stock information | Array | Yes | +| `stocks.site` | Site brand name | String | No | +| `stocks.seller_id` | Seller ID identifier | String | No | +| `stocks.quantity` | Stock quantity | Float | Yes | +| `metadata` | Information returned during ad queries without modification | Object | No | + +For this step, we need an API to query the retailer's catalog, and this catalog must contain: + +|Attribute|Description| +|:--------|:----------| +|seller_id|Filter by seller identifier.| +|name|Partial search by product name.| +|skus|Filter by a list of SKUs.| +|eans|Filter by a list of EANs.| +|quantity|Number of items that should be returned.| +|page|Current page number. Starts at 0 (zero).| + +```http +GET PREFIX/search?name=&seller_id=&skus=sku1,sku2,...,skuN&eans=ean1,ean2,...,eanN&quantity=&page= +``` + +### Response example - Status 200 + +```json +[ + { + "product_sku": "sku123", + "name": "Red Sneakers", + "image_url": "https://example.com/image.jpg", + "categories": "Sports/Shoes", + "brand": "Nike", + "gtins": ["1234567890123"], + "urls": [ + { + "site": "example-store", + "url": "https://example.com/product/red-sneakers" + } + ], + "stocks": [ + { + "site": "example-store", + "seller_id": "seller123", + "quantity": 10 + } + ], + "metadata": { + "color": "red", + "size": "42" + } + } +] +``` + +> ⚠️ Any status other than 200 is considered an error. + +## Advertiser (seller) + +The Advertiser entity manages sellers and their associated data. + +| Endpoints | Description | Filters | +| --- | --- | --- | +| GET /api/v1/advertisers | Search advertisers | quantity, page, name, seller_id | +| POST /api/v1/advertisers | Create advertiser | - | +| GET /api/v1/advertisers/:seller_id | Get advertiser by seller ID | - | +| PATCH /api/v1/advertisers/:seller_id | Update advertiser by seller ID | - | + +## Campaigns + +The Campaigns entity manages advertising campaign creation and updates. + +| Endpoints | Description | Filters | +| --- | --- | --- | +| GET /api/v1/campaigns | List campaigns | seller_id, page, quantity, name, status, ad_type | +| POST /api/v1/campaigns | Create campaign | - | +| GET /api/v1/campaigns/:campaign_id | Get campaign by ID | - | +| PATCH /api/v1/campaigns/:campaign_id | Update campaign by ID | - | + +## Metrics + +The Metrics entity provides macro and historical performance data for campaigns. + +| Endpoints | Description | Filters | +| --- | --- | --- | +| GET /api/v1/metrics/macro/campaigns | Get macro metrics | start_at, end_at, campaign_id, seller_id | +| GET /api/v1/metrics/history/campaigns | Get historical metrics | start_at, end_at, campaign_id, seller_id | + +## Credits + +The Credits entity manages advertiser account balances and transactions. + +| Endpoints | Description | Filters | +| --- | --- | --- | +| GET /api/v1/checking_accounts | List advertiser credit accounts | seller_id, page, quantity | +| GET /api/v1/checking_accounts/:seller_id/transactions | List credits for an account | page, quantity | +| POST /api/v1/checking_accounts/:seller_id/transactions | Add credits to an account | - | + +### Credit purchase with credit card/PIX + +| Endpoints | Description | Filters | +| --- | --- | --- | +| GET /api/v1/payments | List payments | seller_id, page, quantity | +| POST /api/v1/payments/:payment_type | Create a new payment that will add credits | - | +| GET /api/v1/payments/:payment_id | Query a payment | - | + +## SSO (VTEX Ads authentication) + +The idea is that once the customer is connected to the marketplace platform, they can reuse this login to connect to the Retail Media platform. + +> ⚠️ Any status other than 200 is considered an error. + +### Login + +Authentication uses a JWT token with a shared secret. The token must contain: + +- `publisher_id`: Retailer ID in VTEX Ads. +- `seller_id`: Seller ID in the marketplace. +- `user_id`: User ID in the marketplace. +- 24h expiration time + +```http +GET https://app.newtail.com.br/login/marketplace?sso=JWT +``` + +### User information query + +The marketplace must provide an endpoint to query user information by user ID that returns the following fields: + +- `name` +- `email` + +```http +GET PREFIX/users/:user_id?seller_id&=publisher_id= +``` + +### Seller information query + +The marketplace must provide an endpoint to query seller information that returns the following fields: + +- `name` +- `cnpj` (tax ID) + +```http +GET PREFIX/sellers/:seller_id?publisher_id= +``` + +## SSO v2 (VTEX Ads authentication) + +SSO v2 allows retailers to send seller and user information to the VTEX Ads authentication API. VTEX Ads returns a redirect URL for the end user. + +> ⚠️ Authentication follows the same model described in the [Authentication](#authentication) section. + +```http +POST https://api-retail-media.newtail.com.br/sso/marketplace +``` + +### Request example + +```json +{ + "seller_id": "xyz", + "seller_name": "Seller Name", + "user_email": "user@example.com", + "user_name": "User Name" +} +``` + +### Response examples + +**Success** - Status 200 + +```json +{ + "url_redirect": "https://app.newtail.com.br/login/marketplace?token=JWT" +} +``` + +**Failure** + +* Status 400 - Validation error + + ```json + { + "message": "ValidationError", + "errors": [] + } + ``` + +* Status 500 - Internal application error + + ```json + { + "message": "InternalServerError" + } + ``` diff --git a/docs/localization/placement-naming-conventions.md b/docs/localization/placement-naming-conventions.md new file mode 100644 index 0000000000..f1d51cd8c3 --- /dev/null +++ b/docs/localization/placement-naming-conventions.md @@ -0,0 +1,34 @@ +--- +title: "Placement naming conventions" +slug: "placement-naming-conventions" +excerpt: "Learn the standardized naming conventions for VTEX Ads placements to ensure accurate metrics tracking and reporting." +hidden: false +createdAt: "2025-10-13T00:00:00.000Z" +updatedAt: "2025-10-13T00:00:00.000Z" +--- + +When implementing VTEX Ads on your storefront, placement names are essential for accurate measurement and reporting of advertising metrics for each ad region on your site. + +VTEX Ads uses placement identifiers to track performance, attribution, and revenue across different locations and contexts within your store. Use the following standardized naming convention to ensure consistent tracking and analytics across your VTEX Ads implementation: + +```json +{platform}_{context}_{position}_{type} +``` + +## Naming convention components + +- **Platform**: The medium where the ad is displayed (`site`, `msite`, `app`). +- **Context**: The page or section context (`home`, `product`, `search`, `category`). +- **Position**: The specific location within the page layout. +- **Type**: The advertisement format (`banner`, `product`). + +## Examples + +| Platform | Context | Position | Type | Complete placement name | +| :------- | :--------- | :--------------- | :-------- | :------------------------------------ | +| `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` | diff --git a/docs/localization/segmenting-campaigns-by-pii.md b/docs/localization/segmenting-campaigns-by-pii.md new file mode 100644 index 0000000000..ac8c04787d --- /dev/null +++ b/docs/localization/segmenting-campaigns-by-pii.md @@ -0,0 +1,72 @@ +--- +title: "Segmenting campaigns by PII" +slug: "segmenting-campaigns-by-pii" +excerpt: "Create targeted campaigns using personally identifiable information through secure CSV file integration." +hidden: false +createdAt: "2025-10-13T00:00:00.000Z" +updatedAt: "2025-10-14T00:00:00.000Z" +--- +PII segmentation must be done via CSV and will allow the creation of campaigns with users known by the advertiser. + +## Audience file + +The integration file will be a **CSV** file in **UTF-8** encoding. + +### Attributes + +Most attributes are not required; however, the more complete this information is, the better the relevance will be. + +| Column | Type | Required | Description | +| :---------------- | :----- | :------- | :------------------------------------------- | +| CUSTOMER_ID | String | Yes | Unique customer identifier | +| EMAIL_HASHED | String | No | PII based on customer email | +| PHONE_HASHED | String | No | PII based on customer primary phone number | +| SOCIAL_ID_HASHED | String | No | PII based on customer CPF (tax ID) | +| FIRST_NAME_HASHED | String | No | PII based on customer first name | +| LAST_NAME_HASHED | String | No | PII based on customer last name | + +### 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 data hash, you must remove all SPACES and convert values to **LOWERCASE**. + +> ⚠️ For the PHONE_HASHED attribute, you must format it to the E.164 standard and include the country calling code. + +#### E.164 format + +1. Remove all non-numeric characters, such as spaces, dashes, parentheses, and symbols. +2. Add the country code with a plus sign (+) at the beginning. The country code is a 1 to 3-digit code that identifies the country of the phone number. You can find a list of country codes in the ISO 3166-1 standard. +3. Add the area code (if applicable) without the leading zero. For example, in the United States, the area code consists of three digits and should not start with zero. +4. Include the local phone number without the leading zero (if applicable). + +Examples: + +- A United States phone number with area code 212 and local number 555-1234 would be formatted as: +12125551234 +- A Brazilian phone number with area code 11 and local number 98765-4321 would be formatted as: +5511987654321 + +#### Creating a hash of a formatted attribute using 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 +``` + +### File delivery + +The file must be sent as a ZIP file via email to your Newtail contact. diff --git a/docs/localization/transferring-credit.md b/docs/localization/transferring-credit.md new file mode 100644 index 0000000000..2eafb626bb --- /dev/null +++ b/docs/localization/transferring-credit.md @@ -0,0 +1,83 @@ +--- +title: "Transferring credit" +slug: "transferring-credit" +excerpt: "Learn how to implement credit transfer flow between marketplaces and sellers in VTEX Ads." +hidden: false +createdAt: "2025-10-13T00:00:00.000Z" +updatedAt: "2025-10-13T00:00:00.000Z" +--- +Credit transfer is the flow that allows marketplaces to transfer advertising credits to their sellers. This documentation details the endpoints that marketplaces must implement and the webhook they must consume to integrate with VTEX Ads. + +> ℹ️ The Authentication model follows [Basic Auth](https://developers.vtex.com/docs/guides/integrating-vtex-ads-with-external-marketplaces#vtex-ads-to-marketplace). + +![transferring-credit](https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/VTEX%20Ads/transferring-credit.png) + +## Endpoints to be implemented by the marketplace + +Authentication: Basic Auth + +### 1. Balance inquiry (`GET /checking_account`) + - **Purpose:** Check the seller's available balance. + - **Query parameters:** `seller_id`, `publisher_id` (optional, used only when an entity manages multiple publishers). + - **Success response (200 OK):** + ```json + { "total": "1111.00" } + ``` + +### 2. Transfer request (`POST /checking_account/transfer`) + - **Purpose:** Request the transfer of an 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 rejection" + } + ``` + - **Asynchronous:** `202 Accepted` + ```json + { + "transaction_id": "TRANSACTION_ID", + "status": "processing" + } + ``` + +## Webhook to be consumed by the marketplace + +- **Purpose:** Notify VTEX Ads 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 webhook call failure, the marketplace must retry. +- **Expected response:** `204 No Content` diff --git a/docs/localization/transferring-credit.png b/docs/localization/transferring-credit.png new file mode 100644 index 0000000000..f926b74b91 Binary files /dev/null and b/docs/localization/transferring-credit.png differ diff --git a/docs/localization/vtex-ads-best-practices.md b/docs/localization/vtex-ads-best-practices.md new file mode 100644 index 0000000000..319c8aff85 --- /dev/null +++ b/docs/localization/vtex-ads-best-practices.md @@ -0,0 +1,35 @@ +--- +title: "VTEX Ads best practices" +slug: "vtex-ads-best-practices" +excerpt: "Learn best practices for integrating with the VTEX Ads API to ensure optimal performance and reliability." +hidden: false +createdAt: "2025-10-13T00:00:00.000Z" +updatedAt: "2025-10-13T00:00:00.000Z" +--- +To optimize integration performance with the VTEX Ads API, implement the following practices. + +## HTTP persistence + +For server-side integrations, use persistent HTTP connections to minimize connection overhead per API request. + +HTTP connection reuse allows multiple requests to share the same TCP connection, eliminating the performance cost of establishing and tearing down connections for each request. This approach prevents network resource degradation during high-traffic periods on both client and server sides. + +The following diagram illustrates the performance difference between multiple connections and persistent connections: + +![vtex-ads-best-practices](https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/VTEX%20Ads/getting-started-with-vtex-ads-api/vtex-ads-best-practices.png) + +To implement HTTP persistence, configure your HTTP client to include the following header: + +```curl +Connection: keep-alive +``` + +This header instructs the client to maintain the connection for subsequent requests from the same origin. + +> ℹ️ Learn more about HTTP persistence in the [Mozilla Developer documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Connection_management_in_HTTP_1.x). + +## Timeout implementation + +While the VTEX Ads API maintains high availability standards, network conditions and processing loads can affect response times. Extended response delays may degrade user experience during ad display. + +Implement request timeouts between 500-600ms for all VTEX Ads API calls to maintain optimal performance. This range balances response time requirements with network variability considerations. diff --git a/docs/localization/vtex-ads-best-practices.png b/docs/localization/vtex-ads-best-practices.png new file mode 100644 index 0000000000..624298fca4 Binary files /dev/null and b/docs/localization/vtex-ads-best-practices.png differ diff --git a/docs/localization/vtex-ads-script-agent.md b/docs/localization/vtex-ads-script-agent.md new file mode 100644 index 0000000000..79327c6c1c --- /dev/null +++ b/docs/localization/vtex-ads-script-agent.md @@ -0,0 +1,88 @@ +--- +title: "VTEX Ads Script Agent" +slug: "vtex-ads-script-agent" +excerpt: "Learn how to implement the VTEX Ads tracking script across your site using Google Tag Manager for optimal campaign performance and audience segmentation." +hidden: false +createdAt: "2025-10-13T00:00:00.000Z" +updatedAt: "2025-10-13T00:00:00.000Z" +--- + +This document details the procedure for installing the **VTEX Ads** tracking script on all site pages (except checkout pages) through Google Tag Manager (GTM). Proper implementation of this script is essential for collecting navigation data that enables optimization and targeting of Retail Media campaigns. + +## Data collection + +The VTEX Ads script is designed to collect exclusively non-sensitive navigation data, with the objective of personalizing user experience and optimizing campaigns. + +Learn more about the collected data below: + +- **For off-site campaigns:** + + - `session_id`: Anonymous navigation session identifier. + - `ad_id`: Identifier of the ad that originated the traffic. + +- **For audience segmentation (Page View):** + + - `session_id`: Anonymous navigation session identifier. + - **Page information:** URL, title (``), and description (`<meta name="description">`). + +>⚠️ The script **does not collect** any personally identifiable information (PII), such as name, email, CPF, phone, address, or payment data. Data collection complies with major data protection laws. + +## Script details + +The script must be loaded asynchronously to avoid impacting page loading time. + +**Script URL:** + +```http +https://cdn.newtail.com.br/retail-media/scripts/vtexads-agent.1.0.0.js +``` + +## Implementation via Google Tag Manager (GTM) + +To ensure the script executes as early as possible during page loading, we recommend using the **Initialization** trigger. + +### Step 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 recognizable name, for example: **Custom HTML - VTEX Ads Agent**. +4. Click **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/vtexads-agent.1.0.0.js"></script> + ``` + +### Step 2: Configure the main trigger + +1. Below the tag configuration, click **"Triggering"**. +2. Select the **"Initialization - All Pages"** trigger. This trigger ensures the script fires before most other tags, on all pages. + +### Step 3: Create and add a trigger exception + +To prevent the script from executing on checkout pages, we'll 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. Name the trigger, for example: **"Trigger Exception - Checkout Pages"**. +4. Click **"Trigger Configuration"** and choose the **"Initialization"** type. +5. Under **"This trigger fires on"**, select **"Some Initialization Events"**. +6. Configure the condition to identify 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 4: Save and publish + +1. Save the newly created tag. +2. Submit and publish the changes in your GTM container. + +## User session configuration + +For the VTEX Ads platform to correctly correlate user interactions, you must specify which session identifier is used by your ecommerce. + +>⚠️ **Required action:** The ecommerce team must inform the VTEX Ads team about the **name of the attribute in the `cookie` or `sessionStorage`** that stores the user's session ID. +> +> For example: If the session ID is stored in a cookie called `vtex_session`, this information must be provided. +> +> This configuration allows the script to read the correct identifier and associate it with navigation events. diff --git a/docs/localization/vtex-ads-single-sign-on-sso.md b/docs/localization/vtex-ads-single-sign-on-sso.md new file mode 100644 index 0000000000..befa1815e8 --- /dev/null +++ b/docs/localization/vtex-ads-single-sign-on-sso.md @@ -0,0 +1,51 @@ +--- +title: "VTEX Ads Single Sign On (SSO)" +slug: "vtex-ads-single-sign-on-sso" +excerpt: "Enable seamless user authentication across environments with VTEX Ads SSO integration." +hidden: false +createdAt: "2025-10-13T00:00:00.000Z" +updatedAt: "2025-10-13T00:00:00.000Z" +--- +The purpose of Single Sign On is to allow users to switch between environments without having to log in again. + +> ℹ️ API Authentication +> +> <https://dash.readme.com/project/newtail-media/v1.0/refs/autenticacao> + +## 1. Request redirect URL + +| Attribute | Description | Type | Required | +| :---------- | :--------------------------------------------- | :----- | :------- | +| seller_id | Unique identifier of the advertiser/seller | String | Yes | +| seller_name | Name of the advertiser/seller | String | Yes | +| user_email | User email | String | Yes | +| user_name | User name | String | Yes | + +```json +curl --location --request POST 'https://api-retail-media.newtail.com.br/sso/marketplace' +--header 'x-api-key: XXX' +--header 'x-app-id: YYY' +--header 'Content-Type: application/json' +--data-raw '{ + "seller_id": "1", + "seller_name": "Store Example", + "user_email": "example@example.com.br", + "user_name": "User Example" +}' +``` + +Response: + +```json +{ + "url_redirect": "https://app.newtail.com.br/login/marketplace?token=xxxxx" +} +``` + +## 2. User redirection to the redirect URL + +Once you have the redirect URL, simply redirect the user to this URL and the user will be logged into the platform without requiring any login integration. + +## Login URL (user disconnection) + +Optionally, we can redirect the user to a previously provided URL that will be used when the user is disconnected.