<!--
App*Sprint* docs markdown
Canonical HTML: https://appsprint.app/attribution/docs/tiktok-ads
Markdown URL: https://appsprint.app/attribution/docs/tiktok-ads.md
Docs index: https://appsprint.app/attribution/docs.md
Sitemap: https://appsprint.app/attribution/sitemap.xml
LLM guide: https://appsprint.app/attribution/llms.txt
-->

# TikTok Ads

A TikTok Signal Campaign uses an App*Sprint* Signal link as the Website URL in TikTok Ads Manager. App*Sprint* 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 App*Sprint* 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 App*Sprint*. Falls back to TikTok's reported conversions when App*Sprint* 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 App*Sprint* 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:** App*Sprint* maps app lifecycle signals to TikTok web events: installs use `Download` and sessions use `ViewContent`. Lower-signal events stay under "See more events" and default to off.

| 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 |

## Setup

### 1. Connect TikTok Ads

OAuth lets App*Sprint* load advertisers and Signal Campaign reporting. It is separate from the Events API token used for server-side event forwarding.

1. In App*Sprint*, open your app and go to **Integrations → TikTok Ads**.
2. Click **Connect TikTok Ads** and sign in with a TikTok For Business account.
3. Approve access, then click **Load accounts** and select the advertiser.

### 2. Configure the Pixel ID and Events API token

Already have a Pixel? Find its values:

1. In [TikTok Business Center](https://business.tiktok.com/), go to **Assets** and open the Pixel linked to your advertiser.
2. Click **Open in Events Manager**.
3. Copy the **Pixel ID** at the top of the page.
4. Click **Settings** → **Events API** → **Generate access token** and copy it.
5. Paste both values in App*Sprint* and save.

> **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 App*Sprint*. Use one Pixel per app, and do not mix Pixels between apps. Wrong values will send events to the wrong destination.

To create a new Pixel:

1. Open [TikTok Business Center](https://business.tiktok.com/) and go to **Assets** at the Business Center level.
2. Click **Add a pixel**, choose **Create new pixel**, then click **Next**.
3. If TikTok asks for a website URL, click **Skip** (or add your own website URL here if you want, but it is not mandatory). The App*Sprint* Signal link comes later.
4. Choose **Manual setup**, then select **Events API** only.
5. Name the Pixel after your app. Use one Pixel per app so it is easy to identify later, then click **Create**.
6. In **Set up your business funnel**, keep **E-commerce** template selected, then click **Next**.
7. Copy the **Pixel ID** and paste it into the **Pixel ID** field in the App*Sprint* TikTok ads integration.
8. Click **Generate access token**, copy the Events API access token, then paste it into the App*Sprint* TikTok ads integration and click **Save Pixel setup**.
9. Back in your TikTok Event Manager, click **Next**, then click **Finish**.
10. Go back to [TikTok Business Center](https://business.tiktok.com/) → **Assets** and, in the **Action** column for the Pixel you just created, click **View**.
11. Click **Link accounts**, select the advertiser you selected in App*Sprint*, then confirm.

### 3. 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.

### 4. Review event mapping (optional)

App*Sprint* already saves the default mapping for the main in-app events. Open **Integrations → TikTok Ads → Event mapping** only if you want to change which events are sent, disable an event, or map an App*Sprint* event to a different TikTok event name.

> **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 up to 2 hours after receiving production event data before the Pixel and optimization-event statuses update in campaign setup. 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. App*Sprint* already sends value and currency on Purchase events, so nothing else to enable.

### 5. Copy the Signal Campaign link and launch

1. In App*Sprint*, copy the generated TikTok Signal link. The URL already includes TikTok macros for campaign, ad, placement, callback parameter, IP, and user agent, plus App*Sprint* browser-side click enrichment.
2. In TikTok Ads Manager, click **+ Create** in the top-left corner to start a new campaign.
3. If not done already, switch to the **Full version** at the bottom left, to access the campaign objective and destination options. 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.
4. At the ad set level, use **Website** as the optimization location, select the same Pixel you configured in App*Sprint*, then pick the mapped optimization event.
5. 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.
6. At the ad level, paste the App*Sprint* Signal link into the **Website URL** field. Do not paste the URL parameters again in TikTok's Tracking section.
7. 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 App*Sprint* 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 App*Sprint* 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 | App*Sprint* reports use App*Sprint* attribution. TikTok reports use the Pixel's view. They differ for users without a TikTok click. App*Sprint* 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/attribution/docs) ([Markdown](https://appsprint.app/attribution/docs.md)) — Introduction to App*Sprint*
- [Quickstart](https://appsprint.app/attribution/docs/quickstart) ([Markdown](https://appsprint.app/attribution/docs/quickstart.md)) — Get up and running in 5 minutes
- [React Native](https://appsprint.app/attribution/docs/react-native) ([Markdown](https://appsprint.app/attribution/docs/react-native.md)) — React Native / Expo SDK reference
- [iOS (Swift)](https://appsprint.app/attribution/docs/ios-swift) ([Markdown](https://appsprint.app/attribution/docs/ios-swift.md)) — Native Swift SDK reference
- [Android (Kotlin)](https://appsprint.app/attribution/docs/android) ([Markdown](https://appsprint.app/attribution/docs/android.md)) — Native Android SDK reference
- [Flutter](https://appsprint.app/attribution/docs/flutter) ([Markdown](https://appsprint.app/attribution/docs/flutter.md)) — Flutter plugin reference
- [RevenueCat](https://appsprint.app/attribution/docs/revenuecat) ([Markdown](https://appsprint.app/attribution/docs/revenuecat.md)) — Webhook integration for subscription attribution
- [Superwall](https://appsprint.app/attribution/docs/superwall) ([Markdown](https://appsprint.app/attribution/docs/superwall.md)) — Webhook integration for paywall attribution
- [Apple Search Ads](https://appsprint.app/attribution/docs/apple-search-ads) ([Markdown](https://appsprint.app/attribution/docs/apple-search-ads.md)) — Keyword and ad attribution
- [Google Ads](https://appsprint.app/attribution/docs/google-ads) ([Markdown](https://appsprint.app/attribution/docs/google-ads.md)) — Coming soon
- [TikTok Ads](https://appsprint.app/attribution/docs/tiktok-ads) ([Markdown](https://appsprint.app/attribution/docs/tiktok-ads.md)) — Events API server-side event forwarding
- [Meta Ads](https://appsprint.app/attribution/docs/meta-ads) ([Markdown](https://appsprint.app/attribution/docs/meta-ads.md)) — In review