Install TikTok Pixel: Events, Events API, and Testing | OpsBlu Docs

Install TikTok Pixel: Events, Events API, and Testing

Complete TikTok Pixel implementation guide covering base code, standard events, Events API server-side setup, Advanced Matching, and deduplication.

What the TikTok Pixel Does

The TikTok Pixel is a JavaScript snippet that tracks user actions on your website and reports them back to TikTok Ads Manager. It powers conversion optimization, audience building, and campaign attribution. Without it, TikTok cannot connect ad clicks to downstream actions like purchases or signups.

Install the Base Code

Create a pixel in TikTok Ads Manager under Assets > Events > Web Events > Manage. Choose "Manually Install Pixel Code" and copy the snippet. Place it in the <head> of every page:

<script>
!function (w, d, t) {
  w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie","holdConsent","revokeConsent","grantConsent"],ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e};ttq.load=function(e,n){var r="https://analytics.tiktok.com/i18n/pixel/events.js",o=n&&n.partner;ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=r,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};var i=document.createElement("script");i.type="text/javascript",i.async=!0,i.src=r+"?sdkid="+e+"&lib="+t;var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(i,a)};
  ttq.load('YOUR_PIXEL_ID');
  ttq.page();
}(window, document, 'ttq');
</script>

The ttq.page() call sends a page view event on every load. All conversion events build on top of this base.

Standard Events

TikTok defines a set of standard events for common conversion actions. Fire them with ttq.track('EventName', { parameters }).

Event When to Fire Key Parameters
ViewContent Product or content page view content_id, content_type, content_name, value, currency
AddToCart Item added to cart content_id, content_type, value, currency, quantity
PlaceAnOrder Order initiated (checkout start) content_id, content_type, value, currency
CompletePayment Payment confirmed content_id, content_type, value, currency
Subscribe Subscription signup value, currency
Contact Contact form or inquiry (no required parameters)
SubmitForm General form submission (no required parameters)
CompleteRegistration Account creation (no required parameters)
Download File or app download (no required parameters)

Example purchase event:

ttq.track('CompletePayment', {
  content_id: 'SKU-789',
  content_type: 'product',
  content_name: 'Premium Plan',
  value: 99.00,
  currency: 'USD',
  quantity: 1,
});

Custom Events

For actions that do not map to standard events, fire a custom event name:

ttq.track('PricingPageView', {
  plan_type: 'enterprise',
});

Custom events can be used for audience building and reporting but are not available as optimization objectives in TikTok campaigns.

Advanced Matching

Advanced Matching lets you pass hashed user identifiers alongside events so TikTok can better attribute conversions to ad interactions. Call ttq.identify() before tracking events:

ttq.identify({
  email: 'user@example.com',  // TikTok hashes automatically
  phone_number: '+14155551234',
  external_id: 'user-abc-123',
});

ttq.track('CompletePayment', {
  value: 99.00,
  currency: 'USD',
});

TikTok's pixel code handles SHA-256 hashing client-side before transmission. You can also pre-hash values yourself if you prefer -- just pass them as sha256_email, sha256_phone_number.

TikTok Events API (Server-Side)

The Events API sends conversion data directly from your server to TikTok, bypassing browser limitations. Use it alongside the pixel for maximum signal, or standalone if you cannot load JavaScript on the client.

Generate an Access Token

In TikTok Ads Manager, go to Assets > Events > Web Events, select your pixel, and navigate to Settings > Generate Access Token.

Send a Server-Side Event

curl -X POST \
  "https://business-api.tiktok.com/open_api/v1.3/event/track/" \
  -H "Access-Token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pixel_code": "YOUR_PIXEL_ID",
    "event": "CompletePayment",
    "event_id": "order-12345",
    "timestamp": "2024-03-04T12:00:00-06:00",
    "context": {
      "user_agent": "Mozilla/5.0...",
      "ip": "203.0.113.45",
      "ad": {
        "callback": "TTCLID_VALUE"
      },
      "user": {
        "email": "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd",
        "phone_number": "a1b2c3d4..."
      }
    },
    "properties": {
      "contents": [{
        "content_id": "SKU-789",
        "content_type": "product",
        "content_name": "Premium Plan"
      }],
      "value": 99.00,
      "currency": "USD"
    }
  }'

Hash email and phone with SHA-256 before sending. Pass the ttclid click identifier (stored in the _ttp cookie or URL parameter) in context.ad.callback for best attribution.

Event Deduplication

When sending the same event from both the pixel and Events API, TikTok will double-count unless you deduplicate. Pass the same event_id in both channels.

Browser side:

ttq.track('CompletePayment', {
  value: 99.00,
  currency: 'USD',
}, {
  event_id: 'order-12345',
});

Server side: Include "event_id": "order-12345" in the Events API payload. TikTok matches on event + event_id and keeps only one record.

Setting Up Events in TikTok Ads Manager

After installing the pixel and firing events, configure them in Ads Manager:

  1. Go to Assets > Events > Web Events and select your pixel.
  2. Click "Complete Setup" or "Manage" to see incoming events.
  3. Under the Events tab, you will see all detected events with their volume and status.
  4. For each standard event, you can set a conversion value, attribution window (1-day click, 7-day click, or 28-day click), and optimization priority.
  5. When creating a campaign, select the configured event as your optimization goal under "Optimization Event."

Testing with TikTok Pixel Helper

Install the TikTok Pixel Helper Chrome extension. It displays:

  • Whether the pixel base code is detected on the page
  • Each event fired, with its parameters and values
  • Errors like malformed parameters or missing required fields
  • Whether Advanced Matching data was sent

Test Events in Events Manager

In your pixel settings, use the "Test Events" tool. Enter your website URL, browse your site, and events appear in real time. Verify that event names, parameter values, and Advanced Matching data look correct before launching campaigns.

Common Pitfalls

  • Missing ttq.page() call -- without the initial page view, the pixel initializes but does not send baseline data. Always include ttq.page() in the base snippet.
  • Wrong event names -- TikTok event names are case-sensitive. completepayment will not match CompletePayment. Use the exact casing from the documentation.
  • No deduplication -- running the pixel and Events API without matching event_id values will inflate your conversion counts and corrupt campaign optimization.
  • Missing ttclid -- the TikTok click ID is appended to landing page URLs as a query parameter. If your site strips URL parameters or redirects lose them, attribution breaks. Preserve ttclid through redirects and store it in a first-party cookie.
Nach oben