Restriction mode

Tag restrictions let you decide, from WordPress, which kinds of tags, triggers and variables are allowed to run on your site, whatever the container in Google Tag Manager contains. This page covers both settings, what each restriction mode does, and how to tell that the result is what you wanted.

This page describes GTM4WP 2.0.0 and newer. Where the legacy 1.x versions of the plugin behaved differently, the older behavior is marked with a bold GTM4WP 1.x: lead-in.

What this is for

Anyone with edit access to your container can add a tag to it, and a Custom HTML tag can run any JavaScript it likes on your pages. Tag restrictions are the counterweight: the page itself declares what it will accept, so a tag type you never intended to allow does not execute even if somebody publishes it in the container.

The mechanism is Google’s, not the plugin’s. GTM4WP writes the restriction into the data layer under the key names Google documents, and Google Tag Manager enforces it. Google’s own page on the feature is restricting tags, triggers and variables.

Read the rest of this page before switching it on. A restriction that is too tight breaks tag deployment quietly, and the settings screen cannot warn you about it because the damage happens inside your container.

Where these settings live

Open the GTM4WP plugin settings page and go to the Tag restrictions section. It has two groups: Restriction mode and Entities.

GTM4WP 1.x: the section is called Blacklist, the modes are called blacklist and whitelist, and the entities are one long list rather than four groups.

Restriction mode

Default: Disabled.

Three choices, and the difference between the last two is the whole feature:

Disabled: no restriction is written to the page. Your container decides what runs, which is the normal WordPress behavior
Blocklist selected entities: everything runs except what you check below. Use it to bar a small number of specific things, most often the Custom HTML tag
Allowlist selected entities: nothing runs except what you check below. Use it when you want the page to accept a known, fixed set and refuse everything else

Only the key for the mode you selected is written to the page, so switching mode replaces the restriction rather than adding to it.

GTM4WP 1.x: both keys were written on every page, and the one for the mode you had not selected was left as an empty list. An empty allowlist is not the absence of an allowlist to Google Tag Manager, it is an allowlist that permits nothing, so blocklist mode blocked every tag, trigger and variable in the container. The symptom was total, silent, and easy to misread as the restriction simply being strict. If you used blocklist mode on 1.x and your tags stopped firing, that was the cause, and your selected entities were never the problem.

Entities

Restricted entities

Default: nothing selected.

The list of things the mode above applies to, in four groups:

Tags: individual tag types, from the Custom HTML and Custom Image tags to the vendor tags Google publishes an ID for
Triggers: the listeners that make tags fire, such as the Click, Form Submit, Scroll Depth and Timer listeners
Variables: the variable types a tag or trigger can read, such as URL, Data Layer Variable, Custom JavaScript and 1st Party Cookie
Entity groups: families of entities that have no individual ID of their own. There is one entry here, Sandboxed custom template scripts, which covers the sandboxed scripts inside custom tag and variable templates

Each group shows how many of its entries you have checked, so you can see at a glance where a restriction is in force.

GTM4WP 1.x: the section had a “Custom tag/variable templates” checkbox that was never written to the page, so it did nothing. It is a working entry now.

The mistake that catches everyone

In allowlist mode it is not enough to allow the tag you want. A tag only runs when its trigger fires, and a trigger only fires when it can read the variables it depends on, so allowing a tag whose trigger or variables you did not allow produces a tag that never fires.

The usual version of this: allowlist the Google tag and nothing else, and it still does not fire, because its Page View trigger reads the URL variable and the URL variable type was not allowed. Work through what each tag you allow actually needs, or start in blocklist mode instead, where this failure cannot happen.

Checking what the restriction actually did

Two checks, and it is worth doing both, because a restriction produces no error message anywhere.

First, on the page: open the browser console and inspect your data layer, which is the dataLayer variable unless you renamed it. In blocklist mode you should find a gtm.blocklist entry holding your selected entity IDs, and no gtm.allowlist. In allowlist mode you should find gtm.allowlist and no gtm.blocklist. If you find an empty list under either key, nothing is restricted in that direction.

Second, in Google Tag Manager preview mode: load a page and read the list of tags for the page view. A tag the restriction stopped appears among the tags that did not fire. Compare that list against what you expected before deciding the restriction is correct, because a tag missing from the fired list is exactly what an over tight allowlist looks like too.

Check your GTM setup if you built a data layer variable, a trigger or a custom template that reads gtm.whitelist or gtm.blacklist. Those key names are no longer written. Read gtm.allowlist and gtm.blocklist instead. The restriction settings themselves need no attention.