Autonnel v1.7.0

TikTok Ads

Set up TikTok conversion postbacks in token mode, and connect TikTok ad accounts over OAuth for spend and click reporting.


TikTok Ads supports token mode for server-side conversion postback via the TikTok Events API. OAuth mode, for ad account discovery and spend/click reporting, is also built into the core.

Prerequisites

  • A TikTok for Business account with an Events (pixel) created
  • An Events API access token for that pixel
  • For OAuth mode: either the hosted relay (“Use our app”, no setup), or your own TikTok for Business app with Marketing API access

Token mode setup

Token mode sends conversion events to TikTok’s Events API when an order is paid.

Generate an access token

  1. Open TikTok Ads Manager.
  2. Go to Tools → Events → Web Events.
  3. Select your pixel.
  4. Under Events API, click Generate access token.
  5. Copy the token.

The Pixel ID (also called Pixel Code in TikTok’s UI) is shown on the pixel overview page.

Add the platform in autonnel

  1. Go to Ads in the autonnel admin.
  2. Click Add platform → TikTok.
  3. Select Token mode.
  4. Enter a display name, your Pixel ID, and the access token.
  5. Save.

Testing events

TikTok provides a test event mode to verify delivery before going live.

  1. In TikTok Events Manager, open your pixel and go to the Test Events tab.
  2. Copy the test event code.
  3. In autonnel’s TikTok platform settings, enter the code in the Test event code field and save.
  4. Complete a test purchase in your funnel.
  5. The event should appear in TikTok’s Test Events view.

Remove the test event code after confirming delivery.

Event mapping defaults

Internal eventTikTok event
PURCHASECompletePayment

PURCHASE → CompletePayment is non-editable. You can add mappings for the remaining internal events. Available TikTok events include:

ViewContent, CompletePayment, AddToCart, InitiateCheckout, PlaceAnOrder, SubmitForm

Common additional mappings:

Internal eventSuggested TikTok event
PAGE_VIEWViewContent
CHECKOUT_VIEWInitiateCheckout
INITIATE_PAYMENTPlaceAnOrder

OAuth mode and ad reporting

Connect a TikTok ad account in either of two ways:

  • Hosted relay. In Marketing → Connect platform, pick TikTok and click Use our app (also on the TikTok card in Settings → Ads). You authorize the advertiser accounts on TikTok for Business and never handle app credentials.
  • Your own app. Register a TikTok for Business app with Marketing API access, enter its App ID and Secret in Settings → Ads, and click Connect (or Use your own app in the Marketing dialog).

Either way, after authorizing you land back where you started with a confirmation banner.

Once connected:

  • Every ad account your token can reach is discovered and connected as a separate account.
  • An hourly job pulls ad-level spend, impressions, clicks, and conversions per account, stored per day in that account’s own reporting timezone.
  • The first connection backfills 30 days of history; after that, use Refresh now for an on-demand sync.
  • Ads are attributed to a funnel by matching their destination URL’s path to one of your pages. Ads that don’t resolve to exactly one funnel land in the assignment list at Analytics → Ads.
  • Reported spend and clicks appear next to your own funnel data at Analytics → Ads and in the Ad Performance panel on each funnel’s Analytics tab.

OAuth mode does not replace token mode for postback, it adds ad reporting on top.

Click-ID routing

The ttclid URL parameter identifies TikTok traffic. If ttclid is present when an order is created, the purchase postback is routed to the TikTok adapter.

Caveats

  • TikTok’s default attribution window is 7 days from click. Postbacks sent after the window expires are accepted by the API but will not be attributed to a campaign.
  • Client-side TikTok Pixel events (ViewContent, AddToCart) are not sent by autonnel. Inject the TikTok Pixel script in the domain’s Custom code (Pages → Domains) if you need those events.