Adobe Analytics

yuhuisg · 6/1/21

(Disclaimer: The following recommendation is based on my personal experience. It is not endorsed nor recommended by Adobe or any of its partners.)

Background: sending more than one beacon in the same page

When it comes to accurate analytics tracking, one of the most important things to guard against is that you don't track variables that shouldn't actually be tracked. This happens particularly often when multiple beacons are sent from the same web page.

A simple example is what happens when you want to track a link click on a page. When the page's Pageview beacon (s.t()) is sent, you might have tracked eVar8 with the page's site section. This eVar8 remains set in the Analytics "s" object. So when you track the click on the link with a Custom Link beacon (s.tl()), that eVar8 would be tracked as well – even if that wasn't your intention.

This problem manifests itself even more so if your website is a Single Page Application (SPA). In that case, your website really only has one "physical" page, and then you have multiple "virtual" pages. Each page would be tracked with a Pageview beacon (s.t()). But because the browser never actually loads a new "physical" page in between pages, there is only one single Analytics "s" object that persists as long as the user keeps interacting with the website. And as you can imagine, multiple props, eVars and events could accumulate in that "s" object, resulting in variables being tracked wrongly!

To work around this problem of variable accumulation, Adobe Analytics provides a clearVars function. In simple terms, it wipes out all of the variables that have been set in the "s" object, giving you a nice, clean slate to track from. But clearVars (or the "Clear variables" action in the Adobe Analytics extension in Adobe Experience Platform ~~Launch~~ Data Collection) is both a blessing and a curse. It wipes out everything!

The Problem: everything gets cleared!

Back to the above example of the Pageview and the Custom Link beacons. Let's say you track site language to eVar5, and you want this to be tracked with all beacons, both Pageview and Custom Link ones. If you were to use clearVars after sending every beacon, then you'll always need to set eVar5 again! In other words, you need to do this all of the time:

User opens the web page.
1. Set s.eVar5 to the site language.
2. Send the Pageview beacon --> s.eVar5 is tracked with the site language.
3. Run clearVars --> s.eVar5 is now blank.
User clicks a link.
1. Set s.eVar5 to the site language.
2. Send the Custom Link beacon --> s.eVar5 is tracked with the site language.
3. Run clearVars --> s.eVar5 is now blank.

If you miss step 2.1, then your tracking implementation is wrong and you have to fix that. And all because you had used clearVars() at step 1.3. You might remember that, but will the future you remember that? Or the person who inherits your implementation after you?

And that is precisely why I don't use clearVars – because it's so destructive!

Solution: use s.registerPostTrackCallback to unset only those variables that should be cleared

Fortunately, Analytics' tracking code has a handy function called "registerPostTrackCallback". Any code that is put inside here will run after every beacon call. This is the perfect place to unset any variables that you don't want to persist between beacons – precisely because you can control what variables you want to clear and/or leave intact.

Here's the code that I use:

s.registerPostTrackCallback(function(requestUrl, s) {
  // unset variables and events that are not needed after sending a beacon
  // BUT LEAVE BEHIND variables that should remain, e.g. those that are set in the Adobe Analytics extension itself

  var doNotUnsetVariables = [
    'pagename', // page name
    'server', // site server
    'eVar5', // site language
    // keep adding more dimension variables: hiers, props, eVars
  ];
  var doNotUnsetVariablesRegExp = new RegExp('^(' + doNotUnsetVariables.join('|') + ')$');

  // find and erase all unneeded variables
  var setVariables = Object.keys(s).filter(function (k) {
    return /^((eVar|hier|list|prop)[0-9]+|(purchase|transaction)ID|campaign|channel|pageType|products|state|zip)$/.test(k);
  });
  var unsetVariables = setVariables.filter(function (k) {
    return !doNotUnsetVariablesRegExp.test(k);
  });
  unsetVariables.forEach(function (v) {
    s[v] = '';
  });

  // erase all success events
  s.events = '';
}, s);

The important part is the "doNotUnsetVariables". This is an array of variable names that you want to retain between beacons. In my example code above, I've kept eVar5, so that site language can still be tracked with every beacon. But you don't see eVar8 because I don't want to track the site section every time.

(Take note of that 2nd last line too: my example code clears out all s.events. If you have any events that you want to retain between beacons, then that line will need to be modified for your specific case.)

This code can be placed before or after the s.doPlugins block in your AppMeasurement code. If you're using Adobe Experience Platform ~~Launch~~ Data Collection, then you can add this in the Adobe Analytics extension's custom code.

What happens is, in my view, beautiful and elegant:

After every beacon, whether it's a Pageview or Custom Link or Download Link or Exit Link, that code inside s.registerPostTrackCallback will run.

When that code runs, it clears out only those variables that are not specified in "doNotUnsetVariables". So variables that should remain in the Analytics "s" object remain intact for the next beacon.

This is much, much, much better than clearVars' all-or-nothing massively destructive approach. clearVars is like a megaton nuclear bomb on the "s" object, while my approach picks and chooses those "s" variables that don't need to be retained.

So don't use clearVars! Instead, clear only those variables that you want to clear, and the example above provides you with a quickstart to doing just that.

What do you think of my recommendation? Is it good or bad? Have you done something similar to this? Or do you actually prefer clearVars, despite its massively destructive approach? Leave a comment and share your views.

Yuhui | yuhui.sg | Analytics, A/B Testing, Development since 2006

atulsingh17 · 6/1/21

This is nice post. I would definitely give it a try.
clearVars() always been a pain area for me too. However, I was wondering, if you have any variable that you would want to set again on next s.tl() call, you can define such variables in doPlugins() section.

Variables which you don't want to persist to linkcalls, can be set in Global Variable in Analytics extension and the variable which you would want there is linkcalls can be set in doPlugins() section. With that, even though clearVars() would clear all the globally set variables but variables like lang/site-section can be set in doPlugins() so next time when you have linkcall you would have those set again.

I have seen most people avoid extra lines of code

yuhuisg · 6/1/21

Thanks for sharing, @atulsingh17 !

Variables which you don't want to persist to linkcalls, can be set in Global Variable in Analytics extension and the variable which you would want there is linkcalls can be set in doPlugins() section. With that, even though clearVars() would clear all the globally set variables but variables like lang/site-section can be set in doPlugins() so next time when you have linkcall you would have those set again.

That is precisely what I want to avoid: remembering to set the variables again somewhere else. That's why instead of the set-clear-reset method that you've described, I've opted to use a method that only clears specific variables, while leaving the others intact.

Also, if I were implementing AA directly in code, then I would definitely go with your method of using doPlugins(). But with Adobe Experience Platform ~~Launch~~ Data Collection, I prefer to rely on the Global Variables as much as possible.

But there's definitely nothing wrong with your approach, and since you're comfortable with that, I'd recommend that you continue with it.

Andrew_Wathen_ · 6/2/21

@yuhuisg - really interesting insight into how you approach this.... and is very different to how I like to set up. I think it is one of those situations where there are multiple approaches and there is no right or wrong approach.

Just for the record in case any one is interested here is our approach...

We have a Launch rule that always runs before everything else that both calls clearVars and sets linkTrackVars & linkTrackEvents to "none". We do this deliberately to create a completely clean slate each time. We then explicitly re-establish the adobe analytics variables that we want.

I like this approach because:

we'll never accidently have anything bleeding over from one call to the next
by looking at the rules we have, it is absolutely clear what variables will be sent for a given scenario (easy for people to understand)

This works well for us, but appreciate your approach clearly works well for you too

Stewart_Schilling · 6/2/21

Interesting approach. I have some concerns with it as written though.

The code block :

  var setVariables = Object.keys(s).filter(function (k) {
    return /^((eVar|hier|prop)[0-9]+|products)$/.test(k);
  });

This fails to include a handful of variables, ['channel', 'campaign', 'state', 'zip', 'pageType', 'purchaseID', 'transactionID', 'list1', 'list2', 'list3', ...maybe some others]. As it stands, these variables would not get cleared.
The s object has a ton of keys on it. It would me more code, but more performant to run some for loops to create the array that gets returned here.

I think that a better implementation for a clearVars function with exclusions would be to overwrite s.clearVars as such:

// This should be run at the top of AA Custom Code
s.clearVars = function() {
  var clearVarsExclusions = _satellite.getVar('clearVarsExclusions') || [];
  var clearVarsAdditions = _satellite.getVar('clearVarsAdditions') || [];

  var aaVars = [
    'chanel', 
    'events', 
    'products', 
    'purchaseID', 
    'transactionID', 
    'state', 
    'zip', 
    'campaign'].filter(function(variable){
      return (clearVarsExclusions.indexOf(variable) === -1);
    });
  var genVars = function(prefix, limit, exclusions){
    var variables = [];
    for (var i=1; i<=limit; i++) {
      var variable = prefix+i;
      (exclusions.indexOf(variable) === -1) && variables.push(variable);
    }
    return variables;
  };
  
  aaVars.concat(
    clearVarsAdditions,
    genVars('prop', 75, clearVarsExclusions), 
    genVars('eVar', 250, clearVarsExclusions), 
    genVars('list', 3, clearVarsExclusions),
    genVars('hier', 250, clearVarsExclusions)
  ).forEach(function(variable){
    s[variable] = void 0;
  });
}

Beyond being more performant, this allows the use of the AA Extension's Clear Variables action if desired. If you would rather call s.clearVars from a postTrackCallback, this solution would support that as well.

Oddly enough, the s.clearVars function in AppMeasurement.js does not clear s.pageName. The solution above allows the specification of an array of variables to include when clearing.

If I were to take this one step further, I would

put this code into an extension so that no changes would need to be made in AA custom code.
also add a UI for management of the exclusion and addition lists.
add the option to call the function after every beacon (via register postTrackCallback).
possibly add some functionality for clearing context variables.

Just my $0.02

yuhuisg · 6/3/21

Thanks for the input, @Stewart_Schilling . I am personally not in favour of overwriting functions that have been specified in the library, because it introduces a new area of error if I or my successors forget about it.

Also, I've corrected my regular expression in the post to accommodate more variable names. There could still be others that are left out, but it would be trivial for someone who wants to use this code to add them into the expression, if needed.

Vijaysarathy_Krishnan · 7/25/21

I was dealing with exactly the same problem and used this solution and it worked beautifully. Thank you for sharing this. @yuhuisg

david--garcia · 7/31/21

Thank you for the insight, helped me out.

Gigazelle · 8/5/21

Great post, thank you for sharing!

There is one use case where clearVars() is ideal, and that's in single-page applications when you genuinely want to clear everything so it doesn't bleed over into the next "page".

jantzen_b · 8/9/21

@yuhuisg Way to think outside the box! Awesome article.

@EricMatisoff Can we get new "..clearVars is like a megaton nuclear bomb ..." t-shirts inspired by this article?

David_Jerome · 8/13/21

Great article @yuhuisg

Gokul_Agiwal · 9/29/21

A really nice insights on clearVars. I was struggling in one of the implementation with clearVars mainly on SPA application but this approach seems good.

Thank you @yuhuisg StewSchilling

Ben_Step · 10/13/21

An interesting approach. I've always relied on ClearVars at the start of each rule, and then global variables and some bits and bobs in the custom code in the extension, and never had a problem. But this is an interesting alternative.

FrederikWerner · 11/18/21

Nice post! I'm thinking of how this could be brought into Launch or the Analytics extension in Launch so we don't need to custom-code it. Could we maybe use a Set Variables action with empty values instead?

PratheepArunRaj · 1/20/22

Nice article @yuhuisg,

We mostly used managevars for this purpose. Can you help us to understand the difference here? From your viewpoint, which one is effective and accurate?

Thanks much, Pratheep Arun Raj B

yuhuisg · 1/20/22

@PratheepArunRaj , manageVars runs inside s.doPlugins, so it manipulates your variables before they are sent to AA.

My recommendation in this article, on the other hand, is focussed on clearing out variables after the hit has been sent and before the next hit.

I suppose you could use manageVars to clear out unneeded variables before the hit is sent, but it has to be done properly so you don't clear out wrong ones incorrectly.

Alexis_Cazes_ · 3/28/22

I believe there is a functionality that allows you to do clean tracking without necessary having to use clearVars or custom code in callbacks.

There is a feature in Adobe Analytics that is called variable Override: https://experienceleague.adobe.com/docs/analytics/implementation/js/overrides.html?lang=en

You can pass an object to the s.t and s.tl code which the configuration you want just in this call. Once the call is sent the s object does not inherit the value from the override object.

So if you use:

var analyticsConfig = {
  pageName: "My test page name",
  eVar1: "New value 123",
  prop1: "ABC"
}

s.t(analyticsConfig)

You will see that you analytics call will contain only config from your analyticsConfig object.

Then check in the developer console and type s.pageName and notice you should see undefined, as the values from your override object did not update the s object. This is a much better solution.

As Adobe Launch support ES6 you can also configure a base object that will be merged to custom object so you are sure default variables to always be set on the call:

var base = {
    pageName: "abc",
    eVar3: "default"
}

var customConfig = {
    eVar1: "123",
    prop1: "abc"
}

s.t({
    ...base,
    ...customConfig
}); //use spread operator

So obviously we will create dataElements here to get base object and custom object.

This is a better solution as you can make sure that your call will only contain the values you need and you do not need to worry to clean up after yourself.

yuhuisg · 3/28/22

@Alexis_Cazes_ thanks, that's a great solution!

Unfortunately, it looks like the AA extension's "Send beacon" action in Adobe ~~Launch~~ Experience Platform Data Collection Tags doesn't support this Override function. In that action's view, there is no field to let you specify the override object. What a pity!

Alexis_Cazes_ · 3/28/22

Interesting point let me see if we can update the extension.

chrish1471105 · 4/5/22

Interesting posts.

Looking for a definitive answer on is there a way to still get Global variables set if you run clearVars at the end of each rule for a 2nd rule running on the same page. My Assumption was the Global variables would be applied again in the 2nd rule as we've asked for these to be global but this doesn't seem to be the case and the variables are blank. We have mulltiple direct calls on the same page so I assumed we could use global variables to set the common evars but without sending multiple copies of the 1st event. If not why does it work this way and can the Adobe team not change how it works for rules to inherit global config.

yuhuisg · 4/6/22

@chrish1471105 The simple answer is that there is no concept of "global variables" in Adobe Analytics' implementation. Adobe Analytics' implementation only knows whatever you track to it when you fire its beacon.

Global variables is something that you understand by yourself as variables that have to be set with every beacon call. So it is up to you to ensure that those variables are set whenever your Rules are triggered.

chrish1471105 · 4/6/22

@yuhuisgI don't think that is true, I'm specifically talking about "global variables" in the Adobe analytics extension in launch. I would expect that would then apply to every individual rule, otherwise what is the point of having that as a concept. What i'm trying to specifically understand is does that only work at the page load level to set global variables rather than on each rule.:

See image below that clearly shows there is a concept of Global Variables with the Adobe product

yuhuisg · 4/6/22

@chrish1471105 Ah yes, the Adobe Analytics extension's global variables. Ok, yes, in that context, there are such things as global variables.

The thing is, these global variables are set once when the web page is loaded. This behaviour has more to do with how extensions work in Adobe Launch, rather than with Adobe Analytics itself. Subsequently, if you use clearVars(), then these global variables will get cleared as well.

chrish1471105 · 4/7/22

Great, Yes I thought that was the behaviour I was seeing.

For the Adobe team, can this not be looked at from the product side though to make those global variables impact each individual rule too, Otherwise there really isn't much point in them (and if anything they just create confusion).

Alexis_Cazes_ · 4/20/22

I have contacted Adobe to update the extension. Now we just need to wait for it to be updated to have the override option to be available in the extension.

@chrish1471105 I personally do not use the Global Variables section of the Adobe Analytics extension.

Best solution is to use the override option (see above) as you are sure you which data will be set and there is not issue with clean up. Also with adobe Launch using ES6, you can create a global object and a custom object that you can merge using the spread operator. At present this would require you to change you action to use JavaScript custom code but that would answer all of your issues.

Another solution that I used and still use in some implementation is to move the global variable logic inside the doPlugins function. as doPlugins is called each time a s.t or s.tl is called, it will ran you logic to get the global variables set.

VaniBhemarasetty · 9/12/22

@yuhuisg This is really helpful

Pablo_Childe · 2/21/23

@yuhuisg

Just an FYI is this a typo?

camapign

Did you mean ?

campaign

yuhuisg · 2/21/23

@Pablo_Childe thanks for catching that! Haha, 2 years after I had posted my article.

Adobe Analytics

Don't use clearVars!

Learn

Documentation

Community

Support

Resources

Adobe account

Adobe