Skip to content

Browse the documentation

TikTok

Events API, test events and the hashing differences that make TikTok's requirements incompatible with Meta's.

updated

Outline — facts still to be confirmed

This article is a structured outline. Its headings and scope are settled; the specific values, screens and steps are marked TODO(owner: verify) until they have been checked against the plugin itself. Blueprint §7 is explicit that no article may state plugin behaviour that has not been verified.

The setup guide is Add TikTok, which covers the phone normalisation difference, event names, batching, and which parts have been verified against the live API. This page is the deeper reference and is still an outline.

Confirmed today

  • Current standard event names are used (Purchase, Lead), not the Events API 1.0 names. TikTok auto-converts legacy names on its side.
  • Phone numbers are sent in E.164 with the leading plus; Meta’s copy has it stripped.
  • International detection accepts a plus anywhere before the first digit, which covers TikTok’s own documented (+1)2133734253 format.
  • Requests chunk at 500 events. TikTok rejects an entire request carrying more than 1000.
  • A batch-level rejection is bisected and retried so one bad row is isolated rather than failing the whole batch repeatedly.
  • The properties field is serialised as a JSON object even when empty, because the specification types it as an object and an empty array is a different type.
  • The error and authentication paths are verified against TikTok’s live API. The successful-delivery path is not yet live-verified.

Outline still to fill

Test events

TODO(owner: verify) — how TikTok’s test event code is obtained and where it goes in the plugin.

Verification

Without a test code, the connection probe sends an authentication-only request rather than a reportable event. The error and authentication paths are verified against the live API; the successful-delivery path is not. TODO(owner: verify) — the acceptance code and the empty-payload behaviour, once a real accepted event has been observed.

Deduplication

TikTok’s dedup key is the event source, the event name and the event ID together — not the event ID alone. This is why a stale event name in the queue breaks pairing even when the ID matches. See Duplicate events.

Field mapping

TODO(owner: verify) — the per-event parameter map, and which Meta fields have no TikTok equivalent.

Was this page helpful?