# 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](https://clitrail.com/docs/domain-verification) first.

## What is sent

```json
{
  "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.