or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

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

tessl/npm-gatsby-plugin-google-gtag

Gatsby plugin that provides comprehensive Google Global Site Tag (gtag.js) integration for tracking across multiple Google services

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/gatsby-plugin-google-gtag@5.15.x

To install, run

npx @tessl/cli install tessl/npm-gatsby-plugin-google-gtag@5.15.0

index.mddocs/

Gatsby Plugin Google Gtag

Gatsby plugin that provides comprehensive Google Global Site Tag (gtag.js) integration for tracking across multiple Google services. Enables tracking for Google Analytics, Google Ads, Campaign Manager, Display & Video 360, and Search Ads 360 through a unified tagging framework.

Package Information

  • Package Name: gatsby-plugin-google-gtag
  • Package Type: npm
  • Language: JavaScript
  • Production Only: This plugin only works in production mode (gatsby build && gatsby serve)
  • Installation: npm install gatsby-plugin-google-gtag
  • Peer Dependencies: Gatsby ^5.0.0, React ^18.0.0, React-DOM ^18.0.0

Core Imports

import { OutboundLink } from "gatsby-plugin-google-gtag";

For CommonJS:

const { OutboundLink } = require("gatsby-plugin-google-gtag");

Basic Usage

Plugin Configuration

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-google-gtag`,
      options: {
        // Required: tracking IDs for Google services
        trackingIds: [
          "GA-TRACKING_ID", // Google Analytics
          "AW-CONVERSION_ID", // Google Ads
        ],
        // Optional: gtag configuration
        gtagConfig: {
          optimize_id: "OPT_CONTAINER_ID",
          anonymize_ip: true,
          cookie_expires: 0,
        },
        // Optional: plugin behavior configuration
        pluginConfig: {
          head: false,
          respectDNT: true,
          exclude: ["/preview/**"],
          delayOnRouteUpdate: 0,
        },
      },
    },
  ],
};

OutboundLink Component

import React from "react";
import { OutboundLink } from "gatsby-plugin-google-gtag";

export default function MyComponent() {
  return (
    <OutboundLink href="https://example.com">
      Visit External Site
    </OutboundLink>
  );
}

Custom Event Tracking

// Client-side event tracking
if (typeof window !== "undefined" && window.gtag) {
  window.gtag("event", "click", {
    event_category: "engagement",
    event_label: "button_click",
  });
}

Architecture

The plugin integrates with Gatsby's lifecycle through multiple APIs:

  • Plugin Options Schema: Validates configuration using Joi schema validation
  • Server-Side Rendering: Injects gtag scripts and configuration during build
  • Browser Runtime: Handles route change tracking and pageview events
  • React Components: Provides OutboundLink component for tracking external links

Capabilities

Plugin Configuration

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

// Plugin options interface
interface PluginOptions {
  trackingIds: string[];
  gtagConfig?: GtagConfig;
  pluginConfig?: PluginConfig;
}

interface GtagConfig {
  optimize_id?: string;
  anonymize_ip?: boolean;
  cookie_expires?: number;
  cookie_name?: string;
  sample_rate?: number;
  send_page_view?: boolean;
  [key: string]: any;
}

interface PluginConfig {
  head?: boolean;
  respectDNT?: boolean;
  exclude?: string[];
  origin?: string;
  delayOnRouteUpdate?: number;
}

Plugin Configuration

OutboundLink Component

React component for tracking clicks on external links with automatic gtag event firing.

import * as React from "react";

interface OutboundLinkProps {
  onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
}

declare const OutboundLink: React.ForwardRefExoticComponent<
  OutboundLinkProps & React.HTMLProps<HTMLAnchorElement> & React.RefAttributes<HTMLAnchorElement>
>;

OutboundLink Component

Custom Event Tracking

Global gtag function for firing custom events and conversions.

// Global gtag function (available after plugin initialization)
declare function gtag(
  command: "event" | "config" | "js",
  eventNameOrTrackingId: string | Date,
  parameters?: EventParameters | GtagConfig
): void;

interface EventParameters {
  event_category?: string;
  event_label?: string;
  send_to?: string;
  transport_type?: string;
  event_callback?: () => void;
  [key: string]: any;
}

Custom Event Tracking

Gatsby Plugin APIs

Core Gatsby plugin APIs that enable the gtag integration.

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

/**
 * Server-side rendering hook to inject gtag scripts and configuration
 * @param {object} gatsbyUtils - Gatsby SSR utilities (setHeadComponents, setPostBodyComponents)
 * @param {PluginOptions} pluginOptions - Plugin configuration options
 */
function onRenderBody(gatsbyUtils, pluginOptions): void;

/**
 * Browser-side hook to handle route change tracking
 * @param {object} location - Gatsby location object with pathname, search, hash
 * @param {PluginOptions} pluginOptions - Plugin configuration options  
 */
function onRouteUpdate({ location }, pluginOptions): void;