Send events to TikTok Ads Manager

Send events to TikTok Ads to help your brand track offline and web conversions that result from your marketing campaigns. Support for events and parameters is part of the TikTok Events API.

For example: When did a customer purchase? What did a customer purchase? Was it from a store or a website? How many items were purchased? Was there more than one purchase? What was the total revenue for each purchase?

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.

Note

Events are not immediately available in TikTok Ads. Allow for up to 24 hours after the point at which Amperity has finished sending events for them to be available.

Caution

This destination is available for sending query results to TikTok Ads after it is configured by a Datagrid Operator or your Amperity representative.

If this destination cannot be selected for orchestrations ask your Datagrid Operator or Amperity representative to configure a destination for sending query results to TikTok Ads.

Build a query

Use a query to build a combination of data from the your brand’s customer 360 database to represent the set of events that your brand wants to use within TikTok Ads. A query that collects events for use in TikTok Ads is similar to:

SELECT
  'ACME Essentials' AS brand
  ,uit.product_category AS content_category
  ,uit.product_id AS content_id
  ,uit.product_name AS content_name
  ,'product' AS content_type
  ,'USD' AS currency
  ,'mc.email' AS email
  ,'CompletePayment' AS event
  ,'website' AS event_channel
  ,CAST(uit.order_id AS VARCHAR) AS event_id
  ,'7654321098765432109' AS event_source_id
  ,uit.order_id
  ,CONCAT('+1','',REGEXP_REPLACE(mc.phone,'[$\D\s]','')) AS phone
  ,uit.item_price AS price
  ,uit.item_quantity AS quantity
  ,uit.store_id AS shop_id
  ,uit.order_datetime AS timestamp
  ,CAST(uit.item_revenue / uit.item_quantity AS DOUBLE) AS value
FROM Unified_Itemized_Transactions uit
LEFT JOIN Merged_Customers mc ON uit.amperity_id = mc.amperity_id
WHERE uit.order_datetime > (CURRENT_DATE - interval '7' day)

Offline events MUST contain at least one identity field (email or phone) and a timestamp. Web events MUST contain at least one identity field (email, phone, or external_id), a timestamp, and a page_url. The query should also include an event column unless the Fixed event name connector setting is configured. Review the list of supported events parameters while building the query.

Amperity automatically normalizes and SHA-256 hashes email, phone, and external_id before sending. Do not apply SHA-256 hashing in the query.

Note

Currency must be in ISO 4217. For example: “EUR”, “USD”, or “JPY”.

Note

The phone number must be in e164 format. If your customer 360 database is not already standardized for e164 format, use the following line instead of ,c360.phone AS phone:

,CONCAT('+1','',REGEXP_REPLACE(mc.phone,'[$\D\s]','')) AS phone_numbers

Important

Validate the audience with TikTok Ads 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. Send the sample audience to TikTok Ads and verify the sample audience is correct in TikTok Ads. 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 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 user interface. Use the event type that best associates how your brand wants to use events within TikTok Ads. 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. 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.