How does analytics.js work?

All calls to the Analytics.js library are done exclusively by the aa() function . This document explains the use and role of this function.

Note: The name of the global function aa() can be changed in the tracking code, in which case you must use this new name to communicate with analytics.js.

The AFS analytics.js library uses the same structure provided by Google Analytics to simplify its use for former GA users.

The aa command queue

The function aa() defined in the JavaScript tracking snippet, adds in a queue all the commands sent to the library analytics.js prior to its downloading. Once analytics.js is loaded, the pending commands are executed and the list flushed. Then the function aa() is changed by a new version available in analytics.js.

Show queue before loading analytics.js

All calls to aa() are saved in the aa.q array. To view the contents of the queue before the loading of the library, you can display the q array:


console.log(aa.q);
Outputs (q array):
[
   ['create', 'XXXXXXXX', 'auto'],
   ['send', 'pageview']
]

Why use a queue?

The queue allows the use of the aa() function without having to worry about the download status of the library. Also, it ensures operation in asynchronous mode without any loss of data.

Adding commands to the queue

All calls to the aa() function share the same structure composed of two minimum arguments. The first is the command to execute, the following defines the arguments attached to the command.

In the call: aa('create', 'XXXXXXXX', 'auto'); Create is the command, xxxxxxxx and auto are the arguments to apply to this command.

A tracker name can be defined with the create command. In this case, if there are several trackers, the send and set commands must be preceded by the name of the tracker (followed by a dot) in order to address the tracker. If no name is defined, only the first tracker, named or not, will be affected by the command.

Example of creating and addressing a named tracker:


aa("create", "XXXXXXXX",auto, "mytracker") ;
aa("mytracker.send","pageview") ;

Note: If the aa() function receives an unknown command, it will be ignored and no error will be generated.

The arguments attached to the command.

Arguments related to a command can be sent in several formats to facilitate the transmission of the most used fields.

Simplified call:

In the following example, field names do not appear because they are determined based on the position of the arguments in the function.


aa('create', 'XXXXXXXX', 'auto');
aa('send', 'pageview','titleindex' , 'home page', 'https://www.mysite.com');

The create command accepts the trackingId, CookieDomain, and other optional fields such as name, callback or params. The send command accepts various parameters depending on the send type defined by hitType. For example, for pageview, the fields page, title, location, hitCallback and params can be filled in. AFS Analytics also accepts the url, index, callback fields as an alternative to the location, page and hitCallback fields.

Call with an object:

All commands can accept one or more objects that define the different fields. The previous code could be written this way.


aa('create', {
trackingID : 'XXXXXXXX' ,
cookieDomain : 'auto'
}) ;
aa('send', {
hitType: 'pageview',
page: 'titleindex' 
title :'home page',
location :'https://www.mysite.com' 
});

The next step

Reading this guide has taught you how the command queue works and how to use the aa() function provided by analytics.js.

The next guide will cover the creation of trackers: How to create a tracker?

By AFS Analytics, Sunday, April 30, 2017