Autonnel v0.1.0
Get started

TikTok Ads

Set up TikTok conversion postbacks in token mode using the TikTok Events API, so purchases report server-side with the click id intact.

TikTok Ads supports token mode in the OSS core for server-side conversion postback via the TikTok Events API. OAuth mode is available with @autonnel/plugin-ads.

Prerequisites

  • A TikTok for Business account with an Events (pixel) created
  • An Events API access token for that pixel
  • For OAuth mode: @autonnel/plugin-ads installed with TikTok app credentials

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

Installing @autonnel/plugin-ads with TikTok app credentials adds a Connect with OAuth button on the Ads page. After authorization, autonnel can query ad account data (spend, impressions, clicks) for the connected account.

To configure the plugin, see Ads overview — Installing the plugin.

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 via Settings → Scripts if you need those events.