Magento 2 integration module for Basicrum

Magento 2, Adobe Commerce, and Mage-OS sending web-performance beacons to Basicrum.
Basicrum is currently in public betaTo try Basicrum with the Magento 2 module, sign up and join our public beta.Freeduring beta testing

Acknowledgements

This module and guide benefited from the time, experience, and feedback of:

  • Louis de Looze — for self-hosting an early version of Basicrum, installing the Magento 2 extension, and providing feedback.
  • Jeroen Boersma — for consulting on and teaching us about the initial Content Security Policy (CSP) implementation.
  • Jisse Reitsma — for helping establish the initial extension structure and apply Magento best practices.
  • Ruud van Zuidam — for sharing best practices, fixing logic bugs, and improving CSP support.
  • The participants of Magento Unconference Netherlands — for sharing feedback about what they wanted to see in a Magento 2 monitoring extension.

View the extension's source code and contribute in the basicrum/basicrum-magento-2 repository on GitHub.

What does the Basicrum Magento 2 module do?

The Basicrum module connects Magento 2 stores to a hosted or self-hosted Basicrum installation. It uses the bundled open-source Boomerang library to measure visitors' real browsing experience, including page loads, resources, interactions, and Core Web Vitals metrics.

The module also adds context to each beacon, including the page URL and page type. It recognises standard Magento storefront pages such as the homepage, categories, products, search results, cart, checkout, order confirmation, and customer account pages. This helps you investigate performance on the pages that matter to your customers.

Module setup

Installation

Run the installation from your Magento root as the filesystem owner. Back up the application and database, and test the change on staging before deploying it to production.

Install the current release from Packagist:

composer require 'basicrum/basicrum-magento-2:^0.1'

Enable and initialise the module:

bin/magento module:enable Basicrum_Analytics
bin/magento setup:upgrade
bin/magento setup:di:compile

In production mode, deploy static content for every storefront and Admin locale. For an English-only installation, run:

bin/magento setup:static-content:deploy en_US

Replace or extend en_US with the locales used by your store. Then clean Magento's cache and confirm that the module is enabled:

bin/magento cache:clean
bin/magento module:status Basicrum_Analytics

Monitoring remains disabled until you configure and enable Basicrum.

Acquire Basicrum collector details

To connect your store to Basicrum, you need two settings:

  • Beacon Endpoint
  • Brum Site ID

During the public beta, create your account from the Basicrum signup page.

Once your account is ready, sign in to the Basicrum portal.

Go to Account → Settings → Sites, then click Add Site or select an existing site to retrieve its collector details.

Basicrum portal showing the Brum Site ID and Beacon Endpoint for a Magento 2 Mage-OS test site.

Enable Basicrum in Magento

In the Magento Admin, open:

Stores → Configuration → Basicrum → Basicrum Analytics

Set Enable Basicrum to Yes, then enter the Beacon Endpoint and Brum Site ID supplied for your site. Save the configuration.

Both values are required. The module does not emit monitoring scripts when monitoring is disabled or either value is missing or invalid. The Monitoring Status row explains why monitoring is inactive.

Settings support Magento's default, website, and store-view scopes, so you can configure individual storefronts where needed.

Magento Admin showing enabled Basicrum Analytics settings with a ready, consent-controlled monitoring status.

Visitor consent

On new installations, Require Consent Before Monitoring is selected by default. In this mode, the module does not load Boomerang, create its monitoring cookie, or send monitoring data until your consent tool explicitly allows monitoring on the current page.

After opt-in, Boomerang loads, creates the first-party RT cookie, and sends performance data to the configured Basicrum collector.

Basicrum does not display a consent banner or store its own consent decision. Your existing consent tool remains responsible for obtaining the visitor's choice and communicating it to Basicrum on each page.

Disable Require Consent Before Monitoring only when the store owner has confirmed that prior consent is not required for the site.

Magento Admin showing Basicrum visitor consent settings and the manual callback API.

Manual consent instrumentation

Connect your consent tool to Basicrum using these JavaScript callbacks.

Opt-in:

if (typeof window.OPT_IN_BASICRUM_LOADER_WRAPPER === "function") {
	window.OPT_IN_BASICRUM_LOADER_WRAPPER();
}

Call this when your consent tool confirms that performance monitoring is allowed on the current page.

Opt-out:

if (typeof window.OPT_OUT_BASICRUM_LOADER_WRAPPER === "function") {
	window.OPT_OUT_BASICRUM_LOADER_WRAPPER();
}

Call this when monitoring is denied, expires, or is withdrawn. The callback removes accessible measurement cookies and disables Boomerang. Data already sent to the collector cannot be retracted.

Call these functions after the Basicrum footer loader has registered them. Calls made before registration are not queued.

A denial before the first opt-in can be followed by an opt-in on the same page. If consent is withdrawn while Boomerang is loading or after it has started, reload the page before granting consent again.

Strip query strings from measured URLs

Strip Query Strings defaults to No. Set it to Yes to keep complete query strings out of the page, navigation, referrer, and resource URLs sent with Basicrum beacons. Boomerang replaces the query with ?qs-redacted while preserving the URL path.

For example, https://shop.example/search?q=boots&utm_source=email is reported as https://shop.example/search?qs-redacted. This helps prevent search terms, campaign values, customer identifiers, or other URL parameters from entering performance data. The setting applies to measured URLs, not the configured Beacon Endpoint, whose own query string remains supported.

Magento Admin showing the enabled Strip Query Strings privacy setting for Basicrum.

Clean caches and verify the storefront

After changing Basicrum settings, clean Magento's configuration, layout, block HTML, and full-page caches. In production, also publish updated static assets and invalidate any CDN or optimiser cache that can retain old HTML or JavaScript.

Visit the storefront using the consent state you want to test, then confirm that requests reach your Beacon Endpoint and include the expected Brum Site ID. If your store delays or combines scripts, verify consent handling and script loading on staging.

The module adds an active collector's origin to Magento's storefront connect-src and img-src Content Security Policy directives. Disabled or invalid configuration does not add a collector origin.