React Integration

Usermaven provides a dedicated SDK for React applications that supports tracking. Our SDK offers:

Automatic page view tracking
Cross-domain tracking support
Flexible event tracking with custom payloads
URL randomization to avoid PII collection
Namespace support for multiple tracking instances

Installation

Install the Usermaven React package:


npm install @usermaven/react
# or
yarn add @usermaven/react

Setup

Provider Setup

Initialize Usermaven and wrap your application with the provider:


import { createClient, UsermavenProvider } from '@usermaven/react';
 
// Initialize Usermaven client
const usermavenClient = createClient({
  // Required Configuration
  key: 'your-api-key',
  trackingHost: 'https://events.usermaven.com',
 
  // Optional Configuration
  autocapture: true, // Enable automatic event capturing
  autoPageview: true, // Automatically track page views
  randomizeUrl: false, // Randomize URLs to avoid PII collection
 
  // Cross-domain Tracking (Optional)
  crossDomainLinking: false, // Enable cross-domain tracking
  domains: 'example.com,example.org', // Specify allowed domains
 
  // Advanced Configuration (Optional)
  namespace: 'my-app', // Custom namespace for multiple tracking instances
});
 
function App() {
  return <UsermavenProvider client={usermavenClient}>{/* Your app components */}</UsermavenProvider>;
}
 
export default App;

Usage in Components

Page View Tracking

Use the usePageView hook to track page views:


import { usePageView } from '@usermaven/react';
 
function PageComponent() {
  // Initialize page view tracking
  usePageView();
 
  return <div>{/* Your page content */}</div>;
}

Tracking Custom Events

Use the useUsermaven hook to track custom events:


import { useUsermaven } from '@usermaven/react';
 
function ButtonComponent() {
  const { track } = useUsermaven();
 
  const handleButtonClick = () => {
    track('button_click', {
      buttonId: 'submit-button',
      page: 'checkout',
      value: 99.99,
    });
  };
 
  return <button onClick={handleButtonClick}>Click Me</button>;
}

Identifying Users

Use the useUsermaven hook to identify users:


import { useUsermaven } from '@usermaven/react';
 
function ProfileComponent() {
  const { id } = useUsermaven();
 
  const identifyUser = () => {
    id({
      // Required attributes
      id: 'lzL24K3kYw', // Unique ID for the user in database
      email: 'user@domain.com', // Email address for the user
      created_at: '2021-01-20T09:55:35', // DateTime string when user first signed up
 
      // Recommended attributes
      first_name: 'John',
      last_name: 'Smith',
 
      // Optional attributes
      custom: {
        plan_name: 'premium',
      },
 
      // Company attributes (for multi-user products)
      company: {
        // Required Attributes
        id: 'uPq9oUGrIt', // Company ID in your database
        name: 'Usermaven', // Company Name in your database
        created_at: '2021-01-20T09:55:35', // DateTime string when company first signed up
 
        // Optional attributes
        custom: {
          plan: 'enterprise',
          industry: 'Technology',
          website: 'https://usermaven.com',
          employees: 20,
        },
      },
    });
  };
 
  return <button onClick={identifyUser}>Update Profile</button>;
}

Configuration Options

Here’s a detailed explanation of all available configuration options:

Required:

key: Your Usermaven API key
trackingHost: The URL of your tracking server

Optional:

autocapture: Enable automatic event capturing (default: false)
autoPageview: Automatically track page views (default: false)
randomizeUrl: Randomize URLs to avoid PII collection (default: false)
namespace: Custom namespace for multiple tracking instances
crossDomainLinking: Enable cross-domain tracking (default: false)
domains: Specify allowed domains for cross-domain tracking (e.g., ‘example.com,example.org’)

For a complete list of configuration options, refer to the Reference Guide.

Example App

For a complete working example, check out our React Example App .