Concepts

Understanding Tags, Triggers, and Zones — the building blocks of YourTM.

Overview

YourTM uses three core concepts to manage tracking and analytics on your website:

Tags

Tags are the code that gets executed when certain conditions are met. They typically send data to analytics platforms, load third-party scripts, or perform custom tracking.

Tag Structure

import { defineTag } from '@yourtm/core'

export default defineTag({
  // Identification
  name: 'GA4 Pageview',
  description: 'Track page views in Google Analytics 4',

  // When to fire
  triggers: ['page-load'],

  // Where to load
  zones: ['global'],

  // Required consent
  consent: ['analytics'],

  // Priority (higher = fires first)
  priority: 100,

  // One-time setup (loads external scripts)
  async setup() {
    const script = document.createElement('script')
    script.src = 'https://www.googletagmanager.com/gtag/js?id=G-XXXXX'
    script.async = true
    document.head.appendChild(script)

    window.dataLayer = window.dataLayer || []
    window.gtag = function() { dataLayer.push(arguments) }
    window.gtag('js', new Date())
  },

  // Runs every time the trigger fires
  execute(ctx) {
    window.gtag('config', 'G-XXXXX', {
      page_title: ctx.dataLayer?.page?.title || document.title,
      page_location: ctx.url.href,
    })
  },
})

Tag Properties

Triggers

Triggers define when tags should fire. They listen for specific events on the page and activate associated tags when conditions are met.

Built-in Trigger Types

Trigger Examples

import { defineTrigger } from '@yourtm/core'

export default defineTrigger({
  name: 'Scroll 75%',
  type: 'scroll',
  config: {
    threshold: 75,    // Fire at 75% scroll depth
    once: true,       // Only fire once per page
  },
})

import { defineTrigger } from '@yourtm/core'

export default defineTrigger({
  name: 'Add to Cart Click',
  type: 'click',
  config: {
    selector: '[data-action="add-to-cart"], .add-to-cart-btn',
    checkChildElements: true,  // Include clicks on child elements
  },
})

import { defineTrigger } from '@yourtm/core'

export default defineTrigger({
  name: 'Contact Form Submit',
  type: 'form',
  config: {
    selector: '#contact-form',
    waitForValidation: true,
  },
})

Variables

Variables are reusable data points that can be used across multiple tags. They allow you to define a piece of data once (like a Product ID or a Cookie value) and use it everywhere.

Variable Types

Defining Variables

import { defineDataLayerVariable, defineComputedVariable } from '@yourtm/core'

// Simple DataLayer variable
export const cartTotal = defineDataLayerVariable({
  name: 'cartTotal',
  path: 'ecommerce.cart.total',
  default: 0
})

// Complex computed variable
export const orderValue = defineComputedVariable({
  name: 'orderValue',
  compute: (ctx) => {
    const items = ctx.dataLayer.ecommerce?.items || []
    return items.reduce((sum, item) => sum + (item.price * item.quantity), 0)
  }
})

Using Variables in Tags

Variables are available on the ctx.variables object in the tag's execute function.

export default defineTag({
  name: 'GA4 Purchase',
  execute(ctx) {
    // Access variables directly
    const value = ctx.variables.orderValue
    const currency = ctx.variables.currencyCode || 'USD'

    gtag('event', 'purchase', {
      value: value,
      currency: currency
    })
  }
})

Zones

Zones define where tags should load. They segment your website into logical areas, ensuring only relevant tags are loaded on each page.

Zone Structure

import { defineZone } from '@yourtm/core'

export default defineZone({
  name: 'checkout',
  description: 'Checkout and payment flow pages',
  match: {
    // Match any of these pathname patterns
    pathname: [
      '/checkout',
      '/checkout/*',
      '/cart',
      '/payment/*',
      '/order/confirmation',
    ],
  },
})

URL Matching

Zones support glob-style URL pattern matching:

Common Zones

import { defineZone } from '@yourtm/core'

export default defineZone({
  name: 'global',
  description: 'Loads on all pages',
  match: {
    pathname: ['**'],  // Match everything
  },
})

import { defineZone } from '@yourtm/core'

export default defineZone({
  name: 'product',
  description: 'Product detail pages',
  match: {
    pathname: ['/products/*', '/p/*', '/item/*'],
  },
})

Consent Management

YourTM has built-in consent management. Tags specify which consent categories they require, and only fire when the user has granted that consent.

Consent Categories

Setting Consent

// In your consent banner / CMP integration
window.YTM.setConsent({
  necessary: true,
  analytics: true,
  marketing: false,
  preferences: true,
})

Tag with Consent

export default defineTag({
  name: 'Meta Pixel',
  triggers: ['page-load'],
  zones: ['global'],
  consent: ['marketing'],  // Only fires if marketing consent granted
  execute(ctx) {
    fbq('track', 'PageView')
  },
})

Data Layer

The data layer is a JavaScript object that stores page and event data. Tags can read from it to send enriched data to analytics platforms.

Pushing to Data Layer

// On your website
window.YTM.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'T12345',
    value: 99.99,
    currency: 'USD',
    items: [
      { item_id: 'SKU123', item_name: 'Widget', price: 99.99 }
    ]
  }
})

Reading in Tags

export default defineTag({
  name: 'GA4 Purchase',
  triggers: ['purchase-event'],
  execute(ctx) {
    const { transaction_id, value, currency, items } = ctx.dataLayer.ecommerce
    gtag('event', 'purchase', {
      transaction_id,
      value,
      currency,
      items,
    })
  },
})

Execution Context

Every tag's execute() function receives a context object with useful information about the current page and event.

Context Properties

Tag Lifecycle

Understanding the tag lifecycle helps you write efficient tags.

Bundle Architecture

YourTM compiles your tags into optimized JavaScript bundles, organized by zone.

Bundle Types

Runtime

The YourTM runtime is a lightweight JavaScript engine that manages tag execution.

Runtime API

// Available on window.YTM

// Initialize (called automatically)
YTM.init()

// Register a tag (called by zone bundles)
YTM.registerTag(tagDefinition)

// Set consent state
YTM.setConsent({ analytics: true, marketing: false })

// Push to data layer
YTM.push({ event: 'purchase', value: 99 })

// Access internal state (for debugging)
YTM._state.tags       // Map of registered tags
YTM._state.triggers   // Map of registered triggers
YTM._state.consent    // Current consent state

Performance

YourTM is designed for maximum performance with minimal impact on your site.

Performance Features

• Tiny runtime — Core is ~2KB gzipped vs GTM's 50-80KB
• Zone-based chunking — Only load tags needed for current page
• Tree shaking — Unused code eliminated at build time
• Edge caching — Bundles served from Cloudflare's global CDN
• Async loading — Non-blocking script loading
• Event delegation — Single listener handles multiple triggers

Performance Budgets

Configure budgets in yourtm.config.ts:

budgets: {
  maxBundleSize: 100_000,   // 100KB total
  maxTagSize: 10_000,       // 10KB per tag
  warnOnSlowTags: 100,      // Warn if tag takes >100ms
}