The TikTok Events API Program for Offline Conversions
With the TikTok Events API Program for Offline Conversions, you can measure how your TikTok ads result in offline customer actions (such as in-store purchases).To help you understand the effectiveness of your ad campaigns, TikTok matches your uploaded offline events with metrics from people who saw or clicked on your ads on TikTok.
You can use this program to perform the following actions:
View measurement insights and cross-channel attribution with campaign metrics on offline customers actions
Measure the offline return on your ad spend
Note
TikTok must approve all program participants. Contact your LiveRamp or TikTok representative to find out about getting approved for the TikTok Events API Program for Offline Conversions.
The TikTok Events API Program for Offline Conversions is part of LiveRamp's Conversions API program.
The TikTok Events API Program for Offline Conversions was formerly known as "the TikTok Offline Tracking Program".
Overview of Steps Involved
The following steps need to be performed to enable the attribution analysis on TikTok:
You create an Offline Event Set in TikTok Ads Manager using TikTok's instructions.
You send a sample conversion data file, your TikTok Ads Manager Account ID, and your Offline Event Set ID to your LiveRamp technical representative.
You activate your campaign(s) on TikTok and then assign your campaigns to the Offline Event Set ID using TikTok's instructions.
You grant LiveRamp the ability to deliver data to your TikTok’s Ads Manager Account by creating a TikTok Events API destination account and by performing OAuth authorization in LiveRamp Connect.
You upload conversion data from the last 28 days containing plaintext email addresses and phone numbers to LiveRamp.
Note
The lookback window will be based on the conversion rule you create in TikTok Campaign Manager. Tiktok only allows a maximum lookback window of 28 days for an offline conversion rule. As a result, make sure the transactions in your file are not older than 28 days from the current day.
LiveRamp normalizes and hashes the plaintext email addresses and phone numbers in your conversion data file.
LiveRamp passes your conversion data file through TikTok’s Events API.
TikTok matches the hashed email addresses and phone numbers from your conversion file to TikTok’s universe.
You view the results within TiKTok’s Campaign Manager (results available within 24 hours).
See the appropriate sections below for more information on performing these steps.
Perform Activities in TikTok Ads Manager
Use TikTok's instructions to perform the following activities:
Create an Offline Event Set
Note
Once you’ve created the Offline Event Set, provide your LiveRamp technical representative with the Offline Event Set ID, as well as your TikTok Ads Manager Account ID and a sample conversion data file (for information on preparing the sample file, see the "Format the Conversion File Data" section below).
Associate the Offline Event Set to existing campaigns
Note
You can also enable auto tracking, so that any new campaigns created under this advertiser account will use this event set for ad tracking and attribution.
Create a TikTok Events API Destination Account
To distribute offline conversions data, a TikTok user who has Admin-level access to your TikTok Ads Manager Account will need to activate a TikTok Events API - Offline destination account in Connect.
During destination account activation, you will need to perform OAuth authorization, either by selecting an existing OAuth connection that you own or by creating a new connection. This grants LiveRamp access to your TiKTok Ads Manager account in order to deliver data to your account.
Follow the general instructions in "Activate a New Destination Account”, performing these additional steps:
Remove the end date to leave the end date open ended.
Enter your TikTok account ID in the Account ID field. This ID can be found in the URL when logged into Ads Manager (after "aadvid=").
Note
Contact your TikTok account representative if you’re unsure of which value to use.
In the Destination Account Name field, pick a unique and memorable name for this account. We'll suggest one for you but you can use any name you wish as long as it is less than 50 characters in length.
To use one of your existing TikTok OAuth connections, select it from the OAuth Connection drop-down list and click
.Note
If you use an existing connection, you do not need to perform the remaining steps.
To create a new OAuth connection and validate that connection:
From the OAuth Connection drop-down list, select + New TikTok OAuth Connection.
After the TikTok for Business login dialog appears, enter your credentials and then click Log in.
From the dialog that appears, click Confirm.
Note
Do not uncheck any of the check boxes.
From the destination account configuration screen, click
.
Format the Conversion File Data
Before sending your 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.
If you're using multiple programs, you can often use one universal file for most or all of those programs. For more information and a universal file template, see "Using a Universal File for Multiple Conversions API Programs".
Caution
If an uploaded file does not meet these requirements, you will need to reformat the file until it is formatted correctly.
Headers must be included in the exact order as listed below and must match exactly.
To be passed through to TikTok, each record must contain at least one plaintext email address or phone number.
This program uses our Measurement Enablement workflow. Make sure to follow our recommended file limits for Measurement Enablement workflow files (such as a maximum of 500,000,000 rows per file and a maximum uncompressed file size of 50 GB).
Your conversion data file must use one of our allowed delimiters (commas, tabs, or pipes), and be one of our allowed file types (.csv, .tsv, .psv, or .txt).
Include all of the required columns listed below.
Fields must not have leading or trailing white space.
Unless values are required for a field, fields can be left blank if there is no data for the given row (do not include “N/A” or “null”).
The file must be rectangular. That is every row must have the same number of delimiters and columns of data.
Tip
To download an Excel file template that contains all possible columns and formatting instructions, click here.
After transferring your data into the file template, be sure to delete the row with the formatting instructions and save the file in one of our allowed file types (.csv, .tsv, .psv, or .txt) before uploading.
Once the file has been formatted correctly, upload the file to LiveRamp. See the “Upload the File” section below for more information.
Note
Once you set up the file format for an existing conversions program feed, try to keep the file format (such as the column headers or the column order) the same for all subsequent files. If you change the file format for an existing feed, create a support case before uploading the new file to ensure your existing feeds are not impacted. For more information, see "Changing the Format of an Existing File".
List of All File Columns
See the table below for a list of columns and formatting instructions:
Field Name | Column Required? | Values Required? | Notes |
---|---|---|---|
first_name | No | No | |
last_name | No | No | |
address_1 | No | No | |
address_2 | No | No |
|
city | No | No | |
state | No | No |
|
zip | No | No |
|
email_1 | Yes | Yes (if using email as an identifier) |
|
email_2 | No | No |
|
email_3 | No | No |
|
email_4 | No | No |
|
transaction_category | Yes | Yes |
|
transaction_timestamp | Yes | Yes |
|
transaction_amount | Yes | Yes |
|
phone_1 | No | Yes (if using phone as an identifier) |
|
phone_2 | No | No |
|
order_id | No | No |
|
store_code | No | No |
|
quantity | No | No |
|
product_id | No | No |
|
product_name | No | No |
|
product_category | No | No |
|
product_brand | No | No |
|
product_price | No | No |
|
Header Row Example
The headers shown below are all required.
email_1|transaction_category|transaction_timestamp|transaction_amount
Conversion Data Examples
alex@gmail.com|In Store|2014-03-31|99.99
julian@gmail.com|Offline|2014-03-30|55.55
Send Conversion Data to LiveRamp
To set up the integration, send us a sample conversion data file. This file should contain at least 25 rows and each row should have values for the required fields (you can use placeholder data). Include all the possible values you plan on using in the “transaction_category” field and include only those values in subsequent files.
Once your campaign has started, send conversion data to LiveRamp at your preferred cadence. Files can be delivered at any cadence (daily, weekly, monthly, etc.), but do not send more than one file per day. LiveRamp’s preference is daily or weekly.
Conversion Data Guidelines
To be passed through to TiKTok, each conversion data record must include a plaintext email in the “email_1” field or a phone number, along with the required conversion data listed below:
Transaction category
Transaction timestamp
Transaction amount
The entries in all other PII columns will be ignored. Only the email addresses and phone numbers will be passed through to TikTok after hashing.
Make sure to also follow these additional guidelines:
Avoid sending duplicate transactions (transactions already sent to LiveRamp). If you send weekly or monthly files, only send transactions that occurred since the previous file was sent.
Do not include transactions that exceed the lookback window.
Note
The lookback window will be based on the conversion rule you create in TikTok Campaign Manager. Tiktok only allows a maximum lookback window of 28 days for an offline conversion rule. As a result, make sure the transactions in your file are not older than 28 days from the current day.
If you’re repurposing a conversion data file from another LiveRamp conversions program you do not have to remove any additional PII fields from the file. For example, if a record has name and postal information, as well as email address, you can leave the name and postal information in that record.
Do not include conversions with a conversion date in the future.
Upload the File
Upload conversion data files using LiveRamp’s SFTP server or your SFTP server.
You can also have us pull files from an AWS S3 bucket or GCS bucket. See “Getting Your Data Into LiveRamp” for more information.
Caution
Files for this program cannot be uploaded via Connect. We recommend either uploading via our SFTP server or having us pull files from an S3 bucket.
To upload files using LiveRamp's SFTP: Use the credentials provided by your technical contact once the agreement has been signed and follow the instructions in “Upload a File via LiveRamp's SFTP”.
To upload files using your SFTP: Follow the instructions in “Upload a File via Your SFTP”.
After uploading, email your LiveRamp technical account specialist to confirm that you have uploaded conversion data.
Once the file is uploaded, information on file processing status can be viewed in Connect (see "Check File Processing Status" below for more information).
Once the file has finished processing, the data will be viewable within TikTok Ads Manager.
Check File Processing Status
You can check the status of the files you've uploaded on the Files page in Connect. See "Check the Status of an Uploaded File" for complete instructions.
Note
Once you've uploaded a file, it can take up to 20 minutes before the file appears associated with the appropriate audience(s) on the Files page. If the file does not appear after at least 20 minutes, create a support case.
Files for this program use our Measurement Enablement workflow, and so the column headings that display on the Files page will look different from the ones that display for files that use our Activation workflow.
Because the PII in the files is passed through (and not matched), the recognition rate will be zero.
When you open the details pane on the Files page, all of the stats for RampIDs will always show “0” since we are simply passing through the PII and not matching to RampIDs.
FAQs
At what cadence should I send my conversion data files?
LiveRamp can receive conversion data files for this program on a daily, weekly, or monthly basis, but we highly suggest automated daily or weekly delivery.
What conversion data should I include in my conversion data file?
Include all traceable transactions in your delivery.
Avoid sending duplicate transactions (transactions already sent to LiveRamp). If you send daily files, only include transactions that occurred on that day. If you send weekly or monthly files, only send transactions that occurred since the previous file was sent.
Do not include transactions with a transaction date in the future.
What does adding auto tracking to an event set ID do?
Adding auto tracking will track all future campaigns from your TikTok ad account to use this offline event set for ad tracking and attribution.