Skip to main content

For Match Partners: Uploading CTV Data Files

LiveRamp's match partners can monetize Connected TV (CTV) data by uploading log files to LiveRamp via SFTP. To send CTV data to LiveRamp, perform the following tasks:

  1. Format the file.

  2. Test your hash function.

  3. Name the file.

  4. Upload the file via SFTP.

See the sections below for information on performing these tasks.

Format the File

Create a file that follows the guidelines listed below:

  • Deliver files in .psv (pipe separated value) or .csv (comma separated value) format, gzipped, with unix line endings.

  • Include all of the required columns listed in the table below.

  • The fields for “First Name” and “Last Name” are optional. If you do not have this data, you can either leave these fields blank or leave these fields out of the file as long as all files are consistent.

  • Provide all three hash types for email addresses. Make sure all email addresses are lowercased and all whitespace is removed before hashing.

  • Do not hash mobile device IDs.

  • Remove any duplicate records from your file.

  • If the file is larger than 4GB, split the file and give each file part a unique name. For more information, see the “Name the File” section below.

Note

LiveRamp highly recommends sending only IPv4 IP addresses. You can send IPv6 IP addresses but in most cases, we will not be able to match to those.

Column

Header Label

Definition

Example

Device ID

device_id

The device ID associated with the device (such as the CTV ID).

123e4567-e89b-12d3-a456-426655440000

ID Type

id_type

Device ID type, including (but not limited to) the following ID types:

  • “atv” (Apple TV ID) (we will filter these out)

  • “rida” (Roku)

  • “google_advertising_id”

  • “amazon_advertising_id”

  • “windows_advertising_id”

  • “chtv” (Chromecast)

  • “tifa” (Samsung)

  • “lg” (LG)

idfa

User Agent

user_agent

User Agent string of the device (optional field).

"iPhone 6; iPhone OS 9.2"

IP Address

ip_address

The IP address on which the TV device ID was observed.

70.212.10.74

Timestamp

timestamp

Unix Timestamp (seconds since Unix epoch) of when the user was active/logged in.

1455172609

MD5 Hash

md5_hash

Email address using MD5 hashing (optional field).

a010407ea27f6a9ccc70e5d149a7818f

SHA-1 Hash

sha1_hash

Email address using SHA-1 hashing (optional field).

3b31875f46abd81fb6c003d7a84492f6ef1b2d5e

SHA-256 Hash

sha256_hash

Email address using SHA-256 hashing (optional field).

7f0098da19b0f540dbcde477f969fec3e4d8b40f6d1686c6b24d4c2aaea48fea

Phone

phone

Plaintext phone number (optional field).

Use one of the allowed formats listed below:

  • +1XXXXXXXXXX

  • +1 (XXX) XXX-XXXX

  • (XXX) XXX-XXXX

  • XXX-XXX-XXXX

  • XXX XXX XXXX

  • XXXXXXXXXX

510-999-1111

First Name

first_name

Plaintext first name (optional field).

Maria

Last Name

last_name

Plaintext last name (optional field)

Espinosa

Opted-Out

opted-out

“1” indicates that the user has explicitly opted out (otherwise the value should be “0”). If “1”, all fields except Mobile Device ID and ID Type should be empty.

0

File Examples

Here is an example of what the header row should look like:

device_id|id_type|user-agent|ip_address|timestamp|md5_hash|sha1_hash|sha256_hash|phone|first_name|last_name|opted-out

A populated row might look like this:

AEBE52E7-03EE-455A-B3C4-E57283966239|IDFA|"Mozilla/5.0 (iPhone; CPU iPhone OS7_1_1 like Mac OS X) AppleWebKit/537.51.2 (KHTML, like Gecko) Version/7.0 Mobile/11D201 Safari/9537.53"|208.185.26.20|1441137534|3cb7232fcc48743000cb86d0d5022bd9|790d12777b2a83253a14c748a1b1cb09b3a91cca|899d3387a5c5a7555d51d2f0a0b7b50e397fe481fd9a58fafb389b7dc94e11f6|510-999-1111|Maria|Espinosa|0

Populating the User Agent

The user-agent string describes the software (app or browser) and device of a user. This field allows LiveRamp to perform additional validation on the mobile device IDs.

We recommend that you obtain the user agent with the codes below.

For Android devices:

final String userAgent = System.getProperty("http.agent");

For iOS devices:

NSString *userAgent;

{

struct utsname systemInfo;

uname(&systemInfo);

UIWebView *webView = [[UIWebView alloc] initWithFrame:CGRectZero];

NSString *baseAgent = [webView stringByEvaluatingJavaScriptFromString:@"

navigator.userAgent"];

NSString *hardware = [NSString stringWithCString:systemInfo.machine encoding:

NSUTF8StringEncoding];

userAgent = [NSString stringWithFormat:@"%@ [FBDV/%@;PPOSDK/%@]", baseAgent,

hardware, kPPOSDKVersion, nil];

}

Populating the Opted-Out Column

The opted-out column should be set to ‘1’ only if you have a policy that allows your mobile app users to explicitly opt out of data collection. Click here for an example of an opt-out policy.

Caution

Do not set the opted-out column to ‘1’ if you detect a ‘do not track’ or ‘limit ad tracking’ signal from the device or operating system. Do not send us any records for devices where you find ‘do not track’ or ‘limit ad tracking’.

Test Your Hash Function

Ensure all email addresses meet the requirements below before hashing:

  • The hash input is a valid, non-empty email address.

  • The email address is lowercased.

  • Any whitespace or extra text is removed from the beginning and end of the email address.

Caution

For privacy reasons, LiveRamp does not accept raw (plaintext) email addresses from match partners.

Hash the email address ‘Test@Foo.com’ to verify that your hash function is working properly. ‘Test@Foo.com’ should produce the following alphanumeric strings:

  • MD5: 3cb7232fcc48743000cb86d0d5022bd9

  • SHA-1: 790d12777b2a83253a14c748a1b1cb09b3a91cca

  • SHA-256: 899d3387a5c5a7555d51d2f0a0b7b50e397fe481fd9a58fafb389b7dc94e11f6

Name the File

Name your file using the exact naming syntax below.

match_{TIMESTAMP}.psv.gz

Caution

Files will be rejected from our servers if a different syntax is used.

"{TIMESTAMP}" = date and time on the Internet in RFC 3339 timestamp standard.

An example file name might look like this:

match_2015-10-28T15:04:05.psv.gz

If you need to split a file so that the file parts are not larger than 4GB, give each file part a unique name, such as the following syntax:

match_{TIMESTAMP}_part01.psv.gz

Renaming a File for Re-Upload

A LiveRamp account manager may ask you to re-upload a file if the first upload fails. When you re-upload a file, be sure to give it a unique name. Once we process a file successfully, we will not reprocess another one with the same name even if it is modified.

For example, if you re-upload a file called "match_2015-11-02T09:07:15.psv.gz", change the name to "match_2015-11-02T09:07:15_part02.psv.gz."

Upload the File

Use your SFTP credentials to upload the file via LiveRamp's SFTP.

Note

If you do not have credentials for the LiveRamp SFTP server, email the Match Network team at publisher-success@liveramp.com for assistance.

Tip

  • Upload your files daily to maximize your match rates and device reach.

  • We recommend using the open source client “Cyberduck”.

In this section: