TikTok — Pixel and Events API

Server-side conversion tracking via the TikTok Events API 2.0. Mirror of the Meta CAPI architecture, with ttclid captured from URL parameters on ad-click landings.

What you'll need

• A TikTok Ads Manager account with billing set up.
• About 5 minutes.

1. Create a TikTok data source

• Open TikTok Ads Manager at ads.tiktok.com.
• Tools → Events → Web Events → Connect data source.
• Connection method: pick TikTok Pixel + Events API (Recommended). Not "Events API only" and not "TikTok Pixel only". The combined option uses the same Pixel ID plus access token and keeps hybrid mode (browser-pixel path) open for later.
• Skip the browser-pixel HTML snippet TikTok offers. Beaconry runs server-side, you don't need it.

2. Disable TikTok's invasive defaults

TikTok asks about three privacy options during setup. Disable all three for GDPR-strictness:

• Automatic Advanced Matching (AAM) OFF. Would scan form fields in the browser and send them to TikTok without explicit per-field consent. Beaconry hashes the same fields server-side with controlled code paths.
• Allow first-party cookies OFF. Would set TikTok cookies under your customer-domain, bypassing the consent gate.
• Allow enhanced data postback OFF. Would send meta-tags, structured-data, button-clicks and performance-data to TikTok beyond what you explicitly track.

TikTok labels these as "Recommended" by default. Change every one to OFF.

3. Pick a business funnel template

TikTok asks for a "Business funnel template". Pick Custom (or "Other" / "Skip" if available). Templates only preset which conversion goals TikTok suggests in their UI. Beaconry sends every event you configure regardless of what template you picked. If TikTok forces a template choice, pick whatever roughly matches your business (E-commerce / Lead generation / Travel). It has no impact on what data flows.

4. Get the Pixel ID

Open the Pixel after creation. The Pixel ID (alphanumeric, ~20 characters) is shown directly under the Pixel name. Copy it.

5. Generate a TikTok access token

• Pixel-Settings → Events API → Set up manually → Generate Access Token.
• The token is shown ONCE. Copy it immediately. There is no way to retrieve it later, you would have to regenerate.

6. Paste credentials into Beaconry

WordPress Admin → Beaconry → Tracking → TikTok. Paste the Pixel ID and access token, save.

The token is encrypted at rest with AES-256-CBC. Constants alternative: BCNR_TIKTOK_PIXEL_ID and BCNR_TIKTOK_ACCESS_TOKEN in wp-config.php.

7. (Optional) Set a Test Event Code

In TikTok Events Manager → Test Events tab, generate a Test Event Code. Paste it into Beaconry. While set, every event is routed to Test Events instead of going live. Remove before going to production.

8. Send the test event

Click Send TikTok test event. HTTP 200 with code: 0 means credentials work. Events appear in TikTok Events Manager → Test Events within a few seconds when the code is set.

What ships automatically

All 14 TikTok standard events are supported:

• Pageview, ViewContent, AddToCart, InitiateCheckout, AddPaymentInfo, CompletePayment, Lead, CompleteRegistration, Subscribe, Search, Contact, Download, ClickButton, AddToWishlist.

ttclid capture: TikTok appends a ttclid parameter to every ad-click landing URL. Beaconry captures it on first page-load and persists it in the nl_ext cookie alongside fbclid (Meta) and gclid (Google). Every subsequent server-side event includes ttclid for accurate attribution.

(Optional) Hybrid mode

Loads pixel.js in parallel so TikTok sees the visitor's first-party _ttp and ttclid cookies. Deduplicated via event_id. Server-side alone already covers 100 percent of consenting visitors, hybrid mode is for higher match-rate. Off by default.

Troubleshooting

• "code: 40000". Token invalid or revoked. Regenerate.
• "code: 40005, content_id required". The event was missing a content_id. Beaconry sets one automatically for WooCommerce events. If you fire custom events with the JS API, include content_id in contents[], not at the top level.
• Events arriving but no ad attribution. ttclid capture relies on the visitor landing from a TikTok ad with ?ttclid=.... Direct visits won't have it, that's normal.