diff --git a/docs/docs.json b/docs/docs.json index 4cd54239fa..3158265c81 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -112,6 +112,7 @@ "pages": [ "xm-and-surveys/surveys/website-app-surveys/quickstart", "xm-and-surveys/surveys/website-app-surveys/framework-guides", + "xm-and-surveys/surveys/website-app-surveys/google-tag-manager", { "group": "Features", "icon": "wrench", diff --git a/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-tag.webp b/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-tag.webp new file mode 100644 index 0000000000..2111ad177c Binary files /dev/null and b/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-tag.webp differ diff --git a/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-trigger.webp b/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-trigger.webp new file mode 100644 index 0000000000..9d257b67ed Binary files /dev/null and b/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-trigger.webp differ diff --git a/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-variable.webp b/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-variable.webp new file mode 100644 index 0000000000..69a5c19192 Binary files /dev/null and b/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-variable.webp differ diff --git a/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-event-variable.webp b/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-event-variable.webp new file mode 100644 index 0000000000..e184c8dea9 Binary files /dev/null and b/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-event-variable.webp differ diff --git a/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/track-event-trigger.webp b/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/track-event-trigger.webp new file mode 100644 index 0000000000..872d450c5d Binary files /dev/null and b/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/track-event-trigger.webp differ diff --git a/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/user-login-trigger.webp b/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/user-login-trigger.webp new file mode 100644 index 0000000000..29687dfa88 Binary files /dev/null and b/docs/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/user-login-trigger.webp differ diff --git a/docs/xm-and-surveys/surveys/website-app-surveys/google-tag-manager.mdx b/docs/xm-and-surveys/surveys/website-app-surveys/google-tag-manager.mdx new file mode 100644 index 0000000000..7a55ea7804 --- /dev/null +++ b/docs/xm-and-surveys/surveys/website-app-surveys/google-tag-manager.mdx @@ -0,0 +1,223 @@ +--- +title: "Google Tag Manager" +description: "Deploy Formbricks surveys through GTM without modifying your website code." +icon: "tags" +--- + +## 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) + + + Use PUBLIC_URL for multi-domain setups, WEBAPP_URL for single-domain setups. + + +## Basic Setup + + + + 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 `` and if you self-host, replace `` + + + + +```html + +``` + +![Add GTM Custom HTML tag](/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-tag.webp) + + + + + 1. Trigger: **All Pages** - Page View (default) or use case specific event + 2. Save and publish + ![Add a trigger](/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-trigger.webp) + + + + + 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) + + + + +## User Identification + +Identify users to enable targeting and attributes. Learn more about [user identification](/xm-and-surveys/surveys/website-app-surveys/user-identification). + + + User identification is part of the Formbricks [Enterprise Edition](/self-hosting/advanced/license). + + + + + 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](/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-a-variable.webp) + + + + New Custom HTML tag named "Formbricks - User": + +```html + +``` + + + + + 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](/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 +window.dataLayer = window.dataLayer || []; +window.dataLayer.push({ + 'event': 'user-login', + 'userId': 'user-123', + 'userEmail': 'user@example.com', + 'userPlan': 'premium' +}); +``` + + + + +## Track Custom Events + + + + Add code action via Formbricks UI + + ![Add a code action to open source in app survey](/images/xm-and-surveys/surveys/website-app-surveys/actions/code-action.webp "Add a code action to open source in app survey") + + + + 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](/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/create-event-variable.webp) + + + + + New Custom HTML tag: + +```html + +``` + + + + + 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](/images/xm-and-surveys/surveys/website-app-surveys/google-tag-manager/track-event-trigger.webp) + + + + + +```javascript +// 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? + +- [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) +