Integrate Convert Experiences with Microsoft Clarity

This Article Will Help You:

• Convert-Microsoft Clarity Integration
• Sign Up at the Clarity Website
• Add Tracking Code Snippets
• Enable Microsoft Clarity for a specific experience
• Understand how the experience-level toggle works
• View Convert Data in Clarity Dashboard
• Use the manual setup only if needed

Convert-Microsoft Clarity Integration

Convert Experiences can integrate with Microsoft Clarity and this integration offers session replays and heatmaps per experience. Replaying sessions per variation is important for any agency and conversion rate optimization expert.

For each experiment, the integration uses custom instrumentation events to pass along the experiment name and variation name that the visitor is currently bucketed into.

Microsoft Clarity can now also be enabled directly from the Convert app by using the Microsoft Clarity toggle at the experience level. When this toggle is enabled, Convert handles the Clarity integration automatically for that experience.

Sign Up at the Clarity Website

Sign up at the Clarity website using your Microsoft or Facebook or Google account. 

When you create a new Clarity project you will be able to retrieve the uniquely generated JavaScript code for your project. 

Clarity works on any HTML webpage (desktop or mobile) after adding this small piece of JavaScript to the website. As soon as the script is added, Clarity receives your site’s data and you can start using Clarity.

The JavaScript code listens to browser events and instruments layout changes, network requests and user interactions. That data is then uploaded and stored in the Clarity server running on Microsoft Azure. 

Add Tracking Code Snippets

Make sure the Convert tracking code and the Clarity JS code are installed on your page. Once you have added the codes to your website, you will be able to use the Clarity dashboard to start replaying user sessions and gain insights.  

If you are using the in-app Microsoft Clarity toggle, you do not need to manually paste an additional Convert-to-Clarity integration script into Global Project Javascript. The toggle handles that automatically for the selected experience.

Enable Microsoft Clarity in your Convert experience

To enable the integration using the new workflow, open the experience where you want to send data to Microsoft Clarity and turn on the Microsoft Clarity toggle in the Integrations area.

Once the toggle is enabled, Convert automatically sends the relevant experience data for that experience to Microsoft Clarity. No manual integration code is required for this setup.

This integration applies only to experiences where the Microsoft Clarity toggle is enabled. Other experiences in the same project will not send Clarity integration data unless Microsoft Clarity is enabled for them as well.

This update replaces the previous default workflow where users had to add code manually in Global Project Javascript just to make the integration work.

How the experience-level toggle works

When Microsoft Clarity is enabled inside a specific experience, the tracking script uses the serving configuration for that experience and auto-enables the Clarity integration for that experience only.

This resolves the previous issue where adding the article’s manual code to Global Project Javascript could create Clarity tags for all experiences in a project instead of only the experiences where the integration was intended to be enabled.

If you want the integration only on selected experiences, use the experience-level Microsoft Clarity toggle instead of the project-wide manual code method.

View Convert Data in Clarity Dashboard

Using a custom tag in Clarity, you will be able to view all of your Convert Experiences data as they associate to the values that you pass in the tag. 

After enabling the Microsoft Clarity toggle for an experience, verify the integration by visiting a page where the experience runs and then reviewing the corresponding Clarity session data.

Alternative manual setup using Global Project Javascript

Note: because this code is added at the project level, it may affect all qualifying experiences in the project rather than only a single experience. If you need experience-specific control, use the in-app Microsoft Clarity toggle instead.

Manual Convert-Clarity Integration

Add the following code to your Project Configuration > Global Project Javascript only if you need the manual fallback method:

// Function to handle the data sending to another platform

function sendDataToPlatform(data) {

    if (typeof clarity === "function") {

        data.forEach(item => {

            clarity("set", "Exp_Name", item.expName);
            clarity("set", "Var_Name", item.varName);

            // console.log("Sent data to platform: Exp_Name =", item.expName, "Var_Name =", item.varName);

        });

    } else {

        console.error("Clarity function is not available.");

    }

}

// Function to check if a library (e.g., Clarity) is loaded, with a timeout

function whenAvailable(name, callback) {

    const maxTime = 5000;
    const interval = 100;
    let elapsedTime = 0;

    const intervalId = setInterval(() => {
        elapsedTime += interval;

        if (window[name]) {
            clearInterval(intervalId);
            callback();
        } else if (elapsedTime >= maxTime) {
            clearInterval(intervalId);
            console.error(name + " did not load within the allowed time.");
        }
    }, interval);

}

window._conv_q = window._conv_q || [];
window._conv_q.push({
    what: "addListener",
    params: {
        event: "snippet.experiences_evaluated",
        handler: function() {
            whenAvailable("clarity", function() {
                var refObject = window["convert"]["data"]["experiments"];
                var platformData = [];

                for (var key in window["convert"]["currentData"]["experiments"]) {
                    if (!window["convert"]["currentData"]["experiments"].hasOwnProperty(key)) {
                        continue;
                    }

                    var currentExperiment = window["convert"]["currentData"]["experiments"][key];
                    var curExperimentName = refObject[key] && refObject[key].n ? refObject[key].n : "unknown experiment name";
                    curExperimentName = curExperimentName.replace("Test #", "Test ");

                    var curVariant = currentExperiment["variation_name"] ? currentExperiment["variation_name"] : "unknown variant";
                    curVariant = curVariant.replace("Var #", "Variation ");

                    platformData.push({
                        expName: curExperimentName,
                        varName: curVariant
                    });
                }

                sendDataToPlatform(platformData);
            });
        }
    }
});