TikTok Ads
Connect TikTok Ads to send in-app events back to TikTok for campaign optimization and see spend against the installs attributed by App Sprint Attribution to each campaign. You connect the account once, pick which events should fire as TikTok conversions, and paste an ad link into TikTok Ads Manager.
Prerequisites
Before you connect, make sure you have:
- A TikTok For Business account with access to the advertiser you want to track.
- Admin or Operator access to that advertiser in TikTok Ads Manager (Standard access can't create the Events API token).
- At least one web data source (Pixel) created in TikTok Events Manager. If you don't have one yet, create it before connecting.
Reference
Available metrics
| Metric | Definition |
|---|---|
| Spend | Amount spent on the TikTok campaign over the selected window. |
| Installs | Installs attributed by App Sprint Attribution to this campaign. Falls back to TikTok's reported conversions when App Sprint Attribution has no match. |
| CPI | Cost per install. Spend divided by attributed installs. |
| IPM | Installs per 1,000 impressions. |
| Impressions | Times the ad was shown, reported by TikTok. |
| CPM | Cost per 1,000 impressions. |
| Clicks | Ad clicks, reported by TikTok. |
| CPC | Cost per click. |
| CTR | Click-through rate. Clicks divided by impressions. |
| CTI | Click-to-install rate. Installs divided by clicks. |
| ROAS | Return on ad spend. Attributed revenue divided by spend. |
| Revenue | Revenue from in-app events attributed to this campaign. Falls back to TikTok's reported value when App Sprint Attribution has no match. |
In-app events and default mapping
App Sprint Attribution forwards the eligible default-mapped Web events below and eligible events you explicitly map. You can override a default, leave a row blank to disable it, or send custom event names you've defined in TikTok Events Manager. Install, login, and achieve-level events are only forwarded if you explicitly map them. Custom names must start with a letter and use only letters, digits, underscores, and dashes, up to 50 characters.
| SDK event | TikTok event |
|---|---|
| purchase | Purchase |
| subscribe | Subscribe |
| start_trial | StartTrial |
| add_payment_info | AddPaymentInfo |
| sign_up / register | CompleteRegistration |
| add_to_cart | AddToCart |
| add_to_wishlist | AddToWishlist |
| initiate_checkout | InitiateCheckout |
| view_content / view_item / session_start | ViewContent |
| search | Search |
| login | Only forwarded when you explicitly map it as a custom event |
| achieve_level / level_complete | Only forwarded when you explicitly map it as a custom event |
| install | Only forwarded when you explicitly map it |
Connect to TikTok Ads
- In the App Sprint Attribution dashboard, open your app and go to Integrations → TikTok Ads.
- Click Connect TikTok Ads and sign in with a TikTok For Business account that has access to the advertiser you want to track.
- Approve the access request when TikTok prompts you. You'll be redirected back to App Sprint Attribution.
- Click Load accounts to fetch authorized advertisers, then pick the advertiser account from the dropdown. App Sprint Attribution will read campaigns and metrics from this account.
Configure the Events API
Step 1: Get the Pixel ID and access token
- Open TikTok Events Manager and select the web data source (Pixel) you want to use.
- Copy the Pixel ID shown at the top of the page.
- Go to Settings → Events API → Generate access token. Copy the token before you close the dialog. TikTok only shows it once.
- Back in App Sprint Attribution, paste the Pixel ID and Events API access token, then save.
Step 2: Map your in-app events
In Integrations → TikTok Ads → Event mapping, pick which TikTok event each in-app event should fire as. Defaults are pre-filled where TikTok has a matching Web Pixel standard event. Leave rows blank for events TikTok should not receive, and map install, login, or achieve-level events only if you want them forwarded as a specific TikTok standard or custom event.
Some TikTok campaign objectives only optimize for certain events. For example, a Sales objective won't use trial starts. Pick events that match the objective of the campaigns you plan to run.
Step 3: Create the ad link
- In the App Sprint Attribution dashboard, click Create ad link and paste your App Store or Play Store URL as the destination.
- Copy the tracking link App Sprint Attribution generates.
- In TikTok Ads Manager, open the ad you want to track. Use a Website destination/location, TikTok placement, and paste the App Sprint Attribution link into the Website URL field. Don't paste the App Store URL there. Set the operating system targeting to match the app (iOS or Android).
- Launch the campaign. The first conversions usually show up in TikTok Events Manager within 30 to 90 minutes.
Value-based optimization
TikTok unlocks value-based optimization (VBO) for web once it has enough Purchase signal: at least 20 unique attributed payment events within any 7-day window. App Sprint Attribution sends value and currency on matching Purchase events, so there's nothing else to enable on your side. Until you cross the threshold, TikTok still records the events but won't use them for value-based bidding.
Troubleshooting
A few things to check first:
- The ad link pasted into TikTok matches exactly the one App Sprint Attribution generated. TikTok ties the pixel to that URL.
- The campaign's operating-system targeting matches the app platform you connected.
- Allow 30 to 90 minutes after launching for events to appear in TikTok Events Manager.
| Problem | What to try |
|---|---|
| OAuth connection expired or lost advertiser access | The account you connected lost access to the advertiser. Disconnect TikTok Ads from the App Sprint Attribution dashboard and reconnect with an account that still has access. |
| Events API token rejected | Generate a new Events API access token in TikTok Events Manager for the same Pixel ID, then disconnect and reconnect TikTok Ads in App Sprint Attribution to paste the new credentials. |
| Some events are not sent | Create the TikTok ad link before sending production traffic, keep the mapping enabled, and make sure SDK requests include a real client IP and user agent. Events missing TikTok web context are skipped or dead-lettered instead of being sent with low-quality data. |
| Events aren't appearing in Events Manager | Allow 30–90 minutes after the first event is sent. If they still aren't showing up, confirm the ad link is the one pasted into the TikTok ad's Website URL and that the Pixel ID matches the Events API token. |
| Campaign objective rejected an event | Some TikTok campaign objectives don't accept every event. For example, Sales campaigns don't optimize for trial starts. Pick a TikTok event compatible with the campaign objective in TikTok Ads Manager. |
| Reporting numbers don't match TikTok Ads Manager | App Sprint Attribution reports installs and revenue based on its own attribution. TikTok reports based on the pixel's view. The two will differ for users without a TikTok click, and App Sprint Attribution uses its own number whenever it has one. |