Extensions and Adobe Analytics – get-tracker and augment-tracker

I built an Extension some time ago that enables someone to set contextData for Analytics directly in the Launch UI.

You can see the source code for that Extension on github, of course, but today, I want to write about some of the stuff that went into the Extension.

This is also, in a way, part three of the “Launch Load Order” series. While Launch is pretty straight-forward when it comes to load order, the Analytics Extension has its own ideas, and this is part of it, of course.

Shared Modules

Extensions in Launch can provide Shared Modules that other Extensions can consume and use.

To cite the documentation:

A shared module is a mechanism by which you can communicate with other extensions.

and

Shared modules can be anything you would typically be able to export from a CommonJS module (e.g., functions, objects, strings, numbers, booleans).

– Launch Developer documentation, Shared Modules

For my “Context Data Tools” Extension, which allows you to set contextData straight from Launch, I had to modify and amend the Analytics tracker object (fka ‘s object’), a perfect example of where a Shared Module makes sense.

get-tracker vs augment-tracker

As of the 8^th of Feb, 2018, the Analytics Extension exposes the tracker object via Shared Modules. If you want to build an Extension that amends or changes Analytics data, this is the way to go!

The Shared Modules allow you to retrieve the tracker at two different points in its life cycle: in the “augmentation phase” using augment-tracker, or once the tracker has been fully initialised using get-tracker.

What’s the difference?

The augment-tracker Shared Module can be used to pass a function into the Analytics Extension. That function “will be called as soon as the augmentation phase of the tracker initialization process is reached.”

The function provided to augment-tracker can either do quick work and return, or it can put the initialization of the tracker on hold while it does its thing.

Please do not make Analytics wait too much!

The get-tracker Shared Module, on the other hand, provides a promise that you can handle if you want to work with the tracker after it has been initialised.

What you actually do in that handler is completely up to you. Since at the point when the handler is called, all initialisation of the tracker has been done, you can be sure that the changes you make in your handler will not be overwritten implicitly.

Example: I tried to set a “variable” using an augment-tracker function, but the Analytics Extension actually created (and therefore overwrote) the “variable” at the very end of the init process. Easy fix: use a get-tracker promise instead!

Usage

The above leads to a fairly easy conclusion: we should probably use augment-tracker functions in setup-related parts of our Extensions, such as a main module, or other dependencies.

Edge cases like a hypothetical “Inject Media Module” Action Type could also work, ideally with some sort of hint in the UI that the Activity should be used in a Rule based on “Library Loaded”, “Page Bottom”, or “DOM Ready” Event Types, or an even earlier Event Type provided by the Extension itself (called “Immediate” in my test Extensions, if you want to see an example.)

Promises and get-tracker can also be used in such Rules, and the Analytics Extension will make sure they are executed later, when the time is right. My favourite use case for this is a private Extension that sets your (your!) standard variables based on a standard set of Data Elements.

With a setup like that, spinning up a new site is as easy as deploying Launch, pulling in the Extensions (including yours), and publishing the lot.

Other than that, get-tracker promises are cool for Action Types that your Extension provides, such as setting contextData, or other Analytics “variables”.

Timing

With timing being different, plus the option to use sync/async with augment-tracker, the obvious question is: when exactly do these things happen?

Since I had just written about load order in Launch, I just amended the test. I added a self-made Extension that used both, augment-tracker & get-tracker in all places possible, from the main module all the way to Action Types.

It turns out that Launch, or rather the Analytics Extension, has two distinct phases, and whatever you do in your Rules in Launch, the Analytics Extension will stick to those phases: First, it will initialise the tracker, and then, second, it will handle all the promises passed into get-tracker.

But… you ask, but what happens when the Rules you build do not respect those phases?

Say, you use an Action Type which uses get-tracker in a Rule that fires on “DOM Ready”, and you have a different Action Type, this one with augment-tracker, in a “Window Loaded” Rule?

The good news is that both Shared Modules queue the functions and handlers.

That is sort of to be expected.

The other news is that for the “Window Loaded” Event Type, augment-tracker functions have no effect. The same goes for self-made Event Types that trigger after the initialisation of the tracker has concluded.

In the scenario above, the Action in the second Rule would make no difference at all.

As you can see, the Analytics Extension has your back.

The flip side (there is always a flip side) is that stuffing augment-tracker function definitions into Action Types will push back the initialisation of the tracker, potentially to after “Window Loaded”.

And wherever you put your “Send Beacon” Action, it might not happen at that point if the tracker is still initialising.

Using get-tracker promises is different. It’s the responsibility of the Launch user to make sure the Rules makes sense, i.e. “Send Beacon” happens after any Actions that change the data.

So? (tl;dr, of sorts)

So, I would use augment-tracker for adding functionality to the tracker object, such as a Module. An example would be an Extension that injects the Media Module into Analytics.

get-tracker, on the other hand, is for really changing data on the tracker, such as setting “variables”. That makes it a good fit for Action Types.

(Mental note to myself to rewrite the “Context Data Tools” Extension, which uses augment-tracker to set contextData in two of the three Action Types)

As usual, I have put my Extension on github (launch-extension-augment-vs-get-tracker on github), so if you want to play with load order yourself, fork and have a go!

And here is the Console output in all its gory glory:

I set the Extension up to also create a timeline in a Javascript object. Here is what that looks like: