# GTM Form Tracking Documentation

**Last Updated:** 2026-01-10

Complete documentation for the Google Tag Manager form tracking utility.

## Overview

The GTM Form Tracker (`v2/js/gtm-form-tracking.js`) provides centralized form submission tracking in Google Tag Manager via dataLayer.push().

## File Location

- **Source:** `v2/js/gtm-form-tracking.js`
- **Minified:** `v2/js/gtm-form-tracking.min.js`
- **Global Object:** `window.GTMFormTracker`

## Features

- Centralized form tracking utility
- Standardized dataLayer events
- Automatic UTM data collection
- Support for multiple form types
- Custom data support

## API Reference

### `trackCustomHTMLForm(formElement, options)`

Track custom HTML form submission.

**Parameters:**

- `formElement` (HTMLElement|string): Form element or form ID
- `options` (Object): Additional options

**Options:**

- `formName` (string): Custom form name
- `formType` (string): Custom form type
- `hubspotFormGuid` (string): HubSpot form GUID
- `step` (number): Form step (for multi-step forms)
- `contentType` (string): Content type
- `additionalData` (Object): Additional data to include

**Example:**

```javascript
window.GTMFormTracker.trackCustomHTMLForm("my-form", {
  formName: "Contact Form",
  formType: "contact",
  hubspotFormGuid: "12345678-1234-1234-1234-123456789012",
});
```

### `trackHubSpotEmbeddedForm(formData, options)`

Track HubSpot embedded form submission.

**Parameters:**

- `formData` (Object): HubSpot form data
- `options` (Object): Additional options

**Example:**

```javascript
window.GTMFormTracker.trackHubSpotEmbeddedForm(
  {
    formId: "12345678-1234-1234-1234-123456789012",
    portalId: "145133546",
    region: "eu1",
  },
  {
    formName: "HubSpot Embedded Form",
  }
);
```

### `trackAPIForm(endpoint, options)`

Track API-based form submission.

**Parameters:**

- `endpoint` (string): API endpoint name (e.g., 'collect-lead.php')
- `options` (Object): Additional options

**Options:**

- `formName` (string): Form name
- `formId` (string): Form ID
- `hubspotFormGuid` (string): HubSpot form GUID
- `formGuidConstant` (string): Form GUID constant name
- `contentType` (string): Content type
- `templateType` (string): Template type
- `additionalData` (Object): Additional data

**Example:**

```javascript
window.GTMFormTracker.trackAPIForm("collect-lead.php", {
  formName: "Minijob-Rechner Export Form",
  formId: "calculator-export-minijob-rechner",
  hubspotFormGuid: "a91b263c-7ca2-418b-b35c-9664c30e968b",
  formGuidConstant: "TOOLS",
  contentType: "Minijob-Rechner",
});
```

## DataLayer Event Structure

All form tracking events use this structure:

```javascript
{
    event: 'form_submit',
    form_id: string,
    form_name: string,
    form_type: string,           // 'custom_html', 'hubspot_embedded', 'api_based'
    form_subtype: string,        // Form subtype (optional)
    api_endpoint: string,        // For API-based forms
    page_url: string,
    page_title: string,
    page_path: string,
    hubspot_form_guid: string,
    form_guid_constant: string,  // For API-based forms
    utm_source: string,
    utm_medium: string,
    utm_campaign: string,
    utm_term: string,
    utm_content: string,
    gclid: string,
    lead_source: string,
    partner: string,
    content_type: string,        // Optional
    template_type: string,       // Optional
    form_step: number,           // Optional (for multi-step forms)
    // ... additionalData fields
}
```

## Integration Patterns

### Pattern 1: Custom HTML Form

```javascript
document.getElementById("my-form").addEventListener("submit", function (e) {
  window.GTMFormTracker.trackCustomHTMLForm(this, {
    formName: "Contact Form",
    hubspotFormGuid: "12345678-1234-1234-1234-123456789012",
  });
});
```

### Pattern 2: HubSpot Embedded Form

```javascript
hbspt.forms.create({
  portalId: "145133546",
  formId: "ad1036ce-33ec-463b-adde-2fa546324c8a",
  region: "eu1",
  target: "#form-container",
  onFormSubmit: function ($form) {
    window.GTMFormTracker.trackHubSpotEmbeddedForm({
      formId: "ad1036ce-33ec-463b-adde-2fa546324c8a",
      portalId: "145133546",
      region: "eu1",
    });
  },
});
```

### Pattern 3: API-Based Form

```javascript
fetch("/v2/api/collect-lead.php", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(formData),
}).then(() => {
  window.GTMFormTracker.trackAPIForm("collect-lead.php", {
    formName: "Tool Export Form",
    formId: "tool-export-form",
    hubspotFormGuid: "a91b263c-7ca2-418b-b35c-9664c30e968b",
    formGuidConstant: "TOOLS",
  });
});
```

## Automatic UTM Collection

The tracker automatically collects UTM data from:

1. `window.utmTracker.getUTMDataForAPI()` (if available)
2. `window.utmTracking` object (fallback)
3. URL parameters (fallback)
4. Cookies (fallback)

## Browser Compatibility

- Modern browsers (Chrome, Firefox, Safari, Edge)
- Requires `window.dataLayer` support
- Gracefully handles missing GTM

## Related Documentation

- [UTM Tracking System](UTM_TRACKING_SYSTEM.md) - UTM data source
- [Form Tracking Guide](../../forms/FORM_TRACKING_DEVELOPER_GUIDE.md) - Complete tracking guide
- [HubSpot API Reference](../apis/HUBSPOT_API_REFERENCE.md) - API endpoint tracking