Send offline events to TikTok Ads

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

Tip

Offline 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

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

Get details

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

Credential settings Refresh token Required A refresh token is generated by the OAuth process and authorizes Amperity to send data to TikTok Ads Offline Events. The value for the refresh token is updated automatically. TikTok Advertiser Accounts must use OAuth. The account that is used to authorize to TikTok Ads Offline Events is assigned “TikTok Ad Account Operator” or “TikTok Ad Account Admin” permission. OAuth will not work if your account is assigned “TikTok Ad Account Analyst” permission.

Required configuration settings Advertiser ID The advertiser ID for your TikTok Ads Offline Events account. This is a nineteen character string similar to “7654321098765432109” that you can find from the drop-down menu in the top right of TikTok Ads Manager. Event set ID The event set ID is a nineteen character string similar to “7654321098765432109”. The event set must exist before you can send data to it from Amperity. You can create an event set ID from the TikTok Ads Offline Events user interface. If the event set ID already exists, from the TikTok Ads user interface open Assets, then Events, and then from the Offline box select Manage. Each event set will have its own card; the event set ID is located under the name of the event set. Event set name The name of the offline events set in TikTok Ads Manager. Event source The type of event to be uploaded to TikTok Ads Manager. May be one of “web” or “offline”. Use “web” for events that took place on your website and were collected using the payload helper . Use “offline” for events that took place in a physical store and are measured by an offline event set ID.

Configure credentials

Configure credentials for TikTok Ads Offline Events before adding a destination.

Important

TikTok Advertiser Accounts are required to use OAuth. Confirm that the account that will be used to authorize to TikTok Ads Offline Events 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 Offline Events should use SnapPass to securely share “refresh token” details with the individual who will configure 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 Offline Events. 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 are determined by the 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 Offline Events. The value for the refresh token is updated automatically. TikTok Advertiser Accounts must use OAuth. The account that is used to authorize to TikTok Ads Offline Events is assigned “TikTok Ad Account Operator” or “TikTok Ad Account Admin” permission. OAuth will not work if your account is assigned “TikTok Ad Account Analyst” permission.

Reauthorize Amperity

You may need to reauthorize access to TikTok Ads Offline Events. 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 Offline Events. To reauthorize access to TikTok Ads Offline Events, follow the steps to configure OAuth and create a new credential.

Add destination

Use a sandbox to configure a destination for TikTok Ads Offline Events. Before promoting your changes, send a test audience, and then verify the the results in TikTok Ads Offline Events. After the end-to-end workflow has been verified, push the destination from the sandbox to production.

To add a destination for TikTok Ads Manager

	Open the Destinations page, and then click the Add destination button. To configure a destination for TikTok Ads Offline Events, do one of the following: Click the row in which TikTok Ads Offline Events is located. Destinations are listed alphabetically and you can scroll up and down the list. Search for TikTok Ads Offline Events. Start typing “tik”. The list will filter to show only matching destinations. Select “TikTok Ads Offline Events”.
	Select the credential for TikTok Ads Offline Events from the Credential drop-down, and then click Continue. Tip Click the “Test connection” link on the “Configure destination” page to verify that Amperity can connect to TikTok Ads Offline Events.
	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 users with limited access to PII access to this destination. Restricted PII access is enabled when the Restrict PII access policy option that prevents users who are assigned to that option from viewing data that is marked as PII anywhere in Amperity and from sending that data to any downstream workflow.
	Configure the following settings, and then click “Save”. Advertiser ID The advertiser ID for your TikTok Ads Offline Events account. This is a nineteen character string similar to “7654321098765432109” that you can find from the drop-down menu in the top right of TikTok Ads Manager. Event set ID The event set ID is a nineteen character string similar to “7654321098765432109”. The event set must exist before you can send data to it from Amperity. You can create an event set ID from the TikTok Ads Offline Events user interface. If the event set ID already exists, from the TikTok Ads user interface open Assets, then Events, and then from the Offline box select Manage. Each event set will have its own card; the event set ID is located under the name of the event set. Event set name The name of the offline events set in TikTok Ads Manager. Event source The type of event to be uploaded to TikTok Ads Manager. May be one of “web” or “offline”. Use “web” for events that took place on your website and were collected using the payload helper . Use “offline” for events that took place in a physical store and are measured by an offline event set ID. Auto tracking? Select Auto tracking to use this event set for add tracking and attribution.
	After this destination is configured, users may configure Amperity to use orchestrations to send query results TikTok Ads Offline Events.

Offline events parameters

The following table describes each of the parameters that are required by TikTok Ads Offline Events for offline events.

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 renames this field to “(user_agent)” when events are sent to TikTok Ads Manager.)
brand	The brand name of the product item.
content_category	A product category.
content_id	A product identifier.
content_name	The name of a product.
content_type	A product or product type.
cookie_id	Web events only. A unique ID that matches website visitor events with ads on TikTok. (Amperity renames this field to “(ttp)” when events are sent to TikTok Ads Manager.)
currency	The ISO 4217 code for the currency that is associated with the offline event. For example: “USD”.
email	Required. The email associated with the order. The email address that is associated with a customer. A customer may have more than one email address.
event	Required The type of offline event. Add event to your query and then set a value: ,event AS 'CompletePayment' Important The value for event must be one of the supported offline event types defined by TikTok Ads Offline Events. A partial list of event types—ones that are more likely to align to your Amperity use cases—is described in the following table. The value for event must be one of the following: AddPaymentInfo Use when the offline 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 offline 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 offline event is associated with a completed transaction, either in-store or from your brand’s website. CompleteRegistration Use when the offline event is associated with a customer signing up for something, such as joining your brand’s loyalty program or creating an accounnt on your brand’s website. Contact Use when the offline event is associated with a customer’s interaction with your brand’s customer support team. Download Use when the offline event is associated with a customer downloading something from your brand’s website. PlaceAnOrder Use when the offline event is associated with a customer placing an order from your brand’s website. Subscribe Use when the offline event is associated with a customer subscribing to something, such as your brand’s loyalty program or notifications (email or SMS). The value for event is used to categorize offline conversions within the TikTok Ads Offline Events user interface and may not be customized. Use the event type that best associates how your brand wants to use offline events within TikTok Ads Offline Events.
event_channel	The event channel type. Must be one of the following values: email, website, phone_call, in_store, crm, or other.
event_id	Required. The unique identifier for the offline event. TikTok Ads Offline Events recommends that the value for event_id be a string of 32 characters that includes any combination of numeric digits (0-9), uppercase letters (A-Z), and lowercase letters (a-z).
event_set_id	Required. The event set ID. (The event set must exist before you can send data to it from Amperity.) An event set ID is a nineteen character string similar to “7654321098765432109”. You can find the event set ID from the TikTok Ads user interface. Click Assets, then Events, and then from the Offline box select Manage. Each event set will have its own card; the event set ID is located under the name of the event set.
event_source	The type of event to be uploaded to TikTok Ads Manager. May be one of “web” or “offline”. Use “web” for events that took place on your website and were collected using the payload helper . Use “offline” for events that took place in a physical store and are measured by an offline event set ID.
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.
order_id	The unique ID for a transaction.
phone	Recommended. The phone number that is associated with a customer. A customer may have more than one phone number. Note A phone number must be in E.164 format, which represents a phone number as a number up to fifteen digits in length (without spaces) that starts with a + symbol. For example: +12061234567.
price	The price of a product or service.
quantity	The number of items associated with an offline event.
shop_id	The unique ID for a physical store location or for your brand’s website.
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 renames this field to “ttclid” when events are sent to TikTok Ads Manager.)
timestamp	The date and time at which the offline event occurred. The timestamp should use ISO 8601 formatting.
value	The value associated with the offline event. Note This value is required for revenue reports within TikTok Ads Offline Events.