Skip to content
Faisal Mahmud TusherDigital marketing, SEO & analytics
with Faisal Tusher

TikTok Marketing › TikTok Measurement

TikTok Pixel and Events API Setup

A step-by-step TikTok measurement tutorial: creating the pixel, Tag Manager install, standard events, advanced matching, the Events API and deduplication.
Tutorialintermediate14 min readUpdated

Before you start

  • Access: admin rights on the Business Center that owns the ad account, so the pixel is created where it can be shared, and publish rights in the site's Tag Manager container (GTM). The tags, triggers and variables guide is the prerequisite for the container work; if Google Analytics already runs through the same container, the pattern in the Google Analytics via Tag Manager tutorial is the one this tutorial repeats for TikTok.
  • A short list of the actions worth measuring: where each happens on the site, which one represents the real business outcome, and roughly how often it occurs, because an ad group cannot learn from an event that rarely fires. The measurement plan tutorial is the format for writing this down.
  • A data layer or a plan for one: order value, currency, product identifiers and quantities must come from the shop platform, not from text on the page. The data layer guide covers the structure.
  • Consent requirements for every market the site serves, agreed with whoever owns the consent banner, and read alongside the privacy and consent guide.
  • A developer or a server-side route for the Events API step: a partner integration on a hosted shop platform, a server-side Tag Manager container, or backend code with access to order data.
  • A test path: Tag Manager preview mode, a way to place a test order, and a browser without content blockers for testing.

The setup, step by step

  1. Create the pixel in Events Manager

    Open Ads Manager, go to the assets menu and choose events, then web events, and create a new data source. TikTok asks for a name and a connection method: install the code manually, or connect through a partner platform, a list that includes Google Tag Manager and the major hosted shop platforms. It also asks for a setup mode. Standard mode offers an event builder that defines events by URL rules or clicked elements without code; developer mode expects events to be sent in code with their parameters, which is what a Tag Manager install does. Choose developer mode. Name the pixel after the website, because it will outlive campaigns and agencies, and create it in the Business Center that owns the ad accounts rather than in an individual's Ads Manager. Note the pixel identifier, which TikTok calls the pixel code, somewhere the developer and the container owner can both see it; every later step refers to it.

  2. Install the base code through Tag Manager

    In the container, add the pixel base code as a tag that fires on every page. TikTok publishes an official Tag Manager template in the community template gallery that handles the base code and events from one configuration; the alternative is a custom HTML tag holding the base snippet with the pixel code pasted in. The base code loads TikTok's library, which the pixel documentation refers to by the name of its global object, and sends a page view event. It has to execute before any event tag on the same page, so use the template's built-in sequencing or give the base tag priority and make each event tag wait for it. Point the trigger at the consent-aware page view you will create in the consent step rather than the raw all-pages trigger, so that the consent work later is a matter of changing one trigger rather than every tag. Publish to a preview workspace only at this stage.

  3. Check the base code and the click identifier

    Install TikTok's pixel helper browser extension, open the site in preview mode, and confirm that one pixel loads once per page with the right pixel code and that a page view is reported on every template, including checkout and confirmation pages that sometimes live on a different domain or skip the container. Events Manager should show activity within minutes. Then click a test ad or append TikTok's click identifier parameter to a landing page URL by hand and confirm the pixel captures it: TikTok appends a click identifier to the destination URL when someone clicks an ad, and the pixel stores it in a first-party cookie so that later events can be matched to the click. A landing page that strips query parameters, redirects through a system that drops them, or sets the pixel on a domain other than where the parameter landed loses that match for every click-through conversion.

  4. Add standard events

    TikTok documents a fixed list of standard events and recommends them over custom events because delivery can optimise towards them without further configuration. The common ones are ViewContent, AddToCart, InitiateCheckout, AddPaymentInfo, PlaceAnOrder, CompletePayment, CompleteRegistration, SubmitForm, Contact, Subscribe, Search, AddToWishlist, ClickButton and Download. Each becomes a tag in the container with its own trigger: a data layer event pushed by the shop platform, a form submission, or a confirmation page view guarded so that it fires once per order. Decide which event is the business outcome before building: on most shops it is CompletePayment, with PlaceAnOrder reserved for the moment an order is submitted before payment confirms. Give every event tag a trigger that matches the real moment the action happens, not a click on the button that starts it, and keep the spelling of event names exactly as documented, because a misspelt standard event is treated as a custom one.

  5. Send parameters and value

    Events become useful to optimisation and reporting when they carry parameters. TikTok documents value and currency for any event with a monetary outcome, a contents array whose items hold content_id, content_type, content_name, quantity and price, a top-level content_type of product or product group, a description, and a query for search events. Read every one of them from data layer variables in the container, never from page text, and send them with the event they describe: value and currency on CompletePayment are what value-based optimisation and return on spend reporting depend on, and the contents identifiers are what lets TikTok match events to a product catalogue for shopping formats. Check that the currency code is the one the order was placed in and that the value is the order total the business reports, agreed in advance, because a value that includes shipping on TikTok and excludes it in the order system is a reconciliation argument waiting to happen.

  6. Enable advanced matching

    Advanced matching sends hashed identifiers with events so that TikTok can match them to users who saw or clicked an ad, which raises the share of conversions reported and improves what delivery learns from. TikTok documents an identify call that accepts an email address, a phone number in the international format TikTok specifies, and an external identifier, hashed with the algorithm the pixel documentation names; the current pixel hashes the values itself when given plain text, and the Events API expects them already hashed. In the container, read the identifiers from the data layer at the moments they are known, such as login, checkout and form submission, and fire the identify call before the event tag. TikTok also documents an automatic advanced matching option in Events Manager that collects identifiers from form fields on the page without code. Whichever route is used, advanced matching is personal data processing and belongs inside the consent pattern the next step builds.

  7. Gate the pixel behind consent

    Nothing in this setup should fire for a visitor who has not consented where consent is required. The cleaner Tag Manager pattern is to fire the base tag and every event tag on a trigger the consent platform raises after a positive choice, and to hold data layer events until then; the privacy and consent guide covers the policy side and the consent mode guide in the Tag Manager section covers the mechanics. TikTok's pixel documentation also describes controls that stop the pixel from setting its first-party cookies until consent is given, and a limited data use option for jurisdictions with specific rules, both worth reading with legal counsel. Test both branches: with consent refused, the helper should show no pixel and Events Manager should receive nothing from the session; with consent granted, everything from the previous steps should appear. The same decision has to be made on the server for the Events API, because a server does not see the banner.

  8. Connect the Events API

    The Events API (Conversions API, in TikTok's naming) sends events from a server to the same pixel code. In Events Manager, open the pixel's settings, generate an access token for the Events API and store it as a secret. Then choose a route. A hosted shop platform with a maintained TikTok integration sends the standard commerce events server-side with no code; a server-side Tag Manager container can use TikTok's server tag template fed by the same data layer; a custom backend can call the endpoint directly. Each event payload names the pixel code as the source identifier, the event name exactly as the pixel uses it, the event time, an event identifier, a user object with the hashed email and phone, the external identifier, the visitor's address and user agent, the click identifier and the pixel's cookie value where available, and a properties object with the same value, currency and contents as the browser event. The Conversions API guide explains the equivalent design on Meta, and the same architecture serves both.

  9. Deduplicate browser and server events

    When the same action is reported by both routes, TikTok keeps one copy only if the two share an event name and an event identifier. Generate the identifier once, at the moment the action happens, and pass the same value to the pixel call and to the server payload. For purchases the order number is the natural choice, with a prefix if the shop reuses numbers; for forms, a unique submission identifier. In the container, read the identifier from the data layer into a variable and pass it as the event identifier option on each event tag; on the server, write the same field into the payload. TikTok documents the window within which it deduplicates, so the server event should be sent promptly rather than batched hours later. After launch, Events Manager shows how many events arrived by each route and whether they were deduplicated; a pixel count and a server count that add up to twice the shop's orders means the identifiers do not match. Where Meta, Google and other tags read the same purchase, the tutorial on ad platform tags from one data layer builds every one of them from the same data layer event and identifiers.

  10. Verify with the pixel helper and test events

    Events Manager has a test events view that shows events arriving from a browser session you identify, and the Events API accepts a test event code so that server events can be routed to the same view without touching live reporting. With preview mode on, walk the full journey: landing page with a click identifier, product view, add to cart, checkout, a test order, a form. For each event check that it appears once from the browser and once from the server, that the names match, that the two are marked as deduplicated, and that value, currency and contents are correct. The pixel helper shows the browser side in place, including warnings about missing parameters or a pixel that loaded twice. Fix problems in the container, republish the preview and repeat until the sequence is clean. Only then publish the container live, and check the overview a day later for events arriving from real traffic, with the expected split between browser and server.

  11. Hand the events to campaigns

    In Ads Manager, confirm that the pixel is shared with every ad account that will optimise on it, then create or edit an ad group and check that the intended event can be selected as the optimisation event and that value appears as available where CompletePayment carries it. Agree the attribution (Attribution) setting with whoever reads the reports and record it, because it changes every count from this point on; the measurement hub explains the options. Build the first custom audiences from the pixel's events, such as recent site visitors and past purchasers, so that retargeting and exclusions are ready before the campaign launches. Finally, write down what was installed: pixel code, events, parameters, triggers, consent pattern, Events API route, deduplication field and the date. Cost per acquisition (CPA) in the reports is only as good as this record. With the events handed over, the tutorial on launching a first TikTok Ads campaign builds the campaign that optimises on them, step by step.

Verify the result

A finished install has: one pixel loading once per page; every planned standard event arriving with the right parameters and currency; the click identifier captured on landing pages; advanced matching identifiers sent where they are known; no events from sessions that refused consent; the Events API sending the same events with the same identifiers; deduplication confirmed in Events Manager; the pixel shared with the ad accounts; and an ad group able to select each event as its optimisation goal. Compare the pixel's purchase count and value against the order system for the same days. The figures will not be identical, because TikTok counts under its attribution settings and the shop counts everything, but a large gap in either direction points to a trigger problem or a deduplication problem, and the direction of the gap says which. The glossary entry on CPA in TikTok Ads shows how a deduplication fault feeds straight into cost per conversion. The Meta pixel tutorial follows the same verification pattern, and a team running both platforms should run both checks from one spreadsheet. Before each new campaign launches, the TikTok Ads launch QA checklist repeats the test journey and the deduplication check for the event that campaign will optimise toward. Once campaigns run, the tutorial on building a monthly TikTok report keeps this comparison of TikTok, analytics and the order system as a standing line in every report. When the site itself is about to change platform, templates, checkout or domain, the plan for carrying a TikTok account through a website move covers the pixel, server route and ad destinations.

Illustrative example — not a real result

An outdoor-gear shop's first clean week

An outdoor-gear retailer on a self-hosted shop platform had a pixel installed by a previous agency that fired CompletePayment on every load of the order history page. Events Manager showed about 1,900 purchases a week against 260 real orders, and the conversion ad group had been optimising on that signal for two months. The rebuild through Tag Manager took an afternoon: base code on a consent trigger, ViewContent and AddToCart from the data layer, CompletePayment on a single order-complete event carrying value, currency and contents, an identify call at checkout, and an event identifier built from the order number on every tag. The Events API was connected through the shop platform's integration two days later with the same identifiers. In the first clean week the pixel reported 241 purchases and the server 258, deduplicated to 262 unique conversions against the shop's 255 orders under a seven-day click and one-day view setting, with an average reported value of £86 against the shop's £84.

Event reference

The table lists the standard events most sites need, when each should fire, the parameters that make it useful, and what it is typically used for. Names are as TikTok documents them and are case-sensitive.

EventFire whenKey parametersTypical use
ViewContentA product or key content page is viewedcontents with content_id and content_type, value, currencyCatalogue matching; upper-funnel optimisation; audiences
SearchA site search is submittedquery, contentsIntent audiences; rarely an optimisation event
AddToWishlistAn item is savedcontents, value, currencyAudiences for retargeting
AddToCartAn item is added to the basketcontents, value, currencyOptimisation event for low-volume shops; retargeting
InitiateCheckoutCheckout beginscontents, value, currencyMid-funnel optimisation; abandonment audiences
AddPaymentInfoPayment details are enteredvalue, currencyDeep-funnel audiences
PlaceAnOrderAn order is submitted before payment confirmscontents, value, currencyOptimisation where payment confirmation is off-site
CompletePaymentPayment is confirmedcontents, value, currency, event identifierPrimary purchase optimisation; value optimisation; return on spend
CompleteRegistrationAn account or sign-up is completedvalue where relevantLead and registration optimisation
SubmitFormA form is submittedvalue where leads are scoredLead generation optimisation
ContactA contact action is taken, such as a call or chatnone requiredLead generation for service businesses
SubscribeA subscription or newsletter sign-up completesvalue, currencySubscription optimisation
ClickButtonA significant button is clickeddescriptionEngagement signals; custom audiences
DownloadA file or app is downloaded from the sitedescriptionContent and app funnels

Every event in the table can also carry advanced matching identifiers and should carry an event identifier once the Events API is live. Custom events are allowed for actions outside the list, but delivery cannot optimise towards them as readily, so map any business action to a standard event where one fits before inventing a name.

Once SubmitForm and Contact fire reliably, the TikTok Ads setup for lead generation shows how to choose between website forms and instant forms and follow leads up quickly.

If an install that looked finished leaves Events Manager empty, or one event never arrives, the troubleshooting page for a TikTok pixel that is not firing works through the base code, sharing, setup mode, consent and timing in turn.

When the browser events arrive but the server copies from the Events API stay missing, the diagnosis for missing TikTok Events API events follows the server route from the test code and the pixel code to the integration, the container, the payload and the consent check.

Common mistakes

  • Creating the pixel in a personal Ads Manager. The asset then belongs to a person; create it in Business Center and share it to the ad accounts.
  • Standard mode for a shop. The event builder cannot read values or product identifiers; developer mode through Tag Manager can.
  • Values from page text. They work until the next template change and then silently send nothing.
  • A purchase trigger on page view. Refreshes, return visits and order history pages all become purchases; fire on the order-complete event once per order.
  • Different event identifiers on browser and server. TikTok then counts both copies, and delivery optimises on inflated data.
  • Advanced matching outside the consent pattern. Hashed identifiers are still personal data; they fire only after consent where consent is required.
  • Stripping the click identifier. Redirects and parameter-cleaning landing pages lose the match for every click-through conversion.
  • Skipping test events. Publishing an untested container and discovering the doubled purchase event after a month of optimising on it.

Frequently asked questions

Do I need the Events API if the pixel is already working?

For any site that depends on conversion optimisation, yes. TikTok recommends running the pixel and the Events API together because the browser loses events to blockers and cookie limits that a server does not suffer, while the browser still supplies the click identifier and page context that help matching. Deduplication with a shared event identifier means running both does not inflate the count once it is set up correctly.

Should I use the standard mode event builder instead of Tag Manager?

The event builder lets you define events by clicking elements or matching URLs without code, and it suits a simple site with a single form. It cannot read order values or product identifiers from a data layer, it breaks when the page layout changes, and it is awkward to audit. Tag Manager costs more on the first day and is easier to maintain, extend to the Events API and hand over to the next person.

Why does Ads Manager show far more purchases than the shop?

The two usual causes are a purchase tag that fires every time the confirmation page loads, including refreshes and return visits, or the pixel and the Events API both reporting the same order without a matching event identifier. Check the trigger first, then look at the deduplication information in Events Manager before touching bids or budgets, because every day of inflated data is a day of delivery optimising on the wrong signal.

Terms used on this page

Frameworks

Where this page is used

Sources

  1. About TikTok Pixel — TikTok for Business
  2. About Events API — TikTok for Business
  3. TikTok Ads Help Center — TikTok for Business

Related