51Degrees WordPress plugin for developers

Advanced uses of our Optimize by Device & Location plugin

The 51Degrees Optimize by Device & Location WordPress plugin is designed to decorate all incoming requests (as dispatched to Google Analytics) with extra information about the request. The information is derived from our detailed Device Detection and Geolocation Pipeline APIs.

There is documentation for the plugin available, and the companion 51Degrees plugin for marketers blog explains how to use the extra information gathered by the plugin. In this blog, we have additional developer documentation and advanced uses aimed at the web development team.

Using 51Degrees additional information on client and server side

Since the plugin fetches additional information on the requesting device and location, that information can be used by your code.

To begin, you will need to choose which properties you wish to fetch information on. A full list is available with detailed descriptions in our property dictionary. From there, you will need to create a Resource Key with your chosen properties.

Whichever properties you have created a Resource Key for are available to your code in content, server-side PHP, or client-side JavaScript: the Properties page in the plugin settings lists the ways to access them.

For example, in PHP theme or plugin code, use Pipeline::get("device", "browserreleaseage") to access a BrowserReleaseAge property.

In content, a similar WordPress shortcode is automatically created: {Pipeline::get("device", "browserreleaseage")}.

WordPress have their own list of pre-defined shortcodes, which perform a particular function on the site. For example, a shortcode can be used to embed a form onto your page. Or in our case, a 51Degrees shortcode can be used to display the current value of any property specific to this request.

So, the {Pipeline::get("device", "browserreleaseage")} shortcode when used on a page will display the BrowserReleaseAge for the device used to access the page. For more information on using shortcodes in content blocks, Kinsta have a detailed walkthrough.

Additionally, client-side code provides window.fod.complete as a callback listener which receives a data object:


window.onload = function() {
    window.fod.complete(function(data) {
        console.log(data.device.browserreleaseage);
    });
}

This can also be used to integrate with other client-side analytics platforms, such as decorating event requests with this data after fod.complete fires.

How the plugin integrates itself

The standard Google Analytics JavaScript code to add a Universal Analytics (UA) property creates an object named dataLayer and passes it to the Analytics object, exactly because it makes it possible to integrate with that object. The code will look something like this:


window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-xxxxxx-x');

The WordPress plugin uses the 51Degrees Pipeline API to gather the information you requested about the device and location, in order to hand it to Google Analytics as a custom dimension.

To set a custom dimension value in a UA property requires setting the custom_map property on a request to Google Analytics. The plugin does this dynamically for each request by examining the window.dataLayer object to see if it already exists or creating it if not.

This makes it possible for your team to augment that further if required. If you already have extra information being integrated into Google Analytics requests or are using one of the many WordPress plugins to augment Google Analytics tracking, the 51Degrees WordPress plugin should seamlessly work with whatever you're doing.

Configuring custom dimension naming

When you synchronize your Google Analytics to the 51Degrees WordPress plugin, custom dimensions are automatically added from the properties in your Resource Key.

The plugin will automatically create suitable names for each tracked extra property, which will look something like 51d.device.browserreleaseage. For ease, all custom dimensions added by the 51Degrees plugin will always be prefixed with 51D.

For advanced users, you may prefer to change the name of the 51Degrees custom dimensions. For example, you may wish to record the 51Degrees data into a set of custom dimensions that already exist in your analytics report, merging the two.

The ‘Google Analytics’ screen in the plugin settings permits this. Change the ‘Custom Dimension Name’ for a property to one which you prefer and click ‘Update Custom Dimension Mappings’.

Note that the names of available custom dimensions are only recorded when first authorizing the plugin with your Google Analytics account. If you manually change or add to the list of custom dimensions in your Google Analytics property subsequently then you should remove the authorization ('Disable Google Analytics Tracking') and re-authorize.

Additional information

One important thing to note is that the plugin currently supports Universal Analytics (UA) properties in Google Analytics; it does not support the new GA4 properties. We are planning to work on this integration in the future.

For more information on how to get started with our Optimize by Device & Location plugin, check out our WordPress documentation. For more information on how to use the plugin and benefit from real-time data, check out our WordPress blogs.