Userlens Analytics SDK

Track everything. Decide what matters later.

📖 View Full Documentation

The Userlens SDK automatically captures every user interaction in your web app. Define events later in the Userlens platform—no code changes required.

Why Userlens?

| Traditional Analytics | Userlens | |-----------------------|----------| | Add track() calls for each event | Install once, capture everything | | Deploy code to track new events | Create events in the UI instantly | | Forgot to track something? Start over | Backfill historical data automatically |

Installation

npm install userlens-analytics-sdk

Quick Start (React)

import UserlensProvider from 'userlens-analytics-sdk/react';

function App() {
  const config = useMemo(() => ({
    userId: currentUser.id,
    userTraits: { email: currentUser.email, plan: currentUser.plan },
    WRITE_CODE: 'your-write-code',  // From app.userlens.io/settings
  }), [currentUser.id]);

  return (
    <UserlensProvider config={config}>
      <YourApp />
    </UserlensProvider>
  );
}

That's it. Every click and page view is now captured.

Documentation

| Guide | Description | |-------|-------------| | Introduction | Overview and how it works | | React Setup | Complete React integration guide | | Next.js Setup | Next.js with SSR considerations | | Custom Events | Track specific actions manually | | API Reference | HTTP API documentation | | Troubleshooting | Common issues and solutions |

Backend Proxy Guides

For production apps, we recommend the proxy setup (keeps your API key secure, avoids ad blockers):

| Backend | Guide | |---------|-------| | Node.js/Express | Setup Guide | | Python (Flask/Django) | Setup Guide | | Ruby on Rails | Setup Guide |

Two Setup Options

Option A: Client-Side Setup (Quick to setup)

Events go directly to Userlens API.

<UserlensProvider config={{
  WRITE_CODE: 'your-write-code',
  userId: user.id,
  userTraits: {
    email: user.email,
    name: user.name,
    plan: user.plan,
    // Add as many traits as possible for better insights
  },
}}>

Option B: Proxy Setup

Events flow through your backend → Userlens API. Useful if you want to avoid ad blockers.

<UserlensProvider config={{
  userId: user.id,
  userTraits: {
    email: user.email,
    name: user.name,
    plan: user.plan,
  },
  eventCollector: {
    callback: (events) => {
      fetch('/api/userlens/events', {
        method: 'POST',
        body: JSON.stringify(events),
      });
    },
  },
}}>

Track Custom Events

import { useUserlens } from 'userlens-analytics-sdk/react';

function UpgradeButton() {
  const { collector } = useUserlens();

  const handleUpgrade = () => {
    collector?.pushEvent({
      event: 'Plan Upgraded',
      properties: { plan: 'pro' },
    });
  };

  return <button onClick={handleUpgrade}>Upgrade</button>;
}

Requirements

• React: 16.8+ (hooks support)
• Browser: Chrome, Firefox, Safari, Edge (modern versions)

License

ISC