Node.js SDK (Maintenance)

This is Amplitude Node.js SDK written in Typescript, the first backend SDK for Amplitude.

The client-side SDKs are optimized to track session and attribution for a single user or device. The Node SDK's focus is to offer a helpful developer experience to help back-end services reliably and correctly send events from many users and sources.

The Node SDK provides:

• Batching of events to send multiple events in the same request.
• Retry handling mechanisms to handle when a network request fails, or a payload is throttled or invalid.
• Useful utilities and typing help debug instrumentation issues.

By default, the Node SDK uses the HTTP API V2.

Get started¶

Run npm install @amplitude/node in your project directory, the same level with package.json.

Usage¶

Initialize the SDK¶

Before you can instrument, you must initialize the SDK using the API key for your Amplitude project. Initialization creates a default instance, but you can create more instances using getInstance with a string name.

// Option 1, initialize with API_KEY only
Amplitude.init(AMPLITUDE_API_KEY);

// Option 2, initialize including configuration
var options = {};
Amplitude.init(AMPLITUDE_API_KEY, options);

Configuration¶

Configure batching behavior¶

To support high performance environments, the SDK sends events in batches. Every event logged by logEvent method is queued in memory. Events are flushed in batch in background. You can customize batch behavior with maxCachedEvents and uploadIntervalInSec. By default, the serverUrl will be https://api2.amplitude.com/2/httpapi. For customers who want to send large batches of data at a time, you can use the batch mode. You need to set the serverl url to the the batch event upload API based on your needs.

• Standard Server Batch API - https://api2.amplitude.com/batch
• EU Residency Server Batch API - https://api.eu.amplitude.com/batch

Both the regular mode and the batch mode use the same events upload threshold and flush time intervals.

Amplitude.init(AMPLITUDE_API_KEY, {
    // Events queued in memory will flush when number of events exceed upload threshold
    // Default value is 16000
    maxCachedEvents: 20000,
    // Events queue will flush every certain milliseconds based on setting
    // Default value is 0 second. 
    uploadIntervalInSec: 10,
});

EU data residency¶

Sending data to Amplitude's EU servers, you need to configure the server URL during the initialization.

client = Amplitude.init(<AMPLITUDE_API_KEY>, {
    serverUrl: "https://api.eu.amplitude.com/2/httpapi"
});

Send events¶

import * as Amplitude from '@amplitude/node';

const client = Amplitude.init(<AMPLITUDE_API_KEY>);

client.logEvent({
  event_type: 'Node.js Event',
  user_id: 'datamonster@gmail.com',
  location_lat: 37.77,
  location_lng: -122.39,
  ip: '127.0.0.1',
  event_properties: {
    keyString: 'valueString',
    keyInt: 11,
    keyBool: true
  }
});

// Send any events that are currently queued for sending.
// Will automatically happen on the next event loop.
client.flush();

// ES5 Syntax
const Amplitude = require('@amplitude/node');
// ES6 Syntax
import * as Amplitude from '@amplitude/node';

var client = Amplitude.init(<AMPLITUDE_API_KEY>);
client.logEvent({
  event_type: 'Node.js Event',
  user_id: 'datamonster@gmail.com',
  location_lat: 37.77,
  location_lng: -122.39,
  ip: '127.0.0.1',
  event_properties: {
    keyString: 'valueString',
    keyInt: 11,
    keyBool: true
  }
});

// Send any events that are currently queued for sending.
// Will automatically happen on the next event loop.
client.flush();

Middleware¶

Middleware allows you to extend Amplitude by running a sequence of custom code on every event. This pattern is flexible and you can use it to support event enrichment, transformation, filtering, routing to third-party destinations, and more.

Each middleware is a simple function with this signature:

function (payload: MiddlwarePayload: next: MiddlewareNext): void;

The payload contains the event as well as an optional extra that allows you to pass custom data to your own middleware implementations.

To invoke the next Middleware in the queue, use the next function. You must call next(payload) to continue the Middleware chain. If a Middleware doesn't call next, then the event processing stop executing after the current middleware completes.

Add middleware to Amplitude via client.addEventMiddleware(). You can add as many middleware as you like. Each middleware runs in the order in which it was added.

const loggingMiddleware: Middleware = (payload, next) => {
  console.log(`[amplitude] event=${payload.event} extra=${payload.extra}`);
  // continue to next middleware in chain
  next(payload);
}

const filteringMiddleware: Middleware = (payload, next) => {
  const {eventType} =  payload.event;
  if (shouldSendEvent(eventType)) {
    next(payload)
  } else {
    // event will not continue to following middleware or be sent to Amplitude
    console.log(`Filtered event: ${eventType}`);
  }
}

client.addEventMiddleware(loggingMiddleware)
client.addEventMiddleware(filteringMiddleware)

You can find examples for Typescript and JavaScript.

More resources¶

If you have any problems or issues with the SDK, feel free to create a GitHub issue or submit a request on Amplitude Help.