Install HelpAlive with Google Tag Manager (GTM) tags

The Google Tag Manager install is a way to add HelpAlive through Tag Manager, for teams that manage scripts there: you add three Custom HTML tags in Tag Manager, and your app pushes two events to the data layer. This page shows how to set it up.

Google Tag Manager install at a glance

The HelpAlive tag loads the script on All Pages. Your project key is public and safe to put in a tag.
Your app pushes helpalive_identify right after login and on every page load while the user stays signed in.
Your app pushes helpalive_reset in its logout code, apart from the identify push.
A second tag passes the identify fields on to HelpAlive, and a third tag forgets the user at logout.
Each helpalive_ field you push needs a Data Layer Variable with the same name.

Prerequisites

Tag Manager is already on every page of your app.
Your project key, from Settings → Setup & API Key. It is public and safe to put in a tag.
A developer who can add two dataLayer.push calls to your app: one after login, one at logout.
If your users must accept a cookie banner before tools like this run, fire the tag only after they accept. See Consent.
Don’t fire the tag on 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.

How to set up HelpAlive in Tag Manager

Add the HelpAlive tag

In Tag Manager, go to Tags → New → Custom HTML. Paste this, replace YOUR_PROJECT_KEY with your key, and set the trigger to All Pages.

<script>
(function(){
  var s=document.createElement("script");
  s.src="https://cdn.helpalive.com/sdk/helpalive.js";
  s.setAttribute("data-api-key","YOUR_PROJECT_KEY");
  s.async=true;
  document.head.appendChild(s);
})();
</script>

The setup page shows this tag with your key already in it, under Google Tag Manager.

Push the signed-in user to the data layer, from your app

Run this right after login, and on every page load while the user stays signed in. Keep every line: for a value this user doesn’t have, push undefined. Tag Manager keeps the last value pushed, so a line you leave out would carry the previous user’s value over.

// On every page while someone is logged in, starting right after login
dataLayer.push({
  event: "helpalive_identify",
  helpalive_user_id: String(user.id),            // required; your user's stable ID
  helpalive_tenant_id: company ? String(company.id) : undefined, // required in a B2B app; undefined for users with no tenant
  helpalive_tenant_name: company ? company.name : undefined,     // required in a B2B app; the company's name
  helpalive_display_name: user.name,             // required; the person's name
  helpalive_email: user.email,                   // optional
  helpalive_role: user.role,                     // recommended, helps the agent; for example "admin"
  helpalive_plan: (company || user).plan,        // recommended, helps the agent; for example "pro"
  helpalive_created_at: user.createdAt,          // optional; signup date (Unix seconds)
});

The user id and the person’s name are always required. In a B2B app, the tenant id and name are required too; push undefined for users with no tenant. A tenant refers to the company, workspace or account a user belongs to in your app.

Create a Data Layer Variable for each field

In Variables → New → Data Layer Variable (version 2), create one variable for each helpalive_ name you push, with the same name. This is needed because Tag Manager won’t publish a tag that names a variable you haven’t created.

Add a second tag that passes it on

Add another Custom HTML tag, triggered by the custom event helpalive_identify. Delete the lines for fields you don’t push.

<script>window.HelpAlive=window.HelpAlive||{q:[]};["identify","reset","setConsent","track"].forEach(function(m){HelpAlive[m]=HelpAlive[m]||function(){HelpAlive.q.push([m,[].slice.call(arguments)])}})</script>
<script>
  window.HelpAlive.identify({
    userId: {{helpalive_user_id}},
    tenantId: {{helpalive_tenant_id}},
    tenantName: {{helpalive_tenant_name}},
    displayName: {{helpalive_display_name}},
    email: {{helpalive_email}},
    role: {{helpalive_role}},
    plan: {{helpalive_plan}},
    createdAt: {{helpalive_created_at}}
  });
</script>

The first line means that this tag can run before the HelpAlive script has loaded. Keep it.

Forget the user at logout

In your logout code, and wherever your app ends a session, push this. Keep it apart from the identify push.

// In your logout code, and wherever your app ends a session
// Clears every HelpAlive value, so the next person never inherits one
dataLayer.push({
  event: "helpalive_reset",
  helpalive_user_id: undefined,
  helpalive_tenant_id: undefined,
  helpalive_tenant_name: undefined,
  helpalive_display_name: undefined,
  helpalive_email: undefined,
  helpalive_role: undefined,
  helpalive_plan: undefined,
  helpalive_created_at: undefined,
  helpalive_user_token: undefined,  // only if you verify users
});

Then add a third Custom HTML tag, triggered by the custom event helpalive_reset:

<script>window.HelpAlive=window.HelpAlive||{q:[]};["identify","reset","setConsent","track"].forEach(function(m){HelpAlive[m]=HelpAlive[m]||function(){HelpAlive.q.push([m,[].slice.call(arguments)])}})</script>
<script>
  window.HelpAlive.reset();
</script>

Submit the container

Press Submit in Tag Manager to publish the three tags.

Verify users through Tag Manager

Once your server makes user tokens (see Verify users), pass the token through the data layer. Create a Data Layer Variable named helpalive_user_token, then add these lines:

// In your dataLayer.push, next to helpalive_user_id:
helpalive_user_token: userToken,   // the token your server made for this person

// In the identify tag, as its first line:
userToken: {{helpalive_user_token}},

Content Security Policy

If your app sends a Content Security Policy, it must already allow Tag Manager’s Custom HTML tags. Add our sources as well:

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

Content Security Policy explains each source.

Check it works

Open Tag Manager’s Preview mode on your app and sign in. The helpalive_identify event fires the identify tag.
Open your app, sign in and click around, then come back to Settings → Setup & API Key. Step Add HelpAlive to your app gets a check.
Log out in Preview mode and check that helpalive_reset fires the reset tag.

Why won’t Tag Manager publish the identify tag?

Tag Manager won’t publish the identify tag because the tag names a variable you haven’t created. Create each helpalive_ Data Layer Variable, or delete its line from the tag.

Why does the identify tag fire, but nobody is recognized?

Nobody is recognized because the user id reached HelpAlive empty. Check that your push sets helpalive_user_id before the helpalive_identify event, and that the Data Layer Variable has exactly that name. To see the reason, add s.setAttribute("data-debug",""); to the loader tag while you test, and read the browser console.

Why does the previous user’s chat stay open after logout?

The previous user’s chat stays open because the helpalive_reset push or its tag is missing. Add both, and publish the container.

Identify users

What each field means.

Verify users

Sign each user id on your server.

Troubleshooting

The failures that show no error.

Install

Install by framework

Install options and security

Reference

Install HelpAlive with Google Tag Manager (GTM) tags

Google Tag Manager install at a glance

Prerequisites

How to set up HelpAlive in Tag Manager

Verify users through Tag Manager

Content Security Policy

Check it works

Why won’t Tag Manager publish the identify tag?

Why does the identify tag fire, but nobody is recognized?

Why does the previous user’s chat stay open after logout?

Next

Identify users

Verify users

Troubleshooting

​Google Tag Manager install at a glance

​Prerequisites

​How to set up HelpAlive in Tag Manager

​Verify users through Tag Manager

​Content Security Policy

​Check it works

​Why won’t Tag Manager publish the identify tag?

​Why does the identify tag fire, but nobody is recognized?

​Why does the previous user’s chat stay open after logout?

​Next

Identify users

Verify users

Troubleshooting

Google Tag Manager install at a glance

Prerequisites

How to set up HelpAlive in Tag Manager

Verify users through Tag Manager

Content Security Policy

Check it works

Why won’t Tag Manager publish the identify tag?

Why does the identify tag fire, but nobody is recognized?

Why does the previous user’s chat stay open after logout?

Next