To start using Compass on your website, you only need to install our sdk. marfeel-sdk is a Javascript which allows you to integrate several marfeel products in your site and to interact with them.
In order to install it we provide a small Javascript snippet that can be placed anywhere on a page.
Copy this HTML snippet and replace 0 /*accountId*/ with your personal account ID:
<script type="text/javascript">
function e(e){var t=!(arguments.length>1&&void 0!==arguments[1])||arguments[1],c=document.createElement("script");c.src=e,t?c.type="module":(c.async=!0,c.type="text/javascript",c.setAttribute("nomodule",""));var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(c,n)}function t(t,c,n){var a,o,r;null!==(a=t.marfeel)&&void 0!==a||(t.marfeel={}),null!==(o=(r=t.marfeel).cmd)&&void 0!==o||(r.cmd=[]),t.marfeel.config=n,t.marfeel.config.accountId=c;var i="https://sdk.mrf.io/statics";e("".concat(i,"/marfeel-sdk.js?id=").concat(c),!0),e("".concat(i,"/marfeel-sdk.es5.js?id=").concat(c),!1)}!function(e,c){var n=arguments.length>2&&void 0!==arguments[2]?arguments[2]:{};t(e,c,n)}
(window,0 /*accountId*/,{} /*config*/);
</script>
This snippet creates two new script tags in your document for loading asynchronously marfeel-sdk. From the browser point of view, these two tags behave like just one, loading one or the other depending of the features implemented on it.
<script type="module" src="https://sdk.mrf.io/statics/marfeel-sdk.js?id=1234"></script>
<script nomodule src="https://sdk.mrf.io/statics/marfeel-sdk.es5.js?id=1234"></script>
Browsers that understand type=module should ignore scripts with a nomodule attribute. This allows us to serve the most minimal and performant code for most of the browsers while providing a fall-back to other browsers.
It’s the same ID you use for Google AMP and Facebook Instant Articles instrumentation.
Click to open to read the non-minified version of this snippet:
<script type="text/javascript">
function injectScript(src) {
var isModule = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : true;
var script = document.createElement('script');
script.src = src;
if (isModule) {
script.type = 'module';
} else {
script.async = true;
script.type = 'text/javascript';
script.setAttribute('nomodule', '');
}
var firstScript = document.getElementsByTagName('script')[0];
firstScript.parentNode.insertBefore(script, firstScript);
}
function load(window, id, userConfig) {
var _a, _b;
var _c;
(_a = window.marfeel) !== null && _a !== void 0 ? _a : window.marfeel = {};
(_b = (_c = window.marfeel).cmd) !== null && _b !== void 0 ? _b : _c.cmd = [];
window.marfeel.config = userConfig;
window.marfeel.config.accountId = id;
var resourcesPath = 'https://sdk.mrf.io/statics';
injectScript("".concat(resourcesPath, "/marfeel-sdk.js?id=").concat(id), true);
injectScript("".concat(resourcesPath, "/marfeel-sdk.es5.js?id=").concat(id), false);
}
(function (window, accountId) {
var clientConfig = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
load(window, accountId, clientConfig);
})(window, 0 /*accountId*/, {} /*config*/);
</script>
Single Page Application Support
If your site is a Single Page Application (SPA) or Progressive Web App (PWA) where the user changes page without triggering a native browser navigation event, you have to track new pageviews manually.
In the same script where you already track pageviews for your site, include a call to compass page tracking. You can access compass instance through marfeel SDK:
window.marfeel.cmd.push(['compass', function(compass) {
compass.trackNewPage();
}]);
And you’re set!
You can track a new page that appeared dynamically with infinite scroll, or any other method where the DOM refreshes without changing the URL.
If you need to pass a custom URL or a custom recirculation source you can do:
window.marfeel.cmd.push(['compass', function(compass) {
compass.trackNewPage({ url: CUSTOM_URL, rs: CUSTOM_INTERNAL_RECIRCULATION_SOURCE});
}]);
In the example below, articles dynamically loaded, would be attributed to Traffic Medium Internal, and traffic Source Infinite scroll :
window.marfeel.cmd.push(['compass', function(compass) {
compass.trackNewPage({rs: 'infinite scroll'});
}]);
MarfeelSDK Placement on the page
marfeel-sdk is entirely asynchronous, and you have complete freedom as to where to place it on your page.
You can add marfeel-sdk as a custom HTML tag with Google Tag Manager, or directly include it in your HTML pages with your other scripts.
Marfeel Compass works just as well anywhere it is placed on the page, and your pages’ performance doesn’t suffer in any case.
Canonical URL
Compass relies entirely on the canonical version of your site to extract information.
Every page that Compass tracks must have a link to its canonical version in the HTML head tag.
For example:
<link rel="canonical" href="https://www.newspaper.com/latest/article.html">
The canonical URL is the original URL of the page, that search engines use to reference your content.
AMP pages, Facebook Instant Articles and native apps must all contain this canonical link, pointing to the classic Web version of each page.
Sharing data across subdomains
The Marfeel SDK sets up 2 first-party cookies in the publisher domain. The first one stores user information like the unique user identifier, the registered user id when provided, the first visit time, the previous visit time or the original referrer. The second one is a temporal cookie to store session information like the visit start time, referrer domain and landing page. Read more about first and third party cookies used by Marfeel.
By default the user information is tracked at the root-domain level and shared across all sub-domains. This means that a user visiting domain.com and sub.domain.com will be considered the same user, sharing all the data points like the RFV.
The default behaviour can be changed specifying domain in the cookieDomain property of the configuration object:
<script type="text/javascript">
function e(e){var t=!(arguments.length>1&&void 0!==arguments[1])||arguments[1],c=document.createElement("script");c.src=e,t?c.type="module":(c.async=!0,c.type="text/javascript",c.setAttribute("nomodule",""));var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(c,n)}function t(t,c,n){var a,o,r;null!==(a=t.marfeel)&&void 0!==a||(t.marfeel={}),null!==(o=(r=t.marfeel).cmd)&&void 0!==o||(r.cmd=[]),t.marfeel.config=n,t.marfeel.config.accountId=c;var i="https://sdk.mrf.io/statics";e("".concat(i,"/marfeel-sdk.js?id=").concat(c),!0),e("".concat(i,"/marfeel-sdk.es5.js?id=").concat(c),!1)}!function(e,c){var n=arguments.length>2&&void 0!==arguments[2]?arguments[2]:{};t(e,c,n)}(window,0
/*accountId*/,{cookieDomain:'www.mywebsite.com'}/*config*/);
</script>
- When `cookieDomain` specifies a root domain (e.g. `mywebsite.com`), the data is shared among all its subdomains (e.g. `www.mywebsite.com` or `campaign.mywebsite.com`). This is also the default behavior.
Marfeel SDK Performance
The Marfeel SDK is built with performance in mind, and doesn’t affect pages’ smoothness.
CompassJS polls your page at specific intervals to gather information. The polls are fewer and further in-between as the reader spends more time on a page. Marfeel doesn’t actively listen to the reader’s scroll, avoiding unnecessary resource consumption.
Compass tracking network requests happens at the following times:
- Once when the page opens,
- Once 5 seconds later,
- Once 10 seconds after the second event,
- For the next 4 minutes, tracking events are sent every 15 seconds,
- If the reader is still on the page, any additional tracking event is sent every 20 seconds.
- Once right before the user leaves, as the page unloads
This polling strategy results in no impact on the user’s screen refresh rate, and a jank-free experience for the reader.
You can read in details what information is sent to Compass with each request.
Timing-allow-origin header
In case you want to audit and measure the Marfeel JS performance, Marfeel adds the Timing-Allow-Origin response header to all our resources.
The timing-allow-origin header specifies origins that are allowed to see values of attributes retrieved via features of the Resource Timing API, which would otherwise be reported as zero due to cross-origin restrictions.