{"id":15253,"library":"universal-analytics","title":"Universal Analytics Node.js Tracker","description":"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.","status":"deprecated","version":"0.5.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/peaksandpies/universal-analytics","tags":["javascript","google","analytics","universal","tracking"],"install":[{"cmd":"npm install universal-analytics","lang":"bash","label":"npm"},{"cmd":"yarn add universal-analytics","lang":"bash","label":"yarn"},{"cmd":"pnpm add universal-analytics","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library exports a default function for initialization, not named exports. Supports both ES Modules and CommonJS.","wrong":"import { ua } from 'universal-analytics'","symbol":"ua","correct":"import ua from 'universal-analytics'"},{"note":"CommonJS require style. The library exports a default function for initialization.","wrong":"const { ua } = require('universal-analytics')","symbol":"ua","correct":"const ua = require('universal-analytics')"},{"note":"The Visitor instance is created by calling the default export function, not directly imported as a class or named export.","wrong":"import { Visitor } from 'universal-analytics'","symbol":"Visitor","correct":"const visitor = ua('UA-XXXX-XX')"}],"quickstart":{"code":"const ua = require('universal-analytics');\n\n// Replace with your actual Google Analytics UA ID\nconst trackingId = process.env.UNIVERSAL_ANALYTICS_ID ?? 'UA-XXXX-XX';\n\n// Initialize a visitor instance. A random UUID will be generated if client ID is omitted.\nconst visitor = ua(trackingId);\n\n// Track a simple pageview\nvisitor.pageview('/')\n  .send((err) => {\n    if (err) {\n      console.error('Failed to send pageview:', err);\n    } else {\n      console.log('Pageview sent successfully to', trackingId);\n    }\n  });\n\n// Track an event with persistent parameters\nconst sessionVisitor = ua(trackingId, 'some-user-client-id', { uid: 'user123', strictCidFormat: false });\nsessionVisitor.event('Category', 'Action', 'Label', 1, { ipOverride: '127.0.0.1' })\n  .send((err) => {\n    if (err) {\n      console.error('Failed to send event:', err);\n    } else {\n      console.log('Event sent successfully for user123 to', trackingId);\n    }\n  });","lang":"javascript","description":"Demonstrates initializing a Universal Analytics visitor, sending a basic pageview, and sending an event with persistent parameters and an explicit client ID."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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 })`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"To force HTTP, include `{ http: true }` in the options object during visitor initialization: `ua('UA-XXXX-XX', { http: true })`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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'));`","cause":"The tracking request was not explicitly sent to the Google Analytics servers.","error":"Google Analytics is not receiving any data from my application."},{"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.","cause":"The `universal-analytics` initialization function `ua()` was called without a valid tracking ID or resulted in an undefined visitor object.","error":"TypeError: Cannot read properties of undefined (reading 'pageview') or similar chaining errors."}],"ecosystem":"npm"}