This feature is in BETA. For more information, contact your Customer Success Representative.
Amazon Demand-Side Platform (DSP) enables advertisers to programmatically buy display, video, and audio ads on or off Amazon. Amazon DSP is available to advertisers on Amazon irrespective of whether they sell products on Amazon. You can use Amazon's DSP to reach the audience through Amazon sites, apps, publishing partners, and third-party exchanges.
The Amazon DSP Data Provider Export Integration allows you to export segment data like hashed emails and customer information to Amazon DSP.
Prerequisites
Basic knowledge of Amazon DSP and an advertiser account.
Basic Knowledge of Treasure Data functions like Authentication, Queries, Results Export, and (optionally) Workflow.
Limitations
The
External Audience ID
is the key to specifying the target audiences on Amazon. (It is unique to all audiences.) The values of this field will be unique for each advertiser account.The job may split the result set into multiple batches. If one batch fails, the integration will not revert the successfully uploaded batches.
The integration will add the prefixes required per Amazon DSP API (COOKIE- or MAID-). Do not add these prefixes manually in the result set.
The integration will not update the Audience Metadata.
Null or empty column data will be ignored.
The result output schema must have either the cookie or maid columns or both in their metadata.
Maid
andcookie
columns must have thestring
data type.The maximum length for a
cookie
field is 1999 characters.
Steps to create or remove an audience using PII information
Prepare a Hashed Records Datasource, including an external identifier
External identifier (external_id): a unique id represents a customer profile for a target advertiser. Using a hashed number generated from a combination of the advertiser ID and email (or phone) is recommended. If multiple customer profiles use the same external identifier (,.e. ID: 12345), it will be overwritten in the matching process in Amazon DSP, resulting in a low matching rate. Example of generating the external_id using the combination of advertiser_id and email:
External_id is the combination of advertiser_id and email:
SELECT SHA2(CONCAT(advertiser_id, email), 256) AS external_id FROM table_name;
External_id is the combination of advertiser_id and phone:
SELECT SHA2(CONCAT(advertiser_id, phone), 256) AS external_id FROM table_name;
Hashed records table (PII information): include email, name, phone number, …
Select the ‘hashed records’ data source the in the data connector configuration to send the above data to Amazon DSP for matching.
The matching process will begin within the Amazon DSP. The SLA (Service Level Agreement) is set at 48 hours. This timeframe starts from the moment the hashed record API is called to utilize the uploaded external IDs for audience creation. It is important to note that the SLA remains consistent and does not change regardless of the volume of records being processed.
Add to Audience or Remove from Audience:
Prepare an external_user_id table for the audience to be added or removed from. The external_user_id is the external_id in step 1
SELECT external_id as external_user_id
Then, export the result by selecting the ‘Audiences' data source.
Complete
Use the TD Console to Create Your Connection
Create a New Connection
In Treasure Data, before running your query, you must create and configure the data connection to be used during the export. As part of the data connection, you provide authentication to access the integration.
Login to TD Console.
Navigate to Integrations Hub > Catalog.
- Select the search icon on the far right of the Catalog screen, and enter Amazon DSP.
Hover over the Amazon DSP Data Provider connector and select Create Authentication.
The following dialog opens:Choose the Region of your advertiser account.
Enter your Advertiser ID. Then select Continue.
Enter a name for your connection.
Select Done.
Define your Query
1. Navigate to Data Workbench > Queries.
2. Select New Query.
3. Run the query to validate the result set.
Specify the Result Export Target
1. Select Export Results.
2. You can select an existing authentication or create a new authentication for the external service to be used for output. Choose one of the following:
Use Existing Integration
Create a New Integration
(Optional) Specify information for Export to Amazon DSP.
Parameter | Description |
---|---|
Data Source (required) | The data source could be audiences or hashed_records. |
Audience Name (required if the data source is audiences) | The name of the audience you would like to create. |
Audience Description (optional) | Description for your audience. |
External Audience ID (required if the data source is audiences) | Unique key for your audience. |
Time to live (required if the data source is audiences) | The time in seconds that the audience will stay valid. |
Operation (required if the data source is audiences) | The operation to perform on output data (add or remove). |
Ignore Invalid Records | If this check box is selected when the time data is sent to Amazon DSP, incorrect records or errors are skipped, and the remaining rows of data continue sending. If this checkbox is not selected, an exception is thrown when inaccurate records or errors are encountered. |
Column Name for the Query
The Amazon DSP Data Provider data connector understands and interprets only the following columns and data types. It would be best if you modified alias column names to match the following specified columns:
Column name | Type | Required | Description | ||
---|---|---|---|---|---|
Data Source: Audiences (require at least one of the below columns) | |||||
cookie | string | optional | a cookie Id sent from a data provider to Amazon by a cookie sync | ||
maid | string | optional | a mobile advertising identifier | ||
external_user_id | string | optional | an external id defined by data providers | ||
Data Source: Hashed_records (all bellow columns are required) | |||||
first_name | string | required | The first name | ||
last_name | string | required | The last name | ||
address | string | required | The street address | ||
phone | string | required | The phone number | ||
city | string | required | The city | ||
postal_code | string | required | The postal code | ||
state | string | required | The state or province | ||
string | required | The email address | |||
external_id | string | required | The external identifier for this record |
To export results:
Login to TD Console.
Navigate to Data Workbench > Queries.
Select the query that you plan to use to export data.
Example Audience Datasource:
SELECT a_cookie_column AS cookie, a_maid_column AS maid FROM your_table;
Example Hashed Records Datasource:
Note that all columns are required; you can use dummy data strings for fields where you do not have data.SELECT first_name_column AS first_name, last_name_column AS last_name, address_column AS address, phone_column AS phone, city_column AS city, postal_code_column AS postal_code, state_column AS state, email_column AS email, external_id_column AS external_id FROM your_table
Select Export Results, located at the top of your query editor.
The Choose Integration dialog box opens.
You have two options when selecting a connection to use to export the results:using an existing connection
creating a new one
Use an Existing Connection
Type the connection name in the search box to filter.
Select your connection.
Select Next.
Type values for Audience Name, Audience Description, External Audience ID, Time to live, and Operation, and Ignore Invalid Records.
Create a New Amazon DSP Data Provider Connection
Select Create New Integration.
Type a Name for your connection.
Select your region.
Enter your Advertiser ID.
Select Next.
Enter values for the Audience Name, Audience Description, External Audience ID, Time to live, Operation, and Ignore Invalid Records fields.
Select Done.
Use of Scheduled Jobs for Export
Scheduled Jobs with Result Export periodically writes the output result to a specific target destination.
Configure Export Results in Workflow
Example Audience Datasource
timezone: UTC _export: td: database: sample_datasets +td-result-into-target: td>: queries/sample.sql result_connection: your_connections_name result_settings: datasource: audiences region: NA advertiser_id: 12345 audience_name: This is a test audience audience_description: This is for testing purpose external_audience_id: test_audiences time_to_live: 3600 operation: Add ignore_error: false
Example Hashed Records:
timezone: UTC _export: td: database: sample_datasets +td-result-into-target: td>: queries/sample.sql result_connection: your_connections_name result_settings: datasource: hashed_records region: NA advertiser_id: 12345 time_to_live: 3600 ignore_error: false
To learn more about using data connectors in a workflow, refer to the Workflows section of the documentation.
Export Integration Using the CLI
You can also use TD Toolbelt CLI to export results to Amazon DSP.
It would be best to specify the information for export to your Amazon DSP server using the `--result` option of the `td query` command. For more information about `td query,` refer to TD Toolbelt Query Commands.
The format of the option is JSON, and the general structure is as follows:
|