React Google Analytics Module (Universal Analytics)

Common errors

• Error: `gaTrackingID` is required to initialize Google Analytics

  cause The `ReactGA.initialize` method was called without a Universal Analytics (UA-XXXXXX-X) tracking ID, or with an invalid format like a GA4 (G-XXXXXX) measurement ID.
  fix Provide a valid Universal Analytics tracking ID (e.g., 'UA-12345-1') to `ReactGA.initialize`. If you intend to use GA4, you must switch to a GA4-compatible library like `react-ga4` as `react-ga` does not support GA4 measurement IDs.

• No data appearing in Google Analytics Realtime/Standard Reports

  cause This usually indicates incorrect initialization, an invalid tracking ID, an active ad-blocker, or that you are using a GA4 `G-` measurement ID instead of a Universal Analytics `UA-` tracking ID. Additionally, the `siteSpeedSampleRate` default of 1% can make it seem like no data is being collected.
  fix 1. Verify `ReactGA.initialize` is called once with a correct `UA-` tracking ID. 2. Disable ad-blockers for testing. 3. Add `debug: true` to `initialize` options to see console logs. 4. If using GA4, migrate to `react-ga4`. 5. Set `siteSpeedSampleRate: 100` in `gaOptions` for more comprehensive data collection.

Warnings

• breaking Google Universal Analytics (UA) has been officially deprecated and stopped processing new hits on July 1, 2023. This means `react-ga`, which is built exclusively for UA properties, no longer collects data for standard UA properties.
  Fix: Migrate your analytics implementation to Google Analytics 4 (GA4). `react-ga` does not support GA4's `G-` measurement IDs. Consider using `react-ga4` (a separate library) or integrating the native `gtag.js` directly for GA4 tracking.
• gotcha The default `siteSpeedSampleRate` for Universal Analytics is 1%, meaning only a small fraction of page timing hits are sent. This can lead to insufficient data for performance analysis.
  Fix: When initializing, include `siteSpeedSampleRate: 100` in the `gaOptions` object to send 100% of page timing hits. Example: `ReactGA.initialize('UA-XXXXXXXXX-X', { gaOptions: { siteSpeedSampleRate: 100 } });`
• gotcha Using the `debug: true` option in `ReactGA.initialize` will log analytics calls to the console, which is useful during development but should be avoided in production environments to prevent unnecessary console output and potential performance overhead.
  Fix: Ensure `debug: true` is only enabled in non-production environments. A common pattern is `ReactGA.initialize('UA-XXXXXXXXX-X', { debug: process.env.NODE_ENV === 'development' });`
• gotcha The `ReactGA.initialize` function must be called exactly once before any other tracking functions are invoked. Calling it multiple times or after other tracking calls can lead to inconsistent or lost data.
  Fix: Call `ReactGA.initialize` early in your application's lifecycle, typically within a `useEffect` hook in your root component or in your application's entry file, ensuring it runs only once.

Install

• npm install react-ga npm
• yarn add react-ga yarn
• pnpm add react-ga pnpm

Imports

• ReactGA
  wrong:

  const ReactGA = require('react-ga');

  correct:

  import ReactGA from 'react-ga';

  This is the standard named import for the main ReactGA object, providing all tracking methods. CommonJS `require` works but ESM is preferred in modern React projects.
• ReactGA

  import ReactGA from 'react-ga/core';

  Use this path to import the core non-React specific analytics functionalities, if you don't need the React components (like OutboundLink) or want to avoid React as a direct dependency.
• OutboundLink
  wrong:

  import OutboundLink from 'react-ga';

  correct:

  import { OutboundLink } from 'react-ga';

  OutboundLink is a named export for a React component that handles tracking outbound clicks. It requires React to be a peer dependency.

Quickstart

This quickstart demonstrates how to initialize `react-ga` with a Universal Analytics tracking ID and send a pageview and a custom event. It includes a warning for users attempting to use GA4 IDs.

import ReactGA from 'react-ga';
import React, { useEffect } from 'react';

const GA_TRACKING_ID = process.env.REACT_APP_GA_UA_ID ?? 'UA-000000-01'; // Use a Universal Analytics ID

function App() {
  useEffect(() => {
    if (GA_TRACKING_ID.startsWith('UA-')) {
      ReactGA.initialize(GA_TRACKING_ID, { debug: process.env.NODE_ENV === 'development' });
      ReactGA.pageview(window.location.pathname + window.location.search);
      console.log('ReactGA initialized and pageview sent for UA ID:', GA_TRACKING_ID);
    } else {
      console.warn('GA_TRACKING_ID is not a Universal Analytics ID (UA-). react-ga only supports Universal Analytics. Please use react-ga4 for GA4 (G-) IDs.');
    }
  }, []);

  const handleButtonClick = () => {
    if (GA_TRACKING_ID.startsWith('UA-')) {
      ReactGA.event({
        category: 'User',
        action: 'Clicked Button',
        label: 'Demo Button'
      });
      console.log('GA Event sent: Clicked Demo Button');
    }
  };

  return (
    <div>
      <h1>Welcome to React-GA Demo</h1>
      <p>This demo uses react-ga for Universal Analytics tracking.</p>
      <button onClick={handleButtonClick}>Track Me</button>
      <p>Check your Universal Analytics dashboard for data.</p>
      <p>Note: Universal Analytics is deprecated. For GA4, use react-ga4.</p>
    </div>
  );
}

export default App;