JavaScript (Web)

The Engage JavaScript SDK (web) lets you identify users and capture events, actions, and attributes on web. It is also required to display the Engage Help widget, Live Chat widget, Banners, Product Tours, and Web-in app messages.

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/browser
// Or Yarn
yarn add @engage_so/browser

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

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

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

<script>
!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");
</script>

Configuration

Initializing the SDK with your public API key:

Engage.init('api_key')

Initializing with additional options:

Engage.init({
  key: 'api_key',
  no_chat: true, // Disable chat widget
  ignore_anonymous: true // No tracking unless user `identify`ied
})

options:

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

• no_chat: This disables the live chat widget. You can use this on pages where you want chat turned off.

• ignore_anonymous: By default, the SDK will create a new user if the current visitor is not identified. You can prevent this by setting this option to true.

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.

Your private key (secret) should only be used in server-side applications (e.g. Node.js) 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. This is useful for displaying targeted messages through Banners, Product Tours, Web in-app messages and showing necessary Live chat 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.

Once set, email and number cannot be updated with the web SDK. Updating the email and number attributes require your account's secret key and this should only be done 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);

Autotracking

Autotracking lets you automatically captures page views, button and link clicks, and form submissions. This is off by default but can be turned on by more configuration settings.

// Enable all autotracking features
Engage.init({
  key: 'api_key',
  autotrack: true
})

// Configure specific autotrack features
Engage.init({
  key: 'api_key',
  autotrack: {
    pageviews: true,  // Track page views and navigation
    buttons: true,    // Track button and link clicks
    forms: true       // Track form submissions
  }
})

Enabling autotracking for anonymous customers can increase your Engage bill, as pricing is based on active users—and tracking any event marks a user as active. To avoid this, you can set ignore_anonymous to true to disable tracking for anonymous users.

Engage.init({
  key: 'api_key',
  ignore_anonymous: true,
  autotrack: true
})

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.

Livechat

By default, the message widget will be displayed if you have set up livechat on your Engage dashboard. The widget color, position, welcome message, and other customizations can also be done on the dashboard.

To completely turn off livechat on a page, you can use the no_chat configuration option.

Engage.init({
  key: 'api_key',
  no_chat: true, // Disable chat widget
})

If however you want to close and open the widget on your own, you can use the toggleChat function. This requires livechat to be enabled (no_chat shouldn't be true)

Engage.toggleChat();

Help

The message widget also doubles as a help widget that can be used to open content from your help center within the widget.

// Open help article
Engage.openHelp('article-id', 'article', 'en');

Learn more about how to Embed your help content on your webpage.

Tour Functions

Tours are automatically triggered based on URL patterns and target audience configured in your dashboard.

Banner Configuration

Banners are configured in your dashboard and automatically displayed based on:

• URL patterns

• Target Audience

• Display rules (frequency, timing)