Knowledge base | mouseflow

Installation Guide

At Mouseflow, we try to keep it simple. In most cases, Mouseflow can be installed on your website in less than a minute.

Basic Installation

After you create an account, you'll receive a snippet of tracking code (JavaScript).

If you already have an account, you can retrieve the code from the website list or dashboard (by clicking the </> icon) or under Settings > Tracking Code once you open a specific website.

Here's an example:

<script type="text/javascript"> 
    window._mfq = window._mfq || [];
    (function() { 
        var mf = document.createElement("script"); 
        mf.type = "text/javascript"; mf.async = true; 
        mf.src = "//cdn.mouseflow.com/projects/123.js"; 
        document.getElementsByTagName("head")[0].appendChild(mf); 
    })(); 
</script>

To install Mouseflow, simply paste the entire code snippet to any page(s) you want to track before the closing body tag (</body>).

Note: This code snippet is just a sample. Please use the one from your account.

Mouseflow is loaded asynchronously, so it won't slow down or interrupt your site's rendering. We find that most clients install Mouseflow site-wide via their footer template or tag manager, though you can certainly limit it to specific pages if you wish.

Generating a Recording

After installation, browse to a page that has the code installed and click/move your mouse. Then, open the website in your Mouseflow account and click "Recordings" to view the first result.

Note: It can take a few minutes for the first recording(s) to appear; after that, Mouseflow will be near instantaneous.

Excluding Sensitive Data (PII)

If you collect sensitive data, you need to (a) exclude keystroke tracking for certain input fields, (b) disable keystroke for all input fields, or (c) exclude/replace content shown in the page source itself.

By default, Mouseflow excludes all password and credit card number fields automatically.

Blocking Yourself

If you want to exclude your own sessions, you can block IP addresses. This can either be individual IP addresses, a list of IP addresses, or an IP address pattern using wildcards (e.g. 11.22.* will block 11.22.33.44, 11.22.44.55, and so on).

You can also opt-out of being recorded using the cookie method on our public opt-out page. We recommend including a link to this page from your privacy policy, as well.

Advanced Installation

In some cases, you'll want to customize the installation for Mouseflow. We have a few different options, depending on your needs.

A/B Testing

If you run A/B tests on your site, it's useful to have separate heatmaps for each test variation (so you can compare the results).

You can indicate a custom heatmap (bucket) for each variation that data should flow into -- this is done with a simple variable:

<script type="text/javascript"> 
    var mouseflowPath = '/product-a';
    window._mfq = window._mfq || [];
    (function() { 
        var mf = document.createElement("script");
        mf.type = "text/javascript"; mf.async = true; 
        mf.src = "//cdn.mouseflow.com/projects/123.js"; 
        document.getElementsByTagName("head")[0].appendChild(mf); 
    })(); 
</script>

Each time this snippet runs, any data will be sent to the heatmap collection under /product-a.

You'll need to customize and add this code within your A/B testing tool, as part of the code for a variation.

Most A/B testing tools provide their own variable for a page variation. As such, it can be dynamically inserted:

<script type="text/javascript"> 
    var mouseflowPath = '/product-' + variationId;
    window._mfq = window._mfq || [];
    (function() { 
        var mf = document.createElement("script"); 
        mf.type = "text/javascript"; mf.async = true; 
        mf.src = "//cdn.mouseflow.com/projects/123.js"; 
        document.getElementsByTagName("head")[0].appendChild(mf); 
    })(); 
</script>

This assumes a variable called variationId is provided (by the A/B testing tool) that contains the unique ID associated with the variation. The end result would be var mouseflowPath = '/product-a'; or similar.

Note: It is important to include the forward slash in front of the mouseflowPath.

This is correct:

<script type="text/javascript"> 
    var mouseflowPath = '/correct';
</script>

This is not correct:

<script type="text/javascript"> 
    var mouseflowPath = 'notcorrect';
</script>

See this article for more information: Testing Multiple Versions of Website (A/B Testing)

Merging Several Pages Into One Heatmap

If your site has many pages that share a similar layout, it can be helpful to combine/aggregate data into a single heatmap. For example, e-commerce websites have category and product pages that have a similar structure: these are perfect candidates.

You can customize how pages are merged in under Settings > Advanced settings > Merge URLs (once you open a specific website in Mouseflow).

Custom Variables/Tagging

With Mouseflow, you can associate your own custom data with a recorded session. It's important to note that this feature cannot be used to push sensitive or personal information into Mouseflow. This is useful for any website that wants to find sessions by a data layer variable or order ID, for example.

To enable it simply add a line to the main tracking code to associate a key/value pair with the session.

<script type="text/javascript"> 
    window._mfq = window._mfq || [];
    (function() { 
        var mf = document.createElement("script"); 
        mf.type = "text/javascript"; mf.async = true; 
        mf.src = "//cdn.mouseflow.com/projects/123.js"; 
        document.getElementsByTagName("head")[0].appendChild(mf); 
    })(); 
    window._mfq.push(["setVariable", "KEY", "VALUE"]);
</script>

In this example, we tag a session with a key of KEY and a value of VALUE. In reality, a key might be order_id and a value might be 12345.

This feature can be extended for a variety of uses, as described in this article.

Mouseflow also has a number of built-in tags which are automatically applied to each session.

Single Page Applications

When Mouseflow loads, it detects all content present on the page.

In the case of a single page application, this content might change without the URL exhibiting any change at all.

It is important to notify Mouseflow that a new "virtual" page has been rendered -- this is done with a simple function call.

<script type="text/javascript">
    <strong>window._mfq.push(["newPageView"]);</strong>
</script>

Most clients add this function in a "before filter" or as part of their application's routing system. This ensures that it's called each time a page's content is changed.

See this for more information: Single Page Websites