Documentation

TikTok

Suggest Edits

What Is TikTok?

TikTok for Business is a global platform designed to give brands and marketers the solutions to be creative storytellers and meaningfully engage with the TikTok community.

Streamline TikTok customer data streaming with MetaRouter's unified tracking tag. Easily route your website and mobile events to TikTok to create advertising audience segments, measure campaign performance, and attribute conversions to ads that your customers have viewed on TikTok.

What are the benefits of integrating MetaRouter with TikTok for Business?

  • Enables TikTok tag removal.
  • No effect on website load latency.
  • Ensures event data is streaming into TikTok for Business for accurate ad decisioning and measurement.

Capabilities and Considerations

  • This integration uses the TikTok Events 2.0 API as the main connector.
  • Starter-kit is default to web events. For event sources outside of web events, please check TikTok’s API Reference to ensure all required and recommended parameters are included for the event source.
  • Event Tracking: Capture key user interactions like page views, purchases, and sign-ups server-side, ensuring data accuracy.
  • Conversion Tracking: Measure conversions (e.g., purchase) effectively using server-side data.
  • Attribution: Maintain campaign attribution by sending necessary data (e.g., ttclid) through the API.
  • Audience Targeting: Create custom audiences and retarget users based on server-side events.

Limitations

  • Behavioral Tracking: The range of tracked behaviors is less comprehensive compared to pixel tracking, which captures more granular user interactions.
    • The TikTok pixel can track user behaviors like page scroll depth, hover actions, and clicks on expandable product descriptions. Server-side tracking typically only captures high-level events like page views or form submissions.
  • Creative Interaction Data: Server-side tracking may lack the detail provided by the pixel regarding user engagement with ad creatives.
    • Pixel tracking can capture how long a user watches a video ad, whether they mute it, or if they click on a "Shop Now" button within the ad. Server-side tracking usually only registers whether the user clicked a link, missing these finer interaction details.
  • Audience Insights: Insights may be less detailed compared to those obtained through the pixel.
    • The pixel can provide detailed insights such as which ad elements users interacted with most or the specific paths they took on your website before converting. Server-side tracking may not capture the full sequence of these interactions.

Getting Started - From Your TikTok Ads Manager Account

Determine the Event Source for the event_source field:

  • web: The events took place on your website and are measured by a Pixel Code.
    • The default value in the starter-kit is web.
  • app: The events took place on your app and are measured by a TikTok App ID.
  • offline : The conversions took place in a physical store and are measured by an Offline Event Set ID.
  • crm: The lead events took place in a CRM system and are measured by a CRM Event Set ID.

Note: Reporting App Events using Events API 2.0 is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.

Acquire the following keys and IDs:

  • Access Token - Please see here for instructions.
  • Event Source ID - When event_source is set to web, specify a Pixel Code through this field. To obtain a Pixel Code, refer to FAQs - Where can I find the Pixel Code. Please note that the default starter-kit is set to web.
    • When event_source is set to offline, specify an Offline Event Set ID through this field.To obtain an Offline Event Set ID, refer to Setup Guide for Offline.
    • When event_source is set to app, specify a TikTok App ID through this field.To obtain a TikTok App ID, refer to Setup Guide for App.
    • When event_source is set to crm, specify a CRM Event Set ID through this field.To obtain a CRM Event Set ID, use /crm/list/.

Getting Started - From Your MetaRouter Account

Adding a TikTok integration.

From the integration library, add a TikTok integration. Then, fill out the Connection Parameters:

Connection ParameterDescription
API_VERSIONDefault v1.3
ACCESS_TOKENTikTok access token.
EVENT_SOURCEDefault web. Please see above for references to offline, app, or crm event sources.
EVENT_SOURCE_IDFor web event source, please use Pixel Code. If using another event source, please refer to the details above.

Adding a TikTok Sync

To gather the ttclid value and the ttp value, you must add a TikTok sync.

  1. From the Pipelines page, find the pipeline associated with the web property you’d like to add a sync to. Hover over the three dot dropdown and select “Build AJS File.”
  2. In the Identity Syncs section, select the TikTok sync.
  3. Fill out the following fields:
    1. Consent Category
    2. Cookie Time to Live - Default 7 days
    3. Pixel ID - Your Pixel Code as mentioned in the steps above.
  4. Scroll down and click the Save and Build File button.
  5. Deploy your AJS file to propagate changes to your web property.

Event Mappings

MetaRouter provides all of the event mappings that TikTok integrations typically require. You may add custom events, parameters or mappings in accordance with TikTok’s API documentation.

Global

Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.

Output KeyDescriptionExpected Input
partner_name
Required		String: Represents that the data is being sent by MetaRouter.Mr
event_id
Required		String: A unique identifier for the event.N/A - Expression
event_time
Required		Integer: The timestamp of the event in milliseconds.N/A - Expression
page.urlString: The URL of the webpage where the event occurred.context.page.url
page.referrerString: The referrer URL that led to the event.context.page.referrer
user.ttclidString: TikTok Click ID, used to track the origin of the user.context.providers.tiktok.ttclid
user.ttpString: TikTok pixel ID for tracking user sessions across devices.context.providers.tiktok.ttp
user.external_idString: An ID provided by the advertiser, used to match users across different systems.anonymousId
user.emailString: The user's email address, hashed using SHA-256.N/A - Expression
user.phoneString: The user's phone number, hashed using SHA-256.N/A - Expression
user.ipString: The IP address of the user at the time of the event.context.ip
user.user_agentString: The user agent of the user at the time of the event.context.userAgent

Event Specific

Page

Output KeyDescriptionExpected Input
event
Required		String: The type of event, such as 'ViewContent'.Enrichment - 'ViewContent'
properties.descriptionString: A description of the page.Enrichment - 'Page Description'

Products Searched

Output KeyDescriptionExpected Input
properties.query
Required		String: The search query entered by the user.properties.query
event
Required		String: The type of event, such as 'Search'.Enrichment - 'Search'

Product List Viewed

Output KeyDescriptionExpected Input
properties.currencyString: The currency of the transaction.properties.currency
properties.valueInteger: The total value of the products viewed.N/A - Expression
properties.contentsArray: Details of the products viewed.N/A - Expression
event
Required		String: The type of event, such as 'ViewContent'.Enrichment - 'ViewContent'
properties.descriptionString: A description of the product list viewed.Enrichment - 'product list viewed'
properties.content_typeString: The content type, e.g., 'product'.Enrichment - 'product'

Product Viewed

Output KeyDescriptionExpected Input
properties.currencyString: The currency of the transaction.properties.currency
properties.valueInteger: The value of the product viewed.N/A - Expression
properties.contentsArray: Details of the product viewed.N/A - Expression
event
Required		String: The type of event, such as 'ViewContent'.Enrichment - 'ViewContent'
properties.descriptionString: A description of the product viewed.Enrichment - 'product viewed'
properties.content_typeString: The content type, e.g., 'product'.Enrichment - 'product'

Product Added

Output KeyDescriptionExpected Input
properties.currencyString: The currency of the transaction.properties.currency
properties.valueInteger: The value of the product added to the cart.N/A - Expression
properties.contentsArray: Details of the product added to the cart.N/A - Expression
event
Required		String: The type of event, such as 'AddToCart'.Enrichment - 'AddToCart'
properties.content_typeString: The content type, e.g., 'product'.Enrichment - 'product'

Cart Viewed

Output KeyDescriptionExpected Input
properties.currencyString: The currency of the transaction.properties.currency
properties.valueInteger: The value of the products in the cart.N/A - Expression
properties.contentsArray: Details of the products in the cart.N/A - Expression
event
Required		String: The type of event, such as 'ViewCart'.Enrichment - 'ViewCart'
properties.content_typeString: The content type, e.g., 'product'.Enrichment - 'product'

Order Completed

Output KeyDescriptionExpected Input
properties.currencyString: The currency of the transaction.properties.currency
properties.valueInteger: The value of the completed order.N/A - Expression
properties.contentsArray: Details of the products in the completed order.N/A - Expression
event
Required		String: The type of event, such as 'CompletePayment'.Enrichment - 'CompletePayment'
properties.order_idString: The ID of the completed order.N/A - Expression
properties.content_typeString: The content type, e.g., 'product'.Enrichment - 'product'

Signed Up

Output KeyDescriptionExpected Input
event
Required		String: The type of event, such as 'SignUp'.Enrichment - 'SignUp'

Required & Recommended Identifiers

These identifiers must be mapped to TikTok in order for successful user matching to occur. Without these IDs, any events sent to TikTok may not be accurately reflected in reporting. For your convenience, required and recommended IDs are mapped as Global parameters to ensure they are added to every event.

AttributeExampleSync Injector Required?
event_id
Required		"80fba0ae1c48e3978e43e4efc365e14e12ea0c830ba8ba5b9a2dafc7e3f2ab8b”No
ttclid
Highly Recommended		?ttclid=1223123132123Yes
ttp
Recommended		QRNtGPTKx_AiGeQv8-Ux6WD6s7yYes
external_id
Recommended		"80fba0ae1c48e3978e43e4efc365e14e12ea0c830ba8ba5b9a2dafc7e3f2ab8b”No
ip
Recommended		"203.0.113.1" "2001:0db8:85a3:0000:0000:8a2e:0370:7334"No
user_agent
Recommended		"Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A372 Safari/604”No
email
Recommended		"848a771458438fc2ec420560d769fb9b9b86851ee338ec56517baabd79d3bb4f”No
phone
Recommended		"9f7ec22d72092cd3c0b58726ed9c2d91b92e51a3f29837508fb2948bb22dd2fd”No

Additional Identifiers

These identifiers should be mapped to TikTok whenever possible to ensure the highest user match rates possible. If using these identifiers, they must be added as Global or Event Specific mappings.

AttributeDescriptionExample
idfaThe iOS IDFA for app events only.
For iOS 14 and above, ensure that IDFA data collection follows Apple’s policies.

Both raw and SHA-256 IDFAs are accepted: For raw IDFAs, all characters must be UPPERCASE.For SHA-256 IDFAs, all characters must be lowercase, and any leading/trailing spaces must be trimmed before hashing.		Raw IDFA: "EA7583CD-A667-48BC-B806-42ECB2B48606" SHA-256 IDFA: "70574fa9c8f498a7b2e5c8712b1126de7b1406fd02fdc591821c5bd33092fd1c"
idfvThe iOS IDFV for app events only.
gaidThe GAID (Google Advertising ID) for app events only
Both raw and SHA-256 GAIDs are accepted.

For both raw and SHA-256 GAIDs:All characters must be lowercase.Leading/trailing spaces must be trimmed before hashing		Raw GAID: "aaaaaa-2222-1111-8787-809e92233ba0" SHA-256GAID: "0ebad966881e1eebffe69b3abf624631cf83ec9bf8cb3ce134c7c75c6d8ee7fc"
localeFor web and app events only.
The BCP 47 language identifier.

For reference, refer to the IETF BCP 47 standardized code.		"en-US""zh-CN"
att_statusFor app events only.
Whether the user has authorized your mobile app to access app-related data for measuring the user or the device. This is an iOS only field.

Enum values:

AUTHORIZED: The user has authorized access to app-related data that can be used for measuring the user or the device.

DENIED: The user has not agreed to authorize your mobile app to access app-related data for measuring the user or the device via Apple's AppTrackingTransparency framework. If this field is set to DENIED, TikTok will not use the PII data (for instance, user email address or phone number) in this App Event for user-level matching.

NOT_DETERMINED: The user has not yet received an authorization request to authorize access to app-related data that can be used for measuring the user or the device.

RESTRICTED: The authorization to access app-related data is restricted.

NOT_APPLICABLE: The iOS version is below 14 or the device is running Android.		"AUTHORIZED”

Additional TikTok Documentation

TikTok Events API 2.0 - API Reference

Authentication

Updated 2 months ago