Latest Posts

Archives [+]

Customizing the Clickstream Cloud

Last time, I reviewed the basics of the powerful Clickstream Cloud feature of Adobe WEM (formerly CQ5), which is the feature whereby, if you type Ctrl-Alt-C, you get a popup summary of various bits of contextual information about the user, the user's browser, and the page the user is currently visiting (see illustration further below).

As with almost everything else in WEM, the Clickstream Cloud can be customized relatively easily, because the code for the Cloud is easily accessible (and modifiable) in the repository.

If you go in the repository under /libs/cq/personalization/clientlib/source/shared (best done in CRXDE Lite: just aim your browser at http://localhost:4502/crx/de/index.jsp#/crx.default/jcr%3aroot/libs/cq/personalization/clientlib/source/shared), you'll see a half dozen *.js files that govern the Clickstream Cloud's basic behavior, and if you look under /libs/cq/personalization/clientlib/source/clickstreamcloud, you'll find the *.js files that contain code for the various session stores that manage the information fields displayed in the cloud dialog. There's also a js.txt file at /libs/cq/personalization/clientlib/js.txt that governs how all these *.js files are loaded.

As a very simple example of customization of the Clickstream Cloud, let us suppose that you wanted to add a timestamp to the cloud dialog under "Surfer information" as shown below:

Clickstream Cloud Dialog

Notice the part, under Surfer Information, where it says "Thu Sep 08 2011 17:09:45," etc. This information was added as a result of custom code.

There are a couple of ways to do this. One way would be to alter the setSurferInfoInitialData() function in config.json.jsp (which is located in a somewhat obscure place, namely /libs/cq/personalization/components/clickstreamcloud/command/config/). You might be very tempted to do this since that's the function where the user's IP address, for example (which appears under Surfer Information), is set. But making a change in this function would actually be a bad thing to do, for a number of reasons. First, you're dealing with a core WEM file. And you're making hard-coded changes to it. There's no guarantee that this file will stay unmodified (or even continue to exist) in future versions of WEM, and by putting custom code in it, you've created a maintenance nightmare.

A better alternative is to create your own separate file, perhaps called custom.js, and place it under /libs/cq/personalization/clientlib/source/clickstreamcloud/. The content of custom.js is simply:
CQ_Analytics.CCM.addListener("configloaded", function() {
              CQ_Analytics.SurferInfoMgr.setProperty( "timestamp", new Date() );
 }, CQ_Analytics.SurferInfoMgr);

To ensure that custom.js loads at runtime, you do need to make a change to the aforementioned js.txt file (namely, the one at /libs/cq/personalization/clientlib/js.txt). Just add the line "clickstreamcloud/custom.js" to the end of the file.

Now you should be able to go to a new page (or reload the current page) in WEM, type Crtl-Alt-C, and see the timestamp information in the Surfer Information portion of the Clickstream Cloud dialog.

What's neat is that if you now click the Edit link in the upper right portion of the Cloud dialog, then click the Surfer Information tab of the dialog that pops up, you'll see timestamp info among the editable fields of the dialog:


For more information on the Clickstream Cloud API (including how you can create your own custom session store), see the documentation here.



  • By Jörg Hoh - 7:39 PM on Sep 09, 2011   Reply
    I was told, that custom changes must not happen below /libs, because this is considered as CQ5's private parts, where a hotfix/featurepack/new version can change everything. Custom changes should be made below /apps; because of the order in the search path files are first looked up in /apps, and then in /libs.

    Does this still hold true also for clientlibs?
  • By Anonymous - 2:33 PM on Nov 29, 2011   Reply
    Yes - make a copy of the clientlibs folder under a parallel path under /apps and adjust any existing path-ing in the js.txt accordingly.
  • By David Gonzalez - 2:55 PM on Nov 29, 2011   Reply
    What is the recommended method for surfacing data from the JCR or data derived from business rules about data in the JCR? The solution you outline is JavaScript based which would limit the reach of what data you can write to the CSC via setProperty(..)

    I've accomplished the above by extending the data written to config.json, but this was all Server-side Java code, rather than client-side JS.

    What are your thoughts on accessing JCR data via the CQ's JS APIs (they do not seem to be well documented).