Opt-out or Opt-in

Boomerang is an open source JavaScript library that measures a web site’s performance. As such it is considered in some countries in the EU and Asia as “cookie technology” and triggers certain data protection requirements. Such requirements vary depending on the categorization of cookie technology used for website performance measurement by local authorities. Some authorities require consent by end users to the cookie technology prior to its placement on a website ("opt-in"). According to GDPR and other applicable laws, such consent must be freely given, specific, informed and unambiguous. Some authorities accept the placement of cookie technology on a website without consent and require the implementation of a mechanism to stop the cookie usage once the end user requests so ("opt-out"). Such setup is e.g. accepted under CCPA, the California Consumer Privacy Act that entered into force January 1, 2020.

This tutorial describes techniques and configurations that help Boomerang users to instrument opt-out and opt-in scenarios. In addition the tutorial describes how to instrument 3 different consent management techniques via special Consent Inlined Plugin, a Boomerang Loader Wrapper and the Osano Cookies Consent library.

Tutorial structure:

1. Opt-out and Opt-in scenarios
2. Cookies and Local Storage
3. Consent Inline Plugin Overview
   1. Opt-out example
   2. Opt-in example
4. Opt-in with Boomerang Loader Wrapper
5. Cookie Consent library and Consent Inline Plugin example
   1. Opt-out example
   2. Opt-in example

1. Opt-out and Opt-in scenarios

We identified 3 common scenarios how Boomerang could be loaded to comply with the applicable data protection requirements.

• Opt-out from Boomerang: By default Boomerang is loaded on the page and sends performance data. Boomerang will be disabled and the Boomerang cookies will be deleted if a visitor opts-out from Boomerang through Cookie Consent popup.

• Opt-in to Boomerang (Boomerang loaded before opt-in): By default Boomerang is loaded on the page and does NOT send performance data. Performance data will be sent after a visitor opts-in to Boomerang through a Cookie Consent popup.

* cip.in, cip.v parameters are being sent on first beacon after opt-in and they indicate that visitor opted-in and Consent Inlined Plugin version.

• Opt-in to Boomerang (Boomerang loaded after opt-in): Boomerang will be loaded and performance data sent after only after a visitor opts-in to Boomerang through the Cookie Consent popup.

2. Cookies and Local Storage

2.1 Cookies

List of cookies created and used by Boomerang:

For detailed information about what data is kept on the cookies listed above, please read the "Cookies" section of Boomerang documentation page.

2.2 Local Storage (mPulse users specific)

For mPulse customers, in some instances Boomerang will persist data in Browser's Local Storage. In these instances a Local Storage is used for performance optimization and reduction of network round trips.

List of local storage keys used by Boomerang:

3. Consent Inline Plugin

The Consent Inline Plugin is not part of the Boomerang build but it could be easily injected before Boomerang code which will make the plugin available. The plugin provides 2 helper functions window.BOOMR_OPT_OUT() and window.BOOMR_OPT_IN() that can be used for instrumenting opt-out and opt-in.

When window.BOOMR_OPT_OUT() is called Boomerang will stop sending beacon data, RT and BA cookies will be deleted and the new special BOOMR_CONSENT cookie with value opted-out will be created.

Consent Inline Plugin has the capability to instruct Boomerang to hold beacon sending until window.BOOMR_OPT_IN() is called. When window.BOOMR_OPT_IN() is called a cookie BOOMR_CONSENT with value opted-in will be created.

The purpose of BOOMR_CONSENT cookie is to "tell" Boomerang what was the visitor's consent choice when a visitor navigates to a new page.

3.1 Opt-out allowed example

In case we would like to allow website visitors to opt-out from Boomerang we must follow the steps in this order:

1. Inject Consent Inline Plugin configuration:

<script>
window.BOOMR_CONSENT_CONFIG = {
     enabled: true
};
</script>

2. Inject Consent Inline Plugin code:

<script>
!function(o){"use strict";if(void 0!==o.BOOMR_CONSENT_CONFIG&&!0===o.BOOMR_CONSENT_CONFIG.enabled){o.BOOMR=void 0!==o.BOOMR?o.BOOMR:{};var i=o.BOOMR;i.plugins=void 0!==i.plugins?i.plugins:{};if(!i.plugins.ConsentInlinedPlugin){var n={v:"1",OPT_COOKIE:"BOOMR_CONSENT",OPT_IN_COOKIE_VAL:"opted-in",OPT_OUT_COOKIE_VAL:"opted-out",COOKIE_EXP:31536e3,complete:!1,enabled:!0,firedPageReady:!1,deferredOptIn:!1,deferredOptOut:!1,rtCookieFromConfig:!1,bwCookieFromConfig:!1,optOut:function(){if(!i.utils.setCookie(n.OPT_COOKIE,n.OPT_OUT_COOKIE_VAL,n.COOKIE_EXP)){i.error("Can not set Opt Out cookie","ConsentInlinedPlugin");return!1}"function"==typeof i.disable&&i.disable();n.complete=!1;n.removeBoomerangCookies();return!0},optIn:function(){if(!0===n.complete)return!0;if(!i.utils.setCookie(n.OPT_COOKIE,n.OPT_IN_COOKIE_VAL,n.COOKIE_EXP)){i.error("Can not set Opt In value","ConsentInlinedPlugin");return!1}"function"==typeof i.wakeUp&&i.wakeUp();n.complete=!0;i.addVar("cip.in","1",!0);i.addVar("cip.v",n.v,!0);i.sendBeacon();return!0},removeBoomerangCookies:function(){var e=n.rtCookieFromConfig||"RT",o=n.bwCookieFromConfig||"BA";i.utils.removeCookie(e);i.utils.removeCookie(o)},onPageReady:function(){n.firedPageReady=!0;n.deferredOptIn&&n.optIn();n.deferredOptOut&&n.optOut()}};o.BOOMR_OPT_OUT=function(){n.firedPageReady?n.optOut():n.deferredOptOut=!0};o.BOOMR_OPT_IN=function(){n.firedPageReady?n.optIn():n.deferredOptIn=!0};i.plugins.ConsentInlinedPlugin={init:function(e){void 0!==e.RT&&void 0!==e.RT.cookie&&(n.rtCookieFromConfig=e.RT.cookie);void 0!==e.BW&&void 0!==e.BW.cookie&&(n.bwCookieFromConfig=e.BW.cookie);i.subscribe("page_ready",n.onPageReady,null,n);if(o.BOOMR_CONSENT_CONFIG.optInRequired&&i.utils.getCookie(n.OPT_COOKIE)!==n.OPT_IN_COOKIE_VAL){n.complete=!1;return this}if(i.utils.getCookie(n.OPT_COOKIE)===n.OPT_OUT_COOKIE_VAL){void 0===e.RT&&(e.RT={});e.RT.cookie="";void 0===e.BW&&(e.BW={});e.BW.cookie="";n.complete=!1;return this}n.complete=!0;return this},is_complete:function(){return n.complete}}}}}(window);
</script>

3. Load Boomerang via loader snippet.
4. Call window.BOOMR_OPT_OUT() when visitor opts-out via Cookie consent popup or other UI element.

3.2 Opt-in required example

When we would like to not send Beacon data until visitor opts-in to Boomerang we must follow the steps in this order:

1. Inject Consent Inline Plugin configuration:

<script>
window.BOOMR_CONSENT_CONFIG = {
     enabled: true,
     optInRequired: true
};
</script>

2. Inject Consent Inline Plugin code:

<script>
!function(o){"use strict";if(void 0!==o.BOOMR_CONSENT_CONFIG&&!0===o.BOOMR_CONSENT_CONFIG.enabled){o.BOOMR=void 0!==o.BOOMR?o.BOOMR:{};var i=o.BOOMR;i.plugins=void 0!==i.plugins?i.plugins:{};if(!i.plugins.ConsentInlinedPlugin){var n={v:"1",OPT_COOKIE:"BOOMR_CONSENT",OPT_IN_COOKIE_VAL:"opted-in",OPT_OUT_COOKIE_VAL:"opted-out",COOKIE_EXP:31536e3,complete:!1,enabled:!0,firedPageReady:!1,deferredOptIn:!1,deferredOptOut:!1,rtCookieFromConfig:!1,bwCookieFromConfig:!1,optOut:function(){if(!i.utils.setCookie(n.OPT_COOKIE,n.OPT_OUT_COOKIE_VAL,n.COOKIE_EXP)){i.error("Can not set Opt Out cookie","ConsentInlinedPlugin");return!1}"function"==typeof i.disable&&i.disable();n.complete=!1;n.removeBoomerangCookies();return!0},optIn:function(){if(!0===n.complete)return!0;if(!i.utils.setCookie(n.OPT_COOKIE,n.OPT_IN_COOKIE_VAL,n.COOKIE_EXP)){i.error("Can not set Opt In value","ConsentInlinedPlugin");return!1}"function"==typeof i.wakeUp&&i.wakeUp();n.complete=!0;i.addVar("cip.in","1",!0);i.addVar("cip.v",n.v,!0);i.sendBeacon();return!0},removeBoomerangCookies:function(){var e=n.rtCookieFromConfig||"RT",o=n.bwCookieFromConfig||"BA";i.utils.removeCookie(e);i.utils.removeCookie(o)},onPageReady:function(){n.firedPageReady=!0;n.deferredOptIn&&n.optIn();n.deferredOptOut&&n.optOut()}};o.BOOMR_OPT_OUT=function(){n.firedPageReady?n.optOut():n.deferredOptOut=!0};o.BOOMR_OPT_IN=function(){n.firedPageReady?n.optIn():n.deferredOptIn=!0};i.plugins.ConsentInlinedPlugin={init:function(e){void 0!==e.RT&&void 0!==e.RT.cookie&&(n.rtCookieFromConfig=e.RT.cookie);void 0!==e.BW&&void 0!==e.BW.cookie&&(n.bwCookieFromConfig=e.BW.cookie);i.subscribe("page_ready",n.onPageReady,null,n);if(o.BOOMR_CONSENT_CONFIG.optInRequired&&i.utils.getCookie(n.OPT_COOKIE)!==n.OPT_IN_COOKIE_VAL){n.complete=!1;return this}if(i.utils.getCookie(n.OPT_COOKIE)===n.OPT_OUT_COOKIE_VAL){void 0===e.RT&&(e.RT={});e.RT.cookie="";void 0===e.BW&&(e.BW={});e.BW.cookie="";n.complete=!1;return this}n.complete=!0;return this},is_complete:function(){return n.complete}}}}}(window);
</script>

3. Load Boomerang via loader snippet.
4. Call window.BOOMR_OPT_IN() when a visitor opted in via Cookie consent popup or other UI element.

4. Opt-in with Boomerang Loader Wrapper

Users of Boomerang open source and some mPulse customers have to manually inject Boomerang on the page. This opens a possibility of waiting for the Boomerang loader snippet to be executed until after a visitor opts-in to Boomerang through Cookie Consent popup. By doing so, Boomerang won't be loaded until after opt-in has been chosen.

This technique is simple and can be done in 2 steps:

1. Wrap Boomerang loader snippet in BOOMERANG_LOADER_SNIPPET_WRAPPER() function. The example below doesn't include the full loader snippet source code but you can get the full code of the loader snippet from here: Non-Blocking Loader Snippet

<script>
var BOOMERANG_LOADER_SNIPPET_WRAPPER = function() {
     (function() {
          // Boomerang Loader Snippet  
          if (window.BOOMR && (window.BOOMR.version || window.BOOMR.snippetExecuted)) {
               return;
          }
          // ...
          // ...
          // ...
     })();
}
</script>

2. Call BOOMERANG_LOADER_SNIPPET_WRAPPER() function when visitor opts-in. Usually Cookie Consent popup libraries provide callback functions that help us to instrument opt-out and opt-in procedures. For simplicity we will define a callback function with example name onOptIn() where we will run the code needed for opt-in. In our case we have to place BOOMERANG_LOADER_SNIPPET_WRAPPER() in our callback function onOptIn().

<script>
function onOptIn() {
     BOOMERANG_LOADER_SNIPPET_WRAPPER();
}
</script>

5. Cookie Consent library and Consent Inline Plugin example

We prepared Boomerang opt-out and opt-in examples with the popular open source project - Osano Cookie Consent popup library. For the given examples below we assume that the needed Cookie Consent popup script and Boomerang Consent Inline Plugin are loaded on the page.

5.1 Opt-out

// Setup Osano Cookie popup
function onCookieConsentChange(consent) {
	if (consent === "deny") {
		window.BOOMR_OPT_OUT();
	}
}

window.addEventListener("load", function() {
	window.cookieconsent.initialise({
		"type": "opt-out",
		"content": {
			"href": "https://www.example.com/policies/"
		},
		onInitialise: onCookieConsentChange,
		onStatusChange: onCookieConsentChange,
		onRevokeChoice: onCookieConsentChange
	});
});

5.2 Opt-in

// Setup Osano Cookie popup
function onCookieConsentChange(consent) {
	if (consent === "allow") {
		window.BOOMR_OPT_IN();
	}
}

window.addEventListener("load", function() {
	window.cookieconsent.initialise({
		"type": "opt-in",
		"content": {
			"href": "https://www.example.com/policies/"
		},
		onInitialise: onCookieConsentChange,
		onStatusChange: onCookieConsentChange,
		onRevokeChoice: onCookieConsentChange
	});
});