Registry / observability / universal-analytics

universal-analytics

JSON →
library0.5.3jsnpmunverified

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.

observability
npm install universal-analytics
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · UNIVERSAL-ANALYTIC
U
universal-analytics
observabilityjavascriptv0.5.3
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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); } });
Debug
Known issues
breakingGoogle'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.
affects: >=0.1.0
gotchaTracking 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.
affects: >=0.1.0
gotchaBy 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 })`.
affects: >=0.1.0
gotchaThe 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 })`.
affects: >=0.1.0
Errors
Common errors & fixes
Google Analytics is not receiving any data from my application.
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.
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.
Upgrade
Version history
0.5.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
27 hits · last 30 days
node
24
OpenAI (training)
1
Resources
githubhttps://github.com/peaksandpies/universal-analytics ↗
packagehttps://www.npmjs.com/package/universal-analytics ↗
homepagehttps://developers.google.com/analytics/devguides/collection/protocol/v1 ↗
universal-analytics — npm install universal-analytics · libregistry