WordPress site user and visitor data

Use the following data layer variables to access data about the logged in user of your WordPress site and about the anonymous visitor.

Most of the values on this page are personal data. It is your responsibility to obtain the consent you need before you collect and process them, and to comply with the data protection rules that apply to your site, including but not limited to the GDPR and the CCPA. The plugin only makes the data available in the data layer. Whether a tag is allowed to send it has to be set up in your Google Tag Manager container.

Every variable on this page has its own option on the plugin settings screen, in the Visitor data group of the Page variables section. All of them are switched off by default, so if a variable is missing from your data layer, check its option first.

This page describes GTM4WP 2.1.0. Features added by 2.0.0 are marked New in 2.0.0. Where an older version behaves differently, its behavior is marked with a bold GTM4WP 2.0.x: or GTM4WP 1.x: lead-in.

GTM4WP 1.x: the same options lived in the Basic data tab of the settings screen.

visitorLoginState

The Logged in status option adds this variable. The value logged-in means that someone is signed in to your site, whatever their role, and logged-out means that the visitor is anonymous.

visitorId

The internal WordPress ID of the logged in user, as a number, added by the Logged in user ID option. Its main use is User-ID tracking, which lets the tools that support it join the sessions of one person across several devices.

When nobody is logged in, this variable is left out of the data layer, even with the option enabled. Build your Google Tag Manager triggers so that they cope with a variable that is not present.

visitorType

The role of the logged in user, for example administrator or editor, added by the Logged in user role option. A user who has more than one role is reported with all of them in a single string, separated by commas. When nobody is logged in, the value is visitor-logged-out.

visitorUsername

The login name of the logged in user, added by the Logged in user name option. This is the name typed on the login screen, not the display name shown on the site, and the two can differ.

visitorEmail and visitorEmailHash

Both come from the Logged in user email option. visitorEmail holds the email address of the logged in user, and visitorEmailHash holds the SHA-256 hash of the same address as a lowercase hexadecimal string. Advertising platforms usually ask for the hashed form when you send them customer data along with a conversion, so use visitorEmailHash wherever the receiving tag accepts it.

Before hashing, the address is converted to lowercase and spaces are removed. For gmail.com and googlemail.com addresses the dots before the @ sign are removed as well, together with a plus sign and everything after it: for these two domains, J.Doe+news and jdoe before the @ sign give the same hash.

GTM4WP 2.0.x: the address was hashed exactly as WordPress stores it. For addresses with capital letters and for Gmail addresses with dots or a plus sign, hashes collected before the upgrade do not match the new ones.

With this option enabled, the plain email address of every logged in user is written into the HTML of the page they are viewing.

visitorRegistrationDate

The moment the account of the logged in user was created, added by the Logged in user creation date option. The value is a Unix timestamp. Use it to tell long standing members apart from people who registered recently.

What the user variables hold for anonymous visitors

When nobody is logged in, visitorLoginState reads logged-out and visitorType reads visitor-logged-out. visitorId, visitorUsername, visitorEmail, visitorEmailHash and visitorRegistrationDate are left out of the data layer. They are also left out for a logged in user whose account has no value for them.

GTM4WP 2.0.x: only visitorId was left out. visitorUsername, visitorEmail, visitorEmailHash and visitorRegistrationDate were added with an empty value. Review any trigger that checks these variables for an empty value.

visitorIP

The IP address of the current visitor, added by the Visitor IP option for logged in users and anonymous visitors alike. The plugin reads the address from the REMOTE_ADDR server variable, which is the address the web server itself saw, and validates it before adding it to the data layer.

Addresses in the private and reserved ranges are rejected, so the variable is left out of the data layer on a local development site and on any site whose web server reports an internal address instead of the address of the visitor. That is the usual situation behind a reverse proxy or a CDN, and the second option, Visitor IP – Read from custom header, exists for it. Enter the name of the single HTTP header that your proxy sets, for example X-Real-IP or CF-Connecting-IP. Write it as the header name, the plugin translates it into the matching server variable itself. If that header is missing or holds no valid public address, the plugin falls back to REMOTE_ADDR.

If you enter X-Forwarded-For, the plugin reads the comma separated list of addresses in it. Without trusted proxy addresses it uses the first valid public one; with them, it reads the list as described below.

Only name a header that your proxy or CDN overwrites on every request. A header that reaches WordPress unchanged from the browser can be set to any value by the visitor, and the address in your data layer would then be whatever the visitor chose. For the same reason the plugin does not walk through a list of proxy headers on its own, as it did in much older versions. It reads REMOTE_ADDR and the one header you name, nothing else.

New in 2.0.0. The third option, Visitor IP – Trusted proxy addresses, makes the header trustworthy. List the IP addresses or CIDR ranges of the reverse proxies, load balancers and CDNs in front of your site, one per line or separated by commas. Cloudflare publishes its ranges at cloudflare.com/ips. With the list filled in, the plugin uses the header only when the request arrived from one of these addresses, and otherwise falls back to REMOTE_ADDR. An X-Forwarded-For list is then read from the right: your own proxies are skipped, and the first address that is not one of them is taken as the address of the visitor. Without the list, the header is read as described above, and an admin notice reminds you that its value cannot be verified. Leave the list empty, and do not name a header at all, when nothing sits in front of your site.

The same list also decides when the Cloudflare country code is read, as described under Geo data of the visitor below.

GTM4WP 2.0.x: when no valid public address could be found, visitorIP was added with an empty value instead of being left out.

Cache-safe data layer

New in 2.0.0. Every variable on this page describes one particular visitor, so on a site with full page caching they would end up in HTML that is then served to everyone. The Cache-safe data layer option, which has a panel of its own on the settings screen, keeps them out of the cached HTML. With the option enabled, the same values are delivered in the browser instead, under the same names, in a single data layer push that carries the event name gtm4wp.visitorData.

The visitor IP is requested once per session and the user data only when the login state changes, from a first party endpoint that returns the data of the current visitor and nothing else. An anonymous visitor never receives user data.

Two things change for your Google Tag Manager setup:

The values arrive after the page has loaded, not in the first data layer push. Tags that read them need a trigger on the gtm4wp.visitorData custom event instead of a Page View trigger.
Variables that have no value for the current visitor are left out rather than sent empty. An anonymous visitor receives no login state, no role, no username, no email address and no registration date at all, so the logged out values described above are not delivered in this mode.

The option is off by default and is marked experimental. While it is off, the data layer works exactly as described on the rest of this page.

Geo data of the visitor

The Cloudflare country code option sits in the same group on the settings screen and adds the geoCloudflareCountryCode variable. It is described on the geo data page, together with the other geo variables.