TikTok Pixel for Google Tag Manager Web

Template Gallery Updates
1

The TikTok Pixel by Stape tag integrates the TikTok Pixel into your website via a Google Tag Manager Web container. It allows you to send standard or custom events to TikTok, including user data for Advanced Matching, to improve ad performance and attribution.

:white_check_mark: Unlike other TikTok Pixel tag templates, this tag does not require the Base Code installed as a Custom HTML tag to work. Simply add the tag to your GTM container and it will work.

How to Use

  1. Add the TikTok Pixel by Stape tag to your Web GTM container.
  2. Enter one or more TikTok Pixel IDs (array, single item string or comma separate string of Pixel IDs).
  3. Choose how the Event Name is defined:
    • Inherit from DataLayer — maps GTM/GA4 event names to TikTok equivalents.
    • Override — choose from a list of standard events or provide a custom event name.
  4. Enable Automatic Data Layer Mapping (recommended) to automatically parse GA4, UA, and Common Event Data formats for event and user data.
  5. (Optional) Enable Advanced Matching to securely pass user data (e.g., email, phone) to TikTok for better match rates.
  6. (Optional) Enable Event User Data Enhancement to store and reuse user data via localStorage across sessions.
  7. (Optional) Configure Compliance Settings, including TikTok’s consent modes, Google Consent Mode, or Limited Data Use (LDU).
  8. (Optional) Configure Server-Side Tracking Settings by providing an Event ID for deduplication with the TikTok Events API.
  9. (Optional) Add extra metadata to your events using the Event Parameters and Additional Event Parameters sections.
  10. (Optional) Adjust Additional Settings to disable automatic history event tracking for Single Page Applications (SPAs).

Event Name Setup Options

  • Standard Events (when overriding):
    • Pageview, AddToCart, Purchase, Lead, ViewContent, CompleteRegistration, etc.
  • Inherit from DataLayer (default):
    • Maps GA4 events like purchase, add_to_cart, sign_up, etc., to their TikTok equivalents.

Required Fields

  • TikTok Pixel ID(s) — Must be an array, a single Pixel ID or a comma-separated list of IDs.
  • Event Name — Must be resolved either from the Data Layer or the override settings.

Features

Advanced Matching

Securely enrich events with user identifiers to improve ad performance. The tag can automatically hash PII using SHA256 if it’s not already hashed. Supported fields include:

  • Email (email)
  • Phone Number (phone_number)
  • External ID (external_id)

User data can be sourced from:

  • A manually entered table.
  • The Data Layer (user_data object).
  • A custom variable (e.g., a User-Provided Data Variable).

Event User Data Enhancement

When enabled, user data is stored in localStorage to persist across events and sessions. This improves match quality for repeat visitors or multi-page actions. Data can be stored in plain text or hashed.

Compliance Settings

The tag provides robust support for privacy and compliance requirements:

  • TikTok Consent Mode: Configure the pixel to operate in an opt-in (waits for consent before loading the SDK) or opt-out (fires until consent is explicitly revoked) mode.
  • Manual Consent: Explicitly grant or deny consent for the pixel to fire.
  • GTM Consent Mode: The tag respects GTM’s native consent signals, specifically checking for ad_storage consent. When combined with opt-in mode, the SDK load is deferred until consent is granted via a consent listener.
  • Limited Data Use (LDU): Enable LDU for users in U.S. states with specific data privacy laws.

Consent-Aware SDK Loading

The tag gates TikTok SDK loading on consent status. When consent is denied, the tag exits early without loading the SDK or firing any network requests, rather than loading the SDK and relying solely on revokeConsent to suppress events. This means:

  • Opt-out mode: If consent is denied (manually or via ad_storage), the tag returns immediately. No SDK script is injected and no pixel is initialized. If consent was previously granted and the SDK is already loaded, a revokeConsent command is issued to suppress further events.
  • Opt-in mode: The SDK load is deferred until consent is explicitly granted. Events are queued in the shim (the lightweight queue created before the SDK loads) and only flushed once the SDK loads after consent is granted.
  • Google Consent Mode integration: When ad_storage is initially denied, the SDK load is deferred via a consent listener. Once ad_storage is granted, the SDK loads and queued events are sent.

This approach avoids unnecessary script loading, reduces page overhead when consent is withheld, and prevents the pixel from being marked as initialized before consent is verified.

Storage Gating

localStorage interactions (reading and writing Event User Data Enhancement) are also gated on consent. When consent has not been granted, the tag skips reading from and writing to localStorage, ensuring no user data is persisted without permission.

Server-Side Deduplication

If you use both client-side and server-side (Events API) TikTok tracking, you can prevent duplicate conversions:

  • Use the Event ID field to send a unique identifier for each event.
  • Enable DataLayer Push to create a new Data Layer event containing the Event ID, which can be used to trigger your server-side tag and ensure synchronization.

Event and Additional Parameters

Send extra metadata with your events using:

  • Event Parameters Table: For standard TikTok parameters.
  • Additional Event Parameters Table: For custom parameters or those specific to verticals like Travel and Automotive.
  • Data Layer Mapping: Automatically maps standard e-commerce parameters from GA4/UA objects.
  • Custom Variable: Load parameters from a JavaScript object variable.

Supported parameters include:

  • value, currency, contents, content_ids, num_items, and more.

Other Settings

  • Disable History Event Tracking: The TikTok Pixel automatically tracks browser history changes (e.g., in SPAs) as Pageview events. This option allows you to disable this behavior to prevent duplicate pageviews and have more control over tracking, especially when using the Events API for deduplication.

Debugging

You can verify and troubleshoot your pixel implementation using three primary methods:

  • Debug Mode: Check the Pixel debug messages on the browser console (DevTools). Learn more.
  • Test Events: A feature within TikTok Events Manager that allows you to debug pixel events in real-time to ensure they are being received and processed correctly. Learn more.
  • TikTok Pixel Helper: A Chrome extension that provides real-time feedback on your pixel events and helps identify errors. Learn more.

Open Source

The TikTok Pixel for Google Tag Manager Web is developed and maintained by the Stape Team under the Apache 2.0 license.

GTM Gallery Status

:green_circle: Listed