Aggregated Reports for different page states

This article explains how to show different page states in aggregated reports, using Events with the Context API.

The result is similar to the Content Switch - with the difference that this applies for all types of aggregated reports (Attention, Scroll, Click, Move Heatmaps – and also the Form Analytics).

The suggested use of this guide is in cases where you need to display a different page state in BOTH Heatmaps AND Form Analytics (or just Form Analytics). Otherwise, using the Content Switch API is a better solution.

=Overview=

Let's say you have a pop-up on your page that is only displayed when the visitor clicks on a button. That page can be considered to have 2 states - one with the pop-up open, and another with the pop-up closed (the default state). Or, you might have a multi-step form, where the default state of the page is 'Step 1', and each other step can be considered as additional states of the page.

By default, our Aggregated Reports (Heatmaps \ Form Analytics) will always show the default (initial) state of the page. When you need to generate a report for a specific state of the page, you can use ClickTale Events - together with our Aggregated Context API. The end result will be a report that only includes visitors that saw a specific state of the page.

The process of setting this up includes:


 * 1) Identifying and setting up a trigger for the ClickTale Event
 * 2) Using our Aggregated Context API to display a specific page state - based on a ClickTale Event

This article goes through the complete process of this setup.

For the purpose of this article, we’ll start with a basic HTML page, and add the Aggregated Context API to that page. The final versions of the files used in this example can be downloaded from this link.

=Identifying and setting up a trigger for the ClickTale Event=

Events are a convenient way of tracking visitors based on their actions. By adding a piece of code to elements on your site (links, URLs, movies, forms, etc.), visitors who interact with tagged elements will have the Event tag attached to their browsing history. You can then search for and watch recordings of visitors with Events using our Search tool. Learn more about ClickTale Events.

Step 1 – Start with a basic HTML page
We’re starting with the most basic HTML page. This page includes a button and a hidden pop-up. When the visitor clicks on the button, the pop-up is displayed – so we have 2 states for the page:


 * State 1 - (default \ initial) – With the pop-up hidden.


 * State 2 - (requires a ‘click’ on a button) – With the pop-up displayed.

Basic HTML page:

Step 2 – Identifying when to trigger the ClickTale Event
We know that the page changes to its second state (pop-up displayed) when a visitor clicks on the ‘Show pop-up’ button.

This means that we can trigger the ClickTale Event when the visitor clicks on the ‘Show pop-up’ button – which is when the state of the page changes.

Step 3 – Setting up the trigger for the ClickTale Event
We’ll use jQuery to add another event listener to the ‘click’ event on the button.

Our setup first makes sure that the ClickTale Event function is loaded – and only then we trigger a ClickTale Event named ‘Homepage: Pop-up Shown’ (the name of the event can be anything you like).

We’ll add our code to a new tag at the bottom of the page.

Basic HTML page:

=Displaying the Page State=

The page is now set up to trigger a ClickTale Event for every visitor who clicks on the ‘Show pop-up’ button.

Next, you need to use the Aggregated Context API so that when you generate a report based on the ClickTale Event, the correct state of the page (pop-up displayed) will be shown in the report.

Step 1 - Preparing the helper function
The helper function will allow us to easily call the API. We will name this helper function ‘ClickTaleCustomAggCtxt’, and we will use it later in the following step.

For now, simply copy and paste the code below into a new script file named ‘AggCtxtAPI.js’.

AggCtxtAPI.js:

Step 2 – Using the helper function based on a ClickTale Event
We can now use the helper function to make sure that when we generate the report using the ClickTale Event we created – the correct state of the page will be shown (i.e. the pop-up will be displayed).

We do this in by calling our helper function, passing in 2 parameters.

The first parameter is a callback function that will be responsible of doing the actual work, changing the state of the page from it’s default state – to the second state which we’re interested in (showing the pop up in this case).

The second parameter is the ClickTale Event for which this function will run.

The updated ‘AggCtxtAPI.js’ file now looks like this (notice the additional function call at the bottom of the file):

AggCtxtAPI.js:

Step 3 – Adding the API script to our HTML page
The last step is to add the ‘AggCtxtAPI.js‘ script file to the page. We do by using a standard HTML tag – wrapped in special ClickTale HTML comments. These ClickTale comments make sure that the script only runs inside ClickTale, so that the script will only be loaded where it’s needed (the API doesn’t need to run on the live page – it only needs to run inside ClickTale). The updated version of our basic HTML page now looks like this (notice the addition of our script at the bottom of the file):

Basic HTML page:

That’s it!

The page is properly set up now to display the desired state in the Aggregated Reports. Any Aggregated Report can now be opened and filtered using the ClickTale Event created here.

Important Notes


 * 1) The example page above (Basic HTML Page) does not include our tracking code. This code isn’t shown on the page for the sake of brevity. Please make sure that your live page does include our tracking code, so that it will be recorded (the API code is only responsible for showing the pop-up based on a ClickTale Event, it does not record the page).
 * 2) Our Aggregated Context API does not apply for our Session Player. In the example above, the pop-up will not be displayed when playing back a recorded session. To add support of dynamic content for our Session Player, please see the Active Playback API.
 * 3) The special HTML comments used in Step 3 above are part of the ClickTale ExcludeBlock API.
 * 4) Learn more about ClickTale Events here.