Amplitude Node.js Wrapper

6.0.0 verified Thu Apr 23 auth: no javascript

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.

Common errors

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

cause 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'.

error Amplitude error: Missing required field event_type. ↓

cause 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' }.

error TypeError: Amplitude is not a constructor ↓

cause 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');.

Warnings

breaking Version 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.

breaking Since 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.

gotcha In 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.

Install

npm install amplitude

yarn add amplitude

pnpm add amplitude

Imports

Amplitude
wrong
```
const Amplitude = require('amplitude').default;
```
correct
```
import { Amplitude } from 'amplitude';
```
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.

Quickstart

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();