or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

custom-events.mdindex.mdoutbound-link.mdplugin-configuration.md
tile.json

plugin-configuration.mddocs/

Plugin Configuration

Configuration schema validation and setup options for Google Global Site Tag integration in Gatsby.

Capabilities

Plugin Options Schema

Validates plugin configuration using Joi schema validation during Gatsby build process.

/**
 * Joi schema for validating plugin options
 * @param options - Object containing Joi for schema creation
 * @returns Joi schema object for plugin validation
 */
function pluginOptionsSchema({ Joi }): object;

interface PluginOptions {
  /** Required array of Google service tracking IDs */
  trackingIds: string[];
  /** Optional gtag configuration object passed directly to gtag config */
  gtagConfig?: GtagConfig;
  /** Optional plugin-specific behavior configuration */
  pluginConfig?: PluginConfig;
}

Gtag Configuration

Configuration object passed directly to Google's gtag config command.

interface GtagConfig {
  /** Google Optimize container ID for A/B testing */
  optimize_id?: string;
  /** Enable IP anonymization for privacy compliance */
  anonymize_ip?: boolean;
  /** Cookie expiration time in seconds (0 = session only) */
  cookie_expires?: number;
  /** Cookie name override (default: '_ga') */
  cookie_name?: string;
  /** Sampling rate (0.0 to 1.0) to control percentage of sessions tracked */
  sample_rate?: number;
  /** Disable automatic pageview tracking (plugin sets this to false internally) */
  send_page_view?: boolean;
  /** Additional gtag config options */
  [key: string]: any;
}

Plugin Configuration

Plugin-specific behavior and feature configuration.

interface PluginConfig {
  /** Place tracking script in <head> instead of <body> (default: false) */
  head?: boolean;
  /** Respect Do Not Track browser setting (default: false) */
  respectDNT?: boolean;
  /** Array of glob patterns for paths to exclude from tracking */
  exclude?: string[];
  /** Custom origin for gtag script (default: https://www.googletagmanager.com) */
  origin?: string;
  /** Delay in milliseconds before processing pageview events on route update */
  delayOnRouteUpdate?: number;
}

Usage Examples:

Basic Configuration

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-google-gtag`,
      options: {
        trackingIds: ["GA-TRACKING_ID"],
      },
    },
  ],
};

Advanced Configuration

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-google-gtag`,
      options: {
        trackingIds: [
          "GA-TRACKING_ID", // Google Analytics
          "AW-CONVERSION_ID", // Google Ads
          "DC-FLOODLIGHT_ID", // Campaign Manager
        ],
        gtagConfig: {
          optimize_id: "OPT_CONTAINER_ID",
          anonymize_ip: true,
          cookie_expires: 0,
          sample_rate: 0.8,
        },
        pluginConfig: {
          head: true,
          respectDNT: true,
          exclude: ["/preview/**", "/admin/**"],
          origin: "https://my-custom-origin.com",
          delayOnRouteUpdate: 1000,
        },
      },
    },
  ],
};

Privacy-Focused Configuration

// gatsby-config.js - GDPR compliant setup
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-google-gtag`,
      options: {
        trackingIds: ["GA-TRACKING_ID"],
        gtagConfig: {
          anonymize_ip: true,
          cookie_expires: 0,
        },
        pluginConfig: {
          respectDNT: true,
          exclude: ["/privacy/**"],
        },
      },
    },
  ],
};

Validation Rules

The plugin validates configuration during build with the following rules:

  • trackingIds: Required array of strings
  • gtagConfig: Optional object with boolean anonymize_ip (default: false)
  • pluginConfig.head: Optional boolean (default: false)
  • pluginConfig.respectDNT: Optional boolean (default: false)
  • pluginConfig.exclude: Optional array of strings (default: [])
  • pluginConfig.origin: Optional string (default: "https://www.googletagmanager.com")
  • pluginConfig.delayOnRouteUpdate: Optional number (default: 0)

Invalid configurations will cause Gatsby build to fail with descriptive error messages.

Privacy and Anonymization

IP Anonymization Opt-Out

When gtagConfig.anonymize_ip is set to true, the plugin automatically generates opt-out functionality:

/**
 * Global opt-out function generated when anonymize_ip is enabled
 * Allows users to disable tracking by setting a cookie
 */
declare function gaOptout(): void;

Usage in HTML:

<!-- Provide users with an opt-out link -->
<a href="javascript:gaOptout();">Disable Google Tracking</a>

The opt-out function sets a cookie that prevents future tracking:

  • Cookie name: ga-disable-{TRACKING_ID}
  • Cookie value: true
  • Cookie expires: December 31, 2099
  • Cookie path: / (site-wide)