Skip to main content

​
Prerequisites

  • Google Tag Manager 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)
Use PUBLIC_URL for multi-domain setups, WEBAPP_URL for single-domain setups.

​
Basic Setup

1

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>
2

Add initialization script

<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>
Add GTM Custom HTML tag
3

Set trigger

  1. Trigger: All Pages - Page View (default) or use case specific event
  2. Save and publish Add a trigger
4

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 for more details)

​
User Identification

Identify users to enable targeting and attributes. Learn more about user identification.
User identification is part of the Formbricks Enterprise Edition.
1

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) Create a variable
2

Create identification tag

New Custom HTML tag named “Formbricks - User”:
<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>
3

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 User Login Trigger
  6. In your code, push data with the same event name: 
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
    'event': 'user-login',
    'userId': 'user-123',
    'userEmail': '[email protected]',
    'userPlan': 'premium'
});

​
Track Custom Events

1

Create code action in Formbricks

Add code action via Formbricks UIAdd a code action to open source in app survey
2

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 Create Event Variable
3

Create event tracking tag

New Custom HTML tag:
<script>
if (window.formbricks && window.formbricks.track) {
    window.formbricks.track({{Event Name}});
}
</script>
4

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 Track Event Trigger
5

Fire events from your site

// Track button click
window.dataLayer.push({
    'event': 'eventName',
    'eventName': 'code-action'
});

​
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?