Skip to main content

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:

  1. You create an Offline Event Set in TikTok Ads Manager using TikTok's instructions.

  2. You send a sample conversion data file, your TikTok Ads Manager Account ID, and your Offline Event Set ID to your LiveRamp technical representative.

  3. You activate your campaign(s) on TikTok and then assign your campaigns to the Offline Event Set ID using TikTok's instructions.

  4. 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.

  5. 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.

  6. LiveRamp normalizes and hashes the plaintext email addresses and phone numbers in your conversion data file.

  7. LiveRamp passes your conversion data file through TikTok’s Events API.

  8. TikTok matches the hashed email addresses and phone numbers from your conversion file to TikTok’s universe.

  9. 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.

C-TikTok_Offline_Tracking-DA_tile.png

TikTok Events API destination account tile

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:

C-TikTok_Offline_Tracking-DA_configuration.png

TikTok Events API destination account configuration

  1. Remove the end date to leave the end date open ended.

  2. 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=").

    C-TikTok_Offline_Tracking-TikTok_account_ID.png

    Note

    Contact your TikTok account representative if you’re unsure of which value to use.

  3. 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.

  4. To use one of your existing TikTok OAuth connections, select it from the OAuth Connection drop-down list and click Validate OAuth Connection.

    Note

    If you use an existing connection, you do not need to perform the remaining steps.

  5. To create a new OAuth connection and validate that connection:

    1. From the OAuth Connection drop-down list, select + New TikTok OAuth Connection.

    2. After the TikTok for Business login dialog appears, enter your credentials and then click Log in.

      C-Perform_OAuth_TikTok-login.png

    3. From the dialog that appears, click Confirm.

      C-Perform_OAuth_TikTok-confirm_button.png

      Note

      Do not uncheck any of the check boxes.

    4. From the destination account configuration screen, click Validate OAuth Connection.

Format the Conversion File Data

Before sending your conversion data to LiveRamp, make sure to strictly follow the guidelines listed below:

Note

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

  • Include values in this column if you have additional street address info for a given row.

city

No

No

state

No

No

  • If including State, must be a two-character, capitalized abbreviation ("CA", not "California" or "Ca").

zip

No

No

  • If including ZIP codes, ZIP codes can be in 5-digit format or 9-digit format (ZIP+4).

email_1

Yes

Yes (if using email as an identifier)

  • Must be plaintext.

  • If you have multiple emails for a consumer, send your best one in the “email_1” column.

email_2

No

No

  • Must be plaintext.

email_3

No

No

  • Must be plaintext.

email_4

No

No

  • Must be plaintext.

transaction_category

Yes

Yes

  • The field for tracking transactions by conversion category.

  • TikTok accepts the following conversion category values:

    • CompletePayment

    • Contact

    • Subscribe

transaction_timestamp

Yes

Yes

  • Corresponds to the date/time of transaction in UTC - (example “2017-02-07T13:25:00Z-0800" should be the time the conversion happened in UTC).

  • Standard formats:

    • yyyy-MM-dd

    • yyyy-MM-dd'T'HH:mm:ss'Z'-0000 (for example, 2021-06-04T10:01:00Z-0000)

  • Additional formats:

    • MM/dd/yyyy h:mm:ss aa

    • MM,dd,yyyy h:mm:ss

    • MM/dd/yyyy HH:mm:ss

    • yyyy-MM-dd HH:mm:ss

    • yyyy-MM-dd'T'HH:mm:ss

    • yyyy-MM-dd HH:mm:ssZ

transaction_amount

Yes

Yes

  • The transaction amount.

  • Do not include any (currency) symbols.

  • Format required: XXX.XX

phone_1

No

Yes (if using phone as an identifier)

  • Do not include any punctuation, such as hyphens, plus signs, or parentheses.

  • Must be plaintext.

  • If you have multiple phone numbers for a consumer, send your best one in the “phone_1” column.

phone_2

No

No

  • Do not include any punctuation, such as hyphens, plus signs, or parentheses.

  • Must be plaintext.

order_id

No

No

  • A unique ID (such as a transaction ID) that corresponds to the order that the particular item belongs to (this is often referred to as an “ordinal”). If the value is not unique, a partner may deduplicate some of these events when ingesting your conversion data.

  • Must be included if you are providing item/sku-level transaction data.

  • To measure item-level events, the value will need to be a unique value for each item within a basket. LiveRamp recommends using the concatenated value of the order ID + product SKU. For example, if the order ID is “123” and SKU is “456”, the “order_id” value would be “123456”.

  • Do not include special characters, currency symbols, or commas.

store_code

No

No

  • The “store ID”. A unique ID that you assign to each of your store locations.

  • Must not be longer than 64 characters.

  • No special characters (i,e., "<" or ">") and must not contain a URL.

quantity

No

No

  • The number of items purchased.

product_id

No

No

  • An alphanumeric value delineating a unique item in an order, such as a SKU or UPC. For example, if three socks are purchased in one transaction, you could have three transaction rows with different product IDs for each pair of socks but the same order ID.

  • Do not include special characters, currency symbols, or commas.

product_name

No

No

  • Short name of the product.

product_category

No

No

  • Top-level category of the product.

product_brand

No

No

  • Brand name of the product.

product_price

No

No

  • The product price.

  • Do not include currency symbols (for example, “XX.XX”).

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.

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.

In this section: