RFV Javascript SDK and API endpoint for loyalty scores

Marfeel exposes User RFV during a user session through the Marfeel Javascript SDK and via a REST API. Both methods return the composite RFV score along with its individual components: recency, frequency, and volume.

RFV via Javascript SDK

Compass exposes the RFV score of the user in session, and its components, in the frontend. Once marfeel-sdk has been loaded, retrieve the RFV via the compass instance by passing a callback function:

window.marfeel = window.marfeel || { cmd: [] };
window.marfeel.cmd.push(['compass', function(compass) {
  compass.getRFV((rfv) => {
       // { "rfv": 9.91, "r": 18, "f": 4, "v": 9 }
    }));
}]);

The callback receives an object containing the RFV score and its three components: recency (r), frequency (f), and volume (v).

RFV API endpoint

The RFV score is also available via Marfeel’s REST API. The endpoint requires your account ID and the specific user ID you want to query:

Endpoint: https://compassdata.mrf.io/rfv.php

Parameter	Explanation	Example
ac	Your account ID	107
u	The user ID	820c10f4-ec6c-40b4-9cb4-80db5025bbea

GET https://compassdata.mrf.io/rfv.php?ac=107&u=820c10f4-ec6c-40b4-9cb4-80db5025bbea

This endpoint returns the same object as the Javascript SDK callback, containing the RFV value and its components.

Sharing the RFV

Compass is compatible with the IAB Europe Transparency and Consent Framework (TCF). It automatically retrieves user choices regarding privacy as long as the website uses a TCF CMP.

More information: Compass and consent management

Sharing with Piano

If the reader has accepted personalization, you can share the RFV score calculated by Compass with other tools such as Piano. Use the Compass instance to map RFV segments to custom variables:

window.marfeel = window.marfeel || { cmd: [] };
window.marfeel.cmd.push(['compass', function(compass) {
  compass.getRFV(({rfv}) => {
        var userType;

        if (rfv <= 1) {
            userType = 'new';
        } else if (rfv <= 10) {
            userType = 'fly-by';
        } else if (rfv <= 35) {
            userType = 'casual';
        } else if (rfv <= 60) {
            userType = 'loyal';
        } else {
            userType = 'lover';
        }

        window.tp.push(["setCustomVariable", "compassEngagement", userType]);
    });
}]);

The snippet above classifies each user into one of five engagement segments (new, fly-by, casual, loyal, lover) based on their RFV score and passes the result to Piano via setCustomVariable.

---

How do I retrieve the RFV score using the Marfeel Javascript SDK?

Once marfeel-sdk has been loaded, call compass.getRFV() with a callback function. The callback receives an object containing the composite RFV score and its individual components: recency (r), frequency (f), and volume (v).

What parameters does the RFV API endpoint require?

The GET endpoint at https://compassdata.mrf.io/rfv.php requires two parameters: ac (your account ID) and u (the specific user ID). It returns the same RFV object as the Javascript SDK.

Can I share the RFV score with third-party tools like Piano?

Yes. If the reader has accepted personalization under a TCF-compliant CMP, you can map the RFV score to engagement segments (new, fly-by, casual, loyal, lover) and pass them to Piano using setCustomVariable.