Improve consent integration and local setup

Author: Tsvetan Stoychev

.env.example

@@ -1,12 +1,12 @@
 # Local Docker development defaults. Copy to .env to override them.
-WORDPRESS_PORT=8080
+WORDPRESS_PORT=9080
 WORDPRESS_DB_HOST=db:3306
 WORDPRESS_DB_NAME=wordpress
 WORDPRESS_DB_USER=wordpress
 WORDPRESS_DB_PASSWORD=wordpress
 WORDPRESS_DB_ROOT_PASSWORD=root
 
-WP_URL=http://localhost:8080
+WP_URL=http://localhost:9080
 WP_TITLE=Basicrum Local
 WP_ADMIN_USER=admin
 WP_ADMIN_PASSWORD=basicrum-dev-password

AGENTS.md

@@ -7,10 +7,13 @@ namespace, PSR-4 Composer autoloading, PHP 7.4+, and WordPress 6.0+.
 
 - `basicrum.php` is the bootstrap; `src/Plugin.php` registers services.
 - `src/Assets.php` injects Boomerang and config; `PageTypeDetector.php` sets
-  `p_type`; `Compatibility.php` handles cache-plugin exclusions.
-- The standard loader is used without consent mode; consent mode uses the
-  consent loader and exposes `OPT_IN_BASIC_RUM()` / `OPT_OUT_BASIC_RUM()` for
-  integration with a site's consent banner.
+  `p_type`; `Compatibility.php` handles cache-plugin exclusions; `Admin/Privacy.php`
+  contributes editable WordPress privacy-policy text.
+- Immediate loading uses the standard loader. Consent-controlled loading uses
+  the consent loader and exposes `OPT_IN_BASICRUM_LOADER_WRAPPER()` /
+  `OPT_OUT_BASICRUM_LOADER_WRAPPER()` for integration with a site's external
+  consent tool. Load the adapter after the consent loader and call one callback
+  on every page. Basicrum does not persist consent across page loads.
 - Settings use the `basicrum_settings` option. Keep defaults, UI, and
   sanitization in sync in `Helpers`, `Admin\Settings\Page`, and
   `Admin\Settings\Validate`.

README.md

@@ -35,7 +35,7 @@ make package-smoke
 
 `make up` installs Composer dependencies, starts the stack, provisions
 WordPress on a new database, and activates Basicrum. The development site is at
-`http://localhost:8080/wp-admin/`.
+`http://localhost:9080/wp-admin/`.
 
 Default local administrator credentials are `admin` /
 `basicrum-dev-password`. Copy `.env.example` to `.env` to override the
@@ -46,6 +46,46 @@ To use an HTTP beacon URL during local testing, enable **HTTP Strictness**
 under **Basicrum > Developer Settings**. Keep it disabled on production sites
 so HTTP beacon URLs are automatically upgraded to HTTPS.
 
+### Visitor Privacy
+
+Basicrum supports two observable loading policies under **Basicrum > Visitor
+Privacy**:
+
+- **Load immediately** loads Boomerang on every eligible page without waiting
+  for a consent signal.
+- **Wait for visitor consent** blocks Boomerang until the site's external
+  consent tool calls `window.OPT_IN_BASICRUM_LOADER_WRAPPER()` on the current
+  page. The tool must call `window.OPT_OUT_BASICRUM_LOADER_WRAPPER()` when
+  consent is rejected, expires, or is withdrawn.
+
+The callbacks are registered when the consent loader reaches its configured
+Script Position. The consent integration must run after those callbacks are
+available and call one of them on every page. Basicrum does not persist a
+separate consent choice across page loads; the external tool is authoritative
+on every page. If consent is withdrawn after Boomerang loading starts, reload
+the page before granting it again.
+
+Load the adapter after the Basicrum consent loader and use this shape:
+
+```js
+function reportBasicrumConsent(allowed) {
+  const callbackName = allowed
+    ? 'OPT_IN_BASICRUM_LOADER_WRAPPER'
+    : 'OPT_OUT_BASICRUM_LOADER_WRAPPER';
+
+  if (typeof window[callbackName] === 'function') {
+    window[callbackName]();
+  }
+}
+```
+
+A tested Borlabs Cookie v3 adapter is available under
+[`examples/integrations/`](examples/integrations/).
+
+Basicrum does not display a consent popup, select a legal basis, or make a site
+compliant by itself. The WordPress Privacy Policy Guide includes editable
+suggested disclosure text for the configured collector and loading policy.
+
 ## Plugin Source
 
 The WordPress plugin itself lives in `plugins/basicrum/`.

checklist.md

@@ -19,20 +19,33 @@ Acceptance criteria:
 
 ## 2. Resolve the unused consent mode setting
 
-- [ ] Define the intended behavior for `explicit`, `implicit`, and `cookie_popup`
+- [x] Define the intended behavior for `explicit`, `implicit`, and `cookie_popup`
   modes.
-- [ ] Decide whether each mode has distinct runtime behavior.
-- [ ] Implement the defined behavior, or remove modes that do not represent real
+- [x] Decide whether each mode has distinct runtime behavior.
+- [x] Implement the defined behavior, or remove modes that do not represent real
   behavior and keep a single consent-enabled switch.
-- [ ] Keep defaults, settings UI, validation, migrations, documentation, and
+- [x] Keep defaults, settings UI, validation, migrations, documentation, and
   translations synchronized.
-- [ ] Add PHP tests for every supported setting and loader selection path.
+- [x] Add PHP tests for every supported setting and loader selection path.
+
+Decision:
+
+- Immediate loading and consent-controlled loading are the only observable
+  policies. The retired `explicit`, `implicit`, and `cookie_popup` values all
+  selected the same loader and have been removed without changing existing
+  sites' consent gate.
+- Basicrum supplies an integration gate, not a consent popup, legal-basis
+  decision, or compliance guarantee.
+- In consent-controlled loading, the site's external consent tool is the source
+  of truth on every page. Its adapter loads after the consent loader and calls
+  exactly one of the two public callbacks. Basicrum does not persist consent
+  across page loads.
 
 Acceptance criteria:
 
-- [ ] Every consent option shown to an administrator has observable and documented
+- [x] Every consent option shown to an administrator has observable and documented
   runtime behavior.
-- [ ] No unused consent settings remain in stored options or the UI.
+- [x] No unused consent settings remain in stored options or the UI.
 
 ## 3. Add JavaScript consent and loader tests
 
@@ -41,10 +54,8 @@ Acceptance criteria:
 - [x] Test that opt-in loads Boomerang exactly once.
 - [x] Test that repeated opt-in calls do not load duplicate scripts.
 - [x] Test that opt-out disables Boomerang when it is already loaded.
-- [x] Test removal of Boomerang cookies during opt-out.
-- [x] Test consent cookie behavior on HTTP and HTTPS.
-- [x] Test consent cookie behavior for normal hostnames, localhost, and relevant
-  subdomain cases.
+- [x] Test removal of Boomerang RT and BA cookies during opt-out.
+- [x] Test measurement-cookie cleanup for the current host and parent domains.
 - [x] Run the same behavioral assertions against minified and unminified loaders.
 - [x] Add JavaScript tests to CI.
 

docker-compose.yml

@@ -30,7 +30,7 @@ services:
       WORDPRESS_DB_USER: ${WORDPRESS_DB_USER:-wordpress}
       WORDPRESS_DB_PASSWORD: ${WORDPRESS_DB_PASSWORD:-wordpress}
     ports:
-      - "${WORDPRESS_PORT:-8080}:80"
+      - "${WORDPRESS_PORT:-9080}:80"
     volumes:
       - wordpress_data:/var/www/html
       - ./plugins/basicrum:/var/www/html/wp-content/plugins/basicrum
@@ -46,7 +46,7 @@ services:
       WORDPRESS_DB_NAME: ${WORDPRESS_DB_NAME:-wordpress}
       WORDPRESS_DB_USER: ${WORDPRESS_DB_USER:-wordpress}
       WORDPRESS_DB_PASSWORD: ${WORDPRESS_DB_PASSWORD:-wordpress}
-      WP_URL: ${WP_URL:-http://localhost:8080}
+      WP_URL: ${WP_URL:-http://localhost:9080}
       WP_TITLE: ${WP_TITLE:-Basicrum Local}
       WP_ADMIN_USER: ${WP_ADMIN_USER:-admin}
       WP_ADMIN_PASSWORD: ${WP_ADMIN_PASSWORD:-basicrum-dev-password}

examples/integrations/README.md

@@ -0,0 +1,36 @@
+# Consent Tool Integration Examples
+
+These examples are copy-and-paste adapters for webmasters. They are development
+and documentation files outside the installable Basicrum plugin.
+
+## Borlabs Cookie v3
+
+The [`borlabs-cookie-v3.js`](borlabs-cookie-v3.js) adapter follows the public
+Borlabs Cookie v3 JavaScript contract:
+
+- It reads `BorlabsCookie.Consents.hasConsent('basicrum')`.
+- It synchronizes after `borlabs-cookie-after-init`.
+- It synchronizes again after `borlabs-cookie-consent-saved`.
+- It calls exactly one of Basicrum's opt-in or opt-out callbacks.
+
+In Borlabs Cookie, create and enable a custom service with the service ID
+`basicrum`, normally in the Statistics service group. Configure Basicrum to
+**Wait for visitor consent**.
+
+Load the Basicrum consent loader before this adapter. Then load the adapter as
+unblocked site code on every frontend page. Do not place the adapter itself
+behind the Basicrum service consent because it must also report rejection and
+withdrawal. Borlabs remains the consent source of truth.
+
+If consent is withdrawn after Boomerang has loaded, Basicrum disables
+collection and removes its known measurement cookies. Reload the page before
+granting consent again; an already disabled Boomerang instance is not restarted
+on the same page.
+
+The Playwright suite runs this exact adapter against
+`tests/javascript/fixtures/borlabs-cookie-v3-test-double.js`. The test double
+models the documented API and events; it is not the proprietary Borlabs Cookie
+plugin.
+
+Official reference:
+[Borlabs Cookie JavaScript API v3](https://borlabs.io/kb/javascript-api-v3/).

examples/integrations/borlabs-cookie-v3.js

@@ -0,0 +1,48 @@
+( function( window ) {
+	'use strict';
+
+	var serviceId = 'basicrum';
+
+	/**
+	 * Report the current decision to the Basicrum consent loader.
+	 *
+	 * @param {boolean} allowed Whether Borlabs allows the Basicrum service.
+	 * @return {void}
+	 */
+	function reportDecision( allowed ) {
+		var callbackName = allowed
+			? 'OPT_IN_BASICRUM_LOADER_WRAPPER'
+			: 'OPT_OUT_BASICRUM_LOADER_WRAPPER';
+
+		if ( 'function' === typeof window[ callbackName ] ) {
+			window[ callbackName ]();
+		}
+	}
+
+	/**
+	 * Read the authoritative decision from the Borlabs Cookie v3 API.
+	 *
+	 * @return {void}
+	 */
+	function synchronizeConsent() {
+		var consents = window.BorlabsCookie && window.BorlabsCookie.Consents;
+
+		if ( ! consents || 'function' !== typeof consents.hasConsent ) {
+			reportDecision( false );
+			return;
+		}
+
+		try {
+			reportDecision( true === consents.hasConsent( serviceId ) );
+		} catch ( error ) {
+			// Fail closed until Borlabs can report an authoritative decision.
+			reportDecision( false );
+		}
+	}
+
+	window.addEventListener( 'borlabs-cookie-after-init', synchronizeConsent );
+	window.addEventListener( 'borlabs-cookie-consent-saved', synchronizeConsent );
+
+	// Also support snippets added after Borlabs has already initialized.
+	synchronizeConsent();
+}( window ) );

plugins/basicrum/README.md

@@ -2,7 +2,7 @@
 Plugin Name:       Basic Rum Wordpress Plugin
 Plugin URI:        https://www.basicrum.com/
 Description:       Budget - Open Source - Real User Monitoring system.
-Version:           1.0.1
+Version:           1.0.2
 Author:            Tsvetan Stoychev
 Author URI:        https://www.basicrum.com/contact/
 License:           MIT
@@ -114,4 +114,4 @@ Titles are optional, naturally.
 Markdown uses email style notation for blockquotes and I've been told:
 > Asterisks for *emphasis*. Double it up  for **strong**.
 
-`<?php code(); // goes in backticks ?>`
+`<?php code(); // goes in backticks ?>`

plugins/basicrum/assets/css/admin/settings.css

@@ -22,3 +22,23 @@
 	color: #d63638;
 	font-weight: 600;
 }
+
+.basicrum-radio-option {
+	margin-bottom: 12px;
+	max-width: 760px;
+}
+
+.basicrum-radio-option p.description {
+	margin: 4px 0 0 24px;
+}
+
+.basicrum-consent-info {
+	max-width: 760px;
+}
+
+.basicrum-consent-info pre {
+	background: #fff;
+	border: 1px solid #ddd;
+	overflow-x: auto;
+	padding: 8px;
+}