RudderStack's Node SDK lets you track and send the events from your Node applications to the specified destinations.

SDK setup requirements

1. Sign up to RudderStack Cloud.
2. Set up a Node source in the dashboard. You should be able to see the write key for this source, as shown:

You will also need the data plane URL. Refer to the Dashboard Overview guide for more information on the data plane URL and where to find it.

Installing the Node SDK

To install the RudderStack Node SDK using npm, run the following command:

Copy
npm install @rudderstack/rudder-sdk-node

Initializing the SDK

Run the following snippet to initialize the Node SDK. It creates a global RudderStack client object that can be used for all the subsequent event requests.

Copy
const Analytics = require("@rudderstack/rudder-sdk-node")

// RudderStack requires the batch endpoint of the server you are running
const client = new Analytics(WRITE_KEY, DATA_PLANE_URL / v1 / batch)

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

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

SDK initialization options

The RudderStack Node SDK provides the following parameters which you can pass during the SDK initialization:

The following initialization parameters are only available for RudderStack Node SDK v2.x.x and above:

Sending events

Identify

The identify call lets you identify a visiting user and associate them to their actions. It also lets you record the traits about them like their name, email address, etc.

A sample identify call is as shown:

Copy
client.identify({
  userId: "1hKOmRA4GRlm",
  traits: {
    name: "Alex Keener",
    email: "alex@example.com",
    plan: "Free",
    friends: 21,
  },
})

The identify parameters are as described below:

Track

The track call lets you track the user actions along with any properties associated with them.

A sample track call is shown below:

Copy
client.track({
  userId: "1hKOmRA4GRlm",
  event: "Item Viewed",
  properties: {
    revenue: 19.95,
    shippingMethod: "Premium",
  },
})

The track method parameters are as described below:

Page

The page call allows you to record the page views on your application, along with the other relevant information about the page.

A sample page call is as shown:

Copy
client.page({
  userId: "1hKOmRA4GRlm",
  category: "Food",
  name: "Pizza",
  properties: {
    url: "https://example.com",
    title: "Pizza",
    referrer: "https://google.com",
  },
})

The page method parameters are as described below:

Screen

The screen call is the mobile equivalent of the page call. It lets you record the screen views on your mobile app along with other relevant information about the screen.

A sample screen call is as shown:

Copy
client.screen({
  userId: "12345",
  category: "Food",
  name: "Pizza",
  properties: {
    screenSize: 10,
    title: "Pizza",
    referrer: "https://google.com",
  },
})

The screen method parameters are as described below:

Group

The group call lets you link an identified user with a group, such as a company, organization, or an account. It also lets you record any custom traits or properties associated with that group.

A sample group call is as shown:

Copy
client.group({
  userId: "12345",
  groupId: "1",
  traits: {
    name: "Company",
    description: "Google",
  },
})

The group method parameters are as follows:

Alias

The alias call lets you merge different identities of a known user. It is an advanced method that lets you change the tracked user's ID explicitly. You can use alias for managing the user's identity in some of the downstream destinations.

A sample alias call is as shown:

Copy
client.alias({
  previousId: "old_id",
  userId: "new_id",
})

The alias method parameters are as mentioned below:

Data persistence

If the Node SDK fails to deliver the events to RudderStack in the first attempt, it retries the event delivery. However, if RudderStack is unavailable for a longer duration, there is a possibility of data loss. To prevent this scenario, the SDK has the data persistence feature where the event data is persisted in Redis, guaranteeing event delivery. Simultaneously, the SDK can retry multiple times as the queue is maintained in a different process space (Redis).

To achieve data persistence, you need to call the createPersistenceQueue method which takes two parameters - queueOpts and callback. It initializes the persistent queue. A sample SDK initialization is shown below:

Copy
const client = new Analytics("write_key","DATA_PLANE_URL/v1/batch",{
    flushAt: <number> = 20,
    flushInterval: <ms> = 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.
    // This restricts the data in-memory when Redis is down, unreachable etc.
    maxInternalQueueSize: <number> = 20000
});

client.createPersistenceQueue({ redisOpts: { host: "localhost" } }, err => {})

Copy
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
    // the max number of elements that the SDK can hold in memory,
    // this is different than the Redis list created when persistence is enabled.
    // This restricts the data in-memory when Redis is down, unreachable etc.
    maxInternalQueueSize: <number> = 20000
});

client.createPersistenceQueue({ redisOpts: { host: "localhost" } }, err => {})

queueOpts

The syntax for createPersistenceQueue method is as follows:

client.createPersistenceQueue(QueueOpts, callback)

A sample queueOpts initialization is shown below:

Copy
queueOpts {
    queueName ?: string = rudderEventsQueue,
    isMultiProcessor ? : boolean = false
    // pass a value without the {}, this will used as prefix to Redis keys,
    // needed to support Redis cluster slots.
    prefix ? : string = {rudder},
    redisOpts : RedisOpts,
    jobOpts ?: JobOpts
}

The specification of the different queueOpts parameters is listed in the following table:

For more information on these parameters, refer to the Bull docs.

RedisOpts

Copy
RedisOpts {
    port?: number = 6379;
    host?: string = localhost;
    db?: number = 0;
    password?: string;
}

JobOpts

Copy
JobOpts {
    maxAttempts ? : number = 10
}

callback

In case of an error, the createPersistenceQueue method returns a callback. You should retry sending the events in this scenario.

Copy
// createPersistenceQueue calls this with error or nothing(in case of success), // user should retry in case of error
callback: function(error) || function()

Calling the createPersistenceQueue method initializes a Redis list by calling the Bull's utility methods. It also adds a single job processor for the processing (making requests to RudderStack) jobs that are pushed into the list. Any error encountered while doing this leads to a callback with the error.

Event flow

• Calling the SDK methods like track, page, identify, etc. pushes the events to an in-memory array.
• The events from the array are flushed as a batch to the Redis persistence based on the flushAt and flushInterval settings. The in-memory array has a maximum size of maxInternalQueueSize. Once this size limit is reached, __the events won't be accepted if not drained to the other side (cases where Redis connection is slow or the Redis server is not reachable).
• The processor will take the batch from the Redis list and make a request to RudderStack. In case of an error, the processor will retry sending the data again if the error can be retried (errors with status code 5xx and 429). The retry will go up to JobOpts.maxAttempts with an exponential backoff of power 2 with max backoff of 30 seconds.
• If the job fails even after JobOpts.maxAttempts, it will not be retried again and pushed to a failed queue. You can retry them later manually using Bull’s utility methods listed here or get them from Redis directly.
• There might be a scenario where the node process dies with the jobs still in active state (not completed nor failed but in the process of sending/retrying). Since the RudderStack SDK has only 1 processor for sending events (this count should always be 1), the next time the SDK is initialized and createPersistenceQueue is called, the jobs will be picked up first by the processor to get processed to maintain event ordering based on the value of QueueOpts.isMultiProcessor.
• For multiple servers (SDK) connecting to the same queue (QueueOpts.queueName), there will be multiple processors fetching events from the same queue and event ordering won’t be implemented. Hence, QueueOpts.isMultiProcessor should be set to true.

FAQ

How to ensure that all my events in the queue are processed?

You can use the flush() method to ensure that all the events in the queue are processed. The following example highlights the use of flush() with a callback:

Copy
client.flush(function(err, batch){
  console.log('Flushing done');
}
)