dataLayer Event Documentation

FormHQ makes heavy use of Google Tag Managers dataLayer API. This guide will explain the various dataLayer variables available for use inside your GTM configuration.

FormHQ will emit a dataLayer event whenever a form is successfully submitted on the page where the FormHQ embed code is present in the following format:

dataLayer.push({
  event: "FormHQ - Form Submit",
  event_category: "FormHQ",
  event_action: "[group_name]",
  event_label: "[form_name] - [form_id]",
  event_value: [group_value/form_value], 
  form: {
    name: "[form_name]",
    id: "[form_id]",
    value: [form_value]
    group: {
      name: "[group_name]",
      id: "[group_id]",
      value: [group_value]
    }
  }
});

Replacing all the [...] placeholders above – a real payload of data might look something like this:

dataLayer.push({
  event: "FormHQ - Form Submit",
  event_category: "FormHQ",
  event_action: "Resource Download",
  event_label: "Whitepaper - How FormHQ Works - 12345",
  event_value: 0, 
  form: {
    name: "Whitepaper - How FormHQ Works",
    id: "12345",
    value: 0
    group: {
      name: "Resource Download",
      id: "12",
      value: 0
    }
  }
});

Let’s break each dataLayer key:value pair down one-by-one:

event
This is the Google Tag Manager event key that will be used inside of trigger conditions and eventually attached to the tags you would like to port the FormHQ event data into. This value can be customized inside of your FormHQ embed code by overriding the gtmEventName configuration variable if desired.

event_category
By default, FormHQ will set the event category parameter to a value of FormHQ. The default value can be customized inside of your FormHQ embed code by overriding the eventCategory configuration variable if desired.

event_action
If the submitted form is assigned to a group inside of FormHQ – the value for this parameter will be the group forms group name. If the form doesn’t have a group assigned to it – but exists inside of FormHQ, a value of No Group will be assigned. Finally, if the submitted form hasn’t been synced to the FormHQ database a value of Form Missing in FormHQ is assigned.

event_label
The event_label should be one of two things: The form’s native platform name + ID – OR – the native platform id. The form name is not present if the submitted form is not synced to the FormHQ database.

event_value
The value of this parameter will be either a positive integer inherited from the assigned group’s value – or – a value set directly on the form. If there is no value assigned on the group or the form – a value of 0 is used by default.

form
The form object contains properties for specific metadata of the form that was submitted. This object is helpful when you wish to craft your own unique event structures instead of the pre-built event action & labels provided. Note – this makes FormHQ highly compatible with GA4’s new event based data model where the category/action/label hierarchy no longer exists.

Using these variables inside of GTM

You can extract and use these values easily by creating custom dataLayer variables inside of your Google Tag Manager container.

FormHQ uses the version 2 dataLayer variable syntax, this means that if you wish to access nested values inside the a dataLayer property, you can do so using DOT syntax (e.g: form.id). See the example screenshot below:

GTM dataLayer variable naming conventions

We highly recommend prefixing your custom dataLayer variables with DL - and also including the structure of the variable being referenced. For example, if you setup a dataLayer variable to reference the form.id a good name for that variable would be DL - form.id. Following this naming convention will help keep your variables organized and less mentally taxing.