pooriaarab TikTok Ads
TikTok supports self-serve advertiser accounts, TikTok Pixel, and Events API
2.0 for web measurement. Use both Pixel and Events API for better coverage.
Use the same event name and event_id on both channels.
The current web event names are Purchase and Lead. TikTok maps the older
CompletePayment and SubmitForm names to them. New setups should use the
current names. See TikTok's updated standard events guide.
Account and access
TikTok provides a self-serve signup path through its Ads Manager account setup. Create a TikTok for Business login, then provide country, industry, legal business name, time zone, phone, currency, billing, and payment details. TikTok reviews the account before ads can deliver. Most reviews take less than 24 hours.
These steps apply to self-serve customers. Contact the client service team or account manager for a non-self-serve account. The legal business name must match the business documents. Account setup guide.
TikTok may require business verification when the ad account is created.
Verification status can affect the ability to post ads. Submit the acceptable
business document and certificate number in Tools → Account setup → Verify now. Requirements depend on the country or region. Business verification
guide.
Create the web data source in Tools → Events Manager → Connect Data Source → Web. Select Manual Setup, then select TikTok Pixel and Events API. The value
TikTok calls Pixel Code or pixel_code is the public pixel identifier.
Pixel ID setup.
Generate the Events API token in the pixel's Settings tab. An Ads Manager
Admin or Operator role can generate this token. A developer app can also use
the Measurement → Report Pixel Event permission. Events API setup guide.
Use these adapter secret names. TikTok does not prescribe environment variable names.
TIKTOK_PIXEL_ID public Pixel Code / pixel identifier
TIKTOK_CAPI_TOKEN server-only Events API access token
Client-side Pixel
Install the base code at the top of the document <head>. Load it only after
the hub's measurement consent gate allows measurement. The official script
loads https://analytics.tiktok.com/i18n/pixel/events.js, calls ttq.load,
and calls ttq.page. Install Pixel using code.
<script>
!function(w,d,t){w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];
ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie"];
ttq.setAndDefer=function(q,m){q[m]=function(){q.push([m].concat([].slice.call(arguments,0)))}};
for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);
ttq.instance=function(id){var q=ttq._i[id]||[];for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(q,ttq.methods[i]);return q};
ttq.load=function(id,n){var src="https://analytics.tiktok.com/i18n/pixel/events.js";
ttq._i=ttq._i||{};ttq._i[id]=[];ttq._i[id]._u=src;ttq._t=ttq._t||{};ttq._t[id]=+new Date;
ttq._o=ttq._o||{};ttq._o[id]=n||{};var s=d.createElement("script");s.async=true;
s.src=src+"?sdkid="+id+"&lib="+t;var a=d.getElementsByTagName("script")[0];a.parentNode.insertBefore(s,a)};
ttq.load("<TIKTOK_PIXEL_ID>");ttq.page()}(window,document,"ttq");
</script>
Fire a standard event after the business action. A successful payment must come from the payment confirmation or webhook state, not a button click.
ttq.track("Purchase", {
value: 25.00,
currency: "USD",
contents: [{ content_id: "plan_pro", quantity: 1, price: 25.00 }],
content_type: "product"
}, { event_id: canonicalEvent.event_id });
TikTok documents the third argument's event_id as the advertiser-chosen
deduplication value. Do not fire Purchase on every confirmation-page reload.
Event deduplication guide.
Events API 2.0
Send web events from the server after the hub's consent gate and after the payment provider confirms the event. The current endpoint is:
POST https://business-api.tiktok.com/open_api/v1.3/event/track/
Access-Token: $TIKTOK_CAPI_TOKEN
Content-Type: application/json
The top-level request needs event_source: "web", the Pixel Code in
event_source_id, and a data array. Each event uses event, event_time
in Unix seconds, and the canonical event_id for an overlapping browser event.
Use user, page, and properties for matching and conversion details.
Events API 2.0 web request.
{
"event_source": "web",
"event_source_id": "<TIKTOK_PIXEL_ID>",
"data": [{
"event": "Purchase", "event_time": 1700000000,
"event_id": "<canonical-event-id>",
"user": {
"email": ["<sha256-email>"], "phone": ["<sha256-e164-phone>"],
"external_id": "<sha256-stable-user-id>", "ttclid": "<if-present>",
"ttp": "<if-present>", "ip": "<browser-ip>",
"user_agent": "<browser-user-agent>"
},
"page": { "url": "https://example.com/checkout/success" },
"properties": {
"value": 25.00, "currency": "USD", "content_type": "product",
"contents": [{ "content_id": "plan_pro", "quantity": 1, "price": 25.00 }]
}
}]
}
TikTok requires SHA-256 for matching identifiers. Trim and lowercase email,
then hash it. Do not apply other email normalization. Normalize phone to E.164,
then hash it. Hash a stable external_id. Send ip, user_agent, ttclid,
and ttp without hashing. TikTok matching parameters.
Apply the hub consent gate before hashing or sending identity. TikTok recommends multiple match keys. A missing click ID must not stop a server purchase.
Canonical event mapping
Use current names for new web data sources.
| Hub event | TikTok event | Notes |
|---|---|---|
page_view |
PageView |
Sent by ttq.page; base code includes it. |
view_content |
ViewContent |
Use content_id in properties. |
lead |
Lead |
Legacy name: SubmitForm. |
signup |
CompleteRegistration |
Account registration event. |
begin_checkout |
InitiateCheckout |
Fire when checkout starts. |
purchase |
Purchase |
Legacy name: CompletePayment. |
subscription_start |
Subscribe |
Use StartTrial for a trial start, not a paid start. |
refund |
No standard web event listed | Keep it in the hub. Do not send it as Purchase. |
TikTok's current standard-event list includes the mapped events above. It does
not list a standard Refund web event. Custom events exist in Events Manager,
but this skill does not define a refund mapping. Standard events and parameters.
Deduplication
Use the exact same event_id in the Pixel third argument and the Events API
event object. Use the same Pixel Code and literal event name as well. A payment
provider transaction ID is a good canonical ID when it is unique per event.
TikTok documents a 48-hour deduplication window and a five-minute boundary for overlapping Pixel and Events API events. Keep twins close and never reuse one ID for two business events. Deduplication windows.
For a legacy pixel that still sends CompletePayment, keep the server event
name aligned until both channels migrate to Purchase. TikTok auto-converts
legacy names for reporting, but deduplication still needs aligned event data.
Click ID and first-party cookies
TikTok appends ttclid to an ad landing-page URL. Send it as user.ttclid.
It remains valid for the CTA window in Attribution Manager. Store it on first
landing in a first-party cookie or server session, then copy it into checkout
or order metadata. Keep first-touch and most-recent values when needed. TikTok
Click ID guide.
TikTok's first-party ttclid cookie lasts 13 months from the last use. The
Pixel's _ttp cookie also lasts 13 months from the last use. Send _ttp as
user.ttp when available. Pixel settings can disable cookie use, so do not
make _ttp or ttclid a condition for dispatch. Cookie specifications.
Tracking quirks that bite
- Attribution is configurable. TikTok's guide gives a default of 7-day click-through and 1-day view-through attribution. Match Attribution Manager settings before comparing TikTok with analytics. Attribution guide.
- Reporting is delayed. TikTok documents a 5–6 hour data delay. Use Test Events for immediate checks. Ads Manager playbook.
- Consent controls cookies. TikTok says to disable the Pixel after opt-out.
Apply the hub's
measurementgate before events andad_user_datagate before hashed identity. Pixel opt-out guidance. - Names and sources changed. New web setups use
PurchaseandLead.ClickButtonandPlaceAnOrderare soft-deprecated until 2027. Web uses a Pixel Code. App measurement uses an App ID and App Events SDK. Name migration, app setup. - The old payload is different. Do not copy
/v1.2/pixel/track/into Events API 2.0. Use/v1.3/event/track/withevent_source,event_source_id, anddata.
Verification
Use TikTok's server test flow before production. Open the pixel's Test Events
tab, copy the Test Server Events code, add it as top-level test_event_code,
send one Purchase with a unique test event_id, and confirm Event Activity.
Remove test_event_code before production.
The pixel detail page's Overview shows Server when server events arrive and
Server & Browser when both channels arrive. This is platform proof. The HTTP
response is only request proof. Reconcile production counts with successful
payment-provider charges. Events API verification guide.
Common pitfalls
- Confusing the Pixel Code, Ads Manager account ID, and access token.
- Sending
event_timein milliseconds, or sending raw identity values. - Hashing phone data before E.164 normalization.
- Mismatching browser and server event names or generating a new twin ID.
- Gating server events on
ttclid, or losing it during redirects. - Firing
Purchaseon checkout start, button click, or page reload. - Treating a 200 response as platform proof before checking Test Events.
- Leaving
test_event_codein production or comparing data before its delay.
Pairing with the conversion hub
Use ad-conversion-hub for taxonomy, consent,
identity normalization, click-ID storage, the adapter contract, retries, and
payment reconciliation. This file owns TikTok syntax and quirks.
The adapter returns skipped when a required secret is absent. It returns
failed for a documented 4xx or 5xx response without failing the payment
webhook. Follow the hub retry policy.
Security
Keep TIKTOK_CAPI_TOKEN in the deployment secret store. Never put it in a
client bundle, URL, log, screenshot, or repository. Send it only in the
server-side Access-Token header over HTTPS.
Keep raw identity data inside the server boundary. Hash only after consent. Do not log hashes, click IDs, cookies, IP addresses, or user agents with event payloads. Redact TikTok responses before storing them. Limit access to Events Manager roles that can generate tokens.