Set up a Node source in the dashboard. You should be able to see the write key for this source:
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.
Make sure to enclose the write key and data plane URL parameters within double quotes (" ").
The Setup tab in the RudderStack dashboard (seen above) has the SDK installation snippet containing both the write key and the data plane URL. Copy it to integrate the Node.js SDK into your application.
Installing the Node.js SDK
To install the RudderStack Node.js SDK using npm, run the following command:
npm install @rudderstack/rudder-sdk-node
Initializing the SDK
Run the following snippet to initialize the Node.js SDK. It creates a global RudderStack client object that can be used for all subsequent event requests.
constRudderAnalytics=require("@rudderstack/rudder-sdk-node")// RudderStack requires the batch endpoint of the server you are running
constclient=newRudderAnalytics(WRITE_KEY,<DATA_PLANE_URL>/v1/batch)
constRudderAnalytics=require('@rudderstack/rudder-sdk-node');constclient=newRudderAnalytics(WRITE_KEY,{dataPlaneUrl:DATA_PLANE_URL,// default: https://hosted.rudderlabs.com
// More initialization options
});
SDK initialization options
The RudderStack Node.js SDK provides the following parameters which you can pass during the SDK initialization:
Parameter
Data type
Description
flushAt
Integer
Number of events flushed by the SDK when reached this limit.
Default value: 20
flushInterval
Integer
Maximum timespan (in milliseconds) after which the events from the in-memory queue are flushed.
Default value: 10000
maxInternalQueueSize
Integer
Maximum length of the in-memory queue.
Default value: 20000
logLevel
String
Sets the logging level. The acceptable values are info, debug, error, etc.
Default value: info
The following initialization parameters are only available for RudderStack Node.js SDK v2.x.x and above:
Parameter
Data type
Description
dataPlaneUrl
String
Data plane URL.
Default value: https://hosted.rudderlabs.com
path
String
Path to the batch endpoint.
Default value: /v1/batch
maxQueueSize
Integer
Maximum payload size of a batch request.
Default value: 460800 (500KB)
axiosConfig
Object
Axios configuration.
axiosInstance
Object
Axios instance.
axiosRetryConfig
Object
Axios retry configuration.
retryCount
Integer
Number of times a request is retried by Axios in case of failure.
Default value: 3
errorHandler
Function
Function that is called if the request to server fails.
gzip
Boolean
Gzip compresses the event request.
Default value: true
For gzipping requests, your rudder-server must be on v1.4.0 or above. Otherwise, your requests will fail.
Sending events
RudderStack does not store or persist the user state in any of the server-side SDKs.
Unlike the client-side SDKs that deal with a single user at a given time, the server-side SDKs deal with multiple users simultaneously. Therefore, you must specify either the userId or anonymousIdevery time while making any API calls supported by the Node.js SDK.
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.
The page method parameters are as described below:
Field
Type
Description
userId Required, if anonymousId is absent.
String
Unique identifier for a user in your database.
anonymousId Required, if userId is absent.
String
Use this field to set an identifier in cases where there is no unique user identifier.
name Required
String
Name of the viewed page.
context
Object
An optional dictionary of information that provides context about a message. It is not directly related to the API call.
timestamp
Date
The timestamp of the message’s arrival.
integrations
Object
An optional dictionary containing the destinations to be either enabled or disabled.
properties
Object
An optional dictionary of the properties associated with the viewed page, like url and referrer.
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.
The screen method parameters are as described below:
Field
Type
Description
userId Required, if anonymousId is absent.
String
Unique identifier for a user in your database.
anonymousId Required, if userId is absent.
String
Use this field to set an identifier in cases where there is no unique user identifier.
name Required
String
Name of the viewed page.
context
Object
An optional dictionary of information that provides context about a message. It is not directly related to the API call.
timestamp
Date
The timestamp of the message’s arrival.
integrations
Object
An optional dictionary containing the destinations to be either enabled or disabled.
properties
Object
An optional dictionary of the properties associated with the screen, like url or referrer.
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.
Use this field to set an identifier in cases where there is no unique user identifier.
groupId Required
String
Unique identifier for the group present in your database.
context
Object
An optional dictionary of information that provides context about a message. It is not directly related to the API call.
integrations
Object
An optional dictionary containing the destinations to be either enabled or disabled.
traits
Object
An optional dictionary of the group’s traits like nameor email.
timestamp
Date
The timestamp of the message’s arrival.
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.
RudderStack supports sending alias events only to select downstream destinations. Refer to the destination-specific documentation for more details.
The alias method parameters are as mentioned below:
Field
Type
Description
userId Required
String
Unique identifier for a user in your database.
anonymousId
String
Use this field to set an identifier in cases where there is no unique user identifier.
previousId Required
String
The previous unique identifier of the user.
context
Object
An optional dictionary of information that provides context about a message. It is not directly related to the API call.
integrations
Object
An optional dictionary containing the destinations to be either enabled or disabled.
traits
Object
An optional dictionary of the user’s traits like name or email.
timestamp
Date
The timestamp of the message’s arrival.
Data persistence
This is a beta feature. Contact the RudderStack team on Slack if you face any issues.
If the Node.js 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 use this feature, you will need to host a Redis server to use it as the intermediary data storage queue. RudderStack uses Bull as the interface layer between the Node.js SDK and 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:
constclient=newAnalytics("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=>{})
constclient=newAnalytics("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=>{})
If the createPersistenceQueue method is not called after initializing the SDK, the SDK will work without any persistence.
queueOpts
The syntax for createPersistenceQueue method is as follows:
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:
Parameter
Description
Default Value
queueName
Name of the queue.
20
isMultiProcessor
Determines whether to handle previously active jobs. If set to false, the previously active job will be picked up first by the processor. Otherwise, Bull moves this job to the back of the Redis queue to be picked up after the already pushed event.
false
prefix
Used as the prefix to the Redis keys needed to support the Redis cluster slots.
For more information on these parameters, refer to the Bull docs.
If the same queue (RudderStack SDK initialized with the same queue name) is used in case of multiple servers (server-side SDKs), set the value of isMultiProcessor to true as event ordering is not applicable in this case.
In case of an error, the createPersistenceQueue method returns a callback. You should retry sending the events in this scenario.
// 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.
If the callback returns with an error, RudderStack recommends retry calling createPersistenceQueue with a backoff.
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 anexponential 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 methodslisted hereor 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 events in the queue are processed. The following example highlights the use of flush() with a callback:
This site uses cookies to improve your experience while you navigate through the website. Out of
these
cookies, the cookies that are categorized as necessary are stored on your browser as they are as
essential
for the working of basic functionalities of the website. We also use third-party cookies that
help
us
analyze and understand how you use this website. These cookies will be stored in your browser
only
with
your
consent. You also have the option to opt-out of these cookies. But opting out of some of these
cookies
may
have an effect on your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This
category only includes cookies that ensures basic functionalities and security
features of the website. These cookies do not store any personal information.
This site uses cookies to improve your experience. If you want to
learn more about cookies and why we use them, visit our cookie
policy. We'll assume you're ok with this, but you can opt-out if you wish Cookie Settings.