Introduction

The Mouseflow JavaScript API allows you to engage with the Mouseflow recording script running on your website. This capability enables you to customize session recording parameters and augment visitor data, offering greater flexibility and control over tracking and analytics.

If you're looking for our server-side API, please see our REST API documentation.

The _mfq object

window._mfq = window._mfq || [];

The _mfq object is the entry point for all communication with the Mouseflow tracking script. Since the tracking script is loaded deferred you need to make sure the _mfq object is present before calling it. That's done my declaring it as an empty array if it's not declared already (see code to the right).

The array object acts like a queue for data that's intended to be associated with a visitor's Mouseflow session. Once the Mouseflow script fully loads and starts running, it takes all the data in the queue and adds it to the current recording. Any new commands pushed while the script is actively running will be handled immediately.

Data can be added to the queue using the JavaScript push() method.

_mfq.push([commandName, argument1, ..., argumentX]);

Adding custom data

Tagging a recording

_mfq.push(["tag", _tag]);

Tags in Mouseflow are labels used to track and categorize specific user actions or data on your website. A tag contains a string value that you define yourself and is added to a recording on the pageview level. They can then be used sort/filter various tools in Mouseflow to isolate specific segments of visitors.

Setting a custom variable

_mfq.push(["setVariable", _key, _value]);

Variables in Mouseflow are key/value pairs used to categorize specific data about a visitor's session. A custom variable contains two string values that you define yourself and is added to the top-level of a recording.

Each time a variable is set in a session, it will overwrite any previous values of the same key. If a variable is assigned KEY1, VALUE1 at the start of the session and is later changed to KEY1, VALUE2, the latter variable will overwrite the first instance of the same key.

If you want to set a variable and make sure it's never overwritten during the session, you can do so by adding the "session", false argument.

_mfq.push(["setVariable", _key, _value, "session", false]);

Identifying a visitor

_mfq.push(["identify", _userInfo]);

Using the identify feature, you can connect user-specific characteristics to a session, simplifying the process of locating users in your recording data.

Friction Events

Custom friction scores

_mfq.push(['addFriction', int, _eventName]);

Custom friction scores can be pushed to Mouseflow to help identify users who have had a bad experience on your website. Friction can be set with an integer value which represents the impact score, and a string value that identifies the triggering event's name.

You can learn more about Mouseflow's friction feature in this help article.

404 Friction

The 404 friction event is triggered for pages that '404'. This autodetection is handled in two ways:

• A check on page load to see if the initial files loaded throw a 404 server error.
• If the first case is not true, a second check is done to determine if the document.title contains the phrases "Not Found" or "404". This can be modified to override the second check to now look for any user defined string by checking the document.title

_mfq.push(['config', 'notFoundIdentifiers', ['Example Page']]); 

A 404 friction event can also be triggered manually: mouseflow.pageNotFound();

Dead-clicks

_mfq.push(['config', 'enableDeadClick', false]);

Default: true

This prevents dead-click events from being triggered for a session.

Virtual paths and pageviews

Setting a virtual path

_mfq.push(["config", "path", _virtualPath]);

By default, Mouseflow determines page paths by using the location.pathname value. However, the path displayed in recordings can be overwritten by pushing a virtual path.

Pushing a virtual pageview

_mfq.push(["newPageView", _virtualPath]);

When triggering a pageview, the recording's current pageview is immediately stopped and a new one begins. This is useful when you want to separate a recording's pages based on user actions.

For example, if a visitor clicks a certain button but your site's URL doesn't change, you can use a virtual pageview to instruct Mouseflow to record the user's next actions as if they were occurring on a different page.

Redefine an href value

window.mouseflowHref = "https://example.com";

This config allows you to redefine the href that Mouseflow will capture on a page, so that the real domain is never sent to Mouseflow.

Starting and stopping recording

Please note that the following section contains calls where you don't use the _mfq variable, instead it calls methods directly on the "mouseflow" global object. You should check if the object is available prior to calling it, to avoid throwing a javascript exception.

Disabling auto-start

_mfq.push(["config", "autoStart", false]);

If you don't want Mouseflow to start recording immediately when a user enters a page, you can set the "autoStart" configuration to false. When at some point you would like the recording to start, use the mouseflow.start() call which is explained below.

Start recording

mouseflow.start();

If the recording has been stopped or autostart has been set to false, this call will start recording the page.

Stop a recording

mouseflow.stop();

If a session is currently being recorded, this call can be used to stop the recording temporarily. This session can be resumed again using the call above.

End a recording

mouseflow.stopSession();

If a session is currently being recorded, this call can be used to stop the recording. This recording cannot be restarted again, a new recording will be created using the start call above.

Check if Mouseflow recording is currently recording

mouseflow.isRecording();

This call will return a boolean value that corresponds to whether Mouseflow is currently recording or not.

Getting Mouseflow recording data

Please note that the following section contains calls where you don't use the _mfq variable, instead it calls methods/values directly on the "mouseflow" global object. You should check if the object is available prior to calling it, to avoid throwing a javascript exception.

Get session ID

mouseflow.getSessionId();

A session id is a 32-character, alphanumeric string that allows you to identify a recorded session.

Sending this value to other web analytics tools via their own JavaScript APIs, enables you to easily cross-reference Mouseflow data with data from other platforms.

Get pageview ID

mouseflow.getPageViewId();

A pageview id is a 40-character, alphanumeric string that allows you to identify a specific pageview within a recording.

Get website ID

mouseflow.websiteId;

A website id is a 32-character, alphanumeric string that allows you to identify the website that is currently being recorded.

Get recording rate

mouseflow.recordingRate;

This returns an integer value, corresponding to the percentage of visitors that are recorded on the current page.

Check for returning visitor

mouseflow.isReturningUser();

This returns a boolean value, indicating whether the visitor is a returning site user or a new visitor.

To determine this, Mouseflow will look for a cookie named mf_user; if that cookie is not found Mouseflow will create it and count the user as visiting your site for the first time. On subsequent visits to your site, that cookie will be detected by Mouseflow and the visitor will be counted as a returning user. This is done simply by a yes/no toggle and no further information about the user is stored. This cookie has a lifetime of 90 days.

Custom form events

In the following snippets, formId serves as the identifier for the targeted form. The formId value should ideally be the unique identifier assigned by Mouseflow to your form in the application. To locate this ID, simply open the form report and copy the alphanumeric string found in the URL.

Alternatively, formId can be set as a valid CSS Selector, provided it is the same selector used by Mouseflow when generating a form report within the application.

Add form submit event

_mfq.push(["formSubmitAttempt", formId]);

This event tells the Mouseflow script that a visitor performed a submit action on a form within the page. This can be used in combination with the success and failure states below to enhance submissions detection.

Add form submit success event

_mfq.push(["formSubmitSuccess", formId]);

This event tells the Mouseflow script that a visitor successfully submitted a form within the page.

Add form submit failure event

_mfq.push(["formSubmitFailure", formId]);

This event tells the Mouseflow script that a attempted to submit a form but the submission was not successful

Advanced form configuration

window._mfq.push(['config', 'forms', [{
    formPath: '',
    redirectPath: '',
    result: ''
}]]);

By modifying the form configuration object, you can setup custom logic for determining form submission states.

window._mfq.push(['config', 'forms', [{
    formPath: '',
    redirectPath: '',
    target: {
        selector: '',
        text: ''
    },
    result: ''
}]]);

• Text does not need to be an exact match as it checks whether the element contains the text
• The element check will only run for 5 seconds. If the element does not appear within 5 seconds, the submit will not be detected.
• If you define a target, it must have a selector, however text is fully optional.

Form Submit Timeout

window.mouseflowRegisterSubmitTimeout = 2000;

Default: 2000 milliseconds

This will modify the amount of time that a form submit event will be listened for.

Advanced settings

Modify the timing of the HTML snapshot

_mfq.push(["config", "htmlDelay", _delayInMilliseconds]);

If content is missing from your static heatmaps, it may be because the Mouseflow heatmap snapshot is taken before all the content is visible on the page (by default: 1000 milliseconds). In order to resolve this, you can set a delay the HTML snapshot timing for your site.

Alternatively, if your site uses a large amount of dynamically loaded content, consider switching to our Live heatmap feature instead.

Disabling auto-tagging

_mfq.push(["config", "autoTagging", false]);

By default, Mouseflow will automatically tag sessions with relevant information pertaining to a user's visit to help isolate visitor segments. This automatic tagging functionality can be disabled using the code snippet to the right.

To learn more about built-in tags, visit this help article.

Enable Cross-domain Recording

window.mouseflowCrossDomainSupport = true;

Default: false

By enabling this config you can use the same Mouseflow Tracking Code on multiple domains. This can be useful if you have a visitor flow over multiple domains - usually if you have your checkout flow on a separate domain. This will capture recordings from both domains and combine them in one session. It will also begin to add the full domain name for each pageview, so you can easily tell the different domains apart inside the Mouseflow app. Note that you still have to add all domains on your settings page, and also install the Mouseflow tracking code on both domains.

Block 'Do not track' visitors

_mfq.push(['config', 'honorDoNotTrack', true]);

Default: false

This will prevent any vistor who has set the 'do not track' flag in their browser from being recorded on your site.