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

# Google Tag Manager

> Deploy Formbricks surveys through GTM without modifying your website code.

## Prerequisites

* [Google Tag Manager](https://tagmanager.google.com/) installed on your website
* Your Formbricks **Environment ID** (Settings > Configuration > Website & App Connection)
* Your **App URL**: `https://app.formbricks.com` (or your self-hosted URL)

<Note>
  Use PUBLIC\_URL for multi-domain setups, WEBAPP\_URL for single-domain setups.
</Note>

## Basic Setup

<Steps>
  <Step title="Create a Custom HTML tag in GTM">
    1. Create a new tag with preferred name e.g. "Formbricks Intercept Surveys"
    2. Tag Type: Custom HTML
    3. Paste the code from Step 2. Make sure to replace `<your-environment-id>` and if you self-host, replace `<your-app-url>`
  </Step>

  <Step title="Add initialization script">
    ```html theme={null}
    <script type="text/javascript">
    !function(){
        var appUrl = "https://app.formbricks.com"; // REPLACE ONLY IF YOUR SELF-HOST
        var environmentId = "<your-environment-id>"; // REPLACE
        var t=document.createElement("script");
        t.type="text/javascript";
        t.async=!0;
        t.src=appUrl+"/js/formbricks.umd.cjs";
        t.onload=function(){
            window.formbricks && window.formbricks.setup({
                environmentId: environmentId,
                appUrl: appUrl
            });
        };
        var e=document.getElementsByTagName("script")[0];
        e.parentNode.insertBefore(t,e);
    }();
    </script>
    ```

    <img src="https://mintcdn.com/formbricks/gz9Y_q0cHdgc2i5-/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-tag.webp?fit=max&auto=format&n=gz9Y_q0cHdgc2i5-&q=85&s=cfa8b579538b26016fedd29ecdaf44f5" alt="Add GTM Custom HTML tag" width="2310" height="1200" data-path="images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-tag.webp" />
  </Step>

  <Step title="Set trigger">
    1. Trigger: **All Pages** - Page View (default) or use case specific event
    2. Save and publish
           <img src="https://mintcdn.com/formbricks/gz9Y_q0cHdgc2i5-/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-trigger.webp?fit=max&auto=format&n=gz9Y_q0cHdgc2i5-&q=85&s=071c28b6a6c5b3d247cc6effddee3e2b" alt="Add a trigger" width="1924" height="744" data-path="images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-trigger.webp" />
  </Step>

  <Step title="Test">
    1. Use GTM Preview mode
    2. Verify the tag fires
    3. Add `?formbricksDebug=true` to the URL to see test logs in browser console (see [Debugging Mode](/xm-and-surveys/surveys/website-app-surveys/framework-guides#debugging-formbricks-integration) for more details)
  </Step>
</Steps>

## User Identification

Identify users to enable targeting and attributes. Learn more about [user identification](/xm-and-surveys/surveys/website-app-surveys/user-identification).

<Note>
  User identification is part of the Formbricks [Enterprise Edition](/self-hosting/advanced/license).
</Note>

<Steps>
  <Step title="Create GTM variables">
    1. Go to Variables on GTM dashboard
    2. Create new User-defined variable
    3. Name it (e.g., "User ID")
    4. Variable Type: Data Layer Variable
    5. Data Layer Variable: "userId"
    6. Save and publish
    7. Repeat for attributes you want to track e.g. "userEmail" and "userPlan" (optional)

           <img src="https://mintcdn.com/formbricks/gz9Y_q0cHdgc2i5-/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-variable.webp?fit=max&auto=format&n=gz9Y_q0cHdgc2i5-&q=85&s=95ad4100e696d8d04da729254b114846" alt="Create a variable" width="1898" height="1284" data-path="images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-variable.webp" />
  </Step>

  <Step title="Create identification tag">
    New Custom HTML tag named "Formbricks - User":

    ```html theme={null}
    <script>
    (function() {
        var check = setInterval(function() {
            if (window.formbricks && window.formbricks.setUserId) {
                clearInterval(check);
                var userId = {{User ID}};
                if (userId) {
                    window.formbricks.setUserId(userId);
                    var attrs = {};
                    if ({{User Email}}) attrs.email = {{User Email}};
                    if ({{User Plan}}) attrs.plan = {{User Plan}};
                    if (Object.keys(attrs).length) {
                        window.formbricks.setAttributes(attrs);
                    }
                }
            }
        }, 100);
        setTimeout(function() { clearInterval(check); }, 10000);
    })();
    </script>
    ```
  </Step>

  <Step title="Set trigger and push data">
    1. Create a custom event trigger in GTM

    2. Trigger Type: Custom Event

    3. Event name: `user-login` (or your preferred event name)

    4. Attach this trigger to your "Formbricks - User" tag

    5. Save and publish

           <img src="https://mintcdn.com/formbricks/gz9Y_q0cHdgc2i5-/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/user-login-trigger.webp?fit=max&auto=format&n=gz9Y_q0cHdgc2i5-&q=85&s=87d38ba5be4e04c81a5b5cf459a951c3" alt="User Login Trigger" width="2314" height="960" data-path="images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/user-login-trigger.webp" />

    6. In your code, push data with the same event name:

    ```javascript theme={null}
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
        'event': 'user-login',
        'userId': 'user-123',
        'userEmail': 'user@example.com',
        'userPlan': 'premium'
    });
    ```
  </Step>
</Steps>

## Track Custom Events

<Steps>
  <Step title="Create code action in Formbricks">
    Add code action via Formbricks UI

    <img src="https://mintcdn.com/formbricks/Y0_rk27eZSQCDXfm/images/xm-and-surveys/surveys/website-app-surveys/actions/code-action.webp?fit=max&auto=format&n=Y0_rk27eZSQCDXfm&q=85&s=5adf1d306ebe2aaf0f082b0e23287dd6" alt="Add a code action to open source in app survey" width="1990" height="1350" data-path="images/xm-and-surveys/surveys/website-app-surveys/actions/code-action.webp" />
  </Step>

  <Step title="Create GTM variable for Event Name">
    1. Go to Variables on GTM dashboard
    2. Create new User-defined variable
    3. Name it "Event Name"
    4. Variable Type: Data Layer Variable
    5. Data Layer Variable: "eventName"
    6. Save and publish

           <img src="https://mintcdn.com/formbricks/gz9Y_q0cHdgc2i5-/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-event-variable.webp?fit=max&auto=format&n=gz9Y_q0cHdgc2i5-&q=85&s=fbd317e8947d0cfbf101730f09db8713" alt="Create Event Variable" width="2350" height="1260" data-path="images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-event-variable.webp" />
  </Step>

  <Step title="Create event tracking tag">
    New Custom HTML tag:

    ```html theme={null}
    <script>
    if (window.formbricks && window.formbricks.track) {
        window.formbricks.track({{Event Name}});
    }
    </script>
    ```
  </Step>

  <Step title="Create custom trigger">
    1. Create a custom event trigger in GTM
    2. Trigger Type: Custom Event
    3. Event name: `eventName` or name that matches with your event in code.
    4. Attach this trigger to your event tracking tag
    5. Save and publish

           <img src="https://mintcdn.com/formbricks/gz9Y_q0cHdgc2i5-/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/track-event-trigger.webp?fit=max&auto=format&n=gz9Y_q0cHdgc2i5-&q=85&s=99ffe24faf44922f0f6c45f7e8c331f9" alt="Track Event Trigger" width="2342" height="996" data-path="images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/track-event-trigger.webp" />
  </Step>

  <Step title="Fire events from your site">
    ```javascript theme={null}
    // Track button click
    window.dataLayer.push({
        'event': 'eventName',
        'eventName': 'code-action'
    });
    ```
  </Step>
</Steps>

## Troubleshooting

**Surveys not showing?**

* Use GTM Preview mode to check tag firing
* Add `?formbricksDebug=true` to your URL
* Check browser console for errors
* Wait 1 minute for the Server Cache to refresh

**User ID not working?**

* Verify Data Layer push syntax
* Check GTM variables are reading correct values
* Ensure user tag fires after initialization

**Events not tracking?**

* Confirm `window.formbricks` exists before calling track
* Match event names exactly with Formbricks action names
* Check timing - Formbricks must be initialized first

## Need Help?

* [GitHub Discussions](https://github.com/formbricks/formbricks/discussions)
* [Framework Guides](/xm-and-surveys/surveys/website-app-surveys/framework-guides)
* [Actions](/xm-and-surveys/surveys/website-app-surveys/actions)
* [User Identification](/xm-and-surveys/surveys/website-app-surveys/user-identification)