> ## 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.

# Install HelpAlive with Google Tag Manager (GTM) tags

> Install HelpAlive through Google Tag Manager with a loader tag, an identify tag fed by the data layer, and a reset tag for logout.

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](/sdk/consent).
* Don't fire the tag on any page that shows data our [Terms of Service](https://helpalive.com/legal/terms) 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

<Steps>
  <Step title="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**.

    ```html theme={null}
    <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**.
  </Step>

  <Step title="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.

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

  <Step title="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.
  </Step>

  <Step title="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.

    ```html theme={null}
    <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.
  </Step>

  <Step title="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.

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

    ```html theme={null}
    <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>
    ```
  </Step>

  <Step title="Submit the container">
    Press **Submit** in Tag Manager to publish the three tags.
  </Step>
</Steps>

## Verify users through Tag Manager

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

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

```text theme={null}
script-src https://cdn.helpalive.com;
connect-src https://api.helpalive.com https://chat.helpalive.com;
```

[Content Security Policy](/sdk/csp) explains each source.

## Check it works

1. Open Tag Manager's **Preview** mode on your app and sign in. The `helpalive_identify` event fires the identify tag.
2. 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.
3. 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.

## Next

<CardGroup cols={3}>
  <Card title="Identify users" icon="user-check" href="/sdk/identify">
    What each field means.
  </Card>

  <Card title="Verify users" icon="shield-check" href="/sdk/verify-users">
    Sign each user id on your server.
  </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.