Node SDK

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.

Initialize the SDK

Before you 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.

1// Option 1, initialize with API_KEY only
2Amplitude.init(AMPLITUDE_API_KEY);
3 
4// Option 2, initialize including configuration
5var options = {};
6Amplitude.init(AMPLITUDE_API_KEY, options);

Configure the SDK

Name Description Default Value
debug boolean. Whether or not the SDK should be started in debug mode. This will enable the SDK to generate logs at WARN level or above, if the logLevel is not specified. false
logLevel LogLevel. Configuration of the logging verbosity of the SDK. None - No Logs will be surfaced. Error - SDK internal errors will be generated. Warn - Warnings will be generated around dangerous/deprecated features. Verbose - All SDK actions will be logged. LogLevel.None
maxCachedEvents number. The maximum events in the buffer. 16000
retryTimeouts number[]. Determines # of retries for sending failed events and how long each retry to wait for (ms). An empty array means no retries. [100, 100, 200, 200, 400, 400, 800, 800, 1600, 1600, 3200, 3200]
optOut boolean. Whether you opt out from sending events. false
retryClass Retry. The class being used to handle event retrying. null
transportClass Transport. The class being used to transport events. null
serverUrl string. If you're using a proxy server, set its url here. https://api2.amplitude.com/2/httpapi
uploadIntervalInSec number. The events upload interval in seconds. 0
minIdLength number. Optional parameter allowing users to set minimum permitted length for user_id & device_id fields. 5
requestTimeoutMillis number. Configurable timeout in milliseconds. 10000
onRetry (response: Response, attemptNumber: number, isLastRetry: boolean) => boolean). @param response - Response from the given retry attempt. @param attemptNumber - Index in retryTimeouts for how long Amplitude waited before this retry attempt. Starts at 0. @param isLastRetry - True if attemptNumber === retryTimeouts.length - 1. Lifecycle callback that is executed after a retry attempt. Called in {@link Retry.sendEventsWithRetry}. null

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 batches 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 server url to 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.

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

EU data residency

To send data to Amplitude's EU servers, configure the server URL during initialization.

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

Send events

Note

This SDK uses the HTTP V2 API and follows the same constraints for events. Make sure that all events logged in the SDK have the event_type field and at least one of device_id or user_id, and follow the HTTP API's constraints on each of those fields.

To prevent instrumentation issues, device IDs and user IDs must be strings with a length of 5 characters or more. If an event contains a device ID or user ID that's too short, the ID value is removed from the event. If the event doesn't have a user_id or device_id value, the upload may be rejected with a 400 status. Override the default minimum length of 5 characters by passing the min_id_length option with the request.

1import * as Amplitude from '@amplitude/node';
2 
3const client = Amplitude.init(AMPLITUDE_API_KEY);
4 
5client.logEvent({
6 event_type: 'Node.js Event',
7 user_id: 'datamonster@gmail.com',
8 location_lat: 37.77,
9 location_lng: -122.39,
10 ip: '127.0.0.1',
11 event_properties: {
12 keyString: 'valueString',
13 keyInt: 11,
14 keyBool: true
15 }
16});
17 
18// Send any events that are currently queued for sending.
19// Will automatically happen on the next event loop.
20client.flush();

1// ES5 Syntax
2const Amplitude = require('@amplitude/node');
3// ES6 Syntax
4import * as Amplitude from '@amplitude/node';
5 
6var client = Amplitude.init(AMPLITUDE_API_KEY);
7client.logEvent({
8 event_type: 'Node.js Event',
9 user_id: 'datamonster@gmail.com',
10 location_lat: 37.77,
11 location_lng: -122.39,
12 ip: '127.0.0.1',
13 event_properties: {
14 keyString: 'valueString',
15 keyInt: 11,
16 keyBool: true
17 }
18});
19 
20// Send any events that are currently queued for sending.
21// Will automatically happen on the next event loop.
22client.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:

1function (payload: MiddlewarePayload: 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.

1const loggingMiddleware: Middleware = (payload, next) => {
2 console.log(`[amplitude] event=${payload.event} extra=${payload.extra}`);
3 // continue to next middleware in chain
4 next(payload);
5}
6 
7const filteringMiddleware: Middleware = (payload, next) => {
8 const {eventType} = payload.event;
9 if (shouldSendEvent(eventType)) {
10 next(payload)
11 } else {
12 // event will not continue to following middleware or be sent to Amplitude
13 console.log(`Filtered event: ${eventType}`);
14 }
15}
16 
17client.addEventMiddleware(loggingMiddleware)
18client.addEventMiddleware(filteringMiddleware)

You can find examples for Typescript and JavaScript.

Was this page helpful?

Thanks for your feedback!

September 17th, 2024

Need help? Contact Support

Visit Amplitude.com

Have a look at the Amplitude Blog

Learn more at Amplitude Academy

© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.