vtexads-api-docs

5.4. Audience Integration

Note: Audience integration is optional, but highly recommended to improve campaign targeting and ad relevance.

Audience integration has a single integration method: Batch Submission to the S3 bucket provided by VTEX Ads.

Important: FTP/SFTP integration is deprecated and should only be used for legacy implementations. New projects must use the S3 bucket exclusively.

Warning: If there is no audience integration, you must open a ticket with your Account Manager requesting pre-population of segmentation information with base data (STATE, CITY, GENDER, and AGE). You can also provide a list of audiences to be registered, and we recommend keeping these audiences updated periodically.

Batch Submission - S3 Bucket

The integration connection occurs through periodic audience uploads to the publisher’s dedicated S3 bucket. Access credentials (IAM key/secret or cross-account role) and the bucket base path must be requested from your Newtail contact.

• File Format: Parquet with Snappy compression.
• Directory Pattern (S3 key): Upload files using: s3://<bucket>/<PREFIX>/audiences/YYYY/mm/dd/TIMESTAMP.parquet.snappy

Attribute	Description	Example
PREFIX	The prefix will be provided by Newtail.	xyz
YYYY	4-digit year of generation.	2023
mm	Two-digit month of generation (January = 01 and December = 12).	09
dd	Two-digit day of generation (from 01 to 31).	31
TIMESTAMP	Timestamp is the number of seconds since 1970 (the file name can be anything, the timestamp is just a suggestion that will never be repeated).	1694812122

Recommendation for submission: In the initial integration, it is essential that all data be sent. This data can be sent in multiple files (depending on the size of the base, a good number is 1 million lines per file). After the first integration, the ideal is to send only the delta of the rows that had any modification.

Legacy compatibility: If you are already integrated via SFTP, contact the VTEX Ads team to plan the migration to the S3 bucket. The SFTP flow will no longer receive new enhancements and may be discontinued.

Runtime Alternative Without Prior Integration

If you choose not to integrate audiences via batch, you can still use segmentation at runtime by sending the data in the segmentation field of the ad query request. See 5.5. Ad Query.

Audience File Attributes

Most attributes are not mandatory, however, the more complete this information is, the better the relevance will be.

The columns are case-sensitive. Keep the column names as they are presented.

Column	Type	Required?	Description
CUSTOMER_ID	String	Yes	Unique customer identifier.
EMAIL_HASHED	String	No	PII based on the customer’s email.
PHONE_HASHED	String	No	PII based on the customer’s primary phone number.
SOCIAL_ID_HASHED	String	No	PII based on the customer’s CPF.
FIRST_NAME_HASHED	String	No	PII based on the customer’s First Name.
LAST_NAME_HASHED	String	No	PII based on the customer’s Last Name.
GENDER	String	No	Indicates the customer’s gender (F for female, M for male, O for others, NULL for unidentified).
AGE	Int	No	Indicates the customer’s age.
CEP	String	No	Indicates the customer’s postal code.
COUNTRY	String	No	Indicates the user’s country.
STATE	String	No	Indicates the state where the customer resides.
CITY	String	No	Indicates the city where the customer resides.
NEIGHBORHOOD	String	No	Indicates the neighborhood where the customer resides.
AUDIENCES	String	No	A list of audiences, separated by a semicolon (;).
NBO_PRODUCTS	String	No	A list of product SKUs, separated by a semicolon (;).
NBO_CATEGORIES	String	No	A list of categories, separated by a semicolon (;). The list can receive a category tree using “ > “ as a separator (e.g., Tablets;Beverages > Non-Alcoholic Beverages;Books > Gastronomy > Bar and Restaurant Guides).

Field Hashing

Confidential data must be encrypted before being sent using the SHA256 algorithm.

• EMAIL_HASHED
• PHONE_HASHED
• SOCIAL_ID_HASHED
• FIRST_NAME_HASHED
• LAST_NAME_HASHED

Before generating the hash of the data, it is necessary to remove all SPACES and convert its values to LOWERCASE. For the PHONE_HASHED attribute, it will be necessary to format it in the E.164 standard and include the country calling code.

E.164 Format

1. Remove all non-numeric characters, such as spaces, hyphens, parentheses, and symbols.
2. Add the country code with the plus sign (+) at the beginning.
3. Add the area code (if applicable) without the leading zero.
4. Include the local phone number without the leading zero (if applicable).

Example:

• A phone number from the United States, with area code 212 and local number 555-1234, would be formatted as: +12125551234

Creating a HASH in Python

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