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


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

email

string

required

The email address

external_id

string

required

The external identifier for this record

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:

{
  "type": "amazon_dsp_dp",
  "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,
  "ignore_error": false

}

  • No labels