outbound-form-tracker.md

outboundFormTracker

This guide explains what the outboundFormTracker plugin is and how to integrate it into your analytics.js tracking implementation.

Overview

When a visitor to your site submits a form that goes to another page on your site, you can usually see this information in Google Analytics because the page being navigated to will typically send its own pageview. However, if a visitor to your site submits a form that points to an external domain, you'll never know unless you track that submit separately.

The outboundFormTracker plugin automatically detects when forms are submitted to sites on different domains and sends an event hit to Google Analytics.

Historically, outbound form tracking has been tricky to implement because most browsers stop executing JavaScript on the current page once a form that requests a new page is submitted. The outboundFormTracker plugin handles these complications for you.

Usage

To enable the outboundFormTracker plugin, run the require command, specify the plugin name 'outboundFormTracker', and pass in any configuration options (if any) you wish to set:

ga('require', 'outboundFormTracker', options);

Determining what is an outbound form

By default a form is considered outbound if the hostname of the URL it's pointing to differs from location.hostname. Note that this means forms pointing to different subdomains within the same higher-level domain are (by default) still considered outbound. To customize this logic, see shouldTrackOutboundForm in the options section below.

Options

The following table outlines all possible configuration options for the outboundFormTracker plugin. If any of the options has a default value, the default is explicitly stated:

Name	Type	Description
formSelector	string	A selector used to identify forms to listen for submit events on. Default: 'form'
shouldTrackOutboundForm	Function	A function that returns true if the form in question should be considered an outbound form. The function is invoked with the form element as its first argument and a parseUrl utility function (which returns a Location-like object) as its second argument. Default: function shouldTrackOutboundForm(form, parseUrl) { var url = parseUrl(form.action); return url.hostname != location.hostname && url.protocol.slice(0, 4) == 'http'; }
fieldsObj	Object	See the common options guide for the fieldsObj description.
attributePrefix	string	See the common options guide for the attributePrefix description. Default: 'ga-'
hitFilter	Function	See the common options guide for the hitFilter description.

Default field values

The outboundFormTracker plugin sends hits with the following values. To customize these values, use one of the options described above.

Field	Value
hitType	'event'
eventCategory	'Outbound Form'
eventAction	'submit'
eventLabel	form.action

Note: the reference to form in the table above refers to the <form> element being submitted.

Methods

The following table lists all methods for the outboundFormTracker plugin:

Name	Description
remove	Removes the outboundFormTracker plugin from the specified tracker, removes all event listeners from the DOM, and restores all modified tasks to their original state prior to the plugin being required.

For details on how analytics.js plugin methods work and how to invoke them, see calling plugin methods in the analytics.js documentation.

Examples

Basic usage

ga('require', 'outboundFormTracker');

<form action="https://example.com">...</form>

Customizing the form selector

This code only tracks form elements with the js-track-submits class.

ga('require', 'outboundFormTracker', {
  formSelector: '.js-track-submits'
});

<form class="js-track-submits" action="https://example.com">...</form>

Customizing what is considered an "outbound" form

This code changes the default logic used to determine if a form is "outbound". It updates the logic to only track forms that submit to the foo.com and bar.com domains:

ga('require', 'outboundFormTracker', {
  shouldTrackOutboundForm: function(form, parseUrl) {
    var url = parseUrl(form.action);
    return /(foo|bar)\.com$/.test(url.hostname);
  }
});

With the above code, submits from the following form won't be tracked, even though the form is submitting to an external domain:

<form action="https://example.com">...</form>