Tutorial: Creating new extension execution windows

[UnknownJ]

In this tutorial we'll look at expanding the set of built-in extension execution windows. Currently extensions can run as:

• Pre-Loader
• DOM Ready
• Before Load Rules
• After Load Rules
• After Tags
• Tag Scoped

But what if we wanted to run code at another point in time?

For this example, let's say that we want to create two new windows - Before Privacy Manager and After Privacy Manager. Use cases might include:

• Logging the before and after status of each tag in order to validate which tags would have fired except for Privacy Manager overriding the load flag
• Hard-coding your list of omitted tags in order to work around a UI bug that can sometimes un-omit tags
• Changing the categorisation of a tag depending on site / environment

And many more. This gives us a way of accessing utag.loader.cfg, which is notoriously difficult to get at because it's destroyed and recreated each time load rules are evaluated, so it's not available to a BLR extension, and has already been acted on by the time you get to ALR extensions. But how do we do this without messing with the master loader template?

The answer is to hollow out a custom tag template, and inject our own code. Add a new Custom Container tag, and edit the template (you may need to save/publish/reload to get the template to show up) and replace it entirely with the following:

var u = {
  map: {},
  extend: []
};

##UTGEN##

if(!utag.loader.OU_old){
  utag.loader.OU_old = utag.loader.OU;
  
  utag.loader.OU = function(){
    for(var i = 0; i < u.extend.length; i++){
      u.extend[i]("BPM", utag.loader.cfg);
    }
    
    this.OU_old();
    
    for(var i = 0; i < u.extend.length; i++){
      u.extend[i]("APM", utag.loader.cfg);
    }
  };
}

We're using the ##UTGEN## substitution in order to inject tag-scoped extensions into the body of the template. We're then wrapping the existing Privacy Manager function in our own function that adds invocations of the tag-scoped extension array before and after PM is run.

For this to work, you must configure the tag to run in a bundled state, you need it to be appended to the bottom of utag.js rather than being loaded externally based on load rules. Name your tag "Before and After Privacy Manager".

Now, to create a Before Privacy Manager extension, simply create a JS extension within the TIQ UI, and scope it to the "Before and After Privacy Manager" tag. Your extension will be passed two variables - a which is the execution window (BPM or APM for before and after Privacy Manager respectively) and b which contains a reference to the utag.loader.cfg object, which defines the current tag configuration, particularly the load and send flags.

So one such extension might be designed to ensure that Tag ID 5 is always omitted from Privacy Manager's logic, even if a bug or well-meaning analyst removes it from the list within the UI. Simple enough:

if(a === "BPM") b["5"].tcat = 0;

Or what if you want to omit all tags from Privacy Manager in the dev environment?

if(a === "BPM" && window.utag.cfg.path.split("/")[6] === "dev"){
  for(var k in b){
    b[k].tcat = 0;
  }
}

Or what if you have a tag which you've classified as Functional which is defaulted to on, but if the customer has Do Not Track set you want to classify it as Marketing which is defaulted to off:

if(a === "BPM" && navigator.doNotTrack === 1){
  b.tcat = 5; // Marketing
} else {
  b.tcat = 4; // Functional
}

Or if you just want to log what Privacy Manager did to the console:

if(a === "BPM"){
  window.beforePM = Object.assign({},b);
}
if(a === "APM" && window.beforePM){
  var c = window.beforePM;
  for(var k in b){
    if(b[k].load === 0 && c[k].load > 0) utag.DB("Tag ID " + k + " load disabled by Privacy Manager");
    if(b[k].send === 0 && c[k].send > 0) utag.DB("Tag ID " + k + " send disabled by Privacy Manager");
  }
}

This will identify any tags whose load or send flag was set to zero after PM ran, but was not zero beforehand.

There are other use cases - interested to hear whether you've got any suggestions for them..

[mitchellt]

I think I need to read through this a few more times, @UnknownJ.  I am particularly intrigued by your example of the prospect of bracketing the privacy manager extension with this custom extension.  Thanks for posting, really enjoy your recipes!