Skip to main content

Enable CTV Targeting by Sending CTV Event Files

To send us CTV event data for Connected TV (CTV) activity data, the guidelines for creating files are somewhat different than our standard file formatting guidelines.

Caution

CTV data only! IP address data can only be used for matching CTV data. IP addresses cannot be included as identifiers for other matching types.

Review those guidelines and the guidelines below to create your files, and then upload the files via your LiveRamp SFTP account.

Note

Want to send us CTV event data via pixel calls? See "Enable CTV Targeting by Sending CTV Events via Pixel" for more information.

LiveRamp's IP address-based matching is most effective when you send every action you log for a given device. Send files with one timestamp per row for every recorded action.

For IP address-based matching, file rows should contain a TV device ID, IP address, timestamp, and either a user agent or device type.

Note

What about rows without a TV device ID? We understand there might be rows in your data that do not have a TV Device ID. You do not need to filter those rows out before sending to LiveRamp.

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.

Include only the columns listed below in the order shown. Remove any additional columns from your file before sending it.

Field

Value Required?

Definition/Notes

Example

TV Device ID (IFA)

Yes (when present)

The persistent TV device ID that is tied to the physical device. A TV device ID is also categorized as a "Custom ID" or "(CID)"; a Connected TV device IFA falls into this category.

If there is no TV device ID present, you can leave the TV Device ID field blank. We will not perform IP address matching on rows that do not include a TV device ID.

“123e4567-e89b-12d3-a456-426655440000”

IP Address

Yes

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

LiveRamp prefers plain text (raw) IP addresses. Where required, LiveRamp can accept SHA1-hashed IP addresses. IP addresses should be converted to integers before hashing to avoid problems with hashing IP addresses as a string.

“11.12.13.14”

Timestamp UTC

Yes

The UNIX timestamp of when the TV device ID was observed on the associated IP address.

“1524252104”

User Agent

Yes (if no Device Type or ID Type present)

The HTTP string that helps a hosting server identify the type of operating system and/or device requesting content. This string should be from the user’s device, not a proxy server.

“Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_1) AppleWebKit/604.3.5 (KHTML, like Gecko) Version/11.0.1 Safari/604.3.5”

Device type and/or ID type

Yes (if no User Agent present or when distributing data to Freewheel)

The device type and/or ID type for the CTV device.

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

  • “rida” (Roku)

  • “other”

  • “google_advertising_id”

  • “amazon_advertising_id”

  • “windows_advertising_id”

  • “chtv” (Chromecast)

  • “idfa”

  • “tifa” (Samsung)

  • “lg”

Data Row Example

123e4567-e89b-12d3-a456-4266554400 |100.0.139.72|1532474112|Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_1) AppleWebKit/604.3.5 (KHTML, like Gecko) Version/11.0.1 Safari/604.3.5

  • Use a flat, text-based format (see “Allowed File Types”).

  • We highly recommend using pipes as the delimiter: We do accept comma-delimited and tab-delimited files but see more data formatting errors with those two formats.

    Note

    If any of the data contains a delimiter character (like a comma), enclose the data with quotation marks.

  • Files must be rectangular: Every row should contain the same number of delimiters and fields.

    Note

    If a given field has no value, simply leave that value empty for that row.

  • Don’t include headers: In contrast to LiveRamp standard formatting guidelines, do not include headers.

  • Use consistent filenames: LiveRamp's recommended naming convention for IP address-based files is

    "<Partner_Name>_IP_LiveRamp_YYYYmmdd-HHMMSS.txt_<part####>" (see “Naming Files for Uploading” for additional guidelines).

  • Use UTF-8 encoding: Make sure to save your files with UTF-8 encoding before uploading them.

  • Repeat file deliveries: If you choose to use LiveRamp for ongoing TV ID matching, we need a recurring file delivery (we recommend weekly, but this can be as often as hourly or as infrequently as quarterly). Files should not contain duplicate data (e.g., one day’s worth of data should not be in two or more different files).

Other Options

  • Compression: Files can be compressed (see “Compressing Files for Uploading”).

    Note

    The tar compression format is not allowed for IP address-based files.

  • Encryption: Files can be encrypted (see “Encrypting Files for Uploading”).

  • Splitting files into parts: LiveRamp recommends splitting files larger than 2GB into 1GB or smaller parts to speed up the upload process and provide redundancy in event of an upload failure.

Once your files have been created, upload the files to LiveRamp via any of our allowed methods (see "Getting Your Data Into LiveRamp" for more information).

Note

If uploading files via LiveRamp's SFTP, files should be uploaded to the following subdirectory: /uploads/ip_logs/. Contact your LiveRamp representative for credentials if an SFTP directory does not already exist for your account.

Once files have been uploaded, it typically takes 2-3 weeks to ingest the data before the files appear in Connect.