Node.js SDK

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-js-node

Initialize the SDK exactly once and export it:

import { HtEvents } from "@ht-sdks/events-sdk-js-node";

// initialize once
export const htevents = new HtEvents({
  writeKey: "HT_WRITE_KEY",
  host: "https://us-east-1.hightouch-events.com",
});

Then, import it into the rest of your app, as needed:

// import your already initialized instance into the rest of your app
import { htevents } from "./events";

// example usage in an express like framework
app.post('/login', (req, res) => {
   htevents.identify({
      userId: req.body.userId,
      previousId: req.body.previousId
  })
  res.sendStatus(200)
})

The HtEvents constructor accepts the following parameters:

Parameter	Type	Description
`writeKey`	String	Key that corresponds to your Hightouch source
`host`	String	The base URL of the API. Default: “https://us-east-1.hightouch-events.com”
`path`	String	The API path route. Default: “/v1/batch”
`maxRetries`	Number	The maximum number of attempts when flushing a batch. Default: 3
`maxEventsInBatch`	Number	The maximum number of messages to enqueue before flushing. Default: 15
`flushInterval`	Number	The maximum amount of time (in milliseconds) to store events locally before forwarding to Hightouch. Defaults to 10000.
`httpRequestTimeout`	Number	The maximum number of milliseconds to wait for an http request. Default: 10000
`disable`	Boolean	Disable the analytics library. All calls will be a noop. Default: false

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:

htevents.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.

htevents.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:

htevents.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.

htevents.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:

htevents.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.

htevents.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:

htevents.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.

htevents.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:

htevents.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.

htevents.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.

Overriding messageId

If you need control over the messageId format, you can override it using a before plugin. A before plugin runs before the event is sent and lets you mutate the event object directly: Example:

import { HtEvents } from "@ht-sdks/events-sdk-js-node";

export const htevents = new HtEvents({
  writeKey: "HT_WRITE_KEY",
  host: "https://us-east-1.hightouch-events.com",
});

let seq = 0;

function generateMessageId() {
  return `msg_${Date.now().toString(36)}_${String(++seq).padStart(5, "0")}`;
}

htevents.register({
  name: "Custom MessageId",
  type: "before",
  version: "1.0.0",
  isLoaded: () => true,
  load: () => Promise.resolve(),
  track: (ctx) => {
    ctx.event.messageId = generateMessageId();
    return ctx;
  },
  identify: (ctx) => {
    ctx.event.messageId = generateMessageId();
    return ctx;
  },
  page: (ctx) => {
    ctx.event.messageId = generateMessageId();
    return ctx;
  },
  group: (ctx) => {
    ctx.event.messageId = generateMessageId();
    return ctx;
  },
});

Add a handler for each event type you want to override, since a plugin only runs for the methods it defines. Only use alphanumeric characters, -, and _ in your custom messageId values. Other special characters aren’t supported.

Get started

Marketing

Data platform

Manage

Resources

API reference

Installation

API

Identify

Track

Page

Screen

Group

Overriding messageId

​Installation

​API

​Identify

​Track

​Page

​Screen

​Group

​Overriding messageId

Installation

API

Identify

Track

Page

Screen

Group

Overriding messageId