Skip to main content

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.

This is the same three-step flow your dashboard’s Setup Guide walks you through the first time you log in. You can do it from this page, or from the Setup Guide modal in the dashboard — both end up at the same place.
1

Get your script tag

Open your dashboard. The first time you log in as an admin, the Setup Guide opens automatically. You can also reopen it any time from Settings → Integration & API Key.The script will look like this — but use the personalized snippet from your dashboard, which has your project’s API key already filled in:
<!-- Paste before </head> -->
<script
  src="https://cdn.helpalive.com/sdk/helpalive.js"
  data-api-key="YOUR_API_KEY"
  async>
</script>
Paste it into the <head> of your HTML, just before </head>, so it loads on every page. Then deploy.
The script loads in the background, so it won’t slow your page down. Any calls you make before it finishes loading are queued and replayed automatically — no extra checks needed in your code.
2

Identify your user after login

Once the user authenticates, call HelpAlive.identify() with their stable user ID and a workspace ID. Both are required. Until you call identify, HelpAlive doesn’t record activity for that user and the AI assistant stays off.
// Call after login (e.g. in your auth callback or app shell)
HelpAlive.identify({
  userId:      user.id,           // required: your app's stable user ID
  tenantId:    tenant.id,         // required: workspace/org ID, or "default"
  tenantName:  tenant.name,       // optional: workspace display name
  displayName: user.name,         // optional: full name
  email:       user.email,        // optional: for display/search
  role:        user.role,         // optional: "admin" / "editor" / "viewer"
  plan:        user.plan,         // optional: "free" / "pro" / "enterprise"
  createdAt:   user.createdAt     // optional: when the user signed up
});
For B2C apps without workspaces, pass tenantId: "default".See Identify for the full field reference, anonymous-session behavior, and tenant-switching patterns.
If you call identify() before the script has finished loading, the call is queued and replayed automatically. You don’t need any extra checks in your code.
3

Verify the connection

Visit a few pages of your app while logged in. Then open the dashboard and check the Setup Guide’s Verify Connection step — it polls every few seconds and shows three things:
CheckWhat it means
Event ingestionYour script is loaded and we’re receiving events.
Identity coverageWe’re seeing userId and tenantId from your identify() call.
Profile enrichmentOptional fields (displayName, email) are being sent. Improves Agent personalization.
Verification typically takes under a minute. If you wait 10+ minutes and still see “Pending”, check the common stumbles below.

​
What you get with the two-step setup

Once the script and identify() call are in place, HelpAlive starts:
  • Auto-capturing clicks, form submits, pageviews, rage clicks, and DOM errors — no event tagging required.
  • Building user and workspace profiles so adoption metrics tie to real accounts.
  • Powering the Agent if you’ve enabled it (the chatbot widget loads automatically).

​
Prefer Google Tag Manager?

The dashboard Setup Guide also offers a Google Tag Manager flow — useful if you already manage other scripts through GTM. The GTM method uses a Custom HTML tag plus a Data Layer push for identify(). See Installation → Google Tag Manager for the full walkthrough.

​
Common stumbles

Add the HelpAlive origins to your CSP header:
script-src  https://cdn.helpalive.com;
connect-src https://api.helpalive.com;
Open your app, press F12 → Console, and look for a red error mentioning helpalive.js or Content Security Policy. If you see one, that’s the fix.
Run through this list:
  1. Snippet not deployed yet. Make sure the build with the snippet is live in the environment you’re testing.
  2. CSP blocking — see above.
  3. identify() was never called. The script can load fine, but no events are sent until you call identify after login.
  4. Browser blockers. Some ad blockers and privacy extensions block analytics scripts. Try in an incognito window with extensions disabled.
The SDK detects history-API navigations automatically — no manual pageview call needed when your router changes the URL.
Pass tenantId: "default". You can switch to real workspace IDs later without re-identifying users.

​
Next steps

Full installation guide

Framework examples for React, Vue, Angular, plain HTML, plus the Google Tag Manager method.

Identify users

Field reference, anonymous sessions, multi-workspace apps.

Set up the Agent

Train the AI assistant on your docs.

Privacy posture

What’s redacted, where, and what data leaves the browser.