Track recirculation modules with the Marfeel SDK

Marfeel recirculation module tracking lets you measure impressions, viewability, and clicks on any module across your site. This applies to recirculation modules, internal navigation elements, and cross-domain traffic sources on the Marfeel platform.

Three ways to track recirculation modules

There are three methods to track recirculation modules, each suited to different implementation needs.

1. HTML attribute: data-mrf-recirculation

Add the data-mrf-recirculation attribute to any HTML element that contains a link. This works on any tag (<div>, <section>, <aside>, <ol>) and directly on <a> elements.

  <div data-mrf-recirculation="module-name">
    <!-- ... -->
    <a href="link">...</a>
    <!-- ... -->
  </div>

2. SDK method: compass.setRecirculationModules

Use the Marfeel JavaScript SDK to register modules without modifying page templates. This is useful when you cannot edit the site’s HTML directly, though a no-code recirculation experience is also available for non-technical teams.

  window.marfeel.cmd.push(['compass', function(compass) {
    compass.setRecirculationModules([
      { selector: '.module1', name: 'module1' },
      { selector: '.module2', name: 'module2' },
    ]);
  }]);

3. UTM parameter: utm_cmp_rs

Append the utm_cmp_rs parameter to the destination URL to track recirculation sources in cross-domain traffic and AMP next-page scenarios. This method registers the source for attribution but does not appear in the recirculation panel.

For example: https://destinationdomain.com/destination_url?utm_cmp_rs=amp-next-page

HubSpot redirect URL tracking

For HubSpot, configure the redirect URL tracking via the SDK by specifying the urlAttribute property:

  window.marfeel.cmd.push(['compass', function(compass) {
    compass.setRecirculationModules([
      {
        selector: '.module1',
        name: 'module1',
        urlAttribute: 'cta_dest_link'
      }
    ]);
  }]);

Subscribe to recirculation events

Recirculation events can be forwarded to third-party data warehouses using the Marfeel event listener API. Subscribe to all recirculation events with the following method:

window.marfeel.cmd.push(['events', (events) => {
  events.on('recirculation', (data) =>
    // send data
  );
}])

You can also filter events by specifying the module name:

window.marfeel.cmd.push(['events', function(events) {
  events.on('recirculation:module_name', function(data) {
    // send data
  });
}])

Module name must be the same as the one specified in data-mrf-recirculation attribute. For Marfeel experiences, this needs to be its ID, such as IL_XiZaB9H8TvyqINhX95lmOK.
Experience ID can be obtained from the browser's url while an experience is open in edit mode, like `https://hub.marfeel.com/experiences/IL_XiZaB9H8TvyqINhX95lmOK/edit/format`.

You can subscribe to all Inline or Flowcard experiences at once:

window.marfeel.cmd.push(['events', function(events) {
  events.on('recirculation:inline', function(data) {
    // send data
  });
  events.on('recirculation:flowcards', function(data) {
    // send data
  });
}])

Event data structure

The data object includes the module name, URL, and position index for each link. Events that occur at the same time are grouped together. The event type field (t) can be eligible, impression, or click.

{
  "t":"impression",
  "m":[
    {
      "n":"module_name_1",
      "e":[
        {
          "url":"https://www.domain.com/example-url-1",
          "p":"0"
        },
        {
          "url":"https://www.domain.com/example-url-2",
          "p":"1"
        },
        {
          "url":"https://www.domain.com/example-url-3",
          "p":"2"
        }
      ]
    },
    {
      "n":"module_name_2",
      "e":[
        {
          "url":"https://www.domain.com/example-url-4",
          "p":"0"
        },
        {
          "url":"https://www.domain.com/example-url-5",
          "p":"1"
        }
      ]
    }
  ]
}

Example: forward impression events to Google Analytics

To track impressions from a specific module and send them to Google Analytics:

window.marfeel.cmd.push(['events', function(events) {
    events.on('recirculation:my_module_name', function(data) {
        if (data.t === 'impression') {
            data.m.forEach(function(module) {
                var moduleName = module.n;
                module.e.forEach(function(event) {
                    ga.trackEvent(moduleName, event.url, event.p);
                });
            });
        }
    });
}]);

If your recirculation sources appear as anonymous “Internal” traffic, see recirculation troubleshooting for steps to identify and tag the correct modules.

What are the methods to track recirculation modules in Marfeel?

There are three methods: add the data-mrf-recirculation HTML attribute to a module containing links, use the Marfeel SDK compass.setRecirculationModules() method without modifying page templates, or append the utm_cmp_rs parameter to destination URLs for cross-domain and AMP tracking.

How do I subscribe to recirculation events in Marfeel?

Use the Marfeel event listener API: window.marfeel.cmd.push(['events', (events) => { events.on('recirculation', callback) }]). You can listen to all recirculation events or filter by module name using recirculation:module_name. Events include eligible, impression, and click types.

What data does a recirculation event contain?

Each event object includes the event type (eligible, impression, or click), an array of modules, and for each module the module name, URLs, and position index of each link. Events that occur at the same time are grouped together.