CLItrail Docs

TikTok

CLItrail sends each attributed install to the TikTok Events API as a web event with the visitor's TikTok click and browser IDs.

#Set it up

  1. #Generate an access token

    In TikTok Ads Manager, open Events Manager, choose your web pixel and open its Settings to generate an Events API access token. Only the Admin and Operator roles can generate one.

  2. #Add the destination

    Enter the pixel code and the access token. The install event defaults to Download, TikTok's standard event for a download from your website; the first run defaults to CLIFirstRun. Custom event names are reported but cannot be optimised for. Optionally add a value and currency.

  3. #Send a test event

    Copy the code from Events Manager → your pixel → Test events → Test server events.

  4. #Go live

    Confirm TikTok's terms and your notice duties, and verify your domain first.

#What is sent

{
  "event_source": "web",
  "event_source_id": "YOUR_PIXEL_CODE",
  "data": [{
    "event": "Download",
    "event_time": 1790172131,
    "event_id": "clt_f399d6357f61bcf15f9370c69a41662457de8a05",
    "user": {
      "external_id":
        "a68e7a64d91bfe305bd5c2a9f285ca38dec72a8a0d4036ee28a92bc72fb773ac",
      "ttclid": "YOUR_TTCLID",
      "ttp": "YOUR_TTP_COOKIE"
    },
    "page": {
      "url": "https://acme.dev/docs/install",
      "referrer": "https://acme.dev/"
    },
    "properties": { "value": 1, "currency": "USD" }
  }]
}
  • The access token goes in the Access-Token header. The body is JSON, the only format TikTok accepts.
  • event_source is web, the only source that accepts TikTok click and cookie IDs. page.url is the page of the touch that supplied the ID.
  • ttclid and ttp are sent as captured, each chosen by the attribution policy; a ttclid re-read from TikTok's cookie is dated by when the SDK saw it land. external_id is a SHA-256 hash of a pseudonymous installation ID.
  • An install needs ttclid or ttp on a touch; otherwise nothing is sent to TikTok.
  • TikTok can report errors with HTTP 200, so only a response with code 0 counts as submitted, and such an error is shown as TikTok error <code>, never as a 200.
  • TikTok deduplicates on the pixel, event name and event_id for 48 hours, and retries stop there. Throttling and system errors wait 5 minutes.