new(guides): VTEX Ads docs migration - part II#2227
Conversation
Navigation Preview LinkNo changes detected in the navigation.json file |
👁️🗨️ Preview changes on Developer PortalYou can use the link below to load the Developer Portal in preview mode with the changes from this branch: Below is the list of modified pages and their corresponding preview URLs:
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| ## Integration connection | ||
|
|
||
| See more about the connection in [Exporting data from VTEX Ads](https://developers.vtex.com/docs/guides/exporting-data-from-vtex-ads). |
There was a problem hiding this comment.
[link-check] reported by reviewdog 🐶
🚨 Found a broken link in a Markdown Link (Error 404):
https://developers.vtex.com/docs/guides/exporting-data-from-vtex-ads
👉 Please review this link before merging your Pull Request.
|
|
||
| ## Integration connection | ||
|
|
||
| See more about the connection in [Exporting data from VTEX Ads](https://developers.vtex.com/docs/guides/exporting-data-from-vtex-ads). |
There was a problem hiding this comment.
[link-check] reported by reviewdog 🐶
🚨 Found a broken link in a Markdown Link (Error 404):
https://developers.vtex.com/docs/guides/exporting-data-from-vtex-ads
👉 Please review this link before merging your Pull Request.
|
|
||
| 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. |
There was a problem hiding this comment.
[link-check] reported by reviewdog 🐶
🚨 Found a broken link in a Markdown Link (Error 404):
https://developers.vtex.com/docs/guides/exporting-ads-events
👉 Please review this link before merging your Pull Request.
|
|
||
| - **[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. |
There was a problem hiding this comment.
[link-check] reported by reviewdog 🐶
🚨 Found a broken link in a Markdown Link (Error 404):
https://developers.vtex.com/docs/guides/exporting-aggregated-data-from-vtex-ads
👉 Please review this link before merging your Pull Request.
|
|
||
| - **[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. |
There was a problem hiding this comment.
[link-check] reported by reviewdog 🐶
🚨 Found a broken link in a Markdown Link (Error 404):
https://developers.vtex.com/docs/guides/exporting-ads-reports
👉 Please review this link before merging your Pull Request.
| | `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. |
There was a problem hiding this comment.
[link-check] reported by reviewdog 🐶
🚨 Found a broken link in a Markdown Link (Error 403):
https://support.vtex.com/hc/en-us/requests
👉 Please review this link before merging your Pull Request.
|
|
||
| > ℹ️ The Authentication model follows [Basic Auth](https://developers.vtex.com/docs/guides/integrating-vtex-ads-with-external-marketplaces#vtex-ads-to-marketplace). | ||
|
|
||
|  |
There was a problem hiding this comment.
[link-check] reported by reviewdog 🐶
🚨 Found a broken link in a Markdown Image (Error 403):
https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/VTEX%20Ads/transferring-credit.png
👉 Please review this link before merging your Pull Request.
| --- | ||
| 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). |
There was a problem hiding this comment.
[link-check] reported by reviewdog 🐶
🚨 Found a broken link in a Markdown Link (Error 404):
https://developers.vtex.com/docs/guides/integrating-vtex-ads-with-external-marketplaces#vtex-ads-to-marketplace
👉 Please review this link before merging your Pull Request.
|
|
||
| The following diagram illustrates the performance difference between multiple connections and persistent connections: | ||
|
|
||
|  |
There was a problem hiding this comment.
[link-check] reported by reviewdog 🐶
🚨 Found a broken link in a Markdown Image (Error 403):
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
👉 Please review this link before merging your Pull Request.
There was a problem hiding this comment.
Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit
markdownlint
[markdownlint] reported by reviewdog 🐶
MD004/ul-style Unordered list style [Expected: dash; Actual: asterisk]
[markdownlint] reported by reviewdog 🐶
MD028/no-blanks-blockquote Blank line inside blockquote
[markdownlint] reported by reviewdog 🐶
MD022/blanks-around-headings Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "### 1. Balance inquiry (GET /checking_account)"]
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 3]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Purpose: Check the selle..."]
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 3]
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 3]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD022/blanks-around-headings Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "### 2. Transfer request (POST /checking_account/transfer)"]
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 3]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Purpose: Request the tra..."]
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 3]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 3]
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 5]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 5]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 5]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
| - 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 | ||
| > |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
| 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 | ||
| > |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
| > ℹ️ API Authentication | ||
| > | ||
| > To access the routes, users must be authenticated. See the [authentication documentation](https://newtail-media.readme.io/reference/autenticacao) for more details. | ||
|
|
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD028/no-blanks-blockquote Blank line inside blockquote
| > 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 | ||
| > |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
|
|
||
| #### Request | ||
|
|
||
| ``` |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| x-api-key: <API_KEY> | ||
| ``` | ||
|
|
||
| #### Query parameters |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Query parameters"]
| ## Data to be exported | ||
|
|
||
| > 📘 File examples | ||
| > |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
| > 📘 File examples | ||
| > | ||
| > Examples of files that will be sent: | ||
| > |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
| } | ||
| ``` | ||
|
|
||
| **Failure** |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD036/no-emphasis-as-heading Emphasis used instead of a heading [Context: "Failure"]
|
|
||
| **Failure** | ||
|
|
||
| * Status 400 - Validation error |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD004/ul-style Unordered list style [Expected: dash; Actual: asterisk]
Documentation feedback for docs/localization/vtex-ads-best-practices.mdOkay, I've reviewed the provided Guide content and compared it against the specified rules. Here's my feedback: 1. General Feedback: The document deviates significantly from the structure and purpose of a "Guide" as defined in the rules. It reads more like a best practices article or conceptual documentation rather than a task-oriented guide. The title is not in gerund form, and the content lacks a clear set of instructions for the reader to follow. The absence of a numbered list of steps is a major deviation. The content focuses on explaining concepts (HTTP persistence, timeout implementation) rather than guiding the user through a specific task. 2. Actionable Feedback:
3. Suggested Revision: Was this feedback useful?
|
Documentation feedback for docs/localization/segmenting-campaigns-by-pii.mdGeneral FeedbackThe provided document does not adhere to the structure of a how-to guide as defined in the rules. It lacks a goal-oriented introduction, a clear set of instructions with numbered steps, and a conclusion suggesting next steps. Instead, it primarily describes the format and requirements for a CSV file used for PII segmentation in campaigns. The content is more akin to a reference document or specification rather than a guide. Actionable Feedback
Suggested Revision---
title: "Preparing a CSV file for PII Campaign Segmentation"
slug: "preparing-csv-file-for-pii-campaign-segmentation"
excerpt: "Learn how to prepare and format a CSV file containing Personally Identifiable Information (PII) to create targeted campaigns, enhancing relevance and reach."
hidden: false
createdAt: "2025-10-13T00:00:00.000Z"
updatedAt: "2025-10-14T00:00:00.000Z"
---
This guide will walk you through the process of preparing a CSV file containing Personally Identifiable Information (PII) for segmenting your campaigns. By using PII segmentation, you can create highly targeted campaigns, increasing their relevance and effectiveness. This method allows you to reach users known by the advertiser, ensuring your message resonates with the intended audience.
## Before you begin
* Ensure you have a Newtail contact for file delivery.
* Familiarize yourself with the SHA256 algorithm for data encryption.
* Have access to a tool or programming language (e.g., Python) for hashing data.
## Instructions
### Step 1 - Format your CSV file
The integration file must be a **CSV** file in **UTF-8** encoding. Use the following structure for your CSV file:
| 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 |
Most attributes are not required; however, the more complete this information is, the better the relevance will be.
### Step 2 - Hash PII fields using SHA256
Confidential data must be encrypted before being sent using the SHA256 algorithm. The following fields must be hashed:
- 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**.
### Step 3 - Format phone numbers to E.164 standard (if applicable)
> 🚧 For the PHONE_HASHED attribute, you must format it to the E.164 standard and include the country calling code.
Follow these steps to format phone numbers:
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
### Step 4 - Create a hash of a formatted attribute using Python (example)
Here's an example of how to create a hash 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
```
### Step 5 - Compress the file
Compress the CSV file into a ZIP file.
### Step 6 - Deliver the file
Send the ZIP file via email to your Newtail contact.
## Next steps
* Confirm with your Newtail contact that the file has been successfully processed.
* Create your targeted campaign in the VTEX Campaigns platform, utilizing the uploaded PII data.
* Monitor the performance of your campaign and adjust your segmentation strategy as needed.Was this feedback useful?
|
Documentation feedback for docs/localization/vtex-ads-single-sign-on-sso.mdOkay, I've reviewed the provided Guide content against the specified rules. Here's my feedback: 1. General Feedback: The document deviates significantly from the required structure and content for a "How-to Guide." It lacks a clear "Before you begin" section, numbered instructions, and imperative step titles. The content reads more like an API reference or explanation than a step-by-step guide. The title also doesn't follow the gerund form. 2. Actionable Feedback:
3. Suggested Revision: ---
title: "Implementing VTEX Ads Single Sign-On"
slug: "implementing-vtex-ads-single-sign-on"
excerpt: "Learn how to implement Single Sign-On (SSO) for VTEX Ads, enabling users to seamlessly switch between environments without repeated logins."
hidden: false
createdAt: "2025-10-13T00:00:00.000Z"
updatedAt: "2025-10-13T00:00:00.000Z"
---
This guide will walk you through the process of implementing Single Sign-On (SSO) for VTEX Ads. By following these instructions, you'll enable users to seamlessly switch between different VTEX Ads environments without needing to log in each time, improving user experience and efficiency.
## Before you begin
* You need an active VTEX Ads account.
* You must have the `x-api-key` and `x-app-id` for your VTEX Ads application.
* Ensure you have the seller ID, seller name, user email, and user name available for the user you want to authenticate.
## Instructions
### Step 1 - Request a Redirect URL
To initiate the SSO process, you need to request a redirect URL from the VTEX Ads API.
1. Use the following table to understand the required parameters for the API request:
| 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 |
2. Execute the following `curl` command, replacing the placeholder values with your actual credentials and user information:
```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"
}'
```
3. Examine the response. A successful request will return a JSON object containing the `url_redirect`. For example:
```json
{
"url_redirect": "https://app.newtail.com.br/login/marketplace?token=xxxxx"
}
```
### Step 2 - Redirect the User to the получен URL
Once you have obtained the `url_redirect`, redirect the user to this URL. This action will automatically log the user into the VTEX Ads platform without requiring them to enter their credentials.
### Step 3 - Implement User Disconnection (Optional)
Optionally, you can implement a user disconnection feature. To do this, redirect the user to a previously provided URL when they log out or are disconnected from your application. This URL should be configured in your VTEX Ads settings.
## Next steps
* Monitor user login activity to ensure the SSO integration is working correctly.
* Implement error handling to manage potential issues during the SSO process.
* Explore other VTEX Ads API functionalities to enhance your integration.Was this feedback useful?
|
Documentation feedback for docs/localization/vtex-ads-script-agent.mdOkay, I've reviewed the provided Guide and have identified several areas for improvement based on the given rules. 1. General Feedback: The guide provides a clear walkthrough of implementing the VTEX Ads script using Google Tag Manager. However, the title is not in gerund form, and the initial sections contain informational content that should be more goal-oriented. The instructions are generally well-structured, but some steps could be more imperative and direct. The guide also lacks a "Before you begin" section. 2. Actionable Feedback:
3. Suggested Revision: ---
title: "Implementing VTEX Ads Script Agent"
slug: "vtex-ads-script-agent"
excerpt: "Implement the VTEX Ads tracking script across your site using Google Tag Manager to optimize campaign performance and audience segmentation."
hidden: false
createdAt: "2025-10-13T00:00:00.000Z"
updatedAt: "2025-10-13T00:00:00.000Z"
---
This guide walks you through installing the **VTEX Ads** tracking script on all your site pages (except checkout pages) using Google Tag Manager (GTM). By following these instructions, you'll be able to collect navigation data, which is essential for optimizing and targeting your Retail Media campaigns.
## Before you begin
* You need a Google Tag Manager account with administrative access.
* You should have basic familiarity with Google Tag Manager concepts like tags, triggers, and variables.
* Ensure you have access to your store's checkout page URLs to configure the exclusion trigger.
## Instructions
### Step 1 - Access your GTM container
1. Go to your Google Tag Manager account.
2. Select the container for the website where you want to implement the VTEX Ads script.
### Step 2 - Create the custom HTML tag
1. In your GTM container, navigate to the **Tags** section.
2. Click **New** to create a new tag.
3. Name the tag something recognizable, like **Custom HTML - VTEX Ads Agent**.
4. Click **Tag Configuration** and choose the **Custom HTML** tag type.
5. In the HTML field, paste 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>
```
> This script is designed to collect exclusively non-sensitive navigation data, with the objective of personalizing user experience and optimizing campaigns. It collects `session_id` and `ad_id` for off-site campaigns, and `session_id` and page information (URL, title, and description) for audience segmentation. The script loads asynchronously to avoid impacting page loading time.
### Step 3 - Configure the main trigger
1. Below the tag configuration, click **Triggering**.
2. Select the **Initialization - All Pages** trigger. This ensures the script fires as early as possible on all pages.
### Step 4 - Create an exception trigger for checkout pages
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 select the **Initialization** trigger type.
5. Under **This trigger fires on**, select **Some Initialization Events**.
6. Configure the condition to identify checkout pages. This may vary depending on your site's URL structure. Here are some 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 5 - Save and publish your changes
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.
> ⚠️ **Important:** 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`, provide this information to the VTEX Ads team.
>
> This configuration allows the script to read the correct identifier and associate it with navigation events.
## Next steps
* Monitor the data collection in your VTEX Ads account to ensure the script is working correctly.
* Contact VTEX Ads support if you encounter any issues.
Was this feedback useful?
|
Documentation feedback for docs/localization/exporting-data-from-vtex-ads.mdOkay, I've reviewed the provided Guide content against the specified rules. Here's my feedback: 1. General Feedback: The Guide is well-structured and provides useful information about exporting data from VTEX Ads. However, it deviates from the required format for a "how-to" guide. It lacks a numbered "Instructions" section with imperative steps. It reads more like a conceptual overview and setup guide than a step-by-step instruction manual. The "Export Types" section could be incorporated into a step-by-step guide on setting up each export type. 2. Actionable Feedback:
3. Suggested Revision: ---
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"
---
This guide will walk you through the process of exporting data from VTEX Ads to your S3-compatible storage solution. By following these instructions, you'll be able to extract campaign events and aggregated performance data for detailed analysis and custom reporting, enabling you to gain deeper insights into your advertising performance.
## Before you begin
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.
## Instructions
### Step 1 - Choose Your Export Type
VTEX Ads supports three types of data export:
1. **Event Export**: Export raw event data including clicks, impressions, and conversions for detailed analysis and custom reporting. See [Exporting Ads Events](https://developers.vtex.com/docs/guides/exporting-ads-events) for more details.
2. **Aggregated Data Export**: Export pre-processed performance metrics and campaign statistics for business intelligence and reporting purposes. See [Exporting Aggregated Data from VTEX Ads](https://developers.vtex.com/docs/guides/exporting-aggregated-data-from-vtex-ads) for more details.
3. **Ads Reports Export**: Export comprehensive advertising reports with campaign performance data, conversion metrics, and ROI analysis. See [Exporting Ads Reports](https://developers.vtex.com/docs/guides/exporting-ads-reports) for more details.
Choose the export type that best suits your needs.
### Step 2 - Configure Your S3-Compatible Connection
To configure your S3-compatible connection, you will need to securely share your credentials 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.
### Step 3 - Contact VTEX Support to Initiate the Export
1. Gather all the necessary information, including your chosen export type (Event, Aggregated Data, or Ads Reports), S3-compatible storage details (endpoint, bucket name), and securely provided credentials.
2. Contact VTEX Support, providing them with the gathered information and requesting the data export setup.
3. Work with VTEX Support to schedule and test the data export process.
### Step 4 - Verify the Data Export
1. After the export is configured, monitor your S3-compatible storage location to ensure that the data is being delivered as expected.
2. Check the data format and content to confirm that it matches your requirements.
3. If any issues arise, contact VTEX Support for assistance.
## Next steps
* Explore the linked documentation for each export type to understand the data schema and available fields.
* Set up automated data processing pipelines to analyze the exported data.
* Monitor the data export process regularly to ensure its continued functionality.Was this feedback useful?
|
Documentation feedback for docs/localization/integrating-audiences.mdGeneral FeedbackThe document provides information on integrating audience data with VTEX Ads. However, it does not follow the structure of a how-to guide. It lacks a goal-oriented introduction, a clear set of instructions, and a conclusion. The content is more descriptive than instructive. It also does not adhere to the required frontmatter format. Actionable Feedback
Suggested Revision---
title: "Integrating Customer Audiences with VTEX Ads"
slug: "integrating-customer-audiences-with-vtex-ads"
excerpt: "Learn how to integrate customer audience data with VTEX Ads using secure S3-based file delivery and PII hashing."
hidden: false
createdAt: "2025-10-13T00:00:00Z"
updatedAt: "2025-10-14T00:00:00Z"
---
In this guide, you will learn how to integrate customer audience data with VTEX Ads. By following these instructions, you can securely deliver audience data via S3, ensuring PII is properly hashed, which will allow you to leverage customer data for targeted advertising campaigns and improve ad performance.
## Before you begin
* Ensure you have requested S3 access credentials from your Newtail contact.
* Familiarize yourself with the required `Parquet` file format and `Snappy` compression.
* Understand the data requirements and hashing procedures outlined in this guide.
## Instructions
### Step 1 - Prepare your data for delivery
Prepare your audience data, ensuring it includes the necessary customer information.
* It is recommended to send all data in the initial integration. You can split the data into multiple files, ideally with 1 million rows per file.
* After the initial integration, send only the delta of rows that have been modified.
### Step 2 - Format your files
Format your files in `Parquet` format with `Snappy` compression.
### Step 3 - Organize your files in the required directory structure
Organize your files according to the following directory pattern:
```
PREFIX/audiences/YYYY/mm/dd/TIMESTAMP.parquet.snappy
```
* `PREFIX`: Provided by Newtail.
* `YYYY`: Generation year with 4 digits.
* `mm`: Generation month with two digits (January = 01, December = 12).
* `dd`: Generation day with two digits (from 01 to 31).
* `TIMESTAMP`: Number of seconds since 1970 (filename can be anything, timestamp is just a suggestion that will never repeat).
### Step 4 - Understand the audience file attributes
Familiarize yourself with the required and optional attributes for the audience file. The more complete the information, the better the relevance will be. Remember that column names are case-sensitive.
| Column | Type | Required | Description
### Step 5 - Hash PII fields
Before sending, hash the following PII fields using the SHA256 algorithm:
* EMAIL\_HASHED
* PHONE\_HASHED
* SOCIAL\_ID\_HASHED
* FIRST\_NAME\_HASHED
* LAST\_NAME\_HASHED
Before generating the hash, remove all spaces and convert values to lowercase. For PHONE\_HASHED, format it to the E.164 standard, including the country calling code.
### Step 6 - Format phone numbers to E.164
To format phone numbers to E.164:
1. Remove all non-numeric characters.
2. Add the country code with a plus sign (+).
3. Add the area code (if applicable) without the leading zero.
4. Include the local phone number without the leading zero (if applicable).
Examples:
* US: +12125551234
* Brazil: +5511987654321
### Step 7 - Create a hash of a formatted attribute using Python (example)
Use the following Python code as an example for creating a hash:
```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
```
### Step 8 - Deliver the files to the S3 bucket
Deliver the prepared and formatted files to the S3 bucket using the credentials provided by Newtail.
## Next steps
* Monitor the integration process to ensure data is being delivered correctly.
* Analyze the performance of your VTEX Ads campaigns using the integrated audience data.
* Consult with your Newtail contact for any further assistance or optimization strategies.Was this feedback useful?
|
Documentation feedback for docs/localization/placement-naming-conventions.mdGeneral FeedbackThe explanation provides a clear and concise guide to naming conventions for VTEX Ads placements. The content is well-structured with a good introduction and clear examples. However, it lacks cross-references to other relevant VTEX documentation. Actionable Feedback
Suggested Revision---
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](https://developers.vtex.com/docs/guides/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` |Was this feedback useful?
|
| - 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 | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
| 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 | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
| > 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 | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
| ## Data to be exported | ||
|
|
||
| > 📘 File examples | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
| > 📘 File examples | ||
| > | ||
| > Examples of files that will be sent: | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
| } | ||
| ``` | ||
| or | ||
| ```json |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| ```json | |
| ```json |
| "message": "Problem description" | ||
| } | ||
| ``` | ||
| - **Retry logic:** In case of webhook call failure, the marketplace must retry. |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| - **Retry logic:** In case of webhook call failure, the marketplace must retry. | |
| - **Retry logic:** In case of webhook call failure, the marketplace must retry. |
|
|
||
| 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). |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > ℹ️ 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). | |
| > ℹ️ 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). |
| 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. | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
| The purpose of Single Sign On is to allow users to switch between environments without having to log in again. | ||
|
|
||
| > 📘 API Authentication | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
github-actions
Bot
force-pushed
the
main
branch
2 times, most recently
from
df4c627 to
f3d116b
Compare
julia-rabello
changed the title
🏷️ Frontmatter errors
|
| Field | Error |
|---|---|
excerpt |
Missing required field: 'excerpt' |
There was a problem hiding this comment.
Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit
markdownlint
[markdownlint] reported by reviewdog 🐶
MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request body example"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
| > 🚧 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. | ||
|
|
||
|
|
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
| > ⚠️ 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 |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
| - **File format:** `Parquet` with `Snappy` compression. Column names are case-sensitive (see [Audience file](#audience-file)). | ||
|
|
||
| > ℹ️ Delivery recommendation | ||
| > |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
| > ℹ️ 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. | ||
|
|
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD028/no-blanks-blockquote Blank line inside blockquote
| Most attributes are not required. However, the more complete this information is, the better the relevance will be. | ||
|
|
||
| > ℹ️ Columns are case-sensitive | ||
| > |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
| "status": "success" | ||
| } | ||
| ``` | ||
| - **Synchronous (Failure):** `400 Bad Request` |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 5]
| } | ||
| ``` | ||
| - **Synchronous (Failure):** `400 Bad Request` | ||
| ```json |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
| "status": "failure", | ||
| "message": "Reason for rejection" | ||
| } | ||
| ``` |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]
| "message": "Reason for rejection" | ||
| } | ||
| ``` | ||
| - **Asynchronous:** `202 Accepted` |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 5]
| } | ||
| ``` | ||
| - **Asynchronous:** `202 Accepted` | ||
| ```json |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 2]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 2]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 2]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h3; Actual: h4]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 2]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 2]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request body example"]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request body example"]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
|
|
||
| ### Adding an item to a subscription |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| ### Adding an item to a subscription | |
| ### Adding an item to a subscription |
|
|
||
| > 🚧 Batch Insert / Update | ||
| > ⚠️ Batch Insert / Update | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
| > ⚠️ Batch Insert / Update | ||
| > | ||
| > For each batch insert/update, a maximum of 500 objects per request and 3 simultaneous requests are allowed. | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
|
|
||
| > 🚧 Batch Insert / Update | ||
| > ⚠️ Batch Insert / Update | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
| > ⚠️ Batch Insert / Update | ||
| > | ||
| > For each batch insert/update, a maximum of 500 objects per request and 3 simultaneous requests are allowed. | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
| - **File format:** `Parquet` with `Snappy` compression. Column names are case-sensitive (see [Audience file](#audience-file)). | ||
|
|
||
| > ℹ️ Delivery recommendation | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
| Most attributes are not required. However, the more complete this information is, the better the relevance will be. | ||
|
|
||
| > ℹ️ Columns are case-sensitive | ||
| > |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| > | |
| > |
| | `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` | | ||
|
|
||
|
|
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
3 participants
EDU-14825
Types of changes