Search
Clear search
Close search
Google apps
Main menu

Triggers

Control how tags fire using triggers.

A trigger is a condition that evaluates to either true or false at runtime. Triggers attached to a tag govern when the tag is fired or not fired.

In this article:

Overview

A tag must have at least one trigger in order to fire. Triggers are evaluated during runtime and associated tags are fired (or not fired) when the trigger conditions are met. For example, a tag with a trigger based on a pageview event with the following filter will be fired on the example.com home page:

url equals example.com/index.html

A trigger is composed of one event and one or more filters (except for custom events which don’t require a filter). Each filter takes the form: [Variable] [Operator] [Value]

Variable Operator Value
Choose between url, referrer, etc. Choose between equals, contains, etc. You provide a value. Google Tag Manager compares the value you provide with the runtime value in the variable.

In our example, the variable “url” is evaluated during runtime. The variable “url” has been defined such that it contains the current page URL . Thus, during runtime, the current page URL is compared to the value you’ve provided, “example.com/index.html”, to determine whether the trigger condition has been met.

In web containers, you can enable built-in variables such as page url, page hostname, or referrer. In addition, when setting up a click based trigger, Google Tag Manager uses built-in variables to automatically populates the variables corresponding to the clicked element id, classes, etc. With these variables, you’re able to construct the triggers you’ll most commonly need. However, you can also define your own variables and use their values in your trigger filters. Read Variables to learn more.

Tag Manager comes with many built-in variables for common needs, such as gathering URLs, click IDs, etc. Built-in variables must be enabled in Tag Manager before they are accessible in drop-down menus. Learn more

You can provide multiple filters ([Variable] [Operator] [Value]) in a single trigger. The trigger is met if all of the conditions in the trigger are met.

Firing/blocking triggers for tags

A tag will fire whenever any one of its triggers are met. For example, if a tag has two triggers, one for "all pages" and another for "only page ABC", the tag will fire on all pages.

A trigger that blocks a tag from firing always overrides a trigger. For example, if a tag has a trigger "all pages" and a blocking trigger "URL equals thankyou.html", the tag will never fire on the page "thankyou.html".

Trigger types

All tag firing in Tag Manager is event-driven. Anytime an event is registered by Tag Manager, triggers from the container are evaluated and tags are fired accordingly. No tag can be fired unless an event occurs.

An event can be a pageview, a click on a button, a form submission, or any custom event that you define. Tag Manager has 6 built-in event types plus a custom event option. The first step in setting up a trigger is selecting the event type associated with it. The built-in events include:

Pageview (web)

This event corresponds to the rendering of a page in the user’s web browser. This event can be further configured via the trigger type drop-down to tell Tag Manager if the tag should be fired immediately when the browser starts parsing the page (Page View), after the browser has finished constructing the full page DOM (DOM ready), or after the page has fully been loaded, including embedded resources such as images and scripts (Window Loaded). Adjusting the timing of a pageview based trigger can be helpful if your tag is using DOM or Javascript variables to capture dynamic values. All pageview based tags that interact with the DOM to populate variables should use DOM Ready as the trigger type to ensure the variables are consistently set.

Clicks (web)

To fire a tag when the user clicks on a link or an element of the page, select the click event type.

In the trigger filter, we recommend that you specify the url (or url pattern) of the page(s) where you expect the click to take place, in order to optimize Tag Manager’s performance.

When the user clicks on any element on pages matching the filter, Tag Manager will automatically populate the following variables (provided that you have enabled these built-in variables):

  • Click Element: The HTML element that was clicked.
  • Click Classes: An array of the values found in the element's class attribute.
  • Click ID: The ID attribute of the clicked element.
  • Click Target: The target attribute of the clicked element.
  • Click URL: The HREF attribute of the clicked element, if any.
  • Click Text: The visible text inside the clicked element.

You can then include those variables in your click trigger filter. For instance, if you have a button with the following markup on the page www.example.com/cart.html

<button type="submit" id="cart-add" class="addToCart" >ADD TO CART</button>

The following trigger configuration will fire a tag when the user clicks on that button:

Trigger Configuration

Trigger type: Click - All Elements
This trigger fires on: Some Clicks
Click ID equals cart-add
Page URL contains example.com/cart.html

You can further configure a click-based trigger to specify if you want it to only listen for clicks on regular links (“Just Links” option) or for clicks on any HTML element on the page (“All Elements” option).

Since link clicks usually cause the browser to load a new page and interrupt any pending HTTP request, you have the option to add a small delay to allow tags fired by Tag Manager to execute properly before redirecting to the next page. Checking the “Wait For Tags” option will delay opening of links until all tags have fired or the specified timeout has elapsed, whichever comes first.

The “Check Validation” option allows you to 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.

Form submission (web)

To fire a tag when a form is submitted by the user, select Form as your trigger event.

In the trigger filter, we recommend that you specify the url (or url pattern) of the page(s) where you expect the form submission to take place, in order to optimize Tag Manager’s performance.

When a form submission trigger is executed, the following variables will be automatically populated:

  • Form Element: The form element that was clicked.
  • Form Classes: An array of the values found in the form's class attribute.
  • Form ID: The ID attribute of the form element.
  • Form Target: The target attribute of the form element.
  • Form URL: The HREF attribute of the form element, if any.
  • Form Text: The visible text inside the form.

The “Wait for Tags” option allows you to delay the form submission until all the tags that depend upon this trigger 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.

The “Check Validation” option allows you to only fire tags if the form will successfully submit. If unselected, fire tags whenever a user tries to submit the form.

History change (web)

Triggers based on the History Change event will fire a tag when the URL fragment (hash) changes or when a site is using the HTML5 pushstate APIs. This trigger is useful to fire tags tracking virtual pageview in an Ajax application, for instance.

When an history change event occurs, Tag Managers populates the following variables:

  • History old url fragment: What the URL fragment used to be.
  • History new url fragment: What the URL fragment is now.
  • History old state: The old history state object, controlled by the site's calls to pushState.
  • History new state: The new history state object, controlled by the site's calls to pushState.

JavaScript error (web)

This type of trigger is used to fire tags when an uncaught JavaScript exception (using window.onError) occurs. When the trigger fires, the following variables will be populated:

  • Error message: A string containing the text of the JavaScript error message.
  • Error url: The URL: where the error was raised.
  • Error line number: The line number in the code where the error was raised.

Note that the JavaScript Error trigger will not report errors that occur before GTM loads, and that it will only report uncaught exceptions.

Timer (web)

Triggers based on this event allow you send events to Tag Manager at custom intervals to raise a Tag Manager event at a desired frequency. When using this trigger, 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. You can then use this event name to create a custom event trigger. For example, if you specify an Event Name of “timer5” in a timer based trigger, you should then create a custom event based trigger where the event condition is event equals timer5. 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.

Custom events (web & mobile)

Custom events are used for tracking interactions that might take place on your website or mobile app that aren't handled by standard methods. The most common use case for this is when you want to track form submissions, but the default behaviors for the form have been re-routed (e.g. the submit browser event has been overridden.)

Here is an example configuration for the web that will fire a tag when a custom event called 'button1-click' is pushed to the data layer:

  1. Add code that will push the event into the data layer when the button is clicked. 
    Example: <a href="#" name="button1" onclick="dataLayer.push({'event': 'button1-click'});" >Button 1</a>
  2. Create your tag. In the Trigger Configuration section of your new tag setup, create a new event with these settings:
    Trigger type: Custom Event
    Event name: button1-click
    This trigger fires on: All Custom Events

With this setup, your tag can fire even when the default submit event is overridden: When the button is clicked, a custom event with the value of button1-click is pushed to the data layer. Tag Manager then detects button1-click as a custom event value, and will proceed to fire the tag.

Tip: Standard event and custom event alike are all pushed into the data layer queue. To view the sequence of events pushed to the data layer on a given page, open the Javascript console on your web browser and type “dataLayer”.

data layer screenshot from Google Chrome
Tip: You can use dataLayer.push() to send multiple variables together with the event, such as pushing the conversion value upon the button click (e.g. dataLayer.push({'event':'button1-click','conversionValue':25});). You could then create the data layer variable in tag manager and use this variable in the conversion value field of your AdWords conversion tracking tag.

YouTube Video (web)

The YouTube Video trigger can be used to fire tags based on various interactions with embedded YouTube videos on your sites.

Upon each interaction, data about the video and playing status is pushed to the data layer. This video data can be captured using built-in video variables.

Basic capture options

  • Start: Fires when the video begins playing.
  • Complete: Fires when the video finishes playing.
  • Pause, Seeking, and Buffering: If the video is paused, the scrub bar is moved to seek or reposition timing within a video, or if the video buffers, the trigger will fire.
  • Progress: Fires upon specific video progress, configured by percentage or timestamp in seconds:
    • Percentages: Enter percentages as a comma separated list of one or more integers, representing the percentage of the video that has been played. Example: 5, 20, 50, 80, representing 5%, 20%, 50%, and 80% respectively.
    • Time Thresholds: Enter time thresholds as a comma separated list of one or more integers, representing the number of seconds that the video has played. Example: 5, 15, 60, 120, representing 5 seconds, 15 seconds, 60 seconds, and 120 seconds respectively.
Note: Percentage and time thresholds will only fire the trigger the first time they are reached. If the user seeks past a particular percentage or time threshold in the video, it will not fire the trigger

Advanced options

  • Add JavaScript API support to all videos: Check this box to enable the YouTube iFrame Player API. This ensures that the enablejsapi parameter is appended to YouTube video player URLs with an assigned value of 1, allowing the player to be controlled via iFrame or JavaScript. Note: This will cause the video to reload if it is playing when Google Tag Manager loads.

Note: YouTube Video triggers will work for videos loaded both on and after page load, so long as at least one of the following is present when Google Tag Manager loads:

  • An embedded YouTube video
  • The YouTube IFrame API <script>
  • Code to create the YouTube IFrame API <script>, as shown in this example

Using RegEx and CSS selector operators

You can use regular expressions and CSS selectors as operators when setting up triggers. When setting a regular expression or CSS selector as the operator for a trigger, you can specify that the trigger matches or does not match the rule you are applying. For example, the regular expression applied to a URL or URL path variable:

/pro/

will match all pages with the string "pro" in the URL path, including "products", "promotions, "professionals", and "processes".

The CSS selector may be used to target specific HTML elements. For instance, this selector applied to a Click Element variable:

#promo .purchase

will match a click for any element with a class attribute value of "purchase" that is a descendant element of a parent with an ID attribute value of "promo".

Adding filters to a trigger

After the selecting the event on which your trigger is based, you can further specify the conditions under which your trigger should fire tags depending on the values of Tag Manager variables. Each built-in event comes with one or more variables automatically populated by Tag Manager, such as the page url for a pageview or the clicked element id for a click event. You build filters for your trigger using variables associated with the type of event you selected, or any other custom variables you may have created.

With the exception of custom event based triggers, you must specify at least one filter when creating a trigger.

Lastly, you can provide a name for your trigger and set up additional configuration options that vary based on the chosen trigger type.

Triggers & variables

If your tag uses variables, the values that will be passed to the tag are the values that those variables have at the time of the event that triggered the tag to fire.

Consider the following example of successive data layer updates:

Screenshot of chrome devtools showing objects in data layer

A tag with a trigger to fire on the event productView would fire twice. If it uses a variables mapped to the data layer variable productId, its value will first be ‘ABCD’ for the first tag fire, then ‘EFGH’ for the second tag fire. If it uses the data layer variable mapped to loggedInUser, the value will be ‘no’ for both tag fires, since the value is initially set to ‘no’ and not overwritten on the second tag fire.

A tag with a trigger to fire on the ‘addToCart’ event would fire with the value ‘XYZ’ for productId, and with the value ‘yes’ for loggedInUser since the loggedInUser variable was modified from its previous value of ‘no’ in a dataLayer update that preceded the addToCart event. Note that the data layer update that sets the loggedInUser variable to ‘yes’ can not be used to trigger tags to fire since no event is associated with this update.

Best practices

Sometimes triggers, when configured improperly, can cause unexpected results. When setting up your triggers, please consider the following guidelines:

  1. Test your triggers with Preview mode: It is important to test form and link triggers before publishing them to your site. These triggers can break if another JavaScript event interrupts the process. A common culprit is that another script returns false before the form or link trigger is reached, preventing those triggers from ever firing. Use Preview mode to see if your tags aren't firing or if form submissions aren't being sent properly.

  2. Test in older web browsers: Older web browsers, especially Internet Explorer 8 and lower, can have issues with tags firing properly. These issues are far less common in modern web browsers. If your product requires support for older browsers, we highly recommend thorough testing using Preview mode before deployment.

  3. Limit the scope of form and link triggers to tested pages: Testing every page on your site can be very time consuming, and you should be judicious in how you deploy form and link triggers. Use filters to ensure that your trigger will only fire when your specified conditions are met (such as Page Path equals /my/tested/form/page) to make sure these triggers are only applied to the pages that you have tested.

Was this article helpful?
How can we improve it?