Documentation
TikTok Ads
A TikTok Signal Campaign uses an AppSprint Signal link as the Website URL in TikTok Ads Manager. AppSprint routes users to the store, forwards selected post-install events to TikTok's web Events API, and reports spend beside attributed installs and revenue.
Requirements
- The AppSprint SDK installed and sending installs/events for this app.
- Admin or Operator access to the TikTok advertiser. Standard access is not enough.
- A Web Pixel in TikTok Business Center, linked to that advertiser.
- Advertiser/reporting access approved during the TikTok OAuth connection.
Available metrics and definitions
| Metric | Definition |
|---|---|
| Spend | Amount spent on the TikTok Signal Campaign over the selected window. |
| Installs | Installs attributed by AppSprint. Falls back to TikTok's reported conversions when AppSprint 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 Signal Campaign. Falls back to TikTok's reported value when AppSprint has no match. |
Available in-app events and default mapping
The dashboard shows primary optimization events first and keeps less common rows collapsed below. Leave a row blank to disable forwarding for that event.
Web Events API only
Install, login, and level events are intentionally omitted from this setup because AppSprint currently uses TikTok's web Events API, not TikTok's separate App Promotion Events API.
| SDK event | TikTok event | Dashboard |
|---|---|---|
| install | Download | Primary row |
| session_start | ViewContent | Primary row |
| sign_up / register | CompleteRegistration | Primary row |
| start_trial | StartTrial | Primary row |
| subscribe | Subscribe | Primary row |
| purchase | Purchase | Primary row |
| initiate_checkout | InitiateCheckout | See more events |
| add_payment_info | AddPaymentInfo | See more events |
| add_to_cart | AddToCart | See more events |
| add_to_wishlist | AddToWishlist | See more events |
| view_content / view_item | ViewContent | See more events |
| search | Search | See more events |
Connect TikTok Ads
OAuth lets AppSprint load advertisers and Signal Campaign reporting. It is separate from the Events API token used for server-side event forwarding.
- In AppSprint, open your app and go to Integrations → TikTok Ads.
- Click Connect TikTok Ads and sign in with a TikTok For Business account.
- Approve access, then click Load accounts and select the advertiser.
Configure the Pixel ID and Events API token
Use one Pixel for the whole setup
The Pixel ID and access token must come from the same Pixel, and that Pixel must be linked to the advertiser selected in AppSprint. Wrong values will send events to the wrong destination.
To create a new Pixel:
- Open TikTok Business Center and go to Assets at the Business Center level.
- Click Add a pixel, choose New pixel, then continue.
- Enter your website URL, then continue.
- Choose Manual setup, then select Events API only.
- Name the Pixel and create it.
- In Set up your business funnel, choose the E-commerce template.
- Copy the Pixel ID.
- Generate an Events API access token and copy it.
- Click Finish.
- Go back to Business Center → Assets and open the Pixel you just created.
- Click Link accounts, select the advertiser you selected in AppSprint, then confirm.
- Paste the Pixel ID and Events API token in AppSprint and save.
Already have a Pixel? Find its values
- In TikTok Business Center and go to Assets and open the Pixel linked to your advertiser.
- Click Open in Events Manager.
- Copy the Pixel ID at the top of the page.
- Click Settings → Events API → Generate access token and copy it.
- Paste both values in AppSprint and save.
Map your in-app events
In Integrations → TikTok Ads → Event mapping, keep the events your TikTok Signal Campaign can optimize for and disable the rest.
Match events to your Signal Campaign objective
Use Sales for Purchase or Subscribe. Use Lead generation for StartTrial or Sign-up. TikTok Ads Manager controls which events are selectable for the objective, so confirm the event is available before launch.
TikTok can take 30 to 90 minutes after receiving production event data before those events appear in Events Manager. Test events are useful for debugging, but they do not unlock campaign optimization.
TikTok unlocks value-based optimization once you have 20 unique attributed Purchase events in any 7-day window. AppSprint already sends value and currency on Purchase events, so nothing else to enable.
Test the Events API (optional)
Copy the test code from TikTok's Test Events panel, paste it in Integrations → TikTok Ads → Test Events API, then send one ViewContent test event to confirm delivery.
Copy the Signal Campaign link and launch
- In AppSprint, copy the generated TikTok Signal link. The URL already includes TikTok macros for campaign, ad, placement, callback parameter, IP, and user agent, plus AppSprint browser-side click enrichment.
- In TikTok Ads Manager, click + Create in the top-left corner to start a new campaign.
- Choose Lead generation when you want TikTok to optimize for StartTrial or Sign-up. Choose Sales when you want it to optimize for Purchase or Subscribe. Use Website as the destination, not App.
- At the ad set level, use Website as the optimization location, select the same Pixel you configured in AppSprint, then pick the mapped optimization event.
- Keep placement on TikTok only, target one operating system per ad set, and choose Conversion or Value bidding depending on the event you are optimizing for. If TikTok does not show OS targeting, switch to manual targeting and use Device to select only iOS or only Android.
- At the ad level, paste the AppSprint Signal link into the Website URL field. Do not paste the URL parameters again in TikTok's Tracking section.
- Launch the campaign. First conversions usually appear within 30 to 90 minutes.
Troubleshooting
| Problem | What to try |
|---|---|
| OAuth connection expired or lost advertiser access | Disconnect TikTok Ads in AppSprint and reconnect with an account that still has advertiser access. |
| Campaigns do not load | Reconnect TikTok Ads and approve advertiser/reporting access. The Pixel Events API token does not grant campaign reporting by itself. |
| Events API token rejected | Generate a new Events API access token in Business Center, then disconnect and reconnect TikTok Ads in AppSprint with the new credentials. |
| Some events are not sent | Copy the generated TikTok Signal link before sending production traffic, keep the mapping enabled, and make sure SDK requests include a real client IP and user agent. |
| Events aren't appearing in Events Manager | Allow 30 to 90 minutes after the first event. Then confirm the Signal link is the one pasted into the TikTok ad's Website URL and that the Pixel ID matches the Events API token. |
| Signal Campaign objective rejected an event | StartTrial is for Lead generation in this setup. If it appears but is disabled under Sales, create a Lead generation Website campaign, confirm the Website URL domain matches the Pixel event URL, and allow 30 to 90 minutes after the first production StartTrial event. |
| Reporting numbers don't match TikTok Ads Manager | AppSprint reports use AppSprint attribution. TikTok reports use the Pixel's view. They differ for users without a TikTok click. AppSprint uses its own number whenever it has one. |