HelpAlive JavaScript SDK reference: script tag and calls

The HelpAlive JavaScript SDK reference lists the script tag’s attributes and each call on the HelpAlive object, for developers: identify(), reset(), setConsent(), track(), flush(), shutdown() and init(). Most apps need only the tag, identify() and reset(), as Install the script shows.

JavaScript SDK at a glance

data-api-key is the only required attribute of the script tag. Your project key is public.
With the four queue lines in place, identify(), reset(), setConsent() and track() can run before our script has loaded.
Call init(), flush() and shutdown() only after the script has loaded.
identify() tells HelpAlive who is signed in, and the agent loads only after it succeeds. reset() forgets the user at logout.
data-debug logs what HelpAlive does to the browser console while you test.

Prerequisites

The HelpAlive tag is in your pages.
The four queue lines from Install the script run before your first call. They let identify(), reset(), setConsent() and track() run before our script has loaded. Call init(), flush() and shutdown() only after it has loaded.

Script tag attributes

<script src="https://cdn.helpalive.com/sdk/helpalive.js" data-api-key="YOUR_PROJECT_KEY" async></script>

Attribute	Required	What it does
`data-api-key`	Yes	Your project key, from Settings → Setup & API Key. It is public. Without it, HelpAlive doesn’t start and logs nothing.
`async`	Recommended	Loads the script without holding up your page.
`nonce`	With a nonce-based policy	Your page’s nonce. HelpAlive puts it on the scripts it adds. See Content Security Policy.
`data-debug`	No	Logs what HelpAlive does to the browser console. Its presence turns it on. Use it while you test, not in production.
`data-endpoint`	No	The address activity is sent to. Leave it out unless HelpAlive gives you a different one.
`data-chat-endpoint`	No	The address the agent talks to. Leave it out unless HelpAlive gives you a different one.

identify()

Tells HelpAlive who is signed in. The agent loads only after it succeeds.

HelpAlive.identify({
  userId: "8412",            // required unless you pass userToken
  tenantId: "acme",          // B2B: required; B2C: leave out
  tenantName: "Acme Inc.",   // B2B: required; B2C: leave out
  displayName: "Priya Sharma", // required
  email: "priya@acme.com",
  role: "admin",
  plan: "pro",
  createdAt: 1704067200,     // Unix seconds
})

Field	Type	Notes
`userId`	string or number	Required unless `userToken` is given. 1 to 255 characters. A number is turned into text.
`tenantId`	string or number	Required in a B2B app; left out for users with no tenant, who appear as B2C customers. 1 to 255 characters.
`tenantName`	string	Required in a B2B app. Shown in your dashboard in place of the tenant id.
`displayName`	string	Required: the person’s name, or their email. Up to 255 characters.
`email`	string	Optional. Up to 320 characters.
`role`	string	Recommended: the agent reads it. Up to 100 characters.
`plan`	string	Recommended: the agent reads it. Up to 100 characters.
`createdAt`	number	Optional. Sign-up time in whole Unix seconds. Other values are ignored.
`userToken`	string	Optional. A JWT your server signs. With it, the user and tenant come from the token. A user or tenant id in it over 200 characters stops the call. See Verify users.
`refreshUserToken`	function	Optional, with `userToken`. Returns a fresh token, or a promise of one. Called when a token has expired; the request is then sent again. The fresh token must name the same user and tenant.

The script refuses a call only for a missing or too-long userId or tenantId; leaving out another required field just leaves your dashboard with less to show. A number in displayName, role or plan is turned into text. A field of the wrong type, or too long, is left out with a console warning, and the call goes on. Returns a promise that resolves when the call has been handled. Calls run one after another, in the order you make them. Calling it again for the same user is safe. Calling it for a different user closes the previous user’s agent first. Identify users explains each field.

reset()

HelpAlive.reset()

Forgets the signed-in user, their tenant, their token and their session. It closes the agent and clears its conversation from the browser. Other tabs of your app in the same browser are signed out of HelpAlive too. Call it in your logout code, apart from identify(). Activity after reset() waits in the page until the next identify().

setConsent()

Does nothing. It remains so pages written for the old consent mode don’t break, and you can remove it. See Consent.

track()

Records an event of your own with the signed-in user’s activity.

HelpAlive.track({ event_type: "report_exported", format: "csv" })

Field	Type	Notes
`event_type`	string	Required. Your event’s name. Use your own names, such as `report_exported`, not HelpAlive’s built-in ones such as `pv`, `click`, `form` or `error`.
Other fields	any	Optional properties, at the top level. Keep them small: past a size limit, extra properties are left out.

Events tracked before identify() wait in the page and are sent once it runs. Because custom properties are stored as you send them, don’t put personal data in them.

flush()

const result = await HelpAlive.flush()
// { success: true } or { success: false, error: "...", errorCode: "..." }

Sends any recorded activity now. You rarely need it: HelpAlive sends activity in batches, and again when the page is hidden or closed.

shutdown()

HelpAlive.shutdown()

Stops recording on this page and removes HelpAlive’s listeners. Calls after it do nothing until init() runs again. It doesn’t close an agent that is already open; call reset() for that.

init()

Most apps never call init(): the tag’s data-api-key starts HelpAlive. Call it only if you load the script without data-api-key, after the script has loaded. Never do both, or HelpAlive starts twice.

await HelpAlive.init({ apiKey: "YOUR_PROJECT_KEY" })

Option	Type	Default	Notes
`apiKey`	string		Required. Your project key.
`capture`	object	all `true`	Turns kinds of recording on or off. See below.
`debug`	boolean	`false`	The same as `data-debug`.
`endpoint`	string	HelpAlive’s	The same as `data-endpoint`.
`chatEndpoint`	string	HelpAlive’s	The same as `data-chat-endpoint`.

The capture keys are pageviews, clicks, forms, formStart, changes, errors, rage, scroll, exposure, outcomes, timing and elementContext. Each is true by default. The agent uses recent activity to understand what the user just did, which is why turning kinds off can make its answers less fitting. init() returns a promise, and rejects if apiKey is missing.

Check it works

In the browser console on a signed-in page, run typeof HelpAlive.init. "function" means that our script has loaded, and "undefined" means that only the queue lines have run. Add data-debug to the tag to see each call logged.

Why is HelpAlive not defined?

The error HelpAlive is not defined means that a call ran before the queue lines. Put the four queue lines above your first call.

Why does a call do nothing?

A call does nothing when the tag has no data-api-key, or when identify() was refused. Add data-debug to the tag and read the console. Troubleshooting lists the silent failures.

Install the script

The tag, identify() and reset().

Identify users

Every field, in detail.

Troubleshooting

The failures that show no error.

Install

Install by framework

Install options and security

Reference

HelpAlive JavaScript SDK reference: script tag and calls

JavaScript SDK at a glance

Prerequisites

Script tag attributes

identify()

reset()

setConsent()

track()

flush()

shutdown()

init()

Check it works

Why is HelpAlive not defined?

Why does a call do nothing?

Next

Install the script

Identify users

Troubleshooting

​JavaScript SDK at a glance

​Prerequisites

​Script tag attributes

​identify()

​reset()

​setConsent()

​track()

​flush()

​shutdown()

​init()

​Check it works

​Why is HelpAlive not defined?

​Why does a call do nothing?

​Next

Install the script

Identify users

Troubleshooting

JavaScript SDK at a glance

Prerequisites

Script tag attributes

identify()

reset()

setConsent()

track()

flush()

shutdown()

init()

Check it works

Why is HelpAlive not defined?

Why does a call do nothing?

Next