Customizing the FormHQ Project Tag

The FormHQ embed code was designed to use sensible defaults. but also allow for customization as needed to fit within an existing measurement configuration as required.

This short guide will highlight how to change some of the default settings in the FormHQ embed code, with supporting examples.

Understanding the Embed Code

Your default embed code will look similar to the example below.

<!-- FormHQ Embed Code for WebMechanix -->
<script>
(function(f,o,r,m,h,q){
f.FormHQ = {
id: "...",
platforms: {
  "hubspot": "..."
}
};
h=o.createElement(r);h.id="FormHQScript";h.async=1;h.src=m+"/base.js";
q=o.getElementsByTagName(r)[0];q.parentNode.insertBefore(h,q);
})(window,document,"script","https://embed.formhq.net/v1");
</script>

You should NEVER change the values for the following parameters unless you know what you are doing:

id
platforms

FormHQ Default Settings

Below is an example of the settings that are available for overriding/customizing in the embed code. Keep in mind – it should be rare that you need to change some of these settings.

{
  redirectDelay:    175,
  dataLayer:        'dataLayer',
  gtmEventName:     'FormHQ - Form Submit',
  categoryParam:    'event_category',
  actionParam:      'event_action',
  labelParam:       'event_label',
  valueParam:       'event_value',
  eventCategory:    'FormHQ',
  notFound:         'Form Missing in FormHQ',
  noGroup:          'No Group',
  payloadFilter:    null
}

redirectDelay
The value (in milliseconds) to delay a form from redirecting on submission. If a user is on an ultra-fast internet connection, the form can redirect and un-load the page before the requests to various platforms are received. If you are having data discrepancies – try changing this value between 300-500.

dataLayer
On rare occasions, GTM may be configured to use a different global variable other than the standard dataLayer. You may customize your global dataLayer variable name using this setting.

gtmEventName
This is the event name that will be used during a dataLayer.push to Google Tag Manager. You may change this value to fit within your existing GTM setup if desired.

categoryParam
actionParam
labelParam
valueParam
If you wish to change the dataLayer parameter keys to something else, you can customize them by overriding these values.

eventCategory
This is the default value that will be used in the event_category (or equivalent) dataLayer parameter for your form submission events.

notFound
Used to set the value used for the event_action (or equivalent) value when the a submitted form has not been synced into the FormHQ database.

noGroup
Used to set the value used for the event_action (or equivalent) value when the submitted form has not been assigned to a group inside of FormHQ.

payloadFilter
Warning – you are approaching power-user territory!

The payloadFilter setting is a callback method made available for allowing complete control over the formatting of your dataLayer events. The callback provides 2 arguments: form, and fields.

The form argument contains a reference to the form submitted. The fields argument is an object of key:value pairs containing the submitted form fields.

The callback should return an object, this object is merged with the dataLayer event object before being emitted to the Google Tag Manager container.

Why use this?

Well – most users probably won’t need to use it at all. The true power of this lies in being able to programmatically append additional dataLayer parameters to your events based off of data submitted through the form by the user.

For example:

payloadFilter: function( form, fields ) {
        
  var parameters = {};

  switch( form.group ) {

    case 'Blog/Newsletter Subscription':
    case 'Resource Download/Access':
      parameters.funnel_depth = 'High';
    break;

    case 'Webinar Replay/Registration':
      parameters.funnel_depth = 'Middle';
    break;

    case 'Free Trial':
    case 'Account Sign Up':
      parameters.funnel_depth = 'Low';
    break;

    default:
      parameters.funnel_depth = undefined;
    break;

  }

  return parameters;

}

In the example above, the callback programmatically sets a funnel_depth parameter based on what group the form is assigned to. This can be helpful with complex tracking setups where you may want to look at data from different angles. This funnel_depth parameter could be passed into a custom dimension or property in Google Analytics for custom reporting needs.