Send query results to TikTok Ads Manager

Use queries to build high-value audiences for retargeting and lookalike modeling, and then use orchestrations to send those audiences to TikTok Ads from Amperity. Marketers can use their best customers as a seed set for acquisition, which leads to improved match rates, stronger ROI, reduced onboarding costs, and stronger net new customer conversion.

Tip

Start with a balanced and stable audience. Allow that audience to complete its learning phase , which is a process TikTok Ads uses to optimize ad delivery for your audience.

Keep your audience stable during the learning phase and only make adjustments if your audience does not look like it will complete the learning phase, which typically ends after ~50 conversions.

Caution

To refresh audiences from Amperity, new one-time segment deliveries need to be created and uploaded to the client’s TikTok account.

Note

Amperity uses a combination of endpoints in the TikTok Ads Segment API to verify existing segments , add or update the list of customers to match the list of customers sent from Amperity, and then map many advertising account IDs to the same business account .

Changes to audience mapping are not immediately available in TikTok Ads. Allow for up to 10 hours after the point at which Amperity has finished sending audience updates for them to be available.

Important

Amperity requires access to TikTok Ads. This access may expire or be removed periodically, depending on how OAuth is managed at TikTok Ads. If Amperity is unable to send data to TikTok Ads ask your DataGrid Operator to reauthorize access to TikTok Ads.

The steps that are required to send email addresses, phone numbers, or advertising IDs (IDFAs for iOS devices or AAIDs for Android devices) to TikTok Ads from Amperity.

1. Build a query

2. Add orchestration

3. Run orchestration

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 query

You need to build a query that outputs email addresses and phone numbers.

Caution

The values for email, phone, and external_id sent to TikTok Ads 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.

Note

Before hashing, Amperity normalizes email addresses sent to TikTok Ads: converts to lowercase, removes dots (.) from the local part, and removes plus-sign suffixes (+tag). For example, John.Doe+promo@example.com becomes johndoe@example.com before hashing. This normalization improves match rates by standardizing email formats.

Tip

Email addresses most often lead to the best match rates.

You may include, in addition to email addresses and phone numbers, mobile advertiser IDs (MAIDs) if they are available. Associate the MAIDs for Apple devices to IDFA and MAIDs for Google Android devices to AAID.

Example

SELECT
  email AS EMAIL
  ,CONCAT('+',REGEXP_REPLACE(phone, '(\s*)([^a-zA-Z0-9])', '')) AS PHONE
FROM Customer360
WHERE email IS NOT NULL
OR phone IS NOT NULL

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.

Send events

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?

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.

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

Add orchestration

An orchestration defines the relationship between query results and a destination, including the destination and the frequency at which an orchestration runs.

To add an orchestration

1. Open the Activations page, select the Orchestrations tab, and then click the Add orchestration button. This opens the Add orchestration dialog box.

2. From the Object type dropdown, select Query.

3. From the Object dropdown, select the query for which results is sent to TikTok Ads.

4. From the Destination dropdown, select a destination that is configured for sending data to TikTok Ads.

5. Verify all settings.

6. Set the workflow to Manual. You can change this to automatic later, after verifying the end-to-end workflow.

7. Click Save.

Run orchestration

Run the orchestration manually to validate that it works.

To run the orchestration

1. Open the Activations page, select the Orchestrations tab, and then open the menu for the TikTok Ads orchestration. Select Run.

2. The Status column for the orchestration updates to say “Waiting to start”, after which the notifications pane updates to include a notification that shows the current status.

3. When the orchestration has run successfully, the status is updated to “Completed”.

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.