Install the HelpAlive script: tag, identify() and reset()

​

Installation at a glance

• Put the tag in the <head> of every page, with data-api-key set to your project key.
• Call identify() for the signed-in user right after login, and on every page load while they stay signed in.
• Call reset() in your logout code, and keep it apart from identify().
• If your app sends a Content Security Policy, add HelpAlive’s sources to it.
• The tag loads in the background (async), so it doesn’t hold up your page.

​

Prerequisites

• Your project key, from Settings → Setup & API Key. It is public, which means that it goes in your pages and is safe to show.
• Access to the layout or template that every page of your app shares.
• Your developer, about 10 minutes.
• If your users must accept a cookie banner before tools like this run, load the tag only after they accept. See Consent.
• Leave the tag off any page that shows data our Terms of Service say HelpAlive must not receive. Hiding the agent on Controls isn’t enough: activity is still recorded.

​

The install rules

1. Put the tag in the <head> of every page, with data-api-key set to your project key.
2. Keep the four queue lines above your first HelpAlive call.
3. Call identify() for the signed-in user right after login, and on every page load while they stay signed in.
4. Pass userId and tenantId as text or a number. 42 and "42" refer to the same person.
5. Use a userId that never changes. Don’t use an email address if users can change theirs.
6. Pass tenantId only if your app has companies, workspaces or accounts. Leave it out otherwise.
7. Pass role, plan, displayName, email and tenantName as text. A field of the wrong type is left out. Pass createdAt as Unix time in seconds.
8. Call reset() in your logout code, and keep it apart from identify(). Never put it straight after identify().
9. If your app sends a Content Security Policy, add our sources, and put your nonce on our tag if your policy uses one.

​

How to install the script

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

// Lets the calls below run before our script has finished loading. Keep it first.
window.HelpAlive = window.HelpAlive || { q: [] };
["identify", "reset", "setConsent", "track"].forEach((m) => {
  if (!HelpAlive[m]) HelpAlive[m] = (...args) => HelpAlive.q.push([m, args]);
});

// On every page while someone is logged in, starting right after login
HelpAlive.identify({
  userId: String(user.id),      // required: your own id for this person
  tenantId: String(company.id), // required: their company or workspace
  tenantName: company.name,     // required: the company's name, shown in your dashboard
  displayName: user.name,       // required: the person's name (or their email), shown in your dashboard
  email: user.email,            // optional
  role: user.role,              // recommended, helps the agent
  plan: company.plan,           // recommended, helps the agent
  createdAt: user.createdAt,    // optional: signup date, Unix time in seconds
})

// On every page while someone is logged in, starting right after login
HelpAlive.identify({
  userId: String(user.id),      // required: your own id for this person
  displayName: user.name,       // required: the person's name (or their email), shown in your dashboard
  email: user.email,            // optional
  plan: user.plan,              // recommended, helps the agent
  createdAt: user.createdAt,    // optional: signup date, Unix time in seconds
})

// In your logout code, and wherever your app ends a session. Until this runs,
// the browser keeps the person, and the next visitor's events count as theirs.
HelpAlive.reset()

script-src https://cdn.helpalive.com;
connect-src https://api.helpalive.com https://chat.helpalive.com;

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

​

TypeScript

// In a .d.ts file your project includes, for example helpalive.d.ts
declare var HelpAlive: any

if (!HelpAlive[m]) HelpAlive[m] = (...args: unknown[]) => HelpAlive.q.push([m, args]);

​

Single-page apps

• HelpAlive records page views by itself when your router changes the address. You don’t call anything on route changes.
• One identify() per page load is enough. Calling it again with the same details is safe.
• If a different user signs in without a page reload, call identify() with the new user. HelpAlive closes the previous user’s agent first.

​

Check it works

​

Troubleshooting

​

Still stuck?

• the address of a page where the problem happens, and the browser you used;
• which steps on Settings → Setup & API Key have a check, and what step 1’s line says;
• what the browser console shows with data-debug on the tag.

​

Next