@rudderstack/rudder-sdk-node

What is @rudderstack/rudder-sdk-node?

@rudderstack/rudder-sdk-node is a Node.js SDK for RudderStack, a customer data platform that helps you collect, transform, and route your customer data to various destinations. This SDK allows you to track events, identify users, and manage user data efficiently.

What are @rudderstack/rudder-sdk-node's main functionalities?

Track Events

The track method allows you to record any actions your users perform, along with any properties that describe the action. This is useful for tracking user behavior and interactions within your application.

const { Analytics } = require('@rudderstack/rudder-sdk-node');
const analytics = new Analytics('YOUR_WRITE_KEY', 'DATA_PLANE_URL');

analytics.track({
  userId: 'user123',
  event: 'Item Purchased',
  properties: {
    item: 'T-shirt',
    price: 19.99
  }
});

Identify Users

The identify method is used to associate a user with their unique ID and record traits about them. This helps in building a comprehensive profile of the user.

const { Analytics } = require('@rudderstack/rudder-sdk-node');
const analytics = new Analytics('YOUR_WRITE_KEY', 'DATA_PLANE_URL');

analytics.identify({
  userId: 'user123',
  traits: {
    email: '[e-mail]',
    name: 'John Doe'
  }
});

Group Users

The group method associates an individual user with a group, like a company or team. This is useful for applications that need to manage users in groups or organizations.

const { Analytics } = require('@rudderstack/rudder-sdk-node');
const analytics = new Analytics('YOUR_WRITE_KEY', 'DATA_PLANE_URL');

analytics.group({
  userId: 'user123',
  groupId: 'group123',
  traits: {
    name: 'Company Inc.',
    industry: 'Software'
  }
});

Other packages similar to @rudderstack/rudder-sdk-node

analytics-node

analytics-node is the official Node.js client for Segment, a popular customer data platform. Like @rudderstack/rudder-sdk-node, it allows you to track events, identify users, and manage user data. However, it is designed to work with Segment's infrastructure and ecosystem.

amplitude

amplitude is a Node.js SDK for Amplitude, an analytics platform focused on product analytics. It provides similar functionalities for tracking events and user data but is tailored towards in-depth product analytics and insights.

mixpanel

mixpanel is a Node.js library for Mixpanel, a platform for advanced analytics. It offers similar event tracking and user identification features, with a focus on providing detailed insights into user behavior and engagement.

README

The Customer Data Platform for Developers

Website · Documentation · Community Slack

---

RudderStack Node.js SDK

The RudderStack Node.js SDK lets you track your customer event data from your Node.js applications and send it to your specified destinations.

Refer to the documentation for more details.

Installing the SDK

Run the following command to install the Node.js SDK via npm:

$ npm install @rudderstack/rudder-sdk-node

Using the SDK

To create a global RudderStack client object and use it for the subsequent event calls, run the following snippet:

const Analytics = require('@rudderstack/rudder-sdk-node');

const client = new Analytics(WRITE_KEY, {
  dataPlaneUrl: DATA_PLANE_URL, // default: https://hosted.rudderlabs.com
});

SDK Initialization Options

Below parameters are optional and can be passed during SDK initialization.

Name	Type	Default value	Description
dataPlaneUrl	String	https://hosted.rudderlabs.com	The data plane URL.
path	String	/v1/batch	Path to batch endpoint.
flushAt	Number	20	The number of events to be flushed when reached this limit.
flushInterval	Number	10000	The maximum timespan (in milliseconds) after which the events from the in-memory queue is flushed
maxQueueSize	Number	460800(500kb)	Maximum payload size of a batch request
maxInternalQueueSize	Number	20000	The maximum length of the in-memory queue
logLevel	String	'info'	Log level. Ex: 'debug', 'error'
axiosConfig	Object	N/A	Axios config
axiosInstance	Object	N/A	Axios instance
axiosRetryConfig	Object	N/A	Axios retry configuration
retryCount	Number	3	Number of times requests will be retried by axios if failed
errorHandler	Function	N/A	A function that will be called if request to server failed
gzip	Boolean	true	Whether to compress request with gzip or not

Supported calls

Refer to the SDK documentation for more information on the supported calls.

Initializing the SDK for data persistence

This is a beta feature. Contact us on our Community Slack in case you face any issues.

RudderStack has a data persistence feature to persist the events in Redis, leading to better event delivery guarantees. Also, the SDK can retry event delivery multiple times as the queue is maintained in a different process space(Redis).

To use this feature, you will need to host a Redis server and use it as the intermediary data storage queue.

A sample SDK initialization is shown below:

const client = new Analytics(
  "write_key",
  {
    dataPlaneUrl: DATA_PLANE_URL // default: https://hosted.rudderlabs.com with default path set to /v1/batch
    flushAt: <number> = 20,
    flushInterval: <ms> = 20000
    maxInternalQueueSize: <number> = 20000 // the max number of elements that the SDK can hold in memory,
                                                                // this is different than the Redis list created when persistence is enabled
  }
);
client.createPersistenceQueue({ redisOpts: { host: "localhost" } }, err => {})

To initialize the data persistence queue, you need to call the createPersistenceQueue method which takes two parameters as input - queueOpts and a callback. The createPersistenceQueue method will initialize a Redis list by calling Bull's utility methods.

If you do not call createPersistenceQueue after initializing the SDK, the SDK will not implement data persistence.

Read the detailed documentation for more information on createPersistenceQueue and the other configurable parameters.

Event flow

For more information on how the event flow occurs with data persistence enabled, refer to the documentation.

Limitations around data persistence

• Refer to this page to understand the limitations
• For more details on the limitations, read: https://redis.io/topics/cluster-tutorial#redis-cluster-data-sharding
• As a workaround, refer to this page: https://gitter.im/OptimalBits/bull/archives/2018/04/17. We pass a prefix with default value as {rudder}.

Contact us

If you come across any issues while configuring or using the RudderStack Node.js SDK, you can contact us or start a conversation in our Slack community.