Installing Usermaven

To integrate your website or SaaS app with Usermaven, you’ll need to incorporate a tracking script into the Header (<head></head>) section of your website. Ensure that this snippet is included on every page you wish to track.

Here’s an example of a tracking script that you can utilize, but be sure to substitute the data-key="YOUR_KEY" attribute with the one provided in your workspace.


<script type="text/javascript">
  (function () {
    window.usermaven = window.usermaven || (function () {
      (window.usermavenQ = window.usermavenQ || []).push(arguments);
    });
 
    var t = document.createElement('script'),
        s = document.getElementsByTagName('script')[0];
 
    t.defer = true;
    t.id = 'um-tracker';
 
    t.setAttribute('data-tracking-host', "https://events.usermaven.com"); // Can be whitelabeled
    t.setAttribute('data-key', 'YOUR_KEY'); // Your workspace identifier
    t.setAttribute('data-randomize-url', 'true'); 
    
    t.setAttribute('data-autocapture', 'true'); // Optional: automatically track clicks, form submissions, etc.
    t.setAttribute('data-privacy-policy', 'strict'); // Optional: enables cookie-less tracking (GDPR-friendly)
    t.setAttribute('data-cross-domain-linking', 'true'); // Optional: enables tracking across multiple domains (not needed for subdomains)
    t.setAttribute('data-domains', 'domain1.com,domain2.com'); // Optional: list of domains for cross-domain tracking
 
    t.src = 'https://t.usermaven.com/lib.js'; //can be whitelabeled
    s.parentNode.insertBefore(t, s);
  })();
</script>

Finding your tracking script

Upon successfully creating your account and workspace, you’ll be directed to a page where your tracking script will be readily available. Simply copy the provided script and insert it into the header section of your website.

In the event that you have created a second workspace, you’ll be shown a setup page displaying the tracking script as shown below.

At any time after the initial installation, you can find the tracking script in Workspace Settings > Setup menu.

Cookie-less tracking (also known as anonymized tracking) allows you to collect information about website visits without storing any user-identifiable data. This makes it a more privacy-friendly solution and helps comply with data protection regulations like GDPR.

To enable cookie-less tracking, make sure the following attribute is added to your tracking script:


t.setAttribute('data-privacy-policy', 'strict');

Learn more about cookie-less tracking →

What is autocapture and how to enable it?

Autocapture lets you automatically track key user interactions—such as page views, button clicks, link clicks, and form submissions—without writing custom code. It simplifies the tracking process and ensures you don’t miss important events.

Usermaven supports both autocapture and manual event tracking. However, we recommend enabling autocapture from the moment you install the script to capture essential actions without needing a developer.

To enable autocapture, ensure this attribute is present in your tracking script:


t.setAttribute('data-autocapture', 'true');

Learn more about event tracking in Usermaven →

What is pixel white-labeling and how to enable it?

Many analytics tools like Google Analytics and Mixpanel are commonly blocked by ad-blockers, which can lead to incomplete or inaccurate data. Usermaven offers pixel white-labeling, allowing you to use a custom domain for the tracking script to reduce ad-blocker interference.

We strongly recommend enabling white-labeling to avoid losing valuable traffic and event data from users who have ad-blockers enabled.

You can follow this guide to enable pixel white-labeling and connect your custom domain.

Note: If you’ve already installed the Usermaven tracking script before enabling white-labeling, you’ll need to replace the old script with the new one using your custom domain.

What is cross-domain tracking and how to enable it?

Cross-domain tracking allows you to follow a user’s journey across multiple domains (e.g., from domain1.com to domain2.com) while treating them as the same visitor. This ensures accurate attribution and session continuity across different websites owned by your business.

Note: Cross-domain tracking is not required for subdomains (e.g., app.domain1.com and www.domain1.com). Those are automatically handled.

Important: If you want to track multiple different domains (not subdomains) in a single workspace, you must also add them in Usermaven → Workspace settings → General → Additional domains.

To enable cross-domain tracking, add the following attributes to your Usermaven tracking script:


t.setAttribute('data-cross-domain-linking', 'true');
t.setAttribute('data-domains', 'domain1.com,domain2.com');

data-cross-domain-linking="true" enables the feature.
data-domains should list all domains where you want to track users across, separated by commas.

Make sure the tracking script is installed on all listed domains, with these attributes included.

This setup helps you understand the complete user journey—especially when users navigate between your landing pages, blog, and app hosted on different domains.

Learn more about cross-domain tracking in Usermaven →

What’s next?

Now that you’ve installed Usermaven, here are the next steps to set up meaningful tracking and get the most out of your analytics:

Create pinned events
Pin key user actions—like sign-ups, purchases, or button clicks—directly from the list of auto-captured events (if enabled). This lets you track important interactions without writing extra code.
Send custom events
For events not captured automatically (like embedded widgets or third-party tools), use Usermaven’s JavaScript API to track them manually.
Send signed-up users’ data to Contacts Hub
For SaaS and subsription-based businesses, associating sessions with real users by sending signed-up user data is recommended. This helps unify their journey and powers identity resolution across devices and visits.