# TikTok Ads Connect TikTok Ads to send in-app events back to TikTok for campaign optimization and see spend against the installs attributed by AppSprint 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 - 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. ## Available metrics | Metric | Definition | |--------|------------| | Spend | Amount spent on the TikTok campaign over the selected window. | | Installs | Installs attributed by AppSprint Attribution to this campaign. Falls back to TikTok's reported conversions when AppSprint 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 AppSprint Attribution has no match. | ## In-app events and default mapping AppSprint 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 1. In the AppSprint Attribution dashboard, open your app and go to **Integrations → TikTok Ads**. 2. Click **Connect TikTok Ads** and sign in with a TikTok For Business account that has access to the advertiser you want to track. 3. Approve the access request when TikTok prompts you. You'll be redirected back to AppSprint Attribution. 4. Click **Load accounts** to fetch authorized advertisers, then pick the advertiser account from the dropdown. AppSprint Attribution will read campaigns and metrics from this account. ## Configure the Events API ### Step 1: Get the Pixel ID and access token 1. Open TikTok Events Manager and select the web data source (Pixel) you want to use. 2. Copy the **Pixel ID** shown at the top of the page. 3. Go to **Settings → Events API → Generate access token**. Copy the token before you close the dialog. TikTok only shows it once. 4. Back in AppSprint 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 1. In the AppSprint Attribution dashboard, click **Create ad link** and paste your App Store or Play Store URL as the destination. 2. Copy the tracking link AppSprint Attribution generates. 3. In TikTok Ads Manager, open the ad you want to track. Use a Website destination/location, TikTok placement, and paste the AppSprint 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). 4. 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. AppSprint 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 AppSprint 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 AppSprint 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 AppSprint 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 | AppSprint 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 AppSprint Attribution uses its own number whenever it has one. | --- ## Docs navigation Use the Markdown URLs when reading the docs programmatically. Use the HTML URLs when you need the interactive docs UI. - [Overview](https://appsprint.app/docs) ([Markdown](https://appsprint.app/docs.md)) — Introduction to AppSprint Attribution - [Quickstart](https://appsprint.app/docs/quickstart) ([Markdown](https://appsprint.app/docs/quickstart.md)) — Get up and running in 5 minutes - [React Native](https://appsprint.app/docs/react-native) ([Markdown](https://appsprint.app/docs/react-native.md)) — React Native / Expo SDK reference - [iOS (Swift)](https://appsprint.app/docs/ios-swift) ([Markdown](https://appsprint.app/docs/ios-swift.md)) — Native Swift SDK reference - [Android (Kotlin)](https://appsprint.app/docs/android) ([Markdown](https://appsprint.app/docs/android.md)) — Native Android SDK reference - [Flutter](https://appsprint.app/docs/flutter) ([Markdown](https://appsprint.app/docs/flutter.md)) — Flutter plugin reference - [RevenueCat](https://appsprint.app/docs/revenuecat) ([Markdown](https://appsprint.app/docs/revenuecat.md)) — Webhook integration for subscription attribution - [Superwall](https://appsprint.app/docs/superwall) ([Markdown](https://appsprint.app/docs/superwall.md)) — Webhook integration for paywall attribution - [Apple Search Ads](https://appsprint.app/docs/apple-search-ads) ([Markdown](https://appsprint.app/docs/apple-search-ads.md)) — Campaign and keyword attribution - [Google Ads](https://appsprint.app/docs/google-ads) ([Markdown](https://appsprint.app/docs/google-ads.md)) — Offline click conversion upload - [TikTok Ads](https://appsprint.app/docs/tiktok-ads) ([Markdown](https://appsprint.app/docs/tiktok-ads.md)) — Events API server-side event forwarding