ActivePlayback API

Overview
Modern web pages are dynamic. Where it used to be the case where a web page was a static page with listings of information, modern web pages are dynamic, including HTML changes using JavaScript and CSS, content delivery via AJAX, and more.

While ClickTale's standard tracking code can record static pages 'out-of-the-box', some additional coding might be required for recording dynamic changes on a web pages (varying from the opening of a simple drop-down menu to adding content with AJAX on one-page applications).

For example, if you have a drop-down menu that opens when the visitor hovers over it, and closes when the visitor moves the mouse away, this is a dynamic change on the web page that will not be recreated in the session (playback) player by default.

To record these dynamic HTML changes, ClickTale provides JavaScript API functions that allow you to record these changes, so that they will also be recreated in ClickTale's session player.

Currently, ClickTale provides two APIs for this:


 * 1) The ClickTaleExec API - Injecting dynamic functions into the recording by running the specific function through the API. (More examples)
 * 2) The ActivePlayback API - A method for web developers to easily re-create (simulate) user actions that took place on their web page, within the ClickTale session player.

This article discusses the ActivePlayback API, its implementation, its advantages and disadvantages.

The way this API works is by listening to user-browser actions - 'click', 'mouse-enter', 'key-press' and others - (Full list) during the recording of a visitor's session. Then, in the session player, these recorded events are re-triggered using JavaScript. This way, the playback matches the actions recorded in the live session. For example, if you want to record a 'click' on a button in your website, the ActivePlayback API will allow you to do so in a simple, none-obtrusive way.

While this method allows to easily recreate HTML changes on the web page, there are a few important notes to keep in mind when using this API:


 * ClickTale listens for DOM events on the document object, so proper event propagation is required when using this API.
 * DOM Events are re-triggered on the session-player – so if you use this API on a submit button - your server might get duplicate submissions.

Please review the following comparison table that can help you decide which API is best suited for your scenario:



Preparation
Before you can use this API, you need to make sure that it is available on your page. You do this by creating a new HTML script tag at the bottom of the page:

&lowast; Make sure to put this script at the bottom of your page, just below the 'ClickTale Bottom Part'

NOTE: The ‘ClickTaleContext’ object only exists inside ClickTale reports – making sure that the code only executes inside ClickTale. On the live page, ‘ClickTaleContext’ will always be ‘undefined’.

That's it for the preparation. You are now ready to move on to the next step – locating our HTML elements. 

Locating Elements
Now, suppose you have a button on your webpage, and you want to re-create the click event for that button, so that whenever the button is 'clicked' on your page, that click will be re-created in the playback.

Before you can do this, you need to know how to reference your button from the script. To find the properties of the button, or any other element on the page, you can use one of the following tools: 1. Using Firefox, right-click on your button, and click on Inspect Element.
 * Firefox "Inspect Element" context menu
 * Chrome "Inspect" context menu (or F12)
 * IE "Developer Tools" (F12)

2. This will bring up Firefox's HTML view below, and highlight your button.

3. You can see that your button has an ID, named 'MyButton'. It also has a class named 'BlueButton'. That's all you needed to know for this step. You will use them in the next step to select the button using JavaScript.

4. If your element does not have an ID or a class, please see Example No.1 in the Advanced Examples section, which shows how to group elements of the same type (like all ' ' tags for example).

Selecting Elements
Now that you have a way to reference your button (using its ID or class), you can add the code to your script that will select the button for later use in your JavaScript.

Your code now looks like this:

&lowast; I've named this JavaScript variable of the button 'Button', but you can name it anything you like.

Next, you'll see how to call the 'addEventSimulation' function, which will trigger a 'click' on your button.

Calling 'addEventSimulation'
The last step in using this API is to add a call to the 'addEventSimulation' function. Since this function takes 2 parameters, let's have a look at the function's signature:

 

HTMLElement is the element for which we want to simulate an event. In the example above, it would be the 'Button' variable created earlier.

Event is the event you want to simulate. In the example, this would be a 'click' event.

When you add the call to this function to your code, the complete script now looks like this:

1. Remember that you can only access the API through the 'ActivePlayback' object, which is why the code reads 'ActivePlayback.addEventSimulation'

2. Notice that for the 'Event' parameter, there is a specific syntax that prefixes the event that you want to simulate with a 'CT.' before the actual name of the event.

3. A complete list of available Events that can be used is included at the bottom of this guide, in the ClickTale Events Reference section.

This is the basic usage of the API.

In the next section, you will learn how to group together multiple elements using JavaScript arrays.

Grouping Elements with Arrays
In most real-world cases, there would be more than just a single element that you would need to record. This can be achieved easily, since the ActivePlayback API supports JavaScript arrays.

The way this would work is - you create an array, and then passing that array into the 'addEventSimulation' function as the first parameter HTMLElement.

The following example groups together all the HTML button elements. Let's have a look:

&lowast; More examples on how to group specific elements, using jQuery & CSS Classes, can be found in the Advanced Examples section

So with minimal coding, you've now setup your code to properly record all the buttons on your page.

Notes & Troubleshooting
So now that you know how to use 'addEventSimulation', here are a few simple but important guidelines to remember when using it:

1. Always make sure that your HTML elements exist on the page – before the API code is executed. The best practice for this is to simply add this code to the bottom of the page, just below the 'ClickTale Bottom Part'.
 * In cases where the HTML element is created dynamically – make sure to also dynamically include the API code after the HTML element was rendered on the page

2. Our tracking code listens to user-events at the document level. This means that event propagation should be enabled to allow the event to bubble up to the document level. This is the default behavior of events, but if you've setup your event-handlers to preventing propagation – you will not be able to use this API for that event, and you should use our 'ClickTaleExec' API instead.

3. Make sure that you are not trying to re-create a 'mouse-down' event – since a 'click' is different than a 'mouse-down'.
 * If this is the case, please change your 'mouse-down' event to a 'click' event.

4. One of the best ways to troubleshoot any technical issue is just going through a check-list.

Here's your check-list for this API:


 * Did you get the ActivePlayback object? (Preparation)
 * Do you know how to reference your HTML element? (Locating Elements)
 * Did you create a Javascript variable to select your HTML element? (Selecting Elements)
 * Did you call 'addEventSimulation' using the ActivePlayback object? (Calling 'addEventSimulation')
 * Is your HTML element on the page before the API is executed?
 * Does your event bubble-up to the document level? (Testing Event Propagation)

Advanced Examples
So now that we know how properly use & troubleshoot this API, it's time for some advanced examples.

Example No. 1: Selecting all HTML input elements

 * You can use this method to include any of the same HTML tags within one single call

Example No. 2: Using the API to re-create more than a single event

 * Here, the API is called twice. The first call re-creates the 'click' event. The second call re-creates the 'mouse-enter' event. You can use as many calls as you need.

Example No. 4: Using an array to group specific HTML elements

 * As you can see, the first parameter of the 'addEventSimulation' function can either be a single HTML element, or an array of HTML elements.


 * Another way of grouping together elements for in an array is by adding a custom CSS class to all the elements you want to group and use jQuery to select all the elements with that class. This is useful with elements that do not share the same class, or are not made up of the same HTML tag.

ClickTale Events Reference
The 'addEventSimulation' function supports the following events:


 * CT.mouseover
 * CT.mouseout
 * CT.mouseup
 * CT.mousedown
 * CT.click
 * CT.keydown
 * CT.keyup
 * CT.focus
 * CT.blur

Testing Event Propagation
Since this API relies on event propagation, it's useful to know how to test if a specific HTML element does bubble-up the event to the document.

You can use the following script to determine if your HTML element does this or not:

This snippet of code can help you determine event propagation for a 'click' event on any element.

Just run this script in Firebug's/Developer Tools console and then click on the element you want to test. If you see something like ' Propagation Found for: …. ' – you can use the API for that element.


 * You can use this same technique to test propagation of other events as well by replacing 'click' with the event you want to test (mouseenter, mousedown etc…).

Debugging your ActivePlayback code
If you have written code that uses the ActivePlayback API on your live or staging site, you should test the page in the following way:


 * 1) Make a recording of the page you have AP code in. You can test the API behavior only on the playback session.
 * 2) Go to your account on ClickTale
 * 3) Open the recording you just made
 * 4) Run the playback while using the browser's console or a tool like Firebug or Fiddler to monitor JS behavior on the page.
 * [[image:AP API debug.png|1000px|border]]

Alternatively, you can use Fiddler to insert the AP code directly into the playback window of a recording and test the code behavior without adding it to your live site.