The Node.js SDK makes it easy to track events from Node.js applications.
Installation
The Node.js SDK is available via NPM.
To install the Node.js SDK, run:
npm install @ht-sdks/events-sdk-node
Then, initialize the SDK wherever you want to track events:
const Analytics = require('@ht-sdks/events-sdk-node');
const client = new Analytics("HT_WRITE_KEY", {
dataPlaneUrl: "https://us-east-1.hightouch-events.com",
});
The Analytics constructor accepts the following parameters:
| Parameter | Type | Description |
|---|---|---|
flushAt | Integer | The maximum number of events to store locally before forwarding to Hightouch. Defaults to 20. |
flushInterval | Integer | The maximum amount of time (in milliseconds) to store events locally before forwarding to Hightouch. Defaults to 10000. |
maxInternalQueueSize | Integer | The maximum number of events to store locally. This may be configured separately from flushAt because the event requests to Hightouch may fail, in which case they remain on the queue so that they can be retried. |
logLevel | String | The log level for internal logs. Can be set to log, info, debug, warn, error, or none. Defaults to info. |
dataPlaneUrl | String | The URL to send events to. Defaults to https://us-east-1.hightouch-events.com |
API
Identify
The identify method sends an identify event.
Unlike the Browser SDK, it does not persist the user ID and traits locally, so user IDs must be explicitly added to other events. This is because server side events are usually servicing many different users at once.
Example usage:
client.identify({
userId: "123",
traits: {
location: "San Francisco",
}
})
The first argument to the method is an object representing the identify event to be sent. The second argument is an optional callback that's invoked after the event is sent.
client.identify(message, [callback])
The message object may include the following fields:
| Parameter | Type | Description |
|---|---|---|
userId | String | The user's persistent ID |
anonymousId | String | The user's anonymous ID. This is automatically set if both userId and anonymousId are omitted. |
traits | Object | Additional traits about the user, such as email and name. |
context | Object | Overrides to values in the event context. By default, context contains information autocollected by the SDK. |
timestamp | Date | The date of the message. When backfilling data, this can be set to the past. By default, this is autoset to the current date. |
Track
The track method sends a track event.
Example usage:
client.track({
userId: "123",
event: "Order completed",
properties: {
total: 29.99,
}
})
The first argument to the method is an object representing the track event to be sent. The second argument is an optional callback that's invoked after the event is sent.
client.track(message, [callback])
The message object may include the following fields:
| Parameter | Type | Description |
|---|---|---|
userId | String | The user's persistent ID |
anonymousId | String | The user's anonymous ID. This is automatically set if both userId and anonymousId are omitted. |
event | String | The name of the event. |
properties | Object | Additional properties about the event, such as product_id. |
context | Object | Overrides to values in the event context. By default, context contains information autocollected by the SDK. |
timestamp | Date | The date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date. |
Page
The page method sends a page event.
Example usage:
client.page({
userId: "123",
category: "Docs",
name: "Getting started",
})
The first argument to the method is an object representing the page event to be sent. The second argument is an optional callback that's invoked after the event is sent.
client.page(message, [callback])
The message object may include the following fields:
| Parameter | Type | Description |
|---|---|---|
userId | String | The user's persistent ID |
anonymousId | String | The user's anonymous ID. This is automatically set if both userId and anonymousId are omitted. |
category | String | The page's category. For example "Docs" |
name | String | The page's name. For example "Getting started" |
properties | Object | Additional properties about the event, such as url. |
context | Object | Overrides to values in the event context. By default, context contains information autocollected by the SDK. |
timestamp | Date | The date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date. |
Screen
The screen method sends a screen event.
Example usage:
client.screen({
userId: "123",
category: "Docs",
name: "Getting started",
})
The first argument to the method is an object representing the screen event to be sent. The second argument is an optional callback that's invoked after the event is sent.
client.screen(message, [callback])
The message object may include the following fields:
| Parameter | Type | Description |
|---|---|---|
userId | String | The user's persistent ID |
anonymousId | String | The user's anonymous ID. This is automatically set if both userId and anonymousId are omitted. |
category | String | The screen's category. For example "Docs" |
name | String | The screen's name. For example "Getting started" |
properties | Object | Additional properties about the screen. |
context | Object | Overrides to values in the event context. By default, context contains information autocollected by the SDK. |
timestamp | Date | The date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date. |
Group
The group method sends a group event.
Example usage:
client.group({
userId: "123",
groupId: "456",
traits: {
company_location: "San Francisco",
},
})
The first argument to the method is an object representing the group event to be sent. The second argument is an optional callback that's invoked after the event is sent.
client.group(message, [callback])
The message object may include the following fields:
| Parameter | Type | Description |
|---|---|---|
userId | String | The user's persistent ID |
anonymousId | String | The user's anonymous ID. This is automatically set if both userId and anonymousId are omitted. |
groupId | String | The id for the group. |
traits | Object | Additional traits about the group, such as company_name. |
context | Object | Overrides to values in the event context. By default, context contains information autocollected by the SDK. |
timestamp | Date | The date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date. |