This document describes the integration details for Custom Audiences CRM partners including file formats & data exchange process.

Summary

Company will provide a list of hashed common user identifiers (i.e. e-mail addresses) or partner user IDs on behalf of a customer to Twitter to perform a blind match and produce a list of Twitter User IDs for targeting. The segments for targeting will be made available to the advertiser’s specific @handle specified by the filename in ads.twitter.com campaign setup.

All files from Company will be provided to Twitter through a secure package on IronBox (www.golockbox.com) through a specific account granted to Company by Twitter. Twitter will provide access to IronBox. Documentation on IronBox APIs can be found at https://secure.goironcloud.com/Docs/Help/.

Partner ID Matching Requirements

If company uses its own standard ID system to track users (i.e. not common user identifiers like email addresses, device ids, twitter user ID, etc...) then this is the recommended process.

1. Full Data match

Initially, Company will provide a comprehensive list of all user records which include a unique common user identifier with Twitter in a single file to perform a full data match and produce a mapping stored by Twitter of Partner IDs (p_user_id) to Twitter IDs (tw_id). This will be done on a 2-3 month basis regularly to ensure proper upkeep. Once the match is completed, Twitter will share a baseline match rate from this file with Company via e-mail.

The format of this file should be:

Name Convention: FullDataMatch.[CompanyName].txt

Hashing Algorithm: HMAC_SHA-256

Format:

Column 1: HMAC hashed value of common identifiers

Column 2: Partner User ID (unique per user, non-unique in file)

Column Delimiter (CSV): Commas will be used to delimit the hashed common user identifier from the Partner ID

Line separated values

• Ex: If user record A has Partner User ID 1 and common identifier 1, 2 and 3:

*See Hashing Directions section for common user identifiers below

2. Custom Segment Lists

Company will provide lists of users in the form of p_user_id to create custom audiences for customers for targeting on Twitter.

• Line separated values
• p_user_id
• • (Same as provided in 1. Full Data Match section above. If the value provided in full data match is hashed then Company will provide same hashed value in audience file. If value provided is not hashed then Company will provide unhashed value.)

Standard Matching Requirements

If company does not use a standard ID for mapping of all customer user identifiers, this is the recommended process.

Custom Segment Lists

Company will provide lists of hashed common user identifiers directly to Twitter on behalf of customers to to create custom audiences.

The format of this file should be:

• Line separated values
• Hashed common user identifier (i.e. e-mail address)
• Follow file naming conventions outlined below
• Follow hashing directions for e-mail addresses below (in Hashing Directions)

Custom Segment List File Naming & Operations

The operation of a file will be dictated by the name of the file with the following available operations and general file naming convention: audiencename_partnername.handle.operation.filetype

• audiencename: The name of the Custom Audience. This field is the name that will be displayed when selecting the audience in the ads.twitter.com campaign setup UI e.g. brand_loyalty_card_holders.
• partnername: Name of the company delivering the data on behalf of advertiser e.g. company_name.
• handle: Twitter Account (@handle) that will have access to Custom Audiences e.g. @pepsi, @dietpepsi
• operation: new, add, remove, removeall, replace (details below)
• : Standard Unix epoch time in seconds, used to ensure that each audience file uploaded is unique
• filetype: file should be in *.txt format

Creating and Updating Audiences

Create a new audience with a single file e.g. loyalty_card_holders_partnername.pepsi.new.txt

Add - Add the matches from a list to an existing audience e.g. loyalty_card_holders_partnername.pepsi.add..txt

Remove - Remove the matches from a list from an existing audience Ex: loyalty_card_holders_partnername.pepsi.remove..txt

Remove All - Remove the matches produced from a regularly updated cumulative list from all audiences for that client (i.e. Client’s Opt Out List). Ex: partnername.pepsi.removeall.txt

• This can be used for a comprehensive list of users who have opted-out from the Advertiser.
• Twitter will only respect the latest list provided in this file, and will respect across all existing and future audiences for matched.

Twitter users at the time this file was provided & processed.

Replace - Remove an existing audience and replace it with a new audience list. Ex: loyalty_card_holders_partnername.pepsi.replace..txt

Overall Company Opt-Out - Company will provide a cumulative Opt-Out file to remove users that have opted out as per the Company’s Opt-Out policy.

Twitter will only respect the latest list provided in this Company Opt-Out file and will respect across all existing and future audiences for matched Twitter users at the time this file was provided & processed. The format of the Company Opt-Out file will be as follows: Ex: partnername.removeall.txt

Delete - Remove an existing audience from the current list of audiences e.g. Ex: loyalty_card_holders_partnername.pepsi.delete.txt

Hashing Directions

Twitter will securely share a base64 encoded production key via PGP for hashing common user identifiers (i.e. email addresses). Company will base64 decode the key to produce a 32-byte key to be used to perform the hashing.

Example base64 encoded key:

BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM=

Example Base64 decoded key:

/:� TшY

Normalization: Company will perform basic normalization on the common user identifiers before hashing (except on Device IDs, see Device ID Normalization section).

E-mail Normalization

Namely, strip out the leading and trailing spaces and also lowercase the email address.

Ex: Raw e-mail address: testemail_Organisational_baseball+884@It92I6Ev2B.Com

After normalization: testemail_organisational_baseball+884@it92i6ev2b.com

Hashed value: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec

Note: The specific number of characters for both the encoded hmac and key could vary based on the input and the encoding so the specific number of characters.

Device ID Normalization

We will have the same requirements for hashing of device IDs using a SHA-256 hashing algorithm and a common salt that we provide to data partners. We strip out spaces like we do with email addresses, but there is no lowercase normalization for IDFAs/Android IDs and the exact format of the IDFA/Android ID should be used.

Here is example raw format of Device IDs for iOS & Android, pre-hashing:

iOS IDFA: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431

Android ID: b5bf2122961b3595

Hashed iOS IDFA: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b

Hashed Android ID: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

Twitter User ID Normalization

Twitter IDs will still be hashed as the grouping of data - ie Customer List of @handles - is private to the advertiser even though it is not PII. We will have the same requirements for hashing of Twitter IDs using a SHA-256 hashing algorithm and a common salt that we provide to data partners. Spaces should be stripped out of both the Twitter ID/@username, but User IDs do not require normalization. @usernames should be lowercased for normalization. And the @ symbol should not be included as part of the username.

The raw ID format will be:

• User ID: 27674040
• @username: testusername

Hashed User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85

Hashed @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812