Tag Setup

Overview

The MyData tag feature of PivotBillions is a Javascript based Web tracking service. Simply embed a small Javascript code block into your web pages to collect tracking data.

Tracking data is stored in the cloud (S3). You can access and analyze your data by logging into your account on the PivotBillions portal.

By default, MyData generates one log event (i.e., one log record) per web page. It is triggered when a page is loaded initially. Additional logs can be generated by calling a Javascript function. This function provides more tracking features such as adding a custom query and/or adding arbitrary data to the log. You can even disable the default tag so that each log can be customized individually.

Basic Setup

To start tracking, simply add the default code block shown on your PivotBillions portal to the pages you want to track. It will generate a single log event automatically. The block can be placed anywhere in the web page. But if you manually call the tag function aqobj.tag() on your page, the code block must be loaded before any of the calls.

The code block has this form, where AQID should be replaced with the value assigned to you when you signed up.

<script> 
(function(s,a,f=""){ 
var d=document, p=s.match(/^([^/]+)(.*\/)([^/]+)\.js$/), k; 
if (typeof f != "object") f = { fg:f }; if (typeof f.fg != "string") f.fg = ""; 
if (!p || window[k = p[3]]) return; 
window[k] = { a:a, f:f, p:p, q:[], tag:function(){ this.q.push(arguments); } }; 
k = d.createElement("script"); 
k.src = "https://" + s + "/0" + f.fg + "/" + a + "?1=" + (localStorage.aqusr || (d.cookie.match(/(^|; ?)aqusr=([^;]*)/) || [])[2] || ""); 
d.getElementsByTagName("script")[0].parentNode.appendChild(k); 
})("mydata.aqtracker.com/r3/aqobj.js", "AQID"); 
</script>

Note: Check your PivotBillions portal occasionally for the latest code block. The code may change at times to provide additional functionalities and/or improved performance.

Optional Setup

The code block above can also be customized to control its behavior. For example, use this setup to turn off the default tag, to enable link decoration, and so on. The customization is done through the last line in the code block:

<script> 
(function(s,a,f=""){ 
// Same code as for the basic setup 
})("CUSTOM_DOMAIN/r3/aqobj.js", "AQID", PARAMETER_OBJECT); 
</script>

CUSTOM_DOMAIN – Use this instead of our standard one (usually mydata.aqtracker.com) if you want to avoid some of the limitations imposed by certain browsers on trackers from external domains. Consult the PivotBillions portal on how to setup such a custom domain.

PARAMETER_OBJECT – Supply this optional object if you want to use any of these features:

• Set control flags. Supply the parameter object with a fg property having a string value containing the desired flags (in any order). Each flag is an ASCII upper or lower case letter (case sensitive):
  • N – An uppercase N. Do not generate the default tag. Log events can then be generated manually by calling aqobj.tag() as appropriate.
  • C – Advanced. An uppercase C. Set the HttpOnly attribute in the HTTP cookie. In general, do not use this when using a CUSTOM_DOMAIN.
  • S – Advanced. An uppercase S. Set the Secure attribute in the HTTP cookie.
  • s – Advanced. A lowercase s. Set the SameSite=None and Secure attributes in the HTTP cookie. Note that some older browsers may not support the SameSite attribute correctly.
  • t – A lowercase t. Do not store the page’s query data in the log (if any). This will be applied to all the logs generated on the page, including manually generated ones. In other words, a custom query manual tag will not work when this option is set.
• Turn on link decoration and set the target domains. Supply the parameter object with a ln property having a string array value containing the list of desired domains. Note that only links belonging to the configured domains will be decorated. Links to the same domain as the page itself are excluded automatically.

Examples

Custom domain can be used without any additional parameters

<script> 
...
})("CUSTOM_DOMAIN/r3/aqobj.js", "AQID"); 
</script>

Custom flags

<script> 
...
})("TRACKER_DOMAIN/r3/aqobj.js", "AQID", {fg:"NC"}); 
</script>

Turn on link decoration by specifying the target domain(s)

<script> 
...
})("TRACKER_DOMAIN/r3/aqobj.js", "AQID", {ln:["sister_site.com"]}); 
</script>

Parameter object with custom flag and link decoration

<script> 
...
})("TRACKER_DOMAIN/r3/aqobj.js", "AQID", {fg:"NC",ln:["sister_site_1.com","sister_site_2.com"]}); 
</script>

Manual Tag – Basic

A basic manual tag will generate a log event exactly like the default action. It is done by calling the Javascript function aqobj.tag(). Simply call the function whenever you want to generate a log event. For example,

<body onunload="aqobj.tag('tag')">
...
</body>

For a basic tag like this without any additional parameter, the 'tag' keyword can be omitted, as in:

<body onunload="aqobj.tag()">

Manual Tag – Custom Query

Custom query parameters can be appended to the URL being logged. To do this, call the tag function with a 'tag_cat' keyword and an additional argument containing the desired query string:

<script>
// Add query parameters key1=val1 and key2=val2
aqobj.tag('tag_cat', encodeURIComponent(key1) + "=" + encodeURIComponent(val1) + "&" + encodeURIComponent(key2) + "=" + encodeURIComponent(val2));
</script>

Note: Your desired query parameters must be concatenated together into a single query string in the call (do not perpend a '?' or a '&' to the string). This query string will be appended to the page URL when it is logged.

Note: The encodeURIComponent() function should be used on each parameter’s key and value individually. The equal sign between each key and value, and the ampersand between parameters, should not be encoded.

Manual Tag – Downloads

A download usually cannot generate its own log, so it must be logged when the download is triggered. Normally, a log event saves the current page’s URL. For a download, the URL of the target is logged instead. Also, the current page becomes the referrer of the download. To do this, call the tag function with a 'tag_file' keyword and an additional argument containing the path or URL to be logged:

<a href="file1.zip" onClick="aqobj.tag('tag_file', 'file1.zip'); return true">Download file1.zip</a>
...
<a href="/somewhere/file2.zip" onClick="aqobj.tag('tag_file', '/somewhere/file2.zip'); return true">Download file2.zip</a>

Note: If the target is not given as a full URL (e.g., “file”, “subdir/file”, “/subdir/file”, etc), one will be constructed automatically based on the current page’s URL.

Manual Tag – Custom Data

This differs from adding a custom query in that the data is stored in a custom-data column in the log rather than being appended to the URL. More importantly, custom data can be added to any of the manual tagging options described earlier. To do this, call the tag function with the desired keyword ('tag', 'tag_cat' or 'tag_file'), add an associated argument if required ('tag_cat' and 'tag_file') and, finally, one or more custom-data strings to log.

Example

<script>
// Basic tag with custom-data
aqobj.tag('tag', "custom_data_1", "custom_key2=custom_val2");
// Custom query tag with custom-data
aqobj.tag('tag_cat', encodeURIComponent(key1) + "=" + encodeURIComponent(val1), "custom_data_1", "custom_key2=custom_val2");
</script>
...
<a href="file1.zip" onClick="aqobj.tag('tag_file', 'file1.zip', 'custom_data_1', 'custom_key2=custom_val2'); return true">Download file1.zip</a>

The data are stored together in a custom-data column in the log like a query string. For the two data values used in the above examples, the column will contain:

URL_encoded_custom_data_1&URL_encoded_custom_key2=URL_encoded_custom_val2

Note: The use of an identifiable key for each parameter is recommended. This would make extracting the data easier during log processing.

Note: There is no need to use encodeURIComponent() on your parameters. The tag function will do so automatically so that the values stored in the log will be encoded values. Furthermore, if a data value has the form “key=value”, the key and the value will be encoded individually as shown in the example column value above.