DocumentationExperience PlatformTags

TikTok web events API extension overview

Last update: Thu Mar 07 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer

The TikTok events API is a secure Edge Network Server API interface that allows you to share information with TikTok directly about user actions on your websites. You can leverage the event forwarding rules to send data from the Adobe Experience Platform Edge Network to TikTok by using the TikTok Web Events API extension.

TikTok prerequisites prerequisites

To configure the TikTok web events API to use the TikTok events API, you need to generate a TikTok pixel code and access token.

You must have a valid TikTok for business account in order to create a TikTok pixel using the partner setup. Go to the TikTok for business registration page to register and create an account if you do not have one already.

You must be logged into your business account to set up TikTok Pixel using partner setup. To do this, follow the steps below:

  1. Navigate to the Assets tab and select Event.
  2. Under Web Events, select Manage.
  3. Select Set Up Web Events.
  4. Select Partner Setup as your connection method.

See the Get Started with Pixel guide for more information on how to setup the TikTok pixel.

You can generate an access token once the pixel has been successfully created. To do this navigate to the Pixel and select the Settings tab. Under Events API, select Generate Access Token.

See the TikTok getting started guide for more information on how to setup the pixel code and access token.

Install and configure the TikTok web events API extension install

To install the extension, select Extensions in the left navigation. In the Catalog tab, select the TikTok Web Events API Extension and then select Install.

The extension catalog showing the TikTok extension card highlighting install.

On the next screen, input the following configuration values that you previously generated from TikTok Ads Manager:

  • Pixel Code
  • Access Token

When finished, select Save.

TikTok configuration screen for the TikTok web events API extension.

Configure an event forwarding rule config-rule

Once all your data elements are set up, you can start creating event forwarding rules that determine when and how your events will be sent to TikTok.

Create a new rule in your event forwarding property. Under Actions, add a new action and set the extension to TikTok Web Events API Extension. To send Edge Network events to TikTok, set the Action Type to Send TikTok Web Events API Event.

The Send TikTok Web Events API Event action type being selected for a TikTok rule in the Data Collection UI.

After selection, additional controls appear to further configure the event, as outlined below. Once complete, select Keep Changes to save the rule.

Web Events and Parameters

Web events and parameters contain general information about the event. Standard events are supported across TikTok integration tools and can be used for reporting , optimizing for conversions, and building audiences.

Input
Description
Event Name
The name of the event. These are actions with predefined names created by TikTok and is a required field. Refer to the TikTok Marketing API documentation for more information on supported events.
Event Time
Date-time as string in ISO 8601 or in yyyy-MM-dd'T'HH:mm:ss:SSSZ format. This is a required field.
Event ID
The unique ID generated by advertisers to indicate each event. This is an optional field and is used for deduplication.

The Web Events and Parameters section showing example data input into the fields.

User Context Parameters

User context parameters contain customer information that is used to match web visitor events with TikTok users. Including multiple types of matching data allows you to increase the accuracy of targeting and optimization models.

Input
Description
IP Address
Non-hashed public IP address of the browser. Support is provided for IPv4 and IPv6 addresses. Both the full and compressed forms of IPv6 addresses are recognized.
User Agent
The non-hashed user agent from the user’s device.
Email
Email address of the contact associated with the conversion event.
Phone
The phone number must be in E164 format [+][country code][area code][local phone number] before hashing.
Cookie ID
If you are using Pixel SDK will automatically save a unique identifier in the _ttp cookie, if cookies are enabled. The _ttp value can extracted and used for this field.
External ID
Any unique identifier such as user IDs, external cookie IDs and so on and must be hashed with SHA256.
TikTok Click ID
The ttclid which is added to the URL of the landing page each time an advertisement is selected on TikTok.
Page URL
The page URL at the time of the event.
Page Referrer URL
The URL of the page referrer.

The User Context Parameters section showing example data input into the fields.

Properties Parameters

Use the properties parameters to configure additional supported properties.

Input
Description
Price
The cost of a single item.
Quantity
The number of items being purchased in the event. This must be a positive number greater than 0.
Content Type
A value of either product or product_group must be assigned to the content_type object property, depending on how you will configure your data feed when you set up your product catalog.
Content ID
A unique identifier of the product item.
Content Category
Category of the page/product.
Content Name
Name of the page/product.
Currency
The currency of the items being purchased in the event. This is expressed in ISO-4217.
Value
The total price of the order. This value will be equal to the price * quantity.
Description
A description of the item or page.
Query
The string of text that was used to lookup a product.
Status
The status of an order, item, or service. For example, “submitted”.

The Properties Parameters section showing example data input into the fields.

Event deduplication deduplication

TikTok pixel will need to be setup for deduplication if you use both the TikTok pixel SDK and the TikTok web events API extension to send the same events to TikTok.

Deduplication is not required if distinct event types are being sent from the client and server without any overlap. To ensure that your reporting is not negatively impacted, you must make sure that any single event that is shared by the TikTok pixel SDK and the TikTok web events API extension is deduplicated.

When sending shared events, make sure that every event includes a pixel ID, event ID and name. Duplicated events that arrive within five minutes of each other will be merged. If the data field was absent from the first event, it will be combined with the subsequent event. Any duplicate events received within 48 hours will be removed.

See the TikTok documentation on Event Deduplication for more details on this process.

Next steps

This guide covered how to send server-side event data to TikTok using the TikTok web events API extension. For more information on event forwarding capabilities in Adobe Experience Platform, refer to the event forwarding overview.

recommendation-more-help
12b4e4a9-5028-4d88-8ce6-64a580811743