tessl/npm-gatsby-plugin-google-gtag

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Gatsby Plugin Google Gtag

Name: tessl/npm-gatsby-plugin-google-gtag
Author: tessl

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;