How tiktok/gtm-template-pixel works
Project type and purpose
• This is not a standalone web app or service but a Google Tag Manager (GTM) Template (plugin) that:
• Parses GA4 events from the GTM Data Layer
• Maps those events (or custom configurations) to TikTok Pixel events
• Fires the corresponding TikTok Pixel calls on your website
File-structure analysis
Top-level files:
• metadata.yaml – defines the GTM UI schema (inputs, parameters, triggers)
• template.tpl – markup/template for GTM’s tag-configuration UI
• template.js – the core JavaScript logic that runs inside GTM
• LICENSE, README.md – docs and license
No backend, database, or external microservices—just a GTM plugin that executes in the browser.
Key insights from README
• Two main pieces must be installed via GTM:
1. A Custom HTML tag containing the TikTok “Base Code” snippet (loads the TikTok Pixel library).
2. This Template tag (with metadata, UI template, and JavaScript)
• The template listens for GA4 events in the dataLayer, optionally applies manual overrides, then calls TikTok’s JavaScript Pixel API.
Main components
a. Website / Client page
b. GTM Web Container
c. GTM Data Layer (JavaScript object on the page)
d. Custom HTML Tag (“TikTok Base Code”)
e. Template Tag (“TikTok Pixel Template”)
– metadata.yaml + template.tpl (configuration/UI)
– template.js (runtime logic)
f. TikTok Pixel JS library (loaded by Base Code)
g. TikTok Endpoint (https://analytics.tiktok.com/i18n/pixel/events)
h. (Optional) TikTok Events Manager / Event Builder interactive setup
Relationships & data flows
1. User interacts on website → pushes events into GTM Data Layer
2. GTM container evaluates triggers →
• Custom HTML Tag loads Pixel library on all pages
• Template Tag fires on GA4-event triggers (or manual triggers)
3. template.js reads dataLayer event → maps GA4 schema to TikTok schema → calls TikTok JS API
4. TikTok JS API batches or sends HTTP requests to TikTok Endpoint
5. TikTok processes pixel events for analytics & ad optimization
Architectural patterns & design principles
• Event-driven, plugin-based architecture
• Separation of concerns:
• Base Code tag solely for loading library
• Template tag for mapping and firing events
• Declarative UI schema (metadata.yaml + .tpl) vs. imperative runtime (template.js)