Skip to main content

Google Analytics 4 Hook

Send feature flag events to Google Analytics 4 for analytics and user behavior correlation.

Overview​

The @ops-ai/toggly-ga4-hook package automatically sends feature flag telemetry to Google Analytics 4. This allows you to:

  • Track feature flag usage as GA4 events
  • Correlate features with user behavior in GA4 reports
  • Set user properties for feature flag states
  • Analyze A/B test results with GA4's built-in analysis tools
  • Build audiences based on feature flag exposure
  • Monitor real-time feature changes via GA4 events

Installation​

$ npm i -s @ops-ai/toggly-ga4-hook

Prerequisites​

  1. Toggly SDK - Any JavaScript-based Toggly SDK with hooks support (v1.0.0+)
  2. Google Analytics 4 - GA4 tracking code (gtag.js) must be loaded on your page

How It Works​

The hook implements multiple lifecycle events:

HookGA4 Action
afterEvaluationSends feature_flag_evaluated event
afterIdentifySets user_id via gtag('config')
afterRefreshSends feature_flag_changed event on state changes

Example evaluation event:

gtag('event', 'feature_flag_evaluated', {
  feature_key: 'checkout-v2',
  feature_enabled: true,
  event_category: 'toggly'
});

Usage​

Vanilla JavaScript​

import { Toggly } from '@ops-ai/feature-flags-toggly';
import { GA4Hook } from '@ops-ai/toggly-ga4-hook';

Toggly.init({
  appKey: 'your-app-key',
  environment: 'Production',
  hooks: [
    new GA4Hook({
      measurementId: 'G-XXXXXXXXXX',
      trackEvaluations: true,
      trackChanges: true,
      setUserProperties: true,
      checkConsent: () => cookieConsent.analytics
    })
  ]
});

React​

import { createTogglyProvider } from '@ops-ai/react-feature-flags-toggly';
import { GA4Hook } from '@ops-ai/toggly-ga4-hook';

const TogglyProvider = await createTogglyProvider({
  appKey: 'your-app-key',
  environment: 'Production',
  hooks: [new GA4Hook({ measurementId: 'G-XXXXXXXXXX' })]
});

Angular​

import { provideToggly } from '@ops-ai/ngx-feature-flags-toggly';
import { GA4Hook } from '@ops-ai/toggly-ga4-hook';

bootstrapApplication(AppComponent, {
  providers: [
    provideToggly({
      appKey: 'your-app-key',
      environment: 'Production',
      hooks: [new GA4Hook({ measurementId: 'G-XXXXXXXXXX' })]
    })
  ]
});

Vue​

import { createApp } from 'vue';
import { TogglyPlugin } from 'vue-feature-flags-toggly';
import { GA4Hook } from '@ops-ai/toggly-ga4-hook';

app.use(TogglyPlugin, {
  appKey: 'your-app-key',
  environment: 'Production',
  hooks: [new GA4Hook({ measurementId: 'G-XXXXXXXXXX' })]
});

Svelte / Astro / Gatsby​

import { Toggly } from '@ops-ai/feature-flags-toggly';
import { GA4Hook } from '@ops-ai/toggly-ga4-hook';

Toggly.init({
  appKey: 'your-app-key',
  environment: 'Production',
  hooks: [new GA4Hook({ measurementId: 'G-XXXXXXXXXX' })]
});

Configuration​

OptionTypeDefaultDescription
enabledbooleantrueEnable or disable the hook
measurementIdstring-GA4 Measurement ID (optional, uses default gtag)
evaluationEventNamestring"feature_flag_evaluated"Custom event name for evaluations
changeEventNamestring"feature_flag_changed"Custom event name for changes
trackEvaluationsbooleantrueTrack feature flag evaluations
trackAllResultsbooleantrueTrack both true and false results
setUserPropertiesbooleanfalseSet GA4 user properties for features
userPropertyPrefixstring"ff_"Prefix for user property names
trackChangesbooleantrueTrack real-time feature changes
trackIdentitybooleantrueSet user_id in GA4
customParametersobject{}Custom parameters for all events
checkConsent() => boolean() => trueConsent callback called before each event
debugbooleanfalseEnable debug logging

Full Configuration Example​

const ga4Hook = new GA4Hook({
  enabled: process.env.NODE_ENV === 'production',
  measurementId: 'G-XXXXXXXXXX',
  evaluationEventName: 'ff_evaluated',
  changeEventName: 'ff_changed',
  trackEvaluations: true,
  trackAllResults: true,
  setUserProperties: true,
  userPropertyPrefix: 'feature_',
  trackChanges: true,
  trackIdentity: true,
  customParameters: {
    app_version: '2.0.0',
    environment: 'production'
  },
  checkConsent: () => {
    return window.cookieConsent?.analytics ?? false;
  },
  debug: false
});

Privacy & Consent (GDPR/CCPA)​

The checkConsent callback integrates with consent management platforms:

// OneTrust
new GA4Hook({
  checkConsent: () => window.OneTrust?.IsAlertBoxClosed() ?? false
});

// Google Consent Mode v2
new GA4Hook({
  checkConsent: () => {
    return window.dataLayer?.some(item =>
      item[0] === 'consent' &&
      item[1] === 'update' &&
      item[2]?.analytics_storage === 'granted'
    ) ?? false;
  }
});

Only feature flag keys, evaluation results, optional custom parameters, and (when enabled) user identity are sent. No automatic PII collection.

Viewing in GA4​

  1. Go to GA4 Admin → Events
  2. Look for feature_flag_evaluated and feature_flag_changed
  3. In Explore → Free Form, add feature_key and feature_enabled as dimensions
  4. Optionally create custom dimensions for ff_* user properties under Custom definitions

Error Handling​

The hook never breaks the Toggly SDK:

  • gtag API calls are wrapped in try-catch
  • Missing gtag is handled silently
  • A console warning (not error) is shown if gtag is not detected at initialization
  • gtag becoming available after initialization is handled automatically

Dynamic Management​

// Add at runtime
Toggly.addHook(new GA4Hook({ measurementId: 'G-XXXXXXXXXX' }));

// Remove by name
Toggly.removeHook('ga4-hook');

Troubleshooting​

Events not appearing​

  1. Verify gtag is loaded: console.log(typeof window.gtag === 'function')
  2. Check your measurement ID format (G-XXXXXXXXXX)
  3. Check your checkConsent callback returns true
  4. Enable debug mode: new GA4Hook({ debug: true })
  5. Use GA4 DebugView for real-time event inspection

Console warning at startup​

The warning "Google Analytics 4 gtag not detected" means gtag was not loaded when the hook was created. The hook will start sending events once gtag becomes available.

Performance​

  • Overhead: <0.1ms per evaluation
  • Bundle size: ~2KB minified
  • No batching (gtag handles its own queue)