The default JavaScript tracking snippet for Google Analytics allows sites to track various user interactions. Every time an user interacts with your site and it results in data being sent to Analytics (i.e. pageview), a payload is composed by analytics.js with standard & supplementatal data fields about the user intereraction. This is known as a Hit, and several Hit Types exist. As your organization's analytics practices evolve, you may need to analyze all hit data in more nuanced and robust ways, specially outside of Google Analytics. Thus, GA Autotrack IDs was created to conveniently enhance the standard hit data collected by analytics.js. It provides default tracking to add Hit, Session & GA Client IDs, as well as a timestamp to every Hit.
The ga-autotrack-ids.js file in this repository is small (1.6K gzipped) and comes with all plugins included. You can use it as is, or you can create a custom build that only includes the plugins you want to make it even smaller.
The following table briefly explains what each plugin does; you can click on the plugin name to see the full documentation and usage instructions:
| Plugin | Description |
|---|---|
hitIdTracker |
Automatically generate a tiny, secure URL-safe UUID for every hit. |
clientIdTracker |
Store the GA Anonimized client id in a Custom Dimension. |
sessionIdTracker |
Automatically generate a tiny, secure URL-safe UUID for every session and/or pass your own session id to be stored. |
hitTimestrampTracker |
Capture and store the current timestamp for every hit |
Disclaimer: GA Autotrack IDs is not in anyway associated with Google or Google Analytics, and is primarily intended for a developer audience. It is not an official Google Analytics product and does not qualify for Google Analytics 360 support. Developers who choose to use this library are responsible for ensuring that their implementation meets the requirements of the Google Analytics Terms of Service and the legal obligations of their respective country.
To add autotrack to your site, you have to do two things:
- Load the
ga-autotrack-id.jsscript file included in this repo (or a custom build) on your page. - Update your tracking snippet to require the various autotrack plugins you want to use on the tracker.
If your site is currently using the default JavaScript tracking snippet, you can modify it to something like this:
<script>
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-XXXXX-Y', 'auto');
// Replace the following lines with the plugins you want to use.
ga('require', 'clientIdTracker');
ga('require', 'sessionIdTracker');
// ...
ga('send', 'pageview');
</script>
<script async src="https://www.google-analytics.com/analytics.js"></script>
<script async src="path/to/ga-autotrack-ids.js"></script>Of course, you'll have to make the following modifications to the above code to customize autotrack to your needs:
- Replace
UA-XXXXX-Ywith your tracking ID - Replace the sample list of plugin
requirestatements with the plugins you want to use. - Replace
path/to/ga-autotrack-ids.jswith the actual location of thega-autotrack-ids.jsfile hosted on your server.
Note: the analytics.js plugin system is designed to support asynchronously loaded scripts, so it doesn't matter if ga-autotrack-ids.js is loaded before or after analytics.js. It also doesn't matter if the ga-autotrack-ids.js library is loaded individually or bundled with the rest of your JavaScript code.
If you use npm and a module loader that understands ES2015 imports (e.g. Webpack, Rollup, or SystemJS), you can include ga-autotrack-ids in your build by importing it as you would any other npm module:
git clone [email protected]:anki/ga-autotrack-ids.git
cd ga-autotrack-ids
npm install -g// In your JavaScript code
import 'ga-autotrack-ids';Note: ga-autotrack-ids's source is published as ES2015, and you will need to make sure you're not excluding it from compilation.
The above import statement will include all autotrack plugins in your generated source file. If you only want to include a specific set of plugins, you can import them individually:
// In your JavaScript code
import 'ga-autotrack-ids/lib/plugins/client-id-tracker';
import 'ga-autotrack-ids/lib/plugins/hit-id-tracker';
import 'ga-autotrack-ids/lib/plugins/session-id-tracker';The above examples show how to include the autotrack plugin source in your site's main JavaScript bundle, which accomplishes the first step of the two-step installation process. However, you still have to update your tracking snippet and require the plugins you want to use on the tracker.
// Import just the plugins you want to use.
import 'ga-autotrack-ids/lib/plugins/client-id-tracker';
import 'ga-autotrack-ids/lib/plugins/hit-id-tracker';
import 'ga-autotrack-ids/lib/plugins/session-id-tracker';
ga('create', 'UA-XXXXX-Y', 'auto');
// Only require the plugins you've imported above.
ga('require', 'hitIdTracker');
ga('require', 'clientIdTracker');
ga('require', 'sessionIdTracker');
ga('send', 'pageview');Note that it's generally not a good idea to include any analytics as part of your site's main JavaScript bundle since analytics are not usually critical application functionality.
If you're using a bundler that supports code splitting (via something like System.import()), it's best to load autotrack plugins lazily and delay their initialization until after your site's critical functionality has loaded:
window.addEventListener('load', () => {
const autotrackPlugins = [
'autotrack/lib/plugins/hit-id-tracker',
'autotrack/lib/plugins/hit-timestamp-tracker',
'autotrack/lib/plugins/client-id-tracker',
// List additional plugins as needed.
];
Promise.all(autotrackPlugins.map((x) => System.import(x))).then(() => {
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'hitIdTracker', {...});
ga('require', 'hitTimestampTracker', {...});
ga('require', 'clientIdTracker', {...});
// Require additional plugins imported above.
ga('send', 'pageview');
});
})If you're not sure how do use code splitting with your build setup, see the custom builds section to learn how to manually generate a custom version of autotrack with just the plugins you need.
All ga-autotrack-ids plugins take a configuration object with required options as the third parameter to the require command.
See the individual plugin documentation to reference what options each plugin accepts and/or requires.
GA Autotrack IDs comes with its own build system, so you can create bundles containing just the plugins you need. Once you've installed autotrack via npm, you can create custom builds by running the ga-autotrack-ids command.
For example, the following command generates an ga-autotrack-ids.js bundle and source map for just the hitIdTracker, and hitTimestampTracker plugins:
ga-autotrack=ids -o path/to/ga-autotrack-ids.custom.js -p hitIdTracker,hitTimestampTrackerOnce this file is generated, you can include it in your HTML templates where you load analytics.js. Note the use of the async attribute on both script tags. This prevents analytics.js and ga-autotrack-ids.custom.js from interfering with the loading of the rest of your site.
<script async src="https://www.google-analytics.com/analytics.js"></script>
<script async src="path/to/ga-autotrack-ids.custom.js"></script>All autotrack plugins support multiple trackers and work by specifying the tracker name in the require command. The following example creates two trackers and requires various autotrack plugins on each.
// Creates two trackers, one named `tracker1` and one named `tracker2`.
ga('create', 'UA-XXXXX-Y', 'auto', 'tracker1');
ga('create', 'UA-XXXXX-Z', 'auto', 'tracker2');
// Requires plugins on tracker1.
ga('tracker1.require', 'hitIdTracker');
ga('tracker1.require', 'hitTimestampTracker');
// Requires plugins on tracker2.
ga('tracker2.require', 'hitIdTracker');
ga('tracker2.require', 'hitTimestampTracker');
ga('tracker2.require', 'clientIdTracker');
// Sends the initial pageview for each tracker.
ga('tracker1.send', 'pageview');
ga('tracker2.send', 'pageview');