Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect TikTok Pixel to Fondoo

Live5 min readUpdated

The TikTok Pixel measures what visitors from TikTok ads do on your site. Fondoo can add the pixel to your published pages and send matching server-side events through TikTok's Events API. TikTok then counts each conversion once, even when a browser blocks the pixel.

What Fondoo can do with it

1. The browser pixel (public, not a secret). Your Pixel Code is saved with configure_site_pixels. Fondoo injects TikTok's pixel loader and a page view on the next publish. Previews do not get it.

2. The server connector (secret). Saved with add_connection_key. It has one action, run through connector_action:

  • events.send (write): send one web event to the Events API. Allowed names: AddPaymentInfo, AddToCart, AddToWishlist, ApplicationApproval, CompleteRegistration, Contact, CustomizeProduct, Download, FindLocation, InitiateCheckout, Lead, Purchase, Schedule, Search, StartTrial, SubmitApplication, Subscribe, ViewContent. Fondoo maps SignUp to CompleteRegistration, and TikTok's older names CompletePayment to Purchase and SubmitForm to Lead. Each event needs eventId, an HTTPS page url, consentGranted:true and at least one customer identifier: email, phone, externalUserId, IP, user agent, or the ttclid / ttp values. You can add value and currency, a referrer, and up to 50 contents items (id, quantity, price).

Fondoo cannot create or manage ads, audiences or pixels. No action needs owner approval. Agents need the analytics:write scope (an owner key also works). Deleting the connection needs owner approval.

Before you start

  • A TikTok Ads Manager account with a web pixel. The pixel and Events API cost nothing to set up; you pay only for ads.
  • To create a pixel: Tools → Events Manager → Connect Data Source → Web, enter your URL, choose Manual Setup, then name the pixel (TikTok help).
  • Fondoo's setup notes say you need the Admin or Operator role on the ad account to generate a token. TikTok's developer page for this could not be read when this guide was written, so this may differ for your account.
  • TikTok's Business Products Data Terms forbid sending sensitive data.

Step by step: get your credentials

Pixel Code (pixelCode, required)

  1. In TikTok Ads Manager open Tools → Events Manager and select your web pixel.
  2. Copy the Pixel Code shown with the pixel name. It is a string of capital letters and digits, often 20 characters, such as CUSG5HBC77UD11VVRQEG. TikTok does not document the format, so this may differ for your account.
  3. It goes into both configure_site_pixels and the connector.

Events API access token (accessToken, required)

  1. On the same pixel, open its Settings.
  2. Look for the Events API section and its Generate Access Token button. TikTok's authentication page describes this; check it if the label differs.
  3. Copy the token. It works only for pixels in the same ad account.

There are no scopes to tick with an Events Manager token. If you use your own TikTok developer app instead, it needs the Measurement permission to report conversion events.

Connect it in Fondoo

a. In the dashboard. Go to Connections → Connect a tool. Type "TikTok" in Find a tool. On the TikTok Pixel card click Use a key, then Open secure key entry. Fill in pixelCode and accessToken, then click Save connection securely. The page expires after 15 minutes and works once.

The dashboard has no screen for the browser pixel; use your agent or REST.

b. By asking your agent. Example prompt: "Add TikTok pixel CUSG5HBC77UD11VVRQEG to my site and send me a secure link for the Events API token."

The agent calls:

configure_site_pixels({siteId, tiktok: {pixelCode: "CUSG5HBC77UD11VVRQEG"}})
add_connection_key({provider: "tiktok_pixel", siteId})

The second call returns a one-use securePasteUrl; never paste the token into chat. Then publish_site injects the pixel.

REST: the same calls are POST /v1/ops/configure_site_pixels and POST /v1/ops/add_connection_key, with the call input as the JSON body:

curl -X POST https://api.getfondoo.com/v1/ops/add_connection_key \
  -H "Authorization: Bearer $FONDOO_API_KEY" -H "Content-Type: application/json" \
  -d '{"provider":"tiktok_pixel","siteId":"YOUR-SITE-ID"}'

Consent. requireConsentForPixels defaults to false, because Fondoo has no per-site region setting. Turn it on for EU or UK visitors. Then no pixel loads until your banner calls window.fondooConsent.grant(). Global Privacy Control is always honored. Server events are refused unless the input says consentGranted:true; only set it for visitors who agreed.

Deduplication. In the browser call window.fondooPixel.track("Purchase", {eventId, value, currency}). It supports Purchase, Lead, CompleteRegistration and InitiateCheckout, and passes your eventId as TikTok's event_id. Send the same eventId and event name in events.send. TikTok keeps the first event and drops repeats within 48 hours (deduplication). Fondoo uses the Events API names (Purchase, Lead) in the browser too, while older TikTok pixel docs use CompletePayment and SubmitForm. This may differ for your account, so confirm in Test Events before relying on it.

Test that it works

  1. Run test_connection({connectionId}). TikTok has no read-only check for this token, so Fondoo only checks the format. The status is limited and events.send stays unknown.
  2. In Events Manager open your pixel's Test Events tab and copy the test code.
  3. Send a test event: connector_action({connectionId, action: "events.send", input: {name: "Lead", eventId: "test-1", url: "https://example.com/contact", email: "test@your-domain", consentGranted: true, testCode: "TEST12345"}}). It should appear under Test Events, and Fondoo returns accepted: true.
  4. Remove testCode afterwards.

Troubleshooting

  • "Credential fields do not match the connector manifest": the Pixel Code must be capital letters and digits only, and the token must be pasted whole.
  • "TikTok rejected the token or pixel (40001)" or (40104), or a permission error: the token is wrong, revoked, or from a different ad account than the pixel. Generate a new one.
  • "Unsupported TikTok event name": use one of the names above, with the same capitals.
  • "url (HTTPS page URL) is required": TikTok needs the page address for web events.
  • Phone not matched: Fondoo sends phone only in international form with a leading + and country code, for example +12133734253. The result shows phoneSent: false otherwise.
  • "TikTok throttled the request": wait and retry.

Limits, data and security

  • Fondoo's notes say TikTok allows 1,000 queries per second on the event endpoint; the official page could not be checked, so this may differ for your account. Fondoo sends one event per request and applies a local budget of 120 requests per minute.
  • Events can be at most 7 days old.
  • Email, phone and externalUserId are SHA-256 hashed before they leave Fondoo. IP, user agent, ttclid and ttp are sent unhashed.
  • Fondoo allows TikTok's loader and event hosts in your site's Content-Security-Policy. TikTok does not publish a host list, so this may differ for your account.
  • Credentials are encrypted in Fondoo's connector vault. list_connections shows only a masked value. A rotation reminder is due after 90 days unless you set rotateAfter.
  • To rotate, run rotate_connection_key({connectionId}) and re-enter both fields. To disconnect, run delete_connection (needs owner approval). This does not revoke the token at TikTok.
  • To remove the browser pixel, call configure_site_pixels({siteId, tiktok: null}) and publish again.
  • This connector does not use webhooks.