> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> Hightouch's Node.js SDK for collecting events

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](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](https://docs.hightouch.com/events/sdks/browser.md), 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:

```js theme={null}
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.