JavaScript

The Engage JavaScript SDK lets you identify users and capture events, actions, and attributes on your site. On the browser, it is required to display the Engage Help widget, Live Chat widget, Banners, and Web-in app messages.

It can be used both in Node.js and in the 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/js
// Or Yarn
yarn add @engage_so/js

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

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

If you want to directly use the CDN version, copy and paste the code below before the closing </body> tag of your webpage instead:

!function(n){if(!window.Engage){window[n]=window[n]||{},window[n].queue=window[n].queue||[],window.Engage=window.Engage||{};for(var e=["init","identify","addAttribute","track"],i=0;i<e.length;i++)window.Engage[e[i]]=w(e[i]);var d=document.createElement("script");d.src="//d2969mkc0xw38n.cloudfront.net/next/engage.min.js",d.async=!0,document.head.appendChild(d)}function w(e){return function(){window[n].queue.push([e].concat([].slice.call(arguments)))}}}("engage");

Configuration

Initializing the SDK with your public API key:

Engage.init('api_key')

Initializing with additional options:

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

options:

• key: Your account API key. Available in your account dashboard.

• secret: Your account secret key. Available in your account dashboard.

Engage identifies your application with the key parameter. This is enough to identify and track user events or actions. If however, you want to do more, like update or delete user data, you need to add your secret. This should only be used in server-side applications as your secret should be treated as a password and kept confidential.

Identifying users

The SDK needs to know who the current visitor is. This is where the identify method comes in. This is especially useful on the frontend to identify the user and display necessary Live chat messages, Banners, and Web in-app messages. It also serves two purposes:

1. If the user does not exist on your account, they are created. This only happens if additional properties beyond just the user ID are added.

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. If you need to update email or number, you need to use the secret parameter to initialize the SDK. Remember, only use your secret key in server-side integrations.

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. Learn more.

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.