Skip to content
  • There are no suggestions because the search field is empty.

Sending Convert Experiment Data to Heatmap.com

Track Convert.com experiment and variation data in Heatmap.com using JavaScript and custom attributes.

Author George F. Crewe

IN THIS ARTICLE YOU WILL:

Overview

This guide explains how to send Convert.com experiment and variation data to Heatmap.com. Because Heatmap.com is not natively supported out of the box, we use a custom JavaScript snippet to push the variation data as a custom attribute.

The Challenge: Race Conditions and Multiple Experiments

Convert.com typically loads synchronously in the <head> to prevent page flicker, while Heatmap.com loads asynchronously. This means Convert's experience.activated event will often fire before Heatmap.com has finished loading.

Additionally, users are often bucketed into multiple experiments simultaneously. The solution below uses a non-blocking retry loop that creates an independent queue for every active experiment, waiting patiently for Heatmap.com to initialize before pushing each payload without overwriting data.

1. Disable Data Anonymization Project Settings

By default, Convert masks experiment and variation names for privacy, which means third-party integrations will only receive numeric IDs. To send human-readable names to Heatmap.com:

  1. Go to your Convert.com dashboard and open your Project Configuration.
  2. Locate the Data Anonymization setting.
  3. Ensure it is disabled. This allows the API to read experience_name and variation_name.

2. Add the Integration Snippet Project Javascript

Copy the code below and paste it into your site's global <head> (after the Convert script) or directly into Convert's Project > Configuration > Global Project Javascript section.

window._conv_q = window._conv_q || [];

window._conv_q.push({
  what: 'addListener',
  params: {
    event: 'experience.activated',
    handler: function(event) {

      // Grab the names (or fallback to IDs if anonymization is on)
      var expName = event.data.experience_name || event.data.experience_id;
      var varName = event.data.variation_name || event.data.variation_id;

      // Set up a retry loop to wait for Heatmap.com to load async
      var maxRetries = 20; // Will try for up to 10 seconds (20 * 500ms)

      function sendToHeatmap() {
        if (typeof window.heatmap === 'function') {
          // Heatmap is ready!
          // The dynamic key ensures multiple active experiments don't overwrite each other.
          window.heatmap('set', 'Convert: ' + expName, varName);
        } else if (maxRetries > 0) {
          // Heatmap isn't ready yet, wait 500ms and try again
          maxRetries--;
          setTimeout(sendToHeatmap, 500);
        } else {
          console.warn('Heatmap.com library failed to load in time to log Convert.com variant.');
        }
      }

      // Kick off the check for this specific experiment
      sendToHeatmap();
    }
  }
});

3. Filter by Variant Dashboard

Because this script dynamically formats the custom attribute key as "Convert: [Your Experiment Name]", every concurrent experiment is tracked separately.

Once the code is live and your experiment is running:

  1. Log into your Heatmap.com dashboard.
  2. Navigate to Filters > Custom Attributes.
  3. Select any of your active Convert experiments from the attributes list to filter your heatmaps by specific variation names.

📒 Technical Note:

Is this script main-thread blocking?

No. The integration code uses setTimeout(), which is entirely asynchronous and non-blocking. It yields control back to the browser's main thread between every 500ms check. It will not freeze page rendering, nor will it negatively impact your site's performance or Core Web Vitals while waiting for Heatmap.com to load.