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 and cookie columns must have the string data type.

• The maximum length for a cookie field is 1999 characters. 

Steps to create or remove an audience using PII information

1. Prepare a Hashed Records Datasource, including an external identifier

   1. 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: 

      1. External_id is the combination of advertiser_id and email: 

         SELECT SHA2(CONCAT(advertiser_id, email), 256) AS external_id FROM table_name;

      2. External_id is the combination of advertiser_id and phone: 

         SELECT SHA2(CONCAT(advertiser_id, phone), 256) AS external_id FROM table_name;

   2. Hashed records table (PII information): include email, name, phone number, …

2. Select the ‘hashed records’ data source the in the data connector configuration to send the above data to Amazon DSP for matching. 

3. 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.

4. Add to Audience or Remove from Audience:

   1. 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

   2. Then, export the result by selecting the ‘Audiences' data source.

5. 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.

1. Login to TD Console.

2. Navigate to Integrations Hub > Catalog.

3. Select the search icon on the far right of the Catalog screen, and enter Amazon DSP.

4. Hover over the Amazon DSP Data Provider connector and select Create Authentication.

   
         The following dialog opens:

5. Choose the Region of your advertiser account.

6. Enter your Advertiser ID. Then select Continue.

7. Enter a name for your connection.

8. 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.

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:

To export results:

1. Login to TD Console.

2. Navigate to Data Workbench > Queries.

3. 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 

4. Select Export Results, located at the top of your query editor. 

5. 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

1. Type the connection name in the search box to filter.

2. Select your connection.

   

3. Select Next.

4. 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

1. Select Create New Integration.

2. Type a Name for your connection.

3. Select your region.

4. Enter your Advertiser ID.

   

   
   

5. Select Next.

6. Enter values for the Audience Name, Audience Description, External Audience ID, Time to live, Operation, and Ignore Invalid Records fields.

   

7. 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: