amplitude

library0.1jsnpmunverified

The `amplitude` package provides a server-side Node.js wrapper for Amplitude's HTTP API, facilitating event tracking and user identification. Currently at stable version 6.0.0, this library integrates with Amplitude's V2 HTTP API for sending analytics data. It supports both individual event tracking and batch submissions, and includes functionality for Amplitude's Identify API to manage user properties without event logging. A notable feature is its built-in handling for Amplitude's past SSL certificate issues, allowing users to configure an alternative endpoint if needed. The package ships with TypeScript type definitions, ensuring type safety for TypeScript projects. While its release cadence isn't extremely rapid, updates address API changes and maintain compatibility with modern Node.js environments.

http-networking communication

npm install amplitude

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AMPLITUDE

amplitude

http-networkingjavascriptv0.1

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.

Amplitude

✓ import { Amplitude } from 'amplitude';

✗ const Amplitude = require('amplitude').default;

For ESM projects, use named import. The package ships TypeScript types.

Amplitude (CommonJS)

✓ const Amplitude = require('amplitude');

CommonJS syntax for Node.js environments. This is demonstrated in the package's basic initialization.

Amplitude instance

✓ const amplitude = new Amplitude(process.env.AMPLITUDE_API_TOKEN ?? '');

The API token is the only required field for initialization. It's recommended to retrieve it from environment variables.

This quickstart demonstrates how to initialize the Amplitude client, track a single user event, and update user properties using the Identify API. It emphasizes using environment variables for the API token.

import { Amplitude } from 'amplitude'; const AMPLITUDE_API_TOKEN = process.env.AMPLITUDE_API_TOKEN ?? ''; if (!AMPLITUDE_API_TOKEN) { console.error('AMPLITUDE_API_TOKEN environment variable is not set.'); process.exit(1); } const amplitude = new Amplitude(AMPLITUDE_API_TOKEN, { // Optionally configure a custom endpoint if needed, e.g., for self-hosted proxies or past SSL issues // tokenEndpoint: 'https://api2.amplitude.com' }); async function trackUserEvent() { try { const eventData = { event_type: 'User Registered', user_id: 'user-12345', event_properties: { plan: 'premium', signup_method: 'email' }, user_properties: { is_new_user: true } }; console.log('Tracking event:', eventData); const response = await amplitude.track(eventData); console.log('Amplitude track response:', response.status); const identifyData = { user_id: 'user-12345', user_properties: { $set: { last_activity: new Date().toISOString() }, $add: { login_count: 1 } } }; console.log('Identifying user properties:', identifyData); const identifyResponse = await amplitude.identify(identifyData); console.log('Amplitude identify response:', identifyResponse.status); } catch (error: any) { console.error('Failed to track event or identify user:', error.message); } } trackUserEvent();

Debug

Known issues

breakingVersion 5.0.0 and above of this package migrated to Amplitude's V2 HTTP API. This change might require reviewing and updating event payload structures to conform to the V2 specification, especially regarding required fields and data types.

fix

Consult Amplitude's HTTP API V2 documentation for required fields and data format. Specifically, ensure `event_type` and either `user_id` or `device_id` are present.

affects: >=5.0.0

breakingSince version 5.0.0, both `user_id` and `device_id` fields, when provided in an event payload, must contain a minimum of 5 characters. Events with shorter IDs will be rejected by the Amplitude API.

fix

Ensure all `user_id` and `device_id` values passed to `amplitude.track()` or `amplitude.identify()` are at least 5 characters long.

affects: >=5.0.0

gotchaIn 2020, Amplitude experienced SSL certificate issues affecting some clients. While Amplitude likely resolved this on their end, the package provides a `tokenEndpoint` configuration option or `AMPLITUDE_TOKEN_ENDPOINT` environment variable to use an alternative endpoint (`https://api2.amplitude.com`). This is useful for specific network configurations or if similar issues re-emerge.

fix

If encountering connection issues, particularly SSL-related, try setting `AMPLITUDE_TOKEN_ENDPOINT='https://api2.amplitude.com'` environment variable or passing `{ tokenEndpoint: 'https://api2.amplitude.com' }` to the `Amplitude` constructor.

affects: >=5.1.0

Errors

Common errors & fixes

Amplitude error: user_id and device_id cannot be null or empty and must be 5 or more characters.

The `user_id` or `device_id` provided in the event payload is either missing, empty, or less than 5 characters long, which is a requirement for Amplitude's V2 API.

fix

Ensure that every event payload includes either a `user_id` or a `device_id`, and that its value is a string of 5 or more characters. Example: `user_id: 'user-abcde'`.

Amplitude error: Missing required field event_type.

The `event_type` field is mandatory for all events sent to Amplitude's `track` method.

fix

Add an `event_type` string to your event data object, e.g., `{ event_type: 'Product Viewed' }`.

TypeError: Amplitude is not a constructor

This typically occurs in ESM contexts when attempting to use `require('amplitude')` directly or in CJS contexts if trying to destructure a non-existent default export.

fix

For ESM, use `import { Amplitude } from 'amplitude';`. For CommonJS, use `const Amplitude = require('amplitude');`.

Upgrade

Version history

0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

45 hits · last 30 days

node

Anthropic

OpenAI (training)

Resources

githubhttps://github.com/geoffdutton/amplitude ↗

packagehttps://www.npmjs.com/package/amplitude ↗

homepagehttps://amplitude.com ↗