Universal Analytics Node.js Tracker

0.5.3 · deprecated · verified Tue Apr 21

This `universal-analytics` package provides a Node.js module for interacting with Google's Universal Analytics (UA) tracking via the Measurement Protocol v1. It enables server-side tracking of user behavior without requiring client-side browser integration. The current stable version is 0.5.3. This library is specifically designed for Universal Analytics, which has been deprecated by Google in favor of Google Analytics 4 (GA4). Consequently, this package is primarily for maintaining existing legacy systems that still rely on Universal Analytics properties, as new UA properties stopped processing data in July 2023, and all UA processing will cease in July 2024. There is no active release cadence as the underlying service is sunsetting, differentiating it from clients for modern GA4 properties.

Common errors

```
Google Analytics is not receiving any data from my application.
```
cause The tracking request was not explicitly sent to the Google Analytics servers.

fix After any tracking call (e.g., `pageview`, `event`), ensure you append `.send()` or provide a callback function, for example: `visitor.pageview('/home').send();` or `visitor.event('Category', 'Action', () => console.log('Event sent'));`
```
TypeError: Cannot read properties of undefined (reading 'pageview') or similar chaining errors.
```
cause The `universal-analytics` initialization function `ua()` was called without a valid tracking ID or resulted in an undefined visitor object.

fix Ensure that `ua('UA-XXXX-XX')` is called with your valid Universal Analytics Tracking ID (e.g., 'UA-12345-6'). Check for typos or missing configuration.

Warnings

breaking Google's Universal Analytics (UA) service, which this package targets, has been deprecated. Standard UA properties stopped processing new hits on July 1, 2023, and all UA properties (including 360) will stop processing new hits on July 1, 2024. This package is therefore unsuitable for new projects and will become fully non-functional once the service is shut down.
Fix: Migrate your analytics implementation to Google Analytics 4 (GA4). This will require using a different client library or implementing the GA4 Measurement Protocol directly, as this package does not support GA4.
gotcha Tracking calls like `pageview()`, `event()`, etc., do not send data to Google Analytics unless explicitly followed by a `.send()` call or by providing a callback function as the last argument to the tracking method.
Fix: Always chain `.send()` at the end of a tracking call (e.g., `visitor.pageview('/').send()`) or provide a callback (e.g., `visitor.event('Cat', 'Act', callback)`). Without it, data will not be transmitted.
gotcha By default, the library expects client IDs (CIDs) to be in UUID v4 format. Providing a non-UUID v4 string as a client ID without specific configuration will result in an error or incorrect tracking.
Fix: If you need to use a custom client ID that is not a UUID v4, pass `strictCidFormat: false` in the options object during visitor initialization: `ua('UA-XXXX-XX', 'CUSTOM_CLIENTID', { strictCidFormat: false })`.
gotcha The library defaults to using HTTPS for all Measurement Protocol requests. If your environment requires or you explicitly wish to use HTTP, this needs to be configured.
Fix: To force HTTP, include `{ http: true }` in the options object during visitor initialization: `ua('UA-XXXX-XX', { http: true })`.

Install

npm install universal-analytics npm
yarn add universal-analytics yarn
pnpm add universal-analytics pnpm

Imports

ua
wrong:
```
import { ua } from 'universal-analytics'
```
correct:
```
import ua from 'universal-analytics'
```
The library exports a default function for initialization, not named exports. Supports both ES Modules and CommonJS.
ua
wrong:
```
const { ua } = require('universal-analytics')
```
correct:
```
const ua = require('universal-analytics')
```
CommonJS require style. The library exports a default function for initialization.
Visitor
wrong:
```
import { Visitor } from 'universal-analytics'
```
correct:
```
const visitor = ua('UA-XXXX-XX')
```
The Visitor instance is created by calling the default export function, not directly imported as a class or named export.

Quickstart

Demonstrates initializing a Universal Analytics visitor, sending a basic pageview, and sending an event with persistent parameters and an explicit client ID.

const ua = require('universal-analytics');

// Replace with your actual Google Analytics UA ID
const trackingId = process.env.UNIVERSAL_ANALYTICS_ID ?? 'UA-XXXX-XX';

// Initialize a visitor instance. A random UUID will be generated if client ID is omitted.
const visitor = ua(trackingId);

// Track a simple pageview
visitor.pageview('/')
  .send((err) => {
    if (err) {
      console.error('Failed to send pageview:', err);
    } else {
      console.log('Pageview sent successfully to', trackingId);
    }
  });

// Track an event with persistent parameters
const sessionVisitor = ua(trackingId, 'some-user-client-id', { uid: 'user123', strictCidFormat: false });
sessionVisitor.event('Category', 'Action', 'Label', 1, { ipOverride: '127.0.0.1' })
  .send((err) => {
    if (err) {
      console.error('Failed to send event:', err);
    } else {
      console.log('Event sent successfully for user123 to', trackingId);
    }
  });

view raw JSON →