Node.js SDK (Legacy)
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.
Legacy SDK
This is a legacy SDK and will only receive bug fixes until deprecation. A new Analytics SDK for Node.js available in Beta. The new SDK offers an improved code architecture which supports plugins.
The Beta SDK does not yet support the Ampli Wrapper. If you use Ampli please continue to use the non-Beta SDK at this time.
Node SDK Resources (Legacy)
Ampli Wrapper versus the Amplitude SDK
The Ampli Wrapper is an autogenerated library based on your pre-defined tracking plan. This is a lightweight wrapper over the Amplitude SDK that provides type-safety, automatic code completion, linting, and schema validation. The generated code replicates the spec in the Tracking Plan and enforces its rules and requirements. This guide is about the Amplitude SDK. To learn more about Ampli Wrapper, see Ampli Wrapper Overview and examples. Click here for more documentation on Ampli for Node.
Installation¶
Run npm install @amplitude/node
in your project directory, the same level with package.json
.
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"
});
Usage¶
Important notes about sending events
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 follows 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 character by passing the min_id_length
option with the request.
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.
Still have questions? Ask them in the Community.