Migrating from H-code to AppMeasurement

In May 2013, the Adobe analytics product team released a new Javascript library, no longer called “H.xx.y” but “AppMeasurement for JavaScript”.

The main selling points for this new lib are it’s speed (3 – 5 times faster than H.25), size (8k compressed, compared to 13k for H.25) and native support for some of the most used plugins (getQueryParam being the big one). My colleague Ed Hewett wrote a post about the new library in May.

The AppMeasurement for Javascript library (I shall call it “the new library” from here on) is small and fast enough to be used on mobile sites but has all of the power of the old H-code so it can also be used on standard sites aimed at desktop browsers. It should therefore be the preferred library going forward for pretty much everybody.

The question then is: how do I migrate from H-code to the new library?

Prerequisites

Let’s start off with the prerequisites.

The new library is new, and it currently comes with support for most but not all Javascript plugins. You will have to check the list of supported plugins to see if all of yours are supported.

Crucially, the “Cookie Combining Utility” is currently not on the list of supported plugins. If you are using it, that is a show-stopper, because removing it would mess with a lot of your data.

The Analytics/Target integration is also not supported at this time (December 2013), which means if you are using both Analytics and Target, you have to wait before migrating.

You might be using the “channelManager” plugin for your marketing channel reporting. Or you might use the “FormAnalysis” plugin to analyse some of your forms. Both are not supported! Do not migrate!

Plugins are usually developed by Adobe Consulting when customers need them. If you are currently using channelManager and you want to migrate to the new library, you should work with a consultant, who will likely be able to create a new channelManager plugin for you. Note that there is a cost associated!

And in case your visitors are stuck on really old browsers, know that the new library does no longer support IE 4 & 5 as well as Opera 6 and earlier. Wow, Opera 6… that is pre-Presto… I was still living in Southern France when that came out!

Migrating

Migrating from H-code to the new library is not overly difficult.

You will basically update your s_code.js file as usual: copy everything below the “DO NOT CHANGE” line from a newly downloaded file into your existing s_code.js file.

Rumours about Adobe engineers diving off cliffs when you do so are wildly exaggerated.

For an upgrade from one H-code to another, this is enough, but when you migrate to the new library, you need to do some extra work.

First, the library now contains functionality to grab URL parameters.

You will have to remove the getQueryParam plugin from your s_code.js file and change all references to it to the built-in s.Util.getQueryParam. Instead of

	s.campaign=s.getQueryParam("cid");

you would now write

	s.campaign = s.Util.getQueryParam("cid");

The parameters are slightly different, and the built-in version does not support multiple URL parameters as far as I can see.

Secondly, if you are using the s.c_r() and s.c_w() functions, you must use s.Util.cookieRead() and s.Util.cookieWrite() instead.

The parameters on the new methods are pretty much unchanged. Note that if you do not give s.Util.cookieWrite() an expiration (a Date object), it will create a session cookie.

If s.Util.cookieRead() does not find the cookie, it will return an empty string, which is in line with most of the plugins in the Analytics universe.

Third, you need to either remove non-supported plugins or test them thouroughly.

Then, you need to test thouroughly.

Seriously, this migration is more than your normal H-code upgrade.

Some s_code.js files out on the Internet have been customised beyond belief! Chances are that yours is one of those, and you owe it to your marketer to double- and triple-check everything is ok before you push your changes to live. Use Charles!

There is no reason why your file should not work with the new library (except for what I mentioned in the section above), but I am quite sure the Adobe QA people couldn’t possibly check everything that people have done to with their s_code.js files.

Again: test until you forget what your job title used to be.

Notes

The new library can go into the <head> of your pages.

I know customers who are using content management systems or templates that would make integration into the <head> much easier than in the <body>. If you are in that camp, migrating to the new library would really make sense for you.

The library offers a new method called s.clearVars(), which removes existing values for most of the “variables”.

This is highly useful for link tracking, or in situations where your page content is changed dynamically and you are “simulating” normal tracking.

You can change the way you instantiate the library.

H-code would rely on a global variable called s_account to be set to the report suite ID(s) before instantiation. The new library can now be used much like it’s siblings from app development. Where formerly, you would use code like this:

	var s_account="rsid";
	var s=s_gi(s_account);

to instantiate the “s object”, you can now do it like this:

	s=new AppMeasurement();
	s.account="rsid";

The old way does still work, though. Because all your page code is also compatible with the new library, the migration can be entirely handled via a change to the s_code.js file.