Event Listeners

The following Event Listener tags are available:

Click Listener

When this tag is fired, Google Tag Manager begins listening for all types of clicks (e.g. button clicks, link clicks, etc) on the page. When a click occurs, the Google Tag Manager event gtm.click is generated. You can check for this event in rule conditions, using {{event}} equals gtm.click. To check whether a specific element was clicked, such as the “add to cart” button, add a rule like {{element id}} equals addToCart. Note that checking the value only works in a rule that's used by the tag that fires in response to the listener. Read Google Analytics Events for examples.

Form Submit Listener

When this tag is fired, Google Tag Manager begins listening for form submits on the page. When a form submit occurs, the Google Tag Manager event gtm.formSubmit is generated. You can check for this event in rule conditions, using {{event}} equals gtm.formSubmit. Note that checking the value only works in a rule that's used by the tag that fires in response to the listener. Read Google Analytics Events for examples.

Wait For Tags

Delay form submit until all the tags that depend upon this event have fired or the specified timeout has elapsed, whichever comes first. If unselected, slow tags may not fire before the form submit causes the next page to load.

Check Validation

Only fire tags if the form will successfully submit. If unselected, fire tags whenever a user tries to submit the form. Read About the Check Validation Option, below, for more information.

Link Click Listener

When this tag is fired, Google Tag Manager begins listening for link clicks on the page. Link Click Listener should be used (instead of Click Listener) for clicks that take the user to another page. When a link is clicked, the Google Tag Manager event gtm.linkClick is generated. You can check for this event in rule conditions, using {{event}} equals gtm.linkClick. Note that checking the value only works in a rule that's used by the tag that fires in response to the listener. Read Google Analytics Events for examples.

Wait For Tags

Delay opening of links until all tags have fired or the specified timeout has elapsed, whichever comes first. If unselected, slow tags may not fire before the link click causes the next page to load.

Check Validation

Only fire tags when opening the link is considered a valid action. If unselected, fire tags whenever a user tries to click the link. Read About the Check Validation Option, below, for more information.

Timer Listener

When this tag is fired, Google Tag Manager starts a countdown timer that fires an event at the Interval (in milliseconds) you specify. An Interval of 5000 will fire an event every five seconds. The name of the event is whatever name you specify in Event Name. For example, if you specify an Event Name of “timer5”, you can check for the event in rule conditions, using {{event}} equals timer5. Note that checking the value only works in a rule that's used by the tag that fires in response to the listener. Read Google Analytics Events for examples. Limit is the maximum number of times to fire the event. Leaving Limit blank causes the event to keep firing until the user leaves the page.

History Listener

This tag will listen for changes to the page's history. These History events typically happen when the URL fragment (hash) changes in an Ajax app, or when a site is using the HTML5 pushstate APIs. This event listener is useful for tracking virtual pageviews.

When a history event occurs, this tag will push the following message onto the data layer:

eventLabels this object as gtm.historyChange.
gtm.historyChangeSourceSource of the history event. Can be polling, popstate, pushState, or replaceState.
gtm.oldUrlFragmentWhat the URL fragment used to be.
gtm.newUrlFragmentWhat the URL fragment is now.
gtm.oldHistoryStateThe old history state object, controlled by the site's calls to pushState.
gtm.newHistoryStateThe new history state object, controlled by the site's calls to pushState.

JavaScript Error Listener

When this tag is fired, Google Tag Manager will listen for uncaught JavaScript exceptions. When one of these exceptions occurs, it will push an object onto the Data Layer with key value pairs describing the error. The following table describes each key available from a JavaScript Error Listener event:

KeyValue
eventLabels this object as gtm.pageError.
gtm.errorMessageA string containing the text of the JavaScript error message.
gtm.errorUrlThe URL where the error was raised.
gtm.errorLineNumberThe line number in the code where the error was raised.

This event can be monitored in rule conditions, using {{event}} equals gtm.pageError. Read Google Analytics Events for examples.

About the Check Validation Option

Validation refers to JavaScript's ability to prevent the browser's default action on an event. In a browser, the default action for a link click is to take the visitor to the linked URL. The default action for a form is to submit the form.

In both link clicks and form submits, JavaScript event listeners on the page have the ability to prevent the default action from happening. This is useful when you want to keep the user on the current page, or if the form being submitted is invalid.

There are a few ways to prevent the default action. In DOM level 0 listeners (e.g. onclick="..."), you can use return false;. In level 2+ listeners, you can use the event.preventDefault method.

The Check Validation option allows you to only fire tags if the default action has not been prevented by some other piece of code in the page. This can help ensure you don't track the same form submit multiple times (e.g. when someone tries to submit an invalid form, corrects their mistake and then resubmits the form).

If enabling Check Validation results in a gtm.linkClick or gtm.formSubmit event not firing, it is because your site is canceling the default browser action for some reason. If you want your tags to fire in all cases, you can simply uncheck Check Validation on your listeners.

Interactions between JavaScript event listeners in a page can affect Google Tag Manager's auto-event tracking in ways you may not anticipate. These interactions make it important that you test your tracking setup in debug mode before deploying to your live site. And, since auto-events take the form of "listener tags", you can use rules to only deploy your listeners in the specific places that you've been able to test.