Track conversions and subscriptions with the SDK

Q: How do I track a subscription conversion with the Marfeel SDK?

Invoke compass.trackConversion('subscribe') inside the window.marfeel.cmd queue. The SDK automatically infers context and calculates attribution models for the conversion.

Q: How do I prevent duplicate conversions on page reloads?

Pass a ConversionOptions object with a scope parameter. Use scope 'page' for once per page load, 'session' for once per session, or 'user' for once per user persisted in localStorage. You can also pass an explicit id (such as a transaction ID) to override scope-based deduplication.

Q: Can I track conversions without writing JavaScript?

Yes. Add the data-mrf-conversion attribute to any button, anchor, or form element. Compass registers a conversion automatically when the element is clicked or the form is submitted.

Marfeel allows tracking goals and conversions such as subscribing to a newsletter, signing up to the site, playing a video, or subscribing to a paywall. When you track a conversion, Marfeel automatically infers the context and calculates different attribution models for each event.

Subscriptions

To track a new subscription, invoke the trackConversion method:

window.marfeel = window.marfeel || { cmd: [] };
window.marfeel.cmd.push(['compass', function(compass) {
  compass.trackConversion('subscribe');
}]);

Registrations and generic goal tracking

You can track different conversions by providing different conversion names.

window.marfeel.cmd.push(['compass', function(compass) {
  compass.trackConversion('Newsletter Elections');
}]);

window.marfeel.cmd.push(['compass', function(compass) {
  compass.trackConversion('signup');
}]);

Automatic conversion tracking

Marfeel can automatically track conversions without custom JavaScript when a user interacts with specific HTML elements:

A user clicks on a <button> or <a> element
A user submits a <form>

For button and a elements, Compass registers a conversion when a click is triggered. For form elements, Compass registers a conversion when a submit is triggered.

Add the attribute data-mrf-conversion="nameOfTheConversion" to the element you want to track. Example:

<form data-mrf-conversion="newsletterSubscription">
  <input type="submit" value="Submit" />
</form>

<a href="/last-news" data-mrf-conversion="lastNews-header" />

<button class="btn btn-big icon–like" data-mrf-conversion="likeButton" />

For a no-code approach to conversion tracking based on URL targeting, see URL based conversions.

Conversion parameters

Conversion parameters are structured data points attached to a conversion that describe what exactly happened during a user interaction. They add context to conversions by capturing the specific details behind an action, turning a generic event into an analyzable signal.

By using conversion parameters, you can measure behavior with precision: which video was watched, which button drove the conversion, or which product was added to cart. This granularity is what makes conversions explainable, comparable, and optimizable.

Add a conversion parameter using the meta property to send additional contextual information as key-value pairs when tracking a conversion.

window.marfeel.cmd.push(['compass', function(compass) {
  compass.trackConversion('Newsletter Elections', {
    meta: {
      template: 'A',
      position: 'header'
    },
    value : 123
  });
}]);

The conversion above includes two conversion parameters:

template describes the template used
position indicates where it was added

Conversion parameters vs. dimensions and metrics

Conversion parameters gather raw data from a website or app. The data from conversion parameters feeds into dimensions and metrics, which are then available in reports, explorations, and other surfaces throughout Marfeel for analysis.

Deduplication and conversion options

By default, every call to trackConversion fires a new conversion, including on page reloads and repeated GTM triggers. To control this behavior, pass a ConversionOptions object as the second argument.

Syntax

window.marfeel = window.marfeel || { cmd: [] };
window.marfeel.cmd.push(['compass', function(compass) {
    compass.trackConversion('subscribe', {
        scope: 'user',
        id: 'optional-explicit-id'
    });
}]);

Parameters

Parameter	Type	Required	Description
scope	’none’ ‘page’ ‘session’ ‘user’	No	Controls deduplication. Defaults to ‘none’ (no dedup).
id	string	No	Explicit deduplication key. Overrides the ID derived from scope.

Scope behavior

Scope	Behavior
`none` (default)	No deduplication: fires on every call, including page reloads
`page`	Tracked at most once per page load
`session`	Tracked at most once per session
`user`	Tracked at most once per user, persisted across sessions in localStorage

Note:
If no `scope` or `id` is provided, every call to `trackConversion` will be recorded as a new conversion. This includes cases where the pixel is triggered on page reload or by repeated GTM tag executions. Set `scope: 'session'` or `scope: 'user'` to avoid counting the same conversion multiple times.

Using an explicit id

If you already have a unique identifier for the conversion (such as a transaction ID or subscription ID from your backend), pass it directly via id. This takes precedence over scope:

compass.trackConversion('subscribe', {
    id: 'txn-abc123',
    value: 9.99
});

Legacy syntax

Passing a plain string as the second argument is still supported and is treated as the initiator:

// Legacy — equivalent to { initiator: 'cta-banner' }
compass.trackConversion('subscribe', 'cta-banner');

GTM implementation notes

When the Marfeel SDK is loaded via Google Tag Manager rather than hardcoded on the page, a race condition can occur where the conversion tag fires before the SDK has initialized. The window.marfeel.cmd queue prevents this: calls pushed to the queue are executed once the SDK is ready.

Always wrap conversion calls in the queue pattern, regardless of load order:

window.marfeel = window.marfeel || { cmd: [] };
window.marfeel.cmd.push(['compass', function(compass) {
    compass.trackConversion('subscribe', { scope: 'session' });
}]);

Do not call compass.trackConversion() directly outside of cmd.push when using GTM, as the SDK may not yet be available.

How do I track a subscription conversion with the Marfeel SDK?

Invoke compass.trackConversion('subscribe') inside the window.marfeel.cmd queue. The SDK automatically infers context and calculates attribution models for the conversion.

How do I prevent duplicate conversions on page reloads?

Pass a ConversionOptions object with a scope parameter. Use scope page for once per page load, session for once per session, or user for once per user persisted in localStorage. You can also pass an explicit id (such as a transaction ID) to override scope-based deduplication.

Can I track conversions without writing JavaScript?

Yes. Add the data-mrf-conversion attribute to any button, anchor, or form element. Compass registers a conversion automatically when the element is clicked or the form is submitted.