# GTM Form Tracking Implementation Guide

**Last Updated:** 2026-02-17

## Overview

This guide provides step-by-step instructions for setting up Google Tag Manager (GTM) form tracking for all acquisition forms on the Ordio website. The implementation uses dataLayer.push() events to track form submissions across HubSpot embedded forms, custom HTML forms, and API-based form submissions.

## Prerequisites

- Access to Google Tag Manager container: `GTM-5DWSFND`
- Access to Google Analytics 4 property
- Understanding of GTM triggers, tags, and variables
- Access to HubSpot account (for form GUID reference)

## Implementation Status

✅ **Completed:**

- Form audit and inventory
- Centralized tracking utility (`v2/js/gtm-form-tracking.js`)
- DataLayer implementation for all form types
- Standardized event structure

⏳ **Pending (GTM Configuration):**

- Enable built-in form variables
- Create dataLayer variables
- Create triggers
- Create GA4 tags
- Configure consent mode

## Step 1: Enable GTM Built-In Form Variables

1. Log in to Google Tag Manager
2. Navigate to **Variables** → **Built-In Variables**
3. Enable the following form-related variables:
   - **Form Element**
   - **Form Classes**
   - **Form ID**
   - **Form Target**
   - **Form URL**
   - **Form Text**

**Why:** These variables allow GTM to automatically capture form information for standard HTML forms.

## Step 2: Create DataLayer Variables

Create custom variables to capture dataLayer push data:

### Required Variables

1. **Form ID Variable**

   - **Type:** Data Layer Variable
   - **Data Layer Variable Name:** `form_id`
   - **Name:** `DLV - Form ID`

2. **Form Name Variable**

   - **Type:** Data Layer Variable
   - **Data Layer Variable Name:** `form_name`
   - **Name:** `DLV - Form Name`

3. **Form Type Variable**

   - **Type:** Data Layer Variable
   - **Data Layer Variable Name:** `form_type`
   - **Name:** `DLV - Form Type`

4. **HubSpot Form GUID Variable**

   - **Type:** Data Layer Variable
   - **Data Layer Variable Name:** `hubspot_form_guid`
   - **Name:** `DLV - HubSpot Form GUID`

5. **Page URL Variable**

   - **Type:** Data Layer Variable
   - **Data Layer Variable Name:** `page_url`
   - **Name:** `DLV - Page URL`

6. **UTM Source Variable**

   - **Type:** Data Layer Variable
   - **Data Layer Variable Name:** `utm_source`
   - **Name:** `DLV - UTM Source`

7. **UTM Campaign Variable**

   - **Type:** Data Layer Variable
   - **Data Layer Variable Name:** `utm_campaign`
   - **Name:** `DLV - UTM Campaign`

8. **Conversion Type Variable** (required for GA4 segmentation)

   - **Type:** Data Layer Variable
   - **Data Layer Variable Name:** `conversion_type`
   - **Name:** `DLV - Conversion Type`

**Naming Convention:** Use prefix `DLV -` for all Data Layer Variables to easily identify them.

## Step 3: Create Universal Form Submission Trigger

Create a catch-all trigger for all form submissions:

1. **Trigger Name:** `Form Submit - All Forms`
2. **Trigger Type:** Form Submission
3. **This trigger fires on:** All Forms
4. **Conditions:** None (fires on all form submissions)

**Use Case:** This trigger captures all form submissions as a fallback. More specific triggers (below) will provide better segmentation.

## Step 4: Create Specific Form Triggers

Create specific triggers for each form type to enable better segmentation and filtering:

### Custom HTML Form Triggers

1. **Trigger Name:** `Form Submit - Demo Form (Main)`

   - **Trigger Type:** Form Submission
   - **This trigger fires on:** Some Forms
   - **Conditions:**
     - Form ID equals `demo-form`
     - Page URL contains `/` (or specific pages where main form appears)

2. **Trigger Name:** `Form Submit - Demo Form (SDR)`

   - **Trigger Type:** Form Submission
   - **This trigger fires on:** Some Forms
   - **Conditions:**
     - Form ID equals `demo-form`
     - Page URL contains `/sdr`

3. **Trigger Name:** `Form Submit - Content Form`

   - **Trigger Type:** Form Submission
   - **This trigger fires on:** Some Forms
   - **Conditions:**
     - Form ID equals `content-form`

4. **Trigger Name:** `Form Submit - Email Form (Hero)`
   - **Trigger Type:** Form Submission
   - **This trigger fires on:** Some Forms
   - **Conditions:**
     - Form ID equals `emailForm`

### HubSpot Embedded Form Trigger

1. **Trigger Name:** `Form Submit - HubSpot Embedded`
   - **Trigger Type:** Custom Event
   - **Event name:** `form_submit`
   - **This trigger fires on:** Some Custom Events
   - **Conditions:**
     - Event equals `form_submit`
     - Form Type equals `hubspot_embedded`

### API-Based Form Trigger

1. **Trigger Name:** `Form Submit - API Based`
   - **Trigger Type:** Custom Event
   - **Event name:** `form_submit`
   - **This trigger fires on:** Some Custom Events
   - **Conditions:**
     - Event equals `form_submit`
     - Form Type equals `api_based`

## Step 5: Create Google Analytics 4 Tags

Create GA4 event tags to send form submission data to Google Analytics:

### Universal Form Submit Tag

1. **Tag Name:** `GA4 Event - Form Submit (All)`
2. **Tag Type:** Google Analytics: GA4 Event
3. **Configuration Tag:** Your GA4 Configuration tag
4. **Event Name:** `form_submit`
5. **Event Parameters:**
   - `form_id` → `{{DLV - Form ID}}`
   - `form_name` → `{{DLV - Form Name}}`
   - `form_type` → `{{DLV - Form Type}}`
   - `hubspot_form_guid` → `{{DLV - HubSpot Form GUID}}`
   - `page_url` → `{{DLV - Page URL}}`
   - `utm_source` → `{{DLV - UTM Source}}`
   - `utm_campaign` → `{{DLV - UTM Campaign}}`
6. **Triggering:** `Form Submit - All Forms`

### Specific Form Submit Tags (Optional)

Create additional tags for specific forms if you need separate events:

1. **Tag Name:** `GA4 Event - Form Submit (Main Lead Capture)`

   - **Event Name:** `form_submit_main_lead`
   - **Triggering:** `Form Submit - Demo Form (Main)`

2. **Tag Name:** `GA4 Event - Form Submit (HubSpot Embedded)`

   - **Event Name:** `form_submit_hubspot`
   - **Triggering:** `Form Submit - HubSpot Embedded`

3. **Tag Name:** `GA4 Event - Form Submit (API Based)`
   - **Event Name:** `form_submit_api`
   - **Triggering:** `Form Submit - API Based`

## Step 6: Configure Consent Mode

Ensure form tracking respects user consent preferences:

1. **Review Consent Settings:**

   - Check that consent mode is configured in your GTM container
   - Verify consent variables are set up (if using consent management platform)

2. **Update Triggers:**

   - Add consent condition to form submission triggers if required
   - Example: `Consent - Analytics equals Granted`

3. **Test Consent Scenarios:**
   - Test with consent granted
   - Test with consent denied
   - Verify tracking behavior matches expectations

## Step 7: Test Implementation

### Using GTM Preview Mode

1. Open GTM Preview mode
2. Navigate to a page with a form
3. Fill out and submit the form
4. Verify in GTM Preview:
   - ✅ Trigger fires (check "Tags Fired" section)
   - ✅ DataLayer push appears (check "DataLayer" tab)
   - ✅ Variables populate correctly
   - ✅ GA4 tag fires

### Testing Checklist

- [ ] HubSpot embedded form (SDR form) - `/sdr` or `/sdr-neu`
- [ ] Main lead capture form (`demo-form`) - Multiple pages
- [ ] Gated content form (`content-form`) - Download pages
- [ ] Hero email form (`emailForm`) - Hero sections
- [ ] Lead capture popup (Step 1 and Step 2) - Various pages
- [ ] Template download forms - `/vorlagen/schichtplan-excel-vorlage`, `/vorlagen/dienstplan-excel-vorlage`
- [ ] Calculator export forms - Calculator tool pages
- [ ] Add-on pricing form - Pricing pages
- [ ] Webinar registration forms - Webinar pages
- [ ] ShiftOps unlock form - `/shiftops/report`

### Verify in Google Analytics 4

1. Navigate to **Reports** → **Realtime**
2. Submit a test form
3. Check **Events** section for `form_submit` event
4. Verify event parameters are populated correctly

## conversion_type Parameter (Required)

All form submissions **must** include `conversion_type` for GA4 segmentation. Register `conversion_type` as an event-scoped custom dimension in GA4 Admin.

**GTM configuration:**
- Create `DLV - Conversion Type` (Data Layer Variable for `conversion_type`)
- When firing `generate_lead` from `form_submit`, pass `conversion_type` → `{{DLV - Conversion Type}}`

**Valid values:** See [GA4_EVENT_NAMING.md](../systems/analytics/GA4_EVENT_NAMING.md): `demo_request`, `lead_capture_popup`, `template_download`, `tools_export`, `webinar_registration`, `gated_content`, `shiftops_unlock`, `addon_request`, `event_registration`, `email_capture`.

## form_submit → generate_lead Mapping

1. **Trigger:** Custom Event `form_submit`
2. **GA4 Tag:** Fire `generate_lead` (not `form_submit`) as the conversion event
3. **Event parameters:** Pass `conversion_type` and `form_id` from dataLayer variables (`{{DLV - Conversion Type}}`, `{{DLV - Form ID}}`)

## DataLayer Event Structure

All form submissions push the following standardized structure to dataLayer:

```javascript
{
  event: 'form_submit',
  form_id: 'demo-form',
  form_name: 'Main Lead Capture Form',
  form_type: 'custom_html', // or 'hubspot_embedded' or 'api_based'
  form_subtype: 'modal_form', // optional, form-specific subtype
  conversion_type: 'demo_request', // for GA4 segmentation
  page_url: 'https://www.ordio.com/page',
  page_title: 'Page Title',
  page_path: '/page',
  hubspot_form_guid: '9b93ee13-fad2-4ce8-8ea2-4e588932af2a',
  utm_source: 'google',
  utm_medium: 'cpc',
  utm_campaign: 'campaign_name',
  utm_term: '',
  utm_content: '',
  gclid: '',
  lead_source: 'google',
  partner: '',
  // Additional form-specific data
  form_step: 1, // for multi-step forms
  content_type: 'whitepaper', // for gated content
  template_type: 'Schichtplan Vorlage - Template', // for template downloads
  addon_name: 'Payroll', // for addon forms
  webinar_type: 'product_webinar' // for webinar forms
}
```

## Troubleshooting

### Issue: Trigger Not Firing

**Possible Causes:**

- Form ID doesn't match trigger condition
- Form submits via JavaScript (not standard form submission)
- Page URL condition too restrictive

**Solution:**

- Check form ID in browser DevTools (Elements tab)
- Use Custom Event trigger for JavaScript-based submissions
- Review trigger conditions in GTM Preview mode

### Issue: DataLayer Variables Not Populating

**Possible Causes:**

- Variable name mismatch
- DataLayer push happens after trigger fires
- Variable not enabled

**Solution:**

- Verify dataLayer variable names match exactly (case-sensitive)
- Check dataLayer tab in GTM Preview to see actual push
- Ensure variables are enabled in GTM

### Issue: Duplicate Events

**Possible Causes:**

- Multiple triggers firing for same form
- DataLayer push happens multiple times
- Both universal and specific triggers active

**Solution:**

- Review trigger conditions to ensure only one fires
- Check JavaScript code for duplicate tracking calls
- Use trigger priority or conditions to prevent duplicates

## Next Steps

1. Complete GTM configuration (Steps 1-6 above)
2. Test all forms in GTM Preview mode
3. Verify data in GA4 real-time reports
4. Set up GA4 custom dimensions for form tracking
5. Create GA4 reports and dashboards for form analytics
6. Set up alerts for tracking failures

## Reference Documents

- `docs/forms/form-audit-inventory.json` - Complete form inventory
- `docs/forms/form-ids-reference.md` - Quick reference for form IDs
- `docs/forms/FORM_TRACKING_DEVELOPER_GUIDE.md` - Developer guide for adding new forms
- `v2/js/gtm-form-tracking.js` - Tracking utility source code

## Support

For questions or issues:

- Review troubleshooting guide: `docs/forms/FORM_TRACKING_TROUBLESHOOTING.md`
- Check developer guide: `docs/forms/FORM_TRACKING_DEVELOPER_GUIDE.md`
- Contact: hady@ordio.com