Ads overview

Autonnel supports conversion postback for four ad platforms: Facebook, TikTok, Bing Ads, and Google Ads. Each platform can operate in one of two modes depending on what you need.

Prerequisites

At least one active funnel
An account on the ad platform you want to connect
For Google Ads or full ad-data queries on any platform: @autonnel/plugin-ads installed and registered

Token mode handles server-side conversion postback. When an order is paid, autonnel sends the event to the ad platform’s conversion API using the credentials you provide. You paste an access token and pixel ID (or UET tag for Bing) directly into the admin UI. No OAuth flow is required.

Facebook, TikTok, and Bing Ads all support token mode. Google Ads does not — see Google Ads for why.

Token mode is available in the OSS core with no additional packages.

OAuth mode (`@autonnel/plugin-ads`)

OAuth mode enables the full authorization flow plus ad-data queries (spend, impressions, clicks). It also enables Google Ads as a platform. OAuth mode requires installing the @autonnel/plugin-ads plugin.

Once the plugin is registered, the admin UI shows a “Connect with OAuth” button on the Ads page for each supported platform.

Installing the plugin

npm install @autonnel/plugin-ads

import autonnel from 'autonnel';
import adsPlugin from '@autonnel/plugin-ads';

export default defineConfig({
  integrations: [
    autonnel({
      plugins: [
        adsPlugin({
          facebook: { appId: '...', appSecret: '...' },
          tiktok:   { appId: '...', appSecret: '...' },
          bing:     { clientId: '...', clientSecret: '...' },
          google:   { clientId: '...', clientSecret: '...', developerToken: '...' },
        }),
      ],
    }),
  ],
});

You only need to supply credentials for the platforms you intend to use in OAuth mode. Platforms without plugin credentials fall back to token mode.

Event mapping

Autonnel defines four internal events:

Internal event	When it fires
`PAGE_VIEW`	Landing page viewed
`CHECKOUT_VIEW`	Checkout page viewed
`INITIATE_PAYMENT`	Payment form submitted
`PURCHASE`	Payment completed successfully

Each ad platform has a set of platform-specific event names. When you add an ad platform, autonnel applies default mappings. The PURCHASE default mapping for every platform is non-editable. You can add mappings for the other three internal events from the event mapping UI on each platform’s settings page.

Custom mappings cannot override the defaults.

Click-ID routing

When a visitor lands on a funnel page, autonnel captures the URL parameters. The presence of a click-ID parameter determines which ad platform receives the postback when the order is paid:

Parameter	Platform
`fbclid`	Facebook
`ttclid`	TikTok
`gclid`, `wbraid`, `gbraid`	Google Ads
`msclkid`	Bing Ads

If an order does not have a matching click ID for a platform, no postback is sent to that platform. A single order can match at most one platform — the first matching parameter wins in the priority order shown above.

wbraid and gbraid are iOS privacy-preserving identifiers used by Google Ads when gclid is not available.

Funnel binding

Before postbacks fire, you must bind an ad platform account to a funnel. Go to your funnel’s Ads tab and select the platform account to bind. A funnel supports one account per platform.

Caveats

Token mode handles server-side postback only. Client-side pixel events (AddToCart, PageView, etc.) are not fired by autonnel — inject those via Settings → Scripts or your funnel’s Scripts tab.
Failed postbacks are retried by a cron job. You can see the retry status in the order detail view under the postback column.
If you remove a platform account that is bound to active funnels, those funnels will stop sending postbacks for that platform.