Using a Universal File for Multiple Conversions API Programs
With LiveRamp's Partner Conversions API programs, you can often use one universal file for most or all of your conversion programs.
See the sections below for more information on using a universal file for your conversion data files.
Using the Universal File Template
To make things easier for you, we've created a universal file template that you can use.
Note
If you're sending non-PII-based data (such as data tied to RampIDs, AbiliTec IDs, MAIDs, or CIDs) to the Meta Conversions API for Offline Conversions Attribution Program, click here to download a sample template for that data.
Make sure you've reviewed the information in the "Situations That Require Additional Files" section above to see if you need to create more than one file or use a different template.
The template contains formatting instructions in the second row of the file, along with info on whether a column is required and whether values are required, depending on which conversion programs you're using. You can also refer to the information in the "List of All Universal File Columns" section below.
Download the file template by clicking here.
If desired, you can remove any non-required columns that aren't utilized by one of your conversion programs, but you can also leave those columns in the file and not populate them with values.
Transfer your data into the template.
After transferring your data into the file template, delete the second row with the formatting instructions.
Save the file as one of our allowed file types (.csv, .tsv, .psv, or .txt).
Upload the file to LiveRamp.
Situations That Require Additional Files
There are some situations where we recommend creating separate files or a completely new file. This is to ensure that there are no disruptions to your existing conversion feeds.
If you're working with any of the conversion programs listed below, you might need to create additional files or use a different file template:
Note
When you're sending multiple files, make sure to name each file distinctly so that it's easier for us to send the data to the correct programs.
The Trade Desk: If you have multiple values for the transaction category field, then you will need to create a separate file for each value. This is to ensure that LiveRamp does not remove any event data.
Facebook or Meta Conversions API Program for Offline Conversions:
If you're sending RampIDs, AbiliTec IDs, MAIDs, or CIDs, you need to send those in a separate file that does not include the PII columns. For Meta, you can download the non-PII identifier template for that data by clicking here.
If you're sending PII to the Facebook or Meta Conversions API Program for Offline Conversions and other programs, you can use the regular universal file template, which does not include the "maid" or "lr_id" columns.
Snapchat: If you are sending online conversion data, you will need to create a separate file for that online data, as the other conversion programs only allow offline conversion data.
File Format for the Universal File
See the sections below for information on formatting guidelines, information on using our universal file template, and a table that lists all possible columns you might include in your universal file.
Formatting Guidelines for the Universal File
Before sending your universal file conversion data to LiveRamp, make sure to strictly follow the guidelines listed below:
Note
If any guidelines listed here conflict with the guidelines in our general file formatting instructions, follow these guidelines.
Caution
If an uploaded file does not meet these requirements, you will need to reformat the file until it is formatted correctly.
Make sure to include all required columns with the exact column headers as shown.
Make sure to keep the columns up to and including the phone number columns in the exact order as shown. After those columns, the remaining columns can be in any order.
Provide the recommended values when possible. If you do not have values for a required field, include the column but with no values (do not include “N/A” or “null”).
Provide plaintext (raw) PII when possible because this is required for the programs that use a Passthrough Activation integration . For more information, see the "Situations That Require Additional Files" section above.
Provide your best email and phone for the user that you are trying to measure in columns “email_1” and “phone_1” (try to keep each column as close to a 100% fill rate as possible).
Not all programs utilize every column in the universal file. See the table in the "List of All Universal File Columns" section below to understand which programs use which fields so that you know which columns you can leave out.
Meta Conversions API for Offline Conversions: You will need to include only plaintext email addresses and/or plaintext phone numbers in the email and phone columns in the file.
Snapchat, OpenAI, or TikTok: These programs use our Passthrough Activation integration to pass through SHA256-hashed PII. You will need to include plaintext email addresses and/or plaintext phone numbers in the "email_1" and "phone_1" columns in the file so we can hash those values. You can also include hashed email addresses and/or phone numbers in the other email or phone columns, but these programs will not utilize them.
Google Store Sales: This program uses our Append integration to pass through SHA256-hashed PII and appends additional hashed PII if available within LiveRamp's Identity Graph. The data is then delivered to your Google Ads account. You will need to include plaintext email addresses and/or plaintext phone numbers in the "email_1" and "phone_1" columns in the file so we can hash those values. We recommend that you do not include additional email addresses and/or phone numbers in the other email or phone columns, but if you do include them, they will not be utilized.
If you're sending data on EMEA and/or UK consumers to Google Store Sales, you must also include the "ad_user_data" and "ad_personalization" columns listed in the "List of All Universal File Columns" section below. For all other regions, these columns are optional. For more info on Google's consent policy, see this Google article.
The file must be rectangular. That is, every row must have the same number of delimiters and columns of data.
List of All Universal File Columns
The table below lists all possible columns you might include in your universal file, along with the following information:
The columns that are always required
The columns that are required to pass product array or item-level data
The columns that are optional, but recommended to improve your conversion data's quality
The columns that are required in certain situations, based on the region of the data you're sending or the conversion programs you're using
Which columns are utilized by which conversion programs, when applicable
Formatting instructions for column values
Column Name | Column Required? | Required for Product Array? | Programs That Utilize This Field | Notes |
|---|---|---|---|---|
first_name | Required | Required |
| |
last_name | Required | Required |
| |
address_1 | Recommended | Recommended |
| |
address_2 | Optional | Optional |
| |
city | Recommended | Recommended |
| |
state | Recommended | Recommended |
| |
zip | Recommended | Recommended |
| |
email_1 | Required | Required |
| |
email_2 | Optional | Optional |
| |
email_3 | Optional | Optional |
| |
email_4 | Optional | Optional |
| |
Country | Optional | Optional |
|
|
Region | Optional | Optional |
|
|
phone_1 | Recommended | Recommended |
| |
phone_2 | Optional | Optional |
| |
transaction_category | Required | Required |
| |
transaction_timestamp | Required | Required |
| |
transaction_amount | Required | Required |
| |
order_id | Required | Required |
| |
item_number | Optional | Required |
|
|
quantity | Optional | Required |
|
|
product_id | Optional | Required |
|
|
store_id | Optional | Optional |
|
|
product_name | Optional | Required |
|
|
promo_code | Optional | Optional |
|
|
product_category | Optional | Recommended |
|
|
product_subcategory | Optional | Optional |
|
|
product_variant | Optional | Optional |
|
|
product_brand | Optional | Recommended |
|
|
event_conversion_type | Optional | Optional |
| Applicable for Snapchat only, and only if sending online data. Use one of the following source types:
|
is_new_customer | Optional | Optional |
|
|
product_price | Optional | Required |
|
|
GTIN | Optional | Optional |
|
|
department | Optional | Optional |
|
|
custom_field | Optional | Optional |
|
|
data_processing_options | Recommended | Recommended |
|
|
data_processing_options_state | Recommended | Recommended |
|
|
data_processing_options_country | Recommended | Recommended |
|
|
ad_user_data | Recommended | Recommended |
|
|
ad_personalization | Recommended | Recommended |
|
|
event_source_URL | Optional | Optional |
|
|
event_name | Required | Required |
| |
currency | Optional | Required |
|
|
client_user_agent | Optional | Optional |
|
|
total_transaction_amount | Optional | Optional |
|
|
merchant_id | Optional | Optional |
|
|
merchantFeedLabel | Optional | Optional |
|
|
merchantFeedLanguage | Optional | Optional |
|
|