Home
compass
instrumentation

# Adding CompassJS to your site

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.

WARNING

Remember to replace the 0 /*accountId*/ with your account ID!

It's the same ID you use for Google AMP and Facebook Instant Articles instrumentation.

You can open the following block to read the non-minified version of this snippet:

Click to open

<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:

WARNING

You should only call this method when a page is loaded dynamically, not in the first page

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 (opens new window), 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.

Compass uses cookies to store information like the user id, the first visit or the original referer. By default, that information is shared among subdomains (e.g. mywebsite.com, www.website.com, eng.website.com, etc.) but this can be avoided by setting a specific 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>

WARNING

When cookieDomain is filled with a subdomain (e.g.en.mywebsite.com), the data is not shared with sibling domains like www.mywebsite.com, it.mywebsite.com nor the root domain (mywebsite.com).
When cookieDomain is filled with the 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 behaviour.

# Recommended Ads Tracking method

Ads are tracked automatically by Compass, but in some cases and depending on the order that you are loading the scripts, some ads can be loaded way before Compass is ready and won't be tracked. In order to address that what is recommended is to create the following script before any ad script:


<script type="text/javascript">
    window.googletag = window.googletag || { cmd: [] };
    window.marfeel = window.marfeel || { cmd: [] };
	
    googletag.cmd.push(function () {
        googletag.pubads().addEventListener('slotRenderEnded', function (event) {
            if (!event.isEmpty) {
                window.marfeel.cmd.push(['compass', function (compass) {
                    compass.trackAdEvent('slotRenderEnded', event.slot);
                }]);
            }
        });
        googletag.pubads().addEventListener('slotVisibilityChanged', function (event) {
            window.marfeel.cmd.push(['compass', function (compass) {
                compass.trackAdEvent('slotVisibilityChanged', event.slot);
            }]);
        });
    });
</script>

This way when ads are loaded compass (even if it's not loaded yet) will have all this information. And in order to tell Compass that ads are counted by an external script we have to add adsTrackingFromClient: true to the configuration:

<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*/,{adsTrackingFromClient:true}/*config*/);
</script>

WARNING

Remember to replace the 000 with your own account ID!

It is the same ID that you use for AMP and FIB instrumentation.

# Interstitial Ads tracking

Interstitial ads need special coding for proper tracking. Compass needs to know which slot contains the interstitial, so we need to set it up.

<script type="text/javascript">
    window.googletag = window.googletag || { cmd: [] };
    window.marfeel = window.marfeel || { cmd: [] };
	
    let interstitialSlot;

    googletag.cmd.push(function () {
        // Define a web interstitial ad slot.
        interstitialSlot = googletag.defineOutOfPageSlot('YOUR_INTERSTITIAL_SLOT', googletag.enums.OutOfPageFormat.INTERSTITIAL);

        if (interstitialSlot) {
            interstitialSlot.addService(googletag.pubads());
            window.marfeel.cmd.push(['compass', function (compass) {
                compass.setInterstitialSlot(interstitialSlot);
            }]);
        }
    });
</script>

Obviously, we can use this method in conjunction with personalized ad tracking, as mentioned in previous chapters.

# ads AmpFirst

If your site is AmpFirst and you are using the javascript tracker instead of the amp-analytics one you'll need to add the isAmpFirst flag to the configuration in order to track amp-ads:

<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*/,{isAmpFirst:true}/*config*/);
</script>

In order to track properly the ads is recomended to add the parameter data-vars-ad-slot to the amp-ad with the slotname information.

<amp-ad width="300" height="250" type="foo" ad-slot="SLOTNAME" data-vars-ad-slot="SLOTNAME">
	 <div placeholder>Loading ...</div>
</amp-ad>

# Scroll tracking

Compass measures how far down on the page the reader has gone. In order to decide what the end of an article is compass will calculated based on the following preferences:

A visible tag with the class mrf-article-body.
A visible tag with tagName <article> (only applicable if there is only one of those).
The whole body of the page.

# CompassJS Performance

The CompassJS Pixel is built with performance in mind, and doesn't affect pages' smoothness.

Indeed, it doesn't actively listen to the reader's scroll, avoiding unnecessary resource consumption. Instead, 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.

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.

← ⬅︎ Back to Main Menu User Subscriber Status →

# Adding CompassJS to your site

# Single Page Application Support

# MarfeelSDK Placement on the page

# Canonical URL

# Sharing data across subdomains

# Recommended Ads Tracking method

# Interstitial Ads tracking

# ads AmpFirst

# Scroll tracking

# CompassJS Performance