# tiktok/gtm-template-pixel architecture

> Architecture diagram of the GitHub repository tiktok/gtm-template-pixel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tiktok/gtm-template-pixel
- Repository: https://github.com/tiktok/gtm-template-pixel

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Layer
    subgraph "Browser" 
        direction TB
        Website["Website / Client Page"]:::infra
        DataLayer["GTM Data Layer\n(JavaScript object)"]:::infra
    end

    Website -->|"pushes events"| DataLayer

    %% GTM Container Layer
    subgraph "GTM Container" 
        direction TB
        CustomHTML["Custom HTML Tag\n(Base Code)"]:::runtime
        subgraph "Template Tag" 
            direction TB
            GtmSchema["GTM UI Schema\n(Template Configuration)"]:::schema
            GtmTpl["GTM Tag-Configuration Markup\n(UI Template)"]:::schema
            RuntimeLogic["Runtime Logic\n(template.js)"]:::runtime
        end
    end

    DataLayer -->|"GA4 Event Trigger"| CustomHTML
    DataLayer -->|"GA4 Event Trigger"| RuntimeLogic
    GtmSchema -->|"configures"| RuntimeLogic
    GtmTpl -->|"configures"| RuntimeLogic

    %% Pixel Library
    PixelLib["TikTok Pixel JS Library\n(loaded by Base Code)"]:::runtime

    CustomHTML -->|"loads"| PixelLib
    RuntimeLogic -->|"calls API"| PixelLib

    %% External Service
    subgraph "External Service" 
        direction TB
        TikTokEndpoint["TikTok Endpoint\n(analytics.tiktok.com/i18n/pixel/events)"]:::external
    end

    PixelLib -->|"HTTP Requests"| TikTokEndpoint

    %% Documentation & License
    Documentation["Project Documentation\n(README.md)"]:::docs
    License["License File\n(LICENSE)"]:::docs

    %% Click Events
    click GtmSchema "https://github.com/tiktok/gtm-template-pixel/blob/main/metadata.yaml"
    click GtmTpl "https://github.com/tiktok/gtm-template-pixel/blob/main/template.tpl"
    click RuntimeLogic "https://github.com/tiktok/gtm-template-pixel/blob/main/template.js"
    click Documentation "https://github.com/tiktok/gtm-template-pixel/blob/main/README.md"
    click License "https://github.com/tiktok/gtm-template-pixel/tree/main/LICENSE"

    %% Styles
    classDef infra fill:#cccccc,stroke:#333,stroke-width:1px
    classDef schema fill:#ccffcc,stroke:#2d7a01,stroke-width:1px
    classDef runtime fill:#cce5ff,stroke:#0366d6,stroke-width:1px
    classDef external fill:#ffe5cc,stroke:#d65a00,stroke-width:1px
    classDef docs fill:#ffffcc,stroke:#999900,stroke-width:1px
```
