OT4: Tagging a session and subsequent sessions

If you want to tag a session with a custom metric then this article is for you. Lets say you want to tag a session with a customerId that comes from another system. This is useful if you want reports on customer's that log into your system.

How do I get the customerId into Opentracker's datastore/ user interface? 

Opentracker's script is written to tag the browser and get data into Opentracker's elastic-search datastore. Url's are quickly parsed to "tag" the browser with keys and values. If an "attribute" in the url starts with "ot_" or "utm_" the browser gets tagged. For example this would turn on this behavior for ot_customerId and utm_campaign:

Prepending the key with "ot_" or "utm_", signals Opentracker's script that you are interested in this key/ value and the pair  is managed across the browser's page loading cycle, sessions, domains and/ or devices depending on your account. The key and value also gets indexed on the server so you can search, report and use api calls on this new custom metric.
For instance, you could use this to tag the people logging into a system. Once the person logs into your system, you redirect them to a url with ot_login=full_name appended to the url.

If this sounds too complicated, Opentracker can provide services to implement solutions for your business needs, as well as making sure you are GDPR compliant, contact us for more info. 

A javascript method

What if you don't have the luxury of prepending the url with with "ot_" or "utm_" ? Is there a way to accomplish the sending of custom metrics without altering the url? 
The short answer is yes. Opentracker manages the key/ value that get sent to Opentracker's servers in a global javascript variable. The following javascript console command, gets you the value we prepended in the previous section: 
To illustrate, refreshing the browser after manufacturing a url would look like this in javascript's console debugger for google chrome (here we are using a custom variable called ot_recipientID):

Debugging a custom metric in Opentracker

The above demonstrates the debugging of a metric prepended with ot_ or utm_. Opentracker's datastore and custom metrics only work with keys that are prepended with these two prefixes. 
This is how to tag the browser with a key/ value pair purely in javascript (i.e. not using the url as in the first section):
var myCustomerId = "This is my id";
if (myCustomerId) ot_tag("ot_myCustomerId", myCustomerId);
// refresh browser
Notice that we are using a variable called ot_myCustomerId. The following looping video illustrates the running of this script in chrome's debugging console:

Creating a custom metric in purely javascript

A problem, also demonstrated towards the end of the above looping gif, is that the browser - while the page loads - does not guarantee that any javascript variables or function exits, and you might have an undefined variable or function that become available as the page renders. While this isn't a problem if you are debugging things, this will become an issue while things load asynchronously. You will need to write code that takes this into account as the page fully loads in the browser. You can read more about this topic and find solutions here:  

Putting the callback function ot_onload to work

The Opentracker script, once loaded, will immediately check for a function called "ot_onload". This is a hidden function that if defined, gets called. This function needs to be loaded before the script itself and needs to call ot_log_state() - to record all data. The function needs to be in the html of the page, or if loaded externally, needs to be placed before the loading of Opentracker's script. A fully functional example looks like this:

// method called by opentracker's callback on script load, must precede actual loading of script
function ot_onload() {
  var myCustomerId = "12345";
  if (myCustomerId) ot_tag("ot_myCustomerId", myCustomerId);
  // needed to load and log the state of all variables, otherwise things won't work
  console.log("ot_myCustomerId: " + ot_map.get("ot_myCustomerId"));
<!-- load the opentracker script with debuging to console.log -->
<script src="//script.opentracker.net/?site=REPLACE_THE_SITE"></script>

You will need to replace REPLACE_THE_SITE with the site you registered at Opentracker when starting your account. You can view a working example here. The reporting interface will now show the new custom metric ot_myCustomerId: