Doppler JS SDK

Installation

Install from npm. Zero dependencies. Works with any JS framework.

npm install dopplerjs

Quick Start

The entire integration, start to finish.

import { doppler } from 'dopplerjs';

// 1. Initialize once when your app loads
doppler.init({ clientKey: 'pk_client_YOUR_KEY' });

// 2. After the user logs in, tell Doppler who they are
doppler.identify('jane@example.com', { name: 'Jane' });

// 3. Tell Doppler when something important happens
doppler.coreAction();  // <- The most important call

// 4. Track revenue (optional but powerful)
doppler.trackRevenue(29, 'Pro Plan');

API Keys

Doppler gives you two keys. Use the right one in the right place.

Set up the SDK. Call this once when your app starts.

Think of this like turning Doppler on. You must call init() before anything else. Give it your Client Key and Doppler is ready to go. It also automatically restores the last known user from localStorage — so if someone refreshes the page, they stay identified.

doppler.init({
  clientKey: string,           // Required. Your public client key.
  apiUrl?: string,             // Optional. Custom API endpoint.
  testMode?: boolean,          // Optional. Sends all emails to YOUR inbox.
  avgRevenuePerUser?: number   // Optional. Monthly revenue per user in USD.
})

import { doppler } from 'dopplerjs';

doppler.init({
  clientKey: 'pk_client_abc123',
  testMode: process.env.NODE_ENV !== 'production',
  avgRevenuePerUser: 49   // $49/month per user
});

Tell Doppler who is logged in right now.

After a user signs in, call identify() with their email. This links everything Doppler tracks to a real person. Without this, Doppler doesn't know who to email. Optionally pass their name and plan — the AI uses this to write more personal recovery emails.

doppler.identify(
  email: string,           // Required. The user's email address.
  options?: {
    name?: string,         // Optional. Personalizes recovery emails.
    plan?: string,         // Optional. e.g. "free" | "pro"
    planDaysLeft?: number  // Optional. Days left in their trial.
  }
)

// After login or session restore:
doppler.identify('jane@example.com', {
  name: 'Jane Smith',
  plan: 'trial',
  planDaysLeft: 8   // Triggers trial-ending email flows
});

Record a revenue event (payment, upgrade, renewal).

Tell Doppler whenever a user pays. This powers the revenue metrics on your dashboard — showing exactly how much money Doppler recovered. You'll see 'Recovered Revenue' and 'Revenue at Risk' figures in your overview.

doppler.trackRevenue(
  amount: number,   // Required. Amount in USD (e.g. 49 = $49).
  label?: string    // Optional. Label for this revenue event.
)

// When a user pays or upgrades:
doppler.trackRevenue(49, 'Pro Plan - Monthly');
doppler.trackRevenue(499, 'Pro Plan - Annual');
doppler.trackRevenue(29, 'Seat Added');

User just began your onboarding flow.

Call this when the user starts your product tour, welcome wizard, or setup guide. If they never finish onboarding, Doppler knows they got stuck early and sends a friendly push to come back.

doppler.onboardingStarted(): Promise<void>

// When your setup wizard starts:
function WelcomeWizard() {
  useEffect(() => {
    doppler.onboardingStarted();
  }, []);
}

User finished your onboarding.

Call this when the user completes your setup steps or dismisses the welcome flow. It moves them past the 'new user' stage and tells Doppler they're ready to get real value.

doppler.onboardingCompleted(): Promise<void>

// When the last onboarding step is done:
async function finishOnboarding() {
  await saveUserSettings();
  doppler.onboardingCompleted();
  router.push('/dashboard');
}

User created their first 'thing' in your product.

This milestone means the user has done the core setup — created a project, workspace, campaign, or whatever the main entity is in your product. If they disappear after this, Doppler sends a 'you set up but drifted away' email.

doppler.projectCreated(): Promise<void>

// After user creates their first workspace/project:
async function createProject(data) {
  const project = await api.post('/projects', data);
  doppler.projectCreated();
  return project;
}

User just hit your product's AHA moment.

This is the single most important call in the SDK. The 'core action' is the one thing users must do to get real value — sending an invoice, publishing a page, running a report, making a sale. Doppler starts tracking how often they do it. If they stop, it detects the drop and sends recovery email.

doppler.coreAction(): Promise<void>

// Map this to your AHA moment:

// Invoice app:
async function sendInvoice(invoice) {
  await api.post('/invoices/send', invoice);
  doppler.coreAction(); // <- user got value!
}

// Analytics app:
async function generateReport() {
  const report = await api.get('/reports/generate');
  doppler.coreAction();
  return report;
}

User did the core action again. They're engaged.

Call this every time the user repeats their core action. Doppler measures the frequency. If the cadence drops (e.g. used to be daily, now gone a week), Doppler flags them as 'at risk' and starts recovery. This is how Doppler catches churn before it happens.

doppler.coreActionRepeat(): Promise<void>

async function sendInvoice(invoice) {
  await api.post('/invoices/send', invoice);

  if (user.invoiceCount === 0) {
    doppler.coreAction();        // First time
  } else {
    doppler.coreActionRepeat();  // Repeating = healthy
  }
  user.invoiceCount++;
}

Send a custom milestone with any name.

checkpoint() lets you define your own milestone names outside the built-in lifecycle set. It calls the same internal milestone pipeline as onboardingStarted() and coreAction() — so any named checkpoint you send gets recorded in the user's journey and appears in your dashboard.

doppler.checkpoint(name: string): Promise<void>

doppler.checkpoint('store_connected');
doppler.checkpoint('first_sale_made');
doppler.checkpoint('team_of_5_reached');
doppler.checkpoint('api_integrated');

Log the user out of Doppler. Call this on sign-out.

When a user signs out, call reset(). It clears the stored email, stops the heartbeat, and wipes all session state. If you skip this, the next user who opens the browser might be tracked under the previous user's session.

doppler.reset(): void

// In your logout function:
async function logout() {
  await auth.signOut();
  doppler.reset(); // <- always call this on logout
  router.push('/login');
}

Capture why a user is leaving or cancelling.

When a user cancels, ask them why and pass it to Doppler. This surfaces as patterns in your dashboard — e.g. '40% say it's too expensive'. Use this insight to fix the actual reasons for churn.

doppler.captureChurnFeedback(
  reason: 'too_expensive' | 'too_complex' | 'found_alternative' | 'not_needed' | 'other',
  comment?: string
)

function CancelModal({ onClose }) {
  const [reason, setReason] = useState('too_expensive');
  const [comment, setComment] = useState('');

  const handleCancel = async () => {
    await api.delete('/subscription');
    doppler.captureChurnFeedback(reason, comment);
    onClose();
  };
}

Toggle test mode at runtime.

In test mode, all recovery emails go to YOUR inbox instead of real users. Lets you see exactly what Doppler would send without spamming actual users.

doppler.setTestMode(enabled: boolean): void

// Enabled in dev automatically via init():
doppler.init({
  clientKey: 'pk_client_abc',
  testMode: process.env.NODE_ENV !== 'production'
});

// Or toggle dynamically:
doppler.setTestMode(true);   // my inbox
doppler.setTestMode(false);  // real users

Check if a user is currently identified.

Returns true if the SDK currently knows who the user is. Useful for conditional logic or for debugging to confirm your identify() call worked.

doppler.isIdentified(): boolean
doppler.getIdentifiedEmail(): string | null

if (doppler.isIdentified()) {
  doppler.coreAction();
}

// Debug:
console.log(doppler.getIdentifiedEmail()); // "jane@example.com"