Skip to Content

Usermaven Magento 2 Integration Guide

Integrate Usermaven with your Magento 2 store using a safe, production-ready approach compatible with Magento’s RequireJS system.

Prerequisites

Make sure you have:

  • Magento 2.x store
  • Access to theme files (SSH/FTP)
  • Usermaven Tracking Key (from your dashboard)

Step 1: Add the Usermaven Loader Script

Create the file:

app/design/frontend/<Vendor>/<Theme>/web/js/usermaven-loader.js

Paste the following code:

require(['domReady!'], function () {
  'use strict';
 
  // Prevent duplicate initialization
  if (window.usermavenInitialized) return;
  window.usermavenInitialized = true;
 
  console.log('Initializing Usermaven...');
 
  // Save AMD environment (DO NOT touch window.require)
  var _define = window.define;
  var _exports = window.exports;
  var _module = window.module;
 
  // Temporarily disable AMD detection
  window.define = undefined;
  window.exports = undefined;
  window.module = undefined;
 
  // Initialize queue
  window.usermaven = window.usermaven || function () {
    (window.usermavenQ = window.usermavenQ || []).push(arguments);
  };
 
  // Inject Usermaven script
  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://t.usermaven.com/lib.js';
 
  script.setAttribute('data-tracking-host', 'https://events.usermaven.com');
  script.setAttribute('data-key', 'YOUR_TRACKING_KEY'); // Replace this
  script.setAttribute('data-autocapture', 'true');
  script.setAttribute('data-auto-pageview', 'true');
 
  // Restore AMD environment
  script.onload = script.onerror = function () {
    window.define = _define;
    window.exports = _exports;
    window.module = _module;
 
    console.log('Usermaven loaded successfully');
  };
 
  document.head.appendChild(script);
});

Replace YOUR_TRACKING_KEY with your actual Usermaven key.

Step 2: Load Script in Magento

Create the file:

app/design/frontend/<Vendor>/<Theme>/Magento_Theme/layout/default_head_blocks.xml

Add:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
  <head>
    <script src="js/usermaven-loader.js"/>
  </head>
</page>

Step 3: Deploy Changes

Run the following commands:

php bin/magento cache:clean
php bin/magento setup:static-content:deploy en_US -f
php bin/magento cache:flush

Optional (development mode):

rm -rf pub/static/frontend/* var/view_preprocessed/*
php bin/magento cache:clean

Step 4: Verify Installation

Console Check

Open DevTools → Console and run:

typeof window.require
typeof window.usermaven

Both should return “function”.

You should also see:

Initializing Usermaven...
Usermaven loaded successfully

Network Check

In the Network tab, filter for:

usermaven

You should see:

Dashboard Check

Events should appear within 1–2 minutes Pageviews are tracked automatically

Step 5: CSP Fix (Magento 2.4+ Only)

If you encounter CSP errors, create:

app/etc/csp_whitelist.xml

Add:

<?xml version="1.0"?>
<csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp/etc/csp_whitelist.xsd">
  <policies>
    <policy id="script-src">
      <values>
        <value id="usermaven_sdk" type="host">https://t.usermaven.com</value>
      </values>
    </policy>
    <policy id="connect-src">
      <values>
        <value id="usermaven_events" type="host">https://events.usermaven.com</value>
      </values>
    </policy>
  </policies>
</csp_whitelist>

Then run:

php bin/magento cache:clean

Optional: Staging vs Production Keys


var isProd = window.location.hostname === 'yourdomain.com';
var key = isProd ? 'PROD_KEY' : 'STAGING_KEY';

script.setAttribute('data-key', key);

Important Notes

  • Do not use:
require(['https://t.usermaven.com/lib.js'])
  • Do not modify:
window.require
  • Do not embed the script directly in HTML
  • Always use the loader approach shown above“

Final Checklist

  • Loader file added
  • Layout XML added
  • Tracking key replaced
  • Cache cleared and deployed
  • Verified in console

Completion

Usermaven will now automatically track:

  • Pageviews
  • User journeys
  • Events (autocaptured)
  • Events visible in the dashboard
Last updated on
Installing Usermaven