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.

20 thoughts on “Migrating from H-code to AppMeasurement

  1. Alexis Cazes

    Hi Jan,

    I believe the product Survey is not working with the new javascript appmeasurement. Is it still the case ?

    Best regards.

    Alexis cazes

    Like

  2. Hi Jan,

    Nice summary of the new approach.

    You mention “clearVars()” – in the old approach (where it was used with the “manageVars()” plugin), it was possible to include arguments where only a specified list of variables would be ‘cleared’ (or, alternatively, only a specified list of variables would be retained); does any of that functionality exist natively in the new library?

    Thanks,
    Barry

    Like

    1. Hi Barry, I lost track of your question and just found it again, sorry about that!

      No, the new library does currently not allow you to specify a set of variables to clear. It’s all or nothing.

      Like

  3. Pingback: Know Your Version | Web Analytics for Developers

  4. Pingback: Analysing Mobile Apps – Debugging | Web Analytics for Developers

  5. Adam Haining

    Just FYI, you can and still should use the old method for creating the s object. Namely, using the s_gi function. It will actually create the s object and place it in the s_c_il object as normal, and it will still use “new AppMeasurement()”. It will also assign the report suite ID correctly. I’d still highly recommend creating the s object this way.

    Like

  6. Adam Haining

    If you don’t use s_gi, it won’t really hurt anything. However, if you use DTM (DTM uses s_gi to create an internally scoped s object) or have any custom link code that uses s_gi, it can possibly create separate objects. This can be an issue if you’ve set variables and expect them to be set again when sending another request on the same page. It’s not going to be detrimental, but it is definitely safest to continue using s_gi.

    Like

  7. Pingback: “Audiences” – Integration von Analytics mit Target | Webanalyse auf Deutsch

  8. SG

    Hi
    we are trying to migrate from s_code to appmeasurement 1.3 version.so for testing purposes, we plan to call both s_code and Appmeasuremnt but pointing to different suites.
    s_code –> SuiteA
    AppMeasurement–>SuiteB

    But I see that the new test suite reports data and the current prod suite does not.

    Here are the calls

    /* You may give each page an identifying name, server, and channel on
    the next lines. */
    s.pageName=””
    /************* DO NOT ALTER ANYTHING BELOW THIS LINE ! **************/
    var s_code=s.t();if(s_code)document.write(s_code)

    <!–

    /* You may give each page an identifying name, server, and channel on
    the next lines. */
    s.pageName=””
    /************* DO NOT ALTER ANYTHING BELOW THIS LINE ! **************/
    var s_code=s.t();if(s_code)document.write(s_code) –>

    And attaching the digital pulse debugger output for the two requests

    Any input on this ?

    Like

    1. You have two different pieces of code on your site which both use a variable called “s” to do stuff. That can’t work.

      Solutions: Either remove one of the codes or rename the object for one of the codes. The latter is not trivial, you might have plugins that have the name “s” hard-coded and would therefore have to be changed.

      Like

  9. Arpit

    If we are evaluating AppMeasurement library vs legacy H-codes is DTM route best way to move forward if we want to switch to AppMeasurement library ?

    Like

    1. Hi Arpit,

      Frankly, it doesn’t matter.

      DTM makes the management of tags and tracking easier, true. but deploying it and switching at the same time has the downside that you do 2 things at the same time. Complexity of the change goes up.

      If you switch to AppMeasurement.js (and maybe Visitor ID Service?) without DTM, you have more focus.

      I guess a good way might be to do both individually, but go to DTM first, making the (later) switch to AppMeasurement.js easier.

      Like

  10. Mukesh

    Hi Jan,

    If I have multiple reporting suites, one for each country, how does the implementation impact the global multi suite tagged reporting suite? Do you recommend migrating?

    Thanks,
    Mukesh

    Like

    1. Hi Mukesh,

      Moving from H.xx to AppMeasurement should not have any impact on _how_ you track, i.e. multi-suite tracking should continue to work just fine.

      I do recommend migrating at some point, yes, but there is currently no reason to hurry.

      HTH,
      Jan

      P.S.: hope you’re doing well, Mukesh!

      Like

  11. Pingback: When exactly does doPlugins run? | Web Analytics for Developers

  12. Pingback: 2016 for Developers | Web Analytics for Developers

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s