There are many tools and methods to make Google Analytics<\/a> more manageable. Google Tag Manager<\/a> is probably the best known of these, and you can find many, many articles about GTM<\/a> on these pages as well.<\/p>\n However, today I want to tell you about one of the features of Universal Analytics that hasn\u2019t, as far as I know, received too much attention. It\u2019s funny, because at the same time almost everyone uses the feature in the shape of eCommerce<\/a>, enhanced link attribution<\/a>, and cross-domain tracking<\/a>. I\u2019m talking, of course, about Universal Analytics plugins<\/strong>.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n Plugins are JavaScript objects, which you can load and execute using the Universal Analytics global object interface<\/a>. This is accessed, by default, using the Plugins allow you to do a number of useful things:<\/p>\n Decouple tracker object access from JavaScript embedded in the page HTML, allowing you to crete, execute, and maintain often used Quickly access the tracker object of choice, without having to prefix every command with the tracker name, or to loop through all the existing trackers to find the correct one<\/p>\n<\/li>\n Execute the plugin commands synchronously<\/em>, which means you can be 100 % sure that anything the plugin does will be available to commands that come after it in the command queue<\/p>\n<\/li>\n<\/ol>\n All the benefits listed above facilitate a plug-and-play integration between a platform and Google Analytics. If you\u2019re the developer of the platform, you can create a plugin that does most of the legwork, such as assigning a new Custom Dimension with its respective value, and the user only has to load the plugin to reap the benefits.<\/p>\n \n \n Subscribe to the Simmer newsletter<\/a> to get the latest news and content from Simo Ahava into your email inbox!\n <\/p>\n <\/span><\/p>\n Before getting into a technical description of plugins themselves, there\u2019s something we need to clear up about the Universal Analytics tracker object first. Here\u2019s a typical tracking code on a typical website:<\/p>\n If you want to understand what the code above does statement by statement, this<\/a> and this<\/a> are good places to start.<\/p>\n What\u2019s important, however, is that the analytics.js<\/em> library is loaded asynchronously<\/em>. The loading starts when the immediately invoked function expression (IIFE) is executed, but the browser\u2019s JavaScript engine moves right to the two <\/p>\n <\/a><\/p>\n<\/div>\n This, in turn, has a significant implication on what you can do with the code. Consider the following example:<\/p>\n If you know your tracker methods, you\u2019ll see that this attempts to send the clientId<\/strong> of the tracker object as a Custom Dimension with the page view hit.<\/p>\n This code will, however, result in the error: ga.getAll is not a function<\/strong>. The reason for this error is due to the library not having loaded yet when the JavaScript engine processes the command in the There are two ways to overcome this. You can pass a callback function as an argument<\/a> to the When you call the Even though the tracker interface is not available when the \u2018require\u2019 command is added to the queue, the interface will<\/em> be available once the queue is being processed.<\/p>\n Let\u2019s create the getClientId<\/strong> plugin from the previous chapter. The plugin code itself consists of two<\/strong> required components:<\/p>\n A constructor<\/strong> that is executed when the plugin is loaded<\/p>\n<\/li>\n A \u2018provide\u2019<\/strong> command that links the constructor with the plugin name<\/p>\n<\/li>\n<\/ol>\n To create the plugin getClientId<\/strong>, you would need something like the following code loaded on the page:<\/p>\n The first lines are for the constructor. It\u2019s just a JavaScript function, but it turns into an object constructor with the If object-oriented JavaScript confuses you, take a look at the excellent JavaScript track at codecademy<\/a>.<\/p>\n Anyway, the tracker object used in the call to the constructor is automatically passed as an argument to the function. This means that you can run commands on the tracker object, and you don\u2019t have to worry about interacting with the right tracker or sending the hits to the right Google Analytics property.<\/p>\n The next lines first make sure that the Finally, the To briefly recap, here is how plugins are loaded and linked to trackers:<\/p>\n The Universal Analytics tracking snippet creates the All function calls to If you have a plugin, both its \u2018require\u2019 and \u2018provide\u2019 calls will be added to the queue as well<\/p>\n<\/li>\n Once the analytics.js<\/em> library has loaded, the commands in the queue are processed in order<\/p>\n<\/li>\n If a \u2018require\u2019 command is encountered, the queue processing halts indefinitely, until a \u2018provide\u2019 call with the same plugin name is run<\/p>\n<\/li>\n The entire plugin constructor function is executed before queue processing continues<\/p>\n<\/li>\n<\/ol>\n Below is an example of the loading order in action. The plugin \u2018require\u2019 call is between the \u2018create\u2019 and \u2018send\u2019 calls, and the library itself is loaded after the Universal Analytics tracking code snippet. This is to secure that the Note that the \u2018require\u2019 command waits for the respective \u2018provide\u2019 command indefinitely<\/em>. This means that if you misspell the plugin name, or if you only have the \u2018require\u2019 command there for some reason, the queue processing will not proceed<\/em>. So try to avoid breaking your analytics implementation, please!<\/p>\n Here\u2019s an example of a plugin I might be tempted to use over and over again. In it, I have two special features:<\/p>\n A generic event pusher<\/strong>, which I can use with all my trackers to send events to their respective properties<\/p>\n<\/li>\n A hit duplicator<\/strong>, which duplicates the hit to the Universal Analytics collection endpoint, and sends it as an HTTP request to any custom endpoint of my choice<\/p>\n<\/li>\n<\/ol>\n I\u2019m storing the plugin in a file called simoPlugin.js<\/strong>, which I then load asynchronously after my tracking code:<\/p>\n As you can see, I have my normal tracker and a tracker with the name rollup<\/strong>, and I\u2019m loading the plugin for both trackers using the typical multiple tracker<\/a> syntax.<\/p>\n The way the hit duplicator<\/strong> works is that whenever a \u2018send\u2019 command is used, e.g. <\/p>\n <\/a><\/p>\n<\/div>\n By duplicating hits like this, you can create your own data collection mechanism. You can even use a cloud endpoint, which will give you a lot more processing power and scale. You might even use this to overcome the schema conspiracy<\/a> I\u2019ve been ranting about before.<\/p>\n The generic event pusher<\/strong> works by sending a custom event object to a plugin method called As you can see, an object literal is passed as the second argument of the The code stored in the simoPlugin.js<\/strong> library looks like this:<\/p>\n![\"Universal](\"https:\/\/www.simoahava.com\/images\/2015\/04\/universal-analytics-plugins.jpg#ZgotmplZ\")
<\/p>\nga()<\/code> function.<\/p>\n\n
ga()<\/code> commands in library files instead of directly in the page<\/p>\n<\/li>\n
\n X<\/span><\/p>\n
\n The Simmer Newsletter<\/strong>\n <\/p>\nHow plugins work<\/h2>\n
script>\n (function<\/span>(i,s,o,g,r,a,m){i['GoogleAnalyticsObject'<\/span>]=r;i[r]=i[r]||function<\/span>(){\n (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1<\/span>*new<\/span> Date<\/span>();a=s.createElement(o),\n m=s.getElementsByTagName(o)[0<\/span>];a.async=1<\/span>;a.src=g;m.parentNode.insertBefore(a,m)\n })(window<\/span>,document<\/span>,'script'<\/span>,'\/\/www.google-analytics.com\/analytics.js'<\/span>,'ga'<\/span>);\n\n ga('create'<\/span>, 'UA-1234567-1'<\/span>, 'auto'<\/span>);\n ga('send'<\/span>, 'pageview'<\/span>);\n\nscript<\/span>><\/code><\/pre>\n<\/div>\nga()<\/code> commands before the analytics.js library has loaded<\/em>. This means that the two ga()<\/code> calls are not actually interacting with analytics.js<\/em>, but instead they are pushing commands into a command queue<\/em>, which is processed first-in first-out as soon as the library has loaded.<\/p>\n![\"The](\"https:\/\/www.simoahava.com\/images\/2015\/04\/process.jpg#ZgotmplZ\")
<\/p>\nscript>\n...the IIFE here...\n\nga('create'<\/span>, 'UA-1234567-1'<\/span>, 'auto'<\/span>);\nga('send'<\/span>, 'pageview'<\/span>, {\n 'dimension1'<\/span> : ga.getAll()[0<\/span>].get('clientId'<\/span>)\n});\nscript<\/span>><\/code><\/pre>\n<\/div>\nga()<\/code> call. It\u2019s the analytics.js<\/em> library that sets up the interface for the global object, not the tracking code.<\/p>\nga()<\/code> call, and any code within that function will not be executed until the library has loaded. The second method would be to use a plugin<\/strong>.<\/p>\nga('require', 'pluginName')<\/code> method, this request is added to the command queue. When the analytics.js<\/em> library has finally loaded, the command queue will be processed in order. Once the processing reaches this \u2018require\u2019 command, the queue will halt until a \u2018provide\u2019 call with the same plugin name is found in or added to the queue. This means that the following code would work nicely:<\/p>\nscript>\n...the IIFE here...\n\nga('create'<\/span>, 'UA-1234567-1'<\/span>, 'auto'<\/span>);\n\/\/ Load the getClientId plugin, which gets the\n<\/span>\/\/ clientId and sets it as dimension1 on following hits\n<\/span>ga('require'<\/span>, 'getClientId'<\/span>);\nga('send'<\/span>, 'pageview'<\/span>);\nscript<\/span>><\/code><\/pre>\n<\/div>\nHow to create a plugin<\/h2>\n
\n
var<\/span> GetClientId = function<\/span>(tracker) {\n tracker.set('dimension1'<\/span>, tracker.get('clientId'<\/span>));\n};\nvar<\/span> ga = window<\/span>[window<\/span>['GoogleAnalyticsObject'<\/span>] || 'ga'<\/span>];\nif<\/span> (ga) {\n ga('provide'<\/span>, 'getClientId'<\/span>, GetClientId);\n}\n<\/code><\/pre>\n<\/div>\nga('require', 'getClientId')<\/code> call, which creates a new object instance of GetClientId<\/code>.<\/p>\nga()<\/code> command exists. The ga()<\/code> function is created in the Universal Analytics tracking snippet, so if your plugin code is executed before<\/em> the browser parses the tracking snippet, it might not work.<\/p>\nga('provide', 'pluginName', Constructor)<\/code> command is run so that the plugin can be found with its respective \u2018require\u2019 call.<\/p>\n\n
ga()<\/code> function and the command queue<\/p>\n<\/li>\nga()<\/code> are added to this command queue<\/p>\n<\/li>\nga()<\/code> function is created before the plugin.<\/p>\nscript>\n...the function<\/span> expression here...\n\nga('create'<\/span>, 'UA-1234567-1'<\/span>, 'auto'<\/span>);\nga('require'<\/span>, 'getClientId'<\/span>);\nga('send'<\/span>, 'pageview'<\/span>);\nscript<\/span>>\nscript src<\/span>=\"https:\/\/www.simoahava.com\/scripts\/getClientId.js\"<\/span> async<\/span>>script<\/span>><\/code><\/pre>\n<\/div>\nExample: SimoPlugin library<\/h2>\n
\n
script>\n...the IIFE here...\n\nga('create'<\/span>, 'UA-1234567-1'<\/span>, 'auto'<\/span>);\nga('create'<\/span>, 'UA-1234567-2'<\/span>, 'auto'<\/span>, {'name'<\/span> : 'rollup'<\/span>});\nga('require'<\/span>, 'simoPlugin'<\/span>);\nga('rollup.require'<\/span>, 'simoPlugin'<\/span>);\nga('send'<\/span>, 'pageview'<\/span>);\nga('rollup.send'<\/span>, 'pageview'<\/span>);\nscript<\/span>>\nscript src<\/span>=\"https:\/\/www.simoahava.com\/scripts\/simoPlugin.js\"<\/span> async<\/span>>script<\/span>><\/code><\/pre>\n<\/div>\nga('send', 'pageview')<\/code>, the exact payload to the Universal Analytics endpoint is copied and sent to a (fictional) endpoint of mine at _http:\/\/process.simoahava.com\/collect_:<\/a><\/p>\n![\"Hit](\"https:\/\/www.simoahava.com\/images\/2015\/04\/local-copy.jpg#ZgotmplZ\")
<\/p>\ntrackEvent<\/code>:<\/p>\nga('simoPlugin:trackEvent'<\/span>, {\n 'cat'<\/span> : 'Link Click'<\/span>, \n 'act'<\/span> : 'Outbound'<\/span>, \n 'lab'<\/span> : 'http:\/\/www.google.com'<\/span>, \n 'di'<\/span> : 4<\/span>, \n 'dv'<\/span> : document<\/span>.location.pathname\n});\n<\/code><\/pre>\n<\/div>\nga()<\/code> call. This argument, in turn, is passed to the trackEvent<\/code> method in the plugin code. The method takes the arguments, makes sure no undefined fields are sent, and pushes an event hit to the property associated with the tracker that was used to call the plugin method. If I wanted to send the call to my rollup<\/em> tracker, I would have used the syntax ga('rollup.simoPlugin:trackEvent')<\/code>.<\/p>\nsimoPlugin code<\/h3>\n
(function<\/span>() {\n\n \/\/ Assign the ga variable to the Google Analytics global function\n<\/span> var<\/span> ga = window<\/span>[window<\/span>['GoogleAnalyticsObject'<\/span>] || 'ga'<\/span>];\n\n \/\/ Helper function for registering the Plugin\n<\/span>