TikTok Ads
AppRefer sends your installs, trials and purchases to TikTok's Events API from the server, matched with the ttclid, and imports your TikTok spend.
What you need
- A TikTok pixel (Events Manager → Web Events) and its Pixel Code.
- A long-lived Marketing API access token (TikTok for Business → Marketing API).
- For spend sync: your advertiser IDs.
Setup
- In Settings → Integrations → TikTok, enter the Pixel Code and access token and save. The integration is connected once both are stored.
- Optionally add a Test Event Code and click Test Connection. With a code the event shows in TikTok's Test Events; without one it counts as a real event.
- Add advertiser IDs to turn on spend sync.
- Use an AppRefer tracking link as the ad URL and add
ttclid=__CLICKID__so TikTok fills in its click ID. See Tracking links for the campaign macros.
What AppRefer sends
POST https://business-api.tiktok.com/open_api/v1.3/event/track/Events are sent with event_source: "web" and your Pixel Code. Each one carries, when known: user.ttclid, the browser's IP address and user agent from the click, the TikTok ttp browser ID from the landing page, a hashed external_id, the hashed email and phone from Advanced Matching, value and currency, the product ID as content, and a stable event_id reused on retries.
Event mapping
These are the defaults; change them in Settings → Event Mapping. Events with no mapping that are not one of TikTok's standard event names are not sent.
| AppRefer event | TikTok event |
|---|---|
| install, sign_up | Lead |
| complete_registration (website sign_up receipts) | CompleteRegistration |
| startTrial, qualified_trial | StartTrial |
| purchase, intro_purchase, promo_purchase (including renewals) | Purchase |
| subscribe (plan change) | Subscribe |
| add_to_cart | AddToCart |
| initiate_checkout | InitiateCheckout |
| search | Search |
| view_content | ViewContent |
ttclid required for attribution
A conversion is credited to a TikTok ad through thettclid captured on the tracking link. Make sure every TikTok ad URL includes ttclid=__CLICKID__.Organic events
By default TikTok also receives organic and unattributed installs and purchases, like the other connected networks. Set organicFanout to false to send TikTok only the events from TikTok clicks, so it can't claim conversions it didn't drive.
Spend sync
Add your advertiser IDs to advertiserIds. AppRefer imports campaign spend, impressions and clicks, using costAccessToken (a Marketing API token that can read reports) if set, else the access token above. It reads each advertiser's currency from TikTok and stores spend in that currency; an advertiser that returns no valid currency is refused rather than assumed to be USD.
If one advertiser account runs campaigns for several apps, add an advertiserOwnership rule per advertiser ID, with the same shape and fail-closed behaviour as Meta's ad account ownership:
{
"advertiserIds": ["7012345678901234567"],
"advertiserOwnership": {
"7012345678901234567": { "mode": "shared", "campaignNamePrefixes": ["Sparkly"] }
}
}