Loading tutorials…
Loading tutorials…
iOS 14+ and ITP strip 20-40% of pixel events. Events API is how you get that data back. This walks through the partner-integration path (Shopify, Segment) AND the direct API path for custom stacks — plus the deduplication settings that prevent double-counting.
Who this is forAdvertisers spending $2K+/month on TikTok who want to recover lost iOS attribution. Also anyone whose Event Match Quality score is stuck below 7 — Events API is the fastest lift available. Note: this is genuinely intermediate-to-advanced; if pixel-only setup felt hard, hire help.
What you'll need
Step 1
iOS 14+ ATT prompt + ITP + ad blockers strip browser pixel events. Events API sends them from your server, bypassing the browser entirely.
Pixel (browser-side) fires from the user's browser. iOS App Tracking Transparency lets users opt out, and Safari ITP blocks third-party cookies. Net result: 20-40% of conversion events never reach TikTok.
Events API (server-side) sends events from YOUR server directly to TikTok's API. The user's browser is not involved, so opt-out and ITP do not apply.
Both can coexist. With proper deduplication (event_id matching), TikTok counts each conversion ONCE even when it fires from both sources.
Industry data: accounts that add Events API typically see 15-30% better reported conversion volume, 5-15% lower CPA (because Smart+ has more data), and 20% better Event Match Quality scores.
Step 2
Easiest path. The partner handles event payloads, deduplication, and TikTok API auth for you.
Shopify: in the official TikTok Shopify app, enable "Events API" (sometimes labeled "TikTok Pixel + Events API" or "Advanced Data Connection").
Generate an Access Token in TikTok Events Manager → your Pixel → "Settings" → "Events API" → "Generate Token."
Paste the token into the Shopify TikTok app settings. Save.
Shopify will now send every purchase, add-to-cart, and checkout event server-side AND via pixel, with auto-deduplication using event_id.
Segment / Tealium: similar flow — enable the TikTok destination, paste the Events API token, configure which events flow server-side.
Validate in Events Manager → "Test Events" tab — should show events arriving from both "Browser" and "Server" with matching event_ids.
Step 3
For custom backends without a partner integration. You build the server-side event sender.
In TikTok Events Manager → your Pixel → "Settings" → "Events API" → "Generate Access Token." Save the token securely (environment variable, never in client-side code).
Endpoint: POST https://business-api.tiktok.com/open_api/v1.3/event/track/
Required fields per event: event_id (a unique UUID per event for deduplication), event_name (Purchase, AddToCart, etc.), event_time (UNIX timestamp), user data (hashed email, phone, IP, user agent), and properties (value, currency, content_id, content_type).
Implement: on every browser-side pixel fire, generate a UUID, pass it BOTH to the pixel (as event_id) AND to your server, which then fires the Events API call with the same event_id.
Test in Events Manager → "Test Events." Send a test event, confirm it arrives with both Browser and Server sources sharing the same event_id.
Deploy and monitor for the first 7 days. Watch for: missing events, duplicate counting (event_id mismatch), or 401 errors (token expired).
Step 4
Deduplication relies on event_id matching between the Pixel call and the Events API call. Get this wrong and every conversion counts twice.
Every event fired from BOTH Pixel and Events API must share the same event_id (also called event_id or eventID — TikTok normalizes both).
Generate the event_id on the server (or in a unified data layer), pass it to both the browser pixel call (as eventID) and the server-side API call (as event_id).
TikTok deduplication window: 24 hours. Same event_id within 24 hours = one conversion counted.
If event_ids do not match, TikTok counts BOTH events. Your Purchase column doubles. CPA looks half of reality. Smart+ chases inflated metrics.
Validate: Events Manager → "Test Events" → fire a real Purchase → confirm the event appears with both "Browser" AND "Server" tags AND a "Deduplicated" status indicator.
Step 5
Events API match quality depends on how much hashed user data you send. Email and phone are the highest-value matches.
Required (always send): event_id, event_name, event_time, IP address, user agent.
High-value matches (send when available): SHA-256 hashed email, SHA-256 hashed phone, external_id (your internal customer ID).
Medium-value matches: hashed first/last name, hashed city, hashed zip, country.
All PII MUST be hashed SHA-256 before sending. TikTok rejects plain-text PII for privacy compliance.
For e-commerce: capture email at the cart step, not just checkout. This raises match quality on AddToCart events too.
After 14 days of data, check Events Manager → your Pixel → "Event Match Quality." Target: 7+. Below 7 means you are missing fields or sending unhashed data.
Step 6
Event Match Quality is your North Star metric for Events API health. Below 7 = leaking data. 8+ = excellent.
Open Events Manager → your Pixel → "Overview" → "Event Match Quality" card.
Score: 0-10. Below 4: critical, audit immediately. 5-6: needs work. 7-8: good. 9-10: excellent.
Click into the score to see WHICH parameters are missing on which events.
Common gaps: email not captured on top-funnel events, phone not collected on checkout, missing external_id, plain-text PII being rejected.
Set a weekly calendar reminder for the first 8 weeks after install. Match quality drifts as your site code evolves.
Step 7
Events API is ALSO your insurance policy against ad blockers. ~15% of users run blockers that strip pixel calls.
If your audience skews tech-savvy (B2B SaaS, developer tools, gaming): assume 20-30% ad blocker rate.
Configure Events API to send EVERY event (not just Purchase) — ViewContent, AddToCart, InitiateCheckout. Otherwise blocked users are invisible to TikTok's top-of-funnel optimization.
For maximum resilience: deploy a first-party DNS proxy (Cloudflare Workers, server-side GTM). This makes your tracking domain match your site domain, bypassing most blockers.
Monitor: compare "Browser" vs "Server" event counts in Events Manager. If Server > Browser, you have an ad blocker gap that Events API is closing.
Common mistakes
Event IDs not matching between Pixel and Events API
What goes wrong: Every conversion is counted twice. Reported CPA looks 50% of reality. Smart+ optimizes toward a target that does not exist, bids inflate, and you waste 20-40% of budget. Often goes undetected for months.
How to avoid: Generate event_id ONCE (server-side or in a unified data layer), pass it to both Pixel (as eventID) and Events API (as event_id). Test in Events Manager → "Test Events" → confirm "Deduplicated" status.
Using a short-term token in production
What goes wrong: Token expires in 24 hours. Events API silently stops sending. You discover it 5-14 days later when conversion volume drops. Smart+ learning phase restarts. Easy $1K-3K of recovery time.
How to avoid: Always use a Long-term Access Token (Events Manager → Settings → Events API → "Generate Long-term Token"). Rotate annually as a security hygiene practice.
Sending plain-text PII
What goes wrong: TikTok rejects unhashed emails, phones, and names. Those events count for conversion but lose user-matching power. Event Match Quality plummets to 3-4. Smart+ retargeting becomes useless.
How to avoid: Hash all PII server-side with SHA-256 before sending. If using a partner integration (Shopify), this is automatic — just enable Advanced Matching.
Only sending Purchase events via Events API
What goes wrong: You recover iOS Purchase data but lose the funnel context (which ViewContent events led to which Purchase). Smart+ cannot optimize the top of funnel because it sees broken sequences.
How to avoid: Send the full e-commerce funnel via Events API: PageView, ViewContent, AddToCart, InitiateCheckout, AddPaymentInfo, CompletePayment. Every event matters for optimization.
Not validating deduplication before launching
What goes wrong: You "install" Events API, launch campaigns, and 30 days later realize Purchase volume doubled overnight because of broken dedup. Roll back, restart learning, lose 21 days of optimization.
How to avoid: Always test with "Test Events" tab BEFORE turning on campaign optimization. Send 5 real purchases, confirm each shows "Deduplicated" status with both Browser and Server sources.
Ignoring Event Match Quality
What goes wrong: Match quality silently drifts over time as site code changes. You launched at 8, six months later you are at 4, and you have no idea Smart+ is starved of user data. CPA climbs 30-50%.
How to avoid: Weekly check during first 8 weeks. Monthly check ongoing. Investigate immediately if score drops below 7.
Recap
Done — what's next
How to install the TikTok Pixel (direct and via GTM)
Read the next tutorial
Hand it off
Events API is the highest-leverage technical lift available in TikTok Ads — and one of the most commonly botched. Most freelance specialists charge $200-400 for a clean setup including deduplication validation, then $50-100/month for ongoing Event Match Quality monitoring. Cheap insurance for any account spending $2K+/mo.
See specialist rates
Probably yes. "Fine" usually means you have 60-80% of true conversion volume captured. Events API gets you the remaining 20-40%. For a $5K/mo account, that is $1-2K of lost attribution per month — far more than the cost of setup.
No — IF deduplication is set up correctly. Same event_id on both Pixel and API calls = TikTok counts once. If your reported conversions DO double after install, deduplication is broken and needs immediate fixing.
Same concept (server-side event API) but different implementations. TikTok's endpoint, token system, and required fields are unique. You cannot reuse Meta CAPI code directly. The conceptual mental model transfers; the integration work does not.
Yes — there is a server-side GTM template for TikTok Events API. This is a strong path if you already run server-side GTM for Meta CAPI or GA4. Combines all server-side event flows in one container.
Reported conversions drop 20-40% (you lose the iOS recovery). Smart+ rebalances toward whatever it can still see, often Android and desktop. CPA reports look worse than reality. Always alert on the Events Manager "Server events / hour" metric dropping below baseline.
Match quality improves in 24-48 hours. Smart+ optimization sees the lift in 7-14 days. Full CPA improvement (5-15% reduction) typically lands in 21-30 days as the algorithm re-optimizes on richer data.
TikTok Ads
TikTok Pixel installs in 10 minutes if you know what you are doing, or 6 hours if you don't. The difference is whether you validate it correctly in Events Manager before launching campaigns. This walks through both paths.
TikTok Ads
Pixel was working last week, today Events Manager shows zero events. Or it never fired at all. Either way, this is the diagnostic sequence specialists run — in order — to find the issue in under an hour.
TikTok Ads
TikTok custom audiences are the difference between $30 CPMs that scale and $30 CPMs that burn. Most DIY advertisers set up one audience and call it done. The advertisers who actually scale on TikTok build 6-8 audience layers and rotate them constantly.
Google Tag Manager
Server-side GTM is the difference between 'tracking works most of the time' and 'tracking works on iOS users behind ad blockers too.' It's not for everyone. But if you're past $5K/mo in ad spend, you're already losing money to client-side strip.