Crazy Egg allows you to customize its tracking behavior in a wide variety of ways using Javascript:

  • Alter the click data that is sent to Crazy Egg to match your specific needs.
  • Track “virtual elements”, regions of the page whose size, position and other properties are entirely determined by you.
  • Tell our tracking script to ignore certain parts of the page (so that you can track them yourself).

Tracking clicks yourself

The CE2.click function can be used to send click data to Crazy Egg. This function can be called in a number of ways:

CE2.click(element, x, y)

element: Either a DOM element or a virtual element
x: The x-coordinate of the click, relative to element
y: The y-coordinate of the click, relative to element

CE2.click(element, event)

element: Either a DOM element or a virtual element
event: A mouse event from element or one of its sub-elements; the x and y coordinates of the click will be derived from the event object

CE2.click(element)

element: Either a DOM element or a virtual element
(The click will be placed in the center of the element.)

Virtual elements

A virtual element is a rectangular region of the page that you define and track as if it were a regular page element.

Virtual elements might be employed to improve the tracking of clicks inside of an interactive Flash clip or <canvas> element.  Suppose you had a Flash video clip with play, pause, and rewind buttons. Normally all clicks on that clip would just be identified the same way, no distinction would be made between clicks on the different buttons it contained. If you were to set up an event handler so that, for instance, a click on the play button resulted in a call to CE2.click, Crazy Egg could track clicks on that button as if it were a normal HTML element. Click data specifically for the video control buttons would appear in the overlay and list views.

Virtual element can be defined by passing a Javascript object as the first argument to CE2.click.

var myElement = {
  // required fields
  left: 100,
  top: 120,
  width: 550,
  height: 400,

  // optional fields
  id: "unique_id",
  ceid: "unique_id",
  name: "human-readable name",
  data: "arbitrary string",
  parentID: "id_of_containing_element"
}
  • left, top, width, and height properties specify the size and absolute position of the virtual element and are required.
  • id has the same meaning as the HTML attribute of the same name; it should be unique to the page
  • ceid forces Crazy Egg to identify an element using only the ceid, ignoring any other property
  • name specifies exactly the name of this element in the list view of your report
  • data is any arbitrary data you want to provide that might help distinguish this element from another similar element
  • parentID is the ID of the parent element, if it has one

Caution: If you provide a parentID, the top and left properties must be relative to the position of the parent

Preventing default click tracking behavior

You can tell Crazy Egg to ignore certain elements with the CSS class -ce-ignore. Simply assign this class to an element and our script will not track clicks on it or its contents:

<p class="-ce-ignore">
 Neither <em>this</em> paragraph,
 nor its <a href="a">child</a>
 <a href="b">elements</a>, will be
 <a href="c">tracked</a>.
</p>

If your element already has a class attribute, you can just add -ce-ignore as an additional CSS class:

<div class="sidebar -ce-ignore">
...
</div>

You can also mark elements as ignored via Javascript:

function CE_READY() {
  var el = document.getElementById('ignore-me');
  CE2.ignore(el);
}

Caution: There is a risk of creating duplicate click data when you are implementing your own tracking behavior. Two clicks could be tracked for each real click from a visitor: one by your custom code and another by the default Crazy Egg click handler.

Other useful functions

The Crazy Egg tracking script provides a few utility functions that you can employ to help you implement custom tracking behaviors.

CE2.getBox(element)

element: A DOM element

Returns an object describing the size and absolute position of element. Example:
{left: 353, top: 1114, width: 426, height: 36}

CE2.listen(target, event, function)

target: A DOM element
event: Name of the event to listen for, e.g. “click”, “keyup”, “load”, etc.
function: The function to call when the event occurs

This is a very simple method of registering event handlers. Unlike a full-featured Javascript framework, this function passes only native event objects to the hander. Do not expect your event handlers to receive wrapped, normalized event objects. Use a full-featured Javascript framework if you require that feature. This function should suffice, however, if all you want to do is pass the event object to CE2.click.

A simple example

Suppose a page you are tracking displays three randomly selected images. Because a visitor to your page will almost always get a different set of images from those that the Crazy Egg agent saw when it took a snapshot of your page, only a portion of the clicks on those random images will appear in your heatmap and confetti reports. (Data for all clicks would still be available in the overlay and list views.)

You can use the Javascript API to work around this limitation and see the position of all clicks on all random images. One approach is to interrupt the normal click-tracking behavior on the images in question. The sample code below changes which page element was reportedly clicked. Any click on a random image will be tracked as if it had actually occurred on the containing element.

Why do this? Because a click on a “known” element (one that was recorded in the page snapshot) will always show up in the heatmap and confetti views. The images’ parent tag (the <div> tag in the following HTML snippet) is an element that we can be sure is a known element, unlike the randomly-selected images it contains. By associating clicks on the images with their parent element instead, we are ensuring that those clicks will appear on the heatmap and confetti views regardless of which image was actually clicked.

HTML:

<div id="random_images" class="-ce-ignore">
  <!-- these images are randomly selected -->
  <a href="image_3432"><img src="image_3432.jpg" /></a>
  <a href="image_9239"><img src="image_9239.jpg" /></a>
  <a href="image_1244"><img src="image_1244.jpg" /></a>
</div>

Javascript:

<script type="text/javascript">
function CE_READY() {
  // get a reference to the random_images element
  var imageContainer = document.getElementById("random_images");

  // define the click event handler
  var handler = function(event {
    // record the click as if it occurred on imageContainer
    // even if it actually occured on one of the images
    CE2.click(imageContainer, event);
  }

  // register the handler
  CE2.listen(imageContainer, "click", handler);
}
</script>