Configure events for TikTok Ads

Events help your brand track offline and web conversions from your marketing campaigns on TikTok Ads Manager. Support for sending events and parameters is part of the TikTok Events API.

Tip

Events must have occurred within the previous 28 days. The maximum attribution windows for

• Click-through attribution (CTA) is 28 days

• View-through attribution (VTA) is 7 days

Events beyond these attribution windows are not matched to ads or displayed in reporting.

Caution

The values for email, phone, and external_id sent to TikTok Ads Manager are SHA-256 hashed automatically by Amperity before sending. Do not use the TO_HEX() function with the email, phone, and external_id fields for queries that return results for TikTok Ads Manager.

Get details

Review the following details before configuring credentials for TikTok Ads Manager and before configuring Amperity to send events to TikTok Ads Manager.

Credential settings Refresh token Required A refresh token is generated by the OAuth process and authorizes Amperity to send data to TikTok Ads Manager. The value for the refresh token is automatically updated. TikTok Advertiser Accounts must use OAuth. Assign the account used to allow access to TikTok Ads Manager the “TikTok Ad Account Operator” or the “TikTok Ad Account Admin” permission. OAuth does not work with the “TikTok Ad Account Analyst” permission.

Required configuration settings Advertiser ID The advertiser ID for your TikTok Ads Manager account. This is a nineteen character string similar to “7654321098765432109” that you can find from the dropdown menu in the top right of TikTok Ads Manager. Event source ID The event source ID is a nineteen character string similar to “7654321098765432109”. For offline events, use the Offline ID of the targeted offline event set in the TikTok Event Manager Dashboard. For web events, use the Pixel ID of the targeted web event source in the TikTok Event Manager Dashboard. The event source must exist before you can send data to it from Amperity. You can configure event sources from the TikTok Ads Manager user interface. Open the TikTok Ads Manager user interface. Choose Assets, then Events. For offline events, select Manage from the Offline box; the Offline ID is located under the name of each event set. For web events, select Manage from the Web box; the Pixel ID is located under the name of each pixel. Event source The type of event to be sent to TikTok Ads Manager. Select “offline” for events that took place in a physical store. Select “web” for events that took place on your website. Fixed event name When the dataset does not include an event column, the connector uses this value to populate the event field across all requests in the batch. Either include an event column in the query or configure this setting. One of the two is required. Limited data use When enabled, signals TikTok to apply limited data processing for web events in applicable U.S. states, supporting compliance with state-level privacy opt-out requirements. Has no effect on offline events.

Configure credentials

Configure credentials for TikTok Ads Manager before adding a destination.

Important

TikTok Advertiser Accounts are required to use OAuth. Confirm that the account that is used to authorize to TikTok Ads Manager has the TikTok Ad Account Operator or TikTok Ad Account Admin permission level. OAuth will not work if your account has TikTok Ad Account Analyst permission.

An individual with access to TikTok Ads Manager should use SnapPass to securely share “refresh token” details with the individual who configures Amperity.

To configure credentials for TikTok Ads Manager

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Credentials settings dialog box, do the following: From the Plugin dropdown, select TikTok Ads Manager. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “tiktok-offline-events” credential type, configure settings, and then click Save. Refresh token Required A refresh token is generated by the OAuth process and authorizes Amperity to send data to TikTok Ads Manager. The value for the refresh token is automatically updated. TikTok Advertiser Accounts must use OAuth. Assign the account used to allow access to TikTok Ads Manager the “TikTok Ad Account Operator” or the “TikTok Ad Account Admin” permission. OAuth does not work with the “TikTok Ad Account Analyst” permission.

Reauthorize Amperity

You may need to reauthorize access to TikTok Ads Manager. This is necessary when an authorization token has expired or when it has been removed by someone with permission to manage access within TikTok Ads Manager. To reauthorize access to TikTok Ads Manager, follow the steps to configure OAuth and create a new credential.

Add destination

Use a sandbox to configure a destination for TikTok Ads Manager. Before promoting your changes, send a sample audience, and then verify the results in TikTok Ads Manager. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination for TikTok Ads Manager

	Open the Destinations page, select the New destinations button, and then select Orchestration. To configure a destination for TikTok Ads Manager, do one of the following: Click the row in which TikTok Ads Manager is located. Destinations list alphabetically and you can scroll up and down the list. Search for TikTok Ads Manager. Start typing “tik”. The list filters to show only matching destinations. Select “TikTok Ads Events”.
	Select the credential for TikTok Ads Manager from the Credential dropdown, and then click Continue. Tip Amperity validates the connection when the destination is saved. If the connection cannot be validated, an error is shown and the destination is not saved.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	Configure the following settings, and then click “Save”. Advertiser ID The advertiser ID for your TikTok Ads Manager account. This is a nineteen character string similar to “7654321098765432109” that you can find from the dropdown menu in the top right of TikTok Ads Manager. Event source ID The event source ID is a nineteen character string similar to “7654321098765432109”. For offline events, use the Offline ID of the targeted offline event set in the TikTok Event Manager Dashboard. For web events, use the Pixel ID of the targeted web event source in the TikTok Event Manager Dashboard. The event source must exist before you can send data to it from Amperity. You can configure event sources from the TikTok Ads Manager user interface. Open the TikTok Ads Manager user interface. Choose Assets, then Events. For offline events, select Manage from the Offline box; the Offline ID is located under the name of each event set. For web events, select Manage from the Web box; the Pixel ID is located under the name of each pixel. Event source The type of event to be sent to TikTok Ads Manager. Select “offline” for events that took place in a physical store. Select “web” for events that took place on your website. Auto tracking? Select Auto tracking to use this event set for ad tracking and attribution. Fixed event name When the dataset does not include an event column, the connector uses this value to populate the event field across all requests in the batch. Either include an event column in the query or configure this setting. One of the two is required. Limited data use When enabled, signals TikTok to apply limited data processing for web events in applicable U.S. states, supporting compliance with state-level privacy opt-out requirements. Has no effect on offline events.
	After configuring this destination users may use orchestrations to send query results TikTok Ads Manager.
	Validate the audience with TikTok Ads Manager by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by TikTok Ads Manager. Send the sample audience to TikTok Ads Manager and verify the sample audience is correct in TikTok Ads Manager. Make adjustments if necessary. Only send full audiences after validation is complete.

Events parameters

The following table describes each of the parameters that are supported by TikTok Ads Manager for offline and web events.

Important

If Event source ID, Advertiser ID, and Event name are not correctly configured, TikTok will return an error without an explanation of the problem. Verify that the Event source ID, Advertiser ID, and Event name are correct before troubleshooting other issues.

The fields are listed alphabetically, but may be returned by a query in any order.

Field name	Description
agent	Web events only. A non-hashed user agent from the user’s device. This field should be sent along with ip when both are available. (Amperity sends this field as user_agent in the user object.)
brand	The brand name of the product item. Sent in the contents array.
content_category	A product category. Sent in the contents array.
content_id	A product identifier. TikTok recommends using sku_id or item_group_id if available.
content_name	The name of a product. Sent in the contents array.
content_type	The type of content in the event. Set to “product” when content_id is a sku_id, or “product_group” when content_id is an item_group_id. Defaults to “product” when blank.
cookie_id	Web events only. A unique ID that matches website visitor events with ads on TikTok. (Amperity sends this field as ttp (TikTok Pixel cookie) in the user object.)
currency	The ISO 4217 code for the currency that is associated with the event. For example: “USD”. Defaults to “USD” if blank.
description	A description of the event. Sent in properties.
email	At least one identity field, email or phone, is required for offline events. At least one of email, phone, or external_id is required for web events. The email address connected with a customer. A customer may have more than one email address. Note PII fields (email, phone, and external_id) are normalized and SHA-256 hashed automatically before sending. Values that already match the 64-character lowercase hex pattern are passed through as-is to prevent double-hashing.
event	The event name for each row. For example: “CompletePayment”. If this column is missing from the dataset, the Fixed event name connector setting is used. One of the two is required. The value for event is used to categorize conversions within the TikTok Ads Manager user interface. Use the event type that best associates how your brand wants to use events within TikTok Ads Manager. Add event to your query and then set a value, for example: ,event AS 'AddPaymentInfo' The value for event may be one of the supported event types defined by TikTok Ads Manager. The following is a partial list of event types that align to common Amperity use cases. See the TikTok supported events documentation for a full list of event values. Caution Names of event types are case-sensitive. AddPaymentInfo Use when the conversion event is associated with a customer adding their payment information as part of the checkout process on your brand’s website. AddToCart Use when the conversion event is associated with a customer adding a product in your product catalog to the cart on your brand’s website. CompletePayment Use when the conversion event is associated with a completed transaction, either in-store or from your brand’s website. CompleteRegistration Use when the conversion event is associated with a customer signing up for something, such as joining your brand’s loyalty program or creating an account on your brand’s website. Contact Use when the conversion event is associated with a customer’s interaction with your brand’s customer support team. Download Use when the conversion event is associated with a customer downloading something from your brand’s website. PlaceAnOrder Use when the conversion event is associated with a customer placing an order from your brand’s website. Subscribe Use when the conversion event is associated with a customer subscribing to something, such as your brand’s loyalty program or notifications (email or SMS).
event_id	The unique identifier for the event. A string of 36 characters A-Z, a-z, 0-9. An event_id is auto-generated from a hash of the email, phone, event, and timestamp if omitted. Used for deduplication.
external_id	Web events only. An external identifier for the user. Trimmed and SHA-256 hashed before sending. At least one of email, phone, or external_id is required for web events.
ip	Web events only. A non-hashed public IP address for the user’s device. May be an IPv4 or an IPv6 address, full or compressed. This field should be sent along with agent when both are available.
locale	Web events only. The locale of the user. Sent in the user object.
order_id	The unique ID for a transaction. Sent in properties.
page_url	Web events only. Required for web events. The URL of the page where the event occurred.
phone	At least one identity field (email or phone) is required for offline events. At least one of email, phone, or external_id is required for web events. The phone number connected with a customer. A customer may have more than one phone number. Note Phone numbers are normalized to E.164 format format (US region) and SHA-256 hashed automatically before sending.
price	The price of a product or service. Used with quantity to compute the value field; both columns must be present for the value to be sent to TikTok.
quantity	The number of items associated with the event. Used with price to compute the value field; both columns must be present for the value to be sent to TikTok.
referrer_url	Web events only. The referrer URL. Sent as referrer in the page object.
shop_id	The unique ID for a physical store location or for your brand’s website. Sent in properties.
tiktok_click_id	Web events only. A parameter that is appended to a landing page URL whenever a user clicks on an ad in TikTok. (Amperity sends this field as ttclid in the user object.)
timestamp	Required. The date and time at which the event occurred. Accepts ISO 8601 format, Unix seconds, or Unix milliseconds. Amperity automatically normalizes all formats to Unix epoch seconds before sending.
value	Computed automatically as the sum of (price * quantity) when both columns are present. You do not supply this field directly. Note This value is required for revenue reports within TikTok Ads Manager.