JavaScript (Node.js)

The Engage JavaScript SDK lets you identify users and capture events, actions, and attributes in your server-side Node.js application. If you are looking to implement the browser version, see the documentation for the JavasScript SDK for browser.

We recommend you read the Connecting Customer Data section to learn more about how to capture user data and what to capture.

New to Engage? Create an account.

Installation and Setup

// NPM
npm install —save @engage_so/core
// Or Yarn
yarn add @engage_so/core

// commonjs/node-style require
const Engage = require('@engage_so/core')

// ES module-style import
import Engage from '@engage_so/core'

Configuration

Initializing the SDK with your API keys:

Engage.init({
  key: 'api_key',
  secret: 'api_secret'
})

options:

• key: Your account public API key. Available in the settings page on your account dashboard.

• secret: Your account private key. Available in the settings page on your account dashboard.

Your private key should only be used in server-side environments and never in client-side implementations like the browser. The secret should be treated as a password and kept confidential.

Identifying users

Identifying users is a way to let the SDK know who the currently logged user is. These serves two major purposes:

1. If the user does not exist on your Engage account, they are created.

2. If the user exists on your account, the added properties will update the existing ones.

In other words, identify can be used to create new users or update existing ones.

Engage.identify({
 id: 'u13345',
 email: '[email protected]',
 created_at: '2020-05-30T09:30:10Z'
})

id should be a unique identifier for the user. It should be a value that will not change in your application. For example, don’t use a username as id if users can update their usernames.

The created_at property is optional. If not added and the user does not exist already, Engage sets it to the current timestamp. The other properties can be any property related to the user, e.g. location, gender, or plan. Here is a list of the ones we use internally; we call them standard attributes:

• first_name

• last_name

• email

• is_acount

• number

• device_token

• device_platform (android or ios)

If you need to update any of the properties, you can call identify with the property set to the new value.

number must include an international dialing code without the +. Valid examples are 15555551234 and 2348166877840

Identifying as an Account

If you want to identify a user as an Account, you can add an is_account property and set it to true:

Engage.identify({
 id: 'u1001',
 email: '[email protected]',
 is_account: true,
 created_at: '2020-04-30T03:12:04Z'
})

If you just want to convert between Customer and Account user types, you can use any of the following methods.

This converts an Account to a Customer:

Engage.convertToCustomer('u1001')

This converts a Customer to an Account:

Engage.convertToAccount('u1001')

Tracking user attributes

You can add attributes to users for Segmentation. Allowed values for user attributes are boolean, numbers, or strings. The first argument of the method is the user’s id. In the examples below, we are assuming the user’s id is u144.

Engage.addAttribute('u144', {
 plan: 'pro',
 promotion: true
})

If an attribute changes at a later date, you can use the same method to update the new value.

Engage.addAttribute('u144', {
 plan: 'premium'
})

Tracking user events and actions

Events and user actions can be tracked in a couple of ways. The simplest way to do this, where u144 is ther user’s id, is like this:

Engage.track('u144', 'deactivate')

Engage.track('u144', {
 event: 'New badge',
 value: 'gold'
 timestamp: '2020-05-30T09:30:10Z'
})

timestamp is optional. If it is not included, Engage uses the current timestamp. If included, it must be a valid date time string.

Some events may have additional properties instead of a single value. Here is how to track those:

Engage.track('u144', {
 event: 'Add to cart',
 timestamp: '2020-05-30T09:30:10Z',
 properties: {
   product: 'T123',
   currency: 'USD',
   amount: 12.99
 }
})

Anonymous ID and Merging Users

Sometimes, you want to track user events before you identify them. For example, a user may download your app and explore some of the available features before they sign up and are assigned a unique ID. We call this an anonymous user. You can use any random ID (we call this an anonymous ID) to track events for the anonymous user and merge it with the actual user when identified.

Other times, you may just want to merge duplicate customers. The merge method, lets you do this.

Engage.merge(source_customer_id, destination_customer_id);

Add a Customer to an Account

Engage.addToAccount(customer_id, account_id, role)

Where

• customer_id - The uid of the Customer you want to add to the Account.

• account_id - The uid of the Account you are adding the Customer to.

• role - The role of the Customer in the Account. This is optional.

Example:

Engage.addToAccount('u_123', 'u_455', 'Admin')

Change Account role

Engage.changeAccountRole(customer_id, account_id, new_role)

Remove a Customer from an Account

Engage.removeFromAccount(customer_id, account_id)

Difference between attribute and event tracking

Attributes are attached to the user’s metadata. If an attribute changes, the new value overrides the previous value. Events are not tracked that way. If an event’s value changes, the old value is not replaced. The new value is tracked with a different timestamp. This lets you be able to Segment users based on old events within a time range.

A note on values

When tracking attributes and events, it is important you use the right data type for better segmentation. For example, instead of using a string value of $12.99 for a price, you can use a number value so that numerical operators like equality, greater than, and less than can be used on the value.

To track a date attribute, use a valid date format like 2020-05-30 or 2020-05-30T09:30:10Z.