OT4: Tagging a session and subsequent sessions. How do I get my custom data?

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.
The prefix utm_ "tags" the user's browser with a value, and this value stays the same throughout the session, it is the first value that gets measured.
The prefix ot_ also "tags" the user's browser with a value, and this value changes if a new value is set, it does not stay the same throughout the session, it is the last value that gets measured. 
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, and you will register the name last used.

You can also provide variables that do not get "tagged" to the user's browser, but get sent along with an event. In this article we will focus on tagging the user's browser. 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 simple example of sending an event with javascript

In the simplest form this is how you send an event:

// run this script when opentracker has loaded
function ot_onload() {
  // map an event
  ot_map.put("ot_video_title", title);

  // send the event

A javascript method continued

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";
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 log or send the state of all variables, otherwise things won't get stored on the server
  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:

Need more information on how to implement things in your business? Schedule a Call