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

# HelpAlive JavaScript SDK reference: script tag and calls

> Every attribute of the HelpAlive script tag and every call your code can make: init, identify, reset, track, flush and shutdown.

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](/installation) 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](/installation) 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

```html theme={null}
<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](/sdk/csp). |
| `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.

```javascript theme={null}
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](/sdk/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](/sdk/identify) explains each field.

## reset()

```javascript theme={null}
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](/sdk/consent).

## track()

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

```javascript theme={null}
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()

```javascript theme={null}
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()

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

```javascript theme={null}
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](/sdk/troubleshooting) lists the silent failures.

## Next

<CardGroup cols={3}>
  <Card title="Install the script" icon="code" href="/installation">
    The tag, identify() and reset().
  </Card>

  <Card title="Identify users" icon="user-check" href="/sdk/identify">
    Every field, in detail.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/sdk/troubleshooting">
    The failures that show no error.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.