# TikTok Ads Setup (/docs/paid-media/tiktok-setup)



The TikTok Ads Manager layer (template ID
`1a7f69d7-c013-4cb4-9d59-eb2d7fd5f52d`) drives TikTok ad campaigns and
Spark Ads.

## Agency mode [#agency-mode]

1. **Install the layer** from the catalog.
2. Setup wizard shows Layers' TikTok Business Center ID.
3. In your TikTok Business Center → Asset Sharing → **Send partnership
   request** to Layers.
4. Pick assets to share:
   * **Ad account** (Standard access).
   * **Pixel** (Manage).
   * **Identities / Spark accounts** if running UGC Spark Ads.
5. Layers accepts the partnership.
6. Bind the ad account to the layer.
7. Wallet check.
8. Save.

## BYO mode [#byo-mode]

1. **Install the layer** in BYO.
2. Click **Connect via OAuth**. You're redirected to
   `business-api.tiktok.com/portal/auth`.
3. Sign in with the TikTok user that admins the ad account.
4. Approve the Layers Marketing app (permissions are configured on the
   app itself in TikTok Business Center — the OAuth URL does not
   itemize scopes).
5. Pick the ad account.
6. Provide:
   * **Pixel ID** — your TikTok Pixel ID.
   * **Events API access token** — from TikTok Business Center → Events
     Manager → your Pixel → **Settings** → **Generate access token**.
7. Layers stores the token in vault.
8. Verify with a test event.

## Layer config [#layer-config]

```json
{
  "mode": "agency" | "byo",
  "tiktokBusinessId": "...",
  "adAccountId": "...",
  "capi": {
    "enabled": true,
    "pixel_id": "...",
    "access_token_vault_id": "vault_xyz"
  },
  "objectives": ["app_installs", "video_view"],
  "monthlyCostCap": 30000
}
```

## Spark Ads [#spark-ads]

To run a creator's organic post as a Spark Ad:

1. Creator opens their post → **Settings** → **Permissions** → **Allow
   ads authorization** → on.
2. Creator copies the **Spark code** (6 chars).
3. In Layers → UGC posts → that post → **Add Spark code**.
4. The optimizer can now select this post into adsets.

See [UGC licensing](/docs/ugc/licensing#tiktok-spark-ads).

## Event mapping [#event-mapping]

TikTok Events API requires standard event names. The relay map is:

| SDK event                               | TikTok event           |
| --------------------------------------- | ---------------------- |
| `purchase_success`, `paywall_purchased` | `Purchase`             |
| `subscription_start`, `trial_start`     | `Purchase`             |
| `add_to_cart`                           | `AddToCart`            |
| `content_open`                          | `ViewContent`          |
| `screen_view`                           | `PageView`             |
| `search`                                | `Search`               |
| `sign_up`                               | `CompleteRegistration` |

Unmapped custom events are dropped at the relay (logged but not
forwarded). Meta uses a similar but distinct map, and also drops
unmapped events.

## Verification [#verification]

* [ ] Campaigns visible in Layers.
* [ ] Test event appears in TikTok Events Debugger.
* [ ] Wallet / billing funded.

## Troubleshooting [#troubleshooting]

* **"Partnership pending"** — TikTok takes 5–15 min to notify.
* **"Custom event dropped"** — your SDK is sending events not in TikTok's
  standard mapping; either rename in your SDK or accept the drop.
* **Spark code expired** — Spark codes have time limits set by the
  creator; ask for a fresh code.