(c) 2013 by Search Discovery
airlock.js may be freely distributed under the MIT license.
For all details and documentation: http://www.searchdiscovery.com/airlock
Airlock is a JavaScript library that automatically turns your asynchronous Google Analytics calls into Universal Analytics calls, lifting the burden of having to re-tag your entire site when upgrading to Universal Analytics.
In order to utilize Airlock you must first upgrade your classic Google Analytics property to Universal Analytics. In your Google Analytics admin panel under the "Property" column you will see an option for "Universal Analytics Upgrade." Select the "Transfer" button to complete the upgrade request.
It may take up to 48 hours to complete the upgrade to Universal Analytics. Do not install Airlock until this upgrade is complete. After your upgrade is complete, your classic Google Analytics code will continue to send data to your property reports. Install Airlock to receive the full benefits of Universal Analytics.
If you have the Bower package manager installed on your system, you can install Airlock from the command line.
bower install airlock --save
This command will clone the latest version of Airlock into your Bower components directory and will specify Airlock as a dependency in your bower.json file, if you have created one.
Download and extract the latest zip package from Github and copy airlock.js and airlock.min.js into your project, then include them using the method specified below that is appropriate for your analytics installation.
Once your property has been successfully transferred to Universal Analytics, it is time to deploy the code on your site.
To upgrade a vanilla Google Analytics installation on a site not using a tag management system, simply replace the standard Google Analytics asynchronous script include with a reference to your local Airlock file.
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-XXXXX-X']);
_gaq.push(['_trackPageview']);
// Remove this:
// (function() {
// var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
// ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
// var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
// })();
</script>
<!-- and add this: -->
<script type="text/javascript" src="[INSERT YOUR PATH]/airlock.min.js"></script>That’s it! Everything else (even the inclusion of the new Universal Analytics JavaScript file) is handled by Airlock.
Adobe DTM implements Airlock natively. To enable Airlock in DTM, go to the settings page for your classic Google Analytics tool (via the gear icon) and check the box labeled "Translate Google Analytics calls to Universal Analytics."
Save, approve, and publish the settings. Once this is done, Airlock is successfully installed on your DTM property.
In your Google Tag Manager account container, create a new tag. Select "Custom HTML Tag" as the tag type. Add the Airlock JavaScript code to the HTML input box (since GTM is expecting HTML here, be sure to use a <script> tag referencing your local Airlock, or paste the Airlock code enclosed within <script> tags).
Click the "Add Rule To Fire Tag" button and select the "All Pages" rule.
Click "Save" and then save again. Preview, test, and publish your update. That's it!
When loaded onto the page, Airlock checks for the presence of an _airlock object in the global namespace. If Airlock finds the object, it will be used to configure your Airlock setup.
var _airlock = {
// your settings
};Universal Analytics has a debug version of analytics.js that outputs verbose logging to the console. To load this version instead of the default, set _airlock.debug = true;.
Universal Analytics allows implementors to choose a custom namespace for the Universal Analytics library (it defaults to ga). To choose a custom namespace, set _airlock.gaNamespace = 'yourCustomNamespace';.
By default, Airlock will map GA custom variable slot numbers to UA dimension numbers, thus _gaq.push(['_setCustomVar', 2, 'name', 'value']); will translate to ga("set", "dimension2", "value");
If you need to override this default behaviour, you can map slot numbers or custom variable names to dimension numbers using the _airlock.dimensionMap property:
_airlock.dimensionMap = {
"2": 1 // customVar in slot 2 will map to "dimension1"
'varName': 2 // customVar with name "varName" will map to "dimension2"
}By default, Airlock will initialize itself automatically. If you need to prevent this in order to initialize at a later time, simply set _airlock.autoInit = false;, then call Airlock.initialize() when ready.
In most situations, implementors will want to let Airlock load Universal Analytics. In special cases, however, users may want to load the Universal Analytics library on their own.
If analytics.js is loaded prior to Airlock, Airlock will not load UA again. However, if you need to load Airlock before UA is loaded and want to intialize analytics.js yourself, you can set _airlock.loadUA = false;.
By default the Airlock object is not exposed to the global namespace (unless autoInit is disabled). If you need to access the Airlock object, set _airlock.expose = true;.
Airlock needs no modification to work seamlessly with the great majority of GA installs. However, if you need to add or modify a procedure for translating a particular type of _gaq.push() call, you can do this by creating and setting conversion procedures on the _airlock.conversions object.
When Airlock receives _gaq.push() calls, it grabs the first argument and checks Airlock.conversions to see if there is a conversion procedure matching that key. Any procedures set on _airlock.conversions will override default conversion procedures on Airlock.conversions. Thus, if you want to override the default behavior of _gaq.push(['_trackSocial'/*, ...*/]); calls, you would set a _trackSocial property on _airlock.conversions.
Conversion procedures can be functions or template objects.
Functions receive _gaq.push() arguments indexed > 0. If an array is returned, ga() will be called using the array members as its arguments.
Conversion template objects contain an input and an output array. The input array contains the keys by which _gaq.push() arguments are indexed. The output array is a template of the arguments that will be passed to ga(). This array's members can either be plain strings, template strings (e.g., "dimension[[slot]]", which will output the string "dimension" concatenated with the value of the slot input key), or a function, which will receive as an argument an object containing the indexed input variables, and whose return value will be the value of the output index at which the function was declared.
Airlock is AMD compatible.