@simple-product/sdk

Track users and product usage with Simple Product.

Installation

npm install @simple-product/sdk

Quick Start

import { SimpleProduct } from '@simple-product/sdk';

// Initialize once in your app
const sp = new SimpleProduct({
  apiKey: 'sk_your_api_key',
});

// Identify users when they sign in
sp.identify({
  userId: user.id,
  email: user.email,
  name: user.name,
  company: user.company,
});

// That's it! Analytics are now tracked automatically.

How It Works

The SDK automatically sends a heartbeat event once per day per user. This single event powers:

• DAU/WAU/MAU - Daily, weekly, monthly active users
• Retention - Cohort retention analysis
• Stickiness - DAU/MAU engagement ratio

No configuration needed. Just identify your users and analytics happen automatically.

API Reference

new SimpleProduct(config)

Create a new SDK instance.

const sp = new SimpleProduct({
  apiKey: 'sk_your_api_key',        // Required
  endpoint: 'https://...',           // Optional, defaults to production
  disableAutoHeartbeat: false,       // Optional, disable auto-tracking
  debug: false,                      // Optional, enable console logging
});

sp.identify(params)

Identify a user. Call this when a user signs in.

sp.identify({
  userId: 'user_123',          // Required - your internal user ID
  email: '[email protected]',   // Optional
  name: 'Jane Doe',            // Optional
  company: 'Acme Inc',         // Optional
  traits: {                    // Optional - any additional data
    plan: 'pro',
    role: 'admin',
  },
});

sp.track(event, properties?)

Track a custom event.

sp.track('feature_used', {
  feature: 'export_report',
  format: 'csv',
});

sp.reset()

Reset the user. Call this when a user signs out.

sp.reset();

sp.destroy()

Clean up SDK resources. Call this if you need to remove the SDK.

sp.destroy();

React Integration (Recommended)

The easiest way to integrate is with our React provider:

// app/providers.tsx
'use client';

import { SimpleProductProvider } from '@simple-product/sdk/react';

export function Providers({ children, user }) {
  return (
    <SimpleProductProvider
      apiKey={process.env.NEXT_PUBLIC_SP_API_KEY!}
      user={user ? {
        id: user.id,
        email: user.email,
        name: user.name,
      } : null}
    >
      {children}
    </SimpleProductProvider>
  );
}

The provider automatically:

• Calls identify() when user changes
• Sends heartbeats once per day
• Resets on logout

Track Custom Events

import { useSimpleProduct } from '@simple-product/sdk/react';

function MyComponent() {
  const { track } = useSimpleProduct();

  return (
    <button onClick={() => track('button_clicked', { button: 'signup' })}>
      Sign Up
    </button>
  );
}

Manual Setup

If you're not using React, you can use the SDK directly:

import { SimpleProduct } from '@simple-product/sdk';

const sp = new SimpleProduct({
  apiKey: process.env.NEXT_PUBLIC_SP_API_KEY!,
});

// When user logs in
sp.identify({
  userId: user.id,
  email: user.email,
  name: user.name,
});

// Track custom events
sp.track('feature_used', { feature: 'export' });

// On logout
sp.reset();

License

MIT