Quick start (npm)

Get FirstDistro running in your React or Next.js app in under 5 minutes. New here? Create an account.

1. install

npm install @firstdistro/sdk

2. add the provider

Wrap your app with FirstDistroProvider and pass your installation token.

// app/providers.tsx
'use client'

import { FirstDistroProvider } from '@firstdistro/sdk/react'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <FirstDistroProvider token={process.env.NEXT_PUBLIC_FIRSTDISTRO_TOKEN!}>
      {children}
    </FirstDistroProvider>
  )
}

// app/layout.tsx
import { Providers } from './providers'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

Get your token: Dashboard → Settings → SDK Configuration

3. set up identity

Use useFirstDistroSetup when the user logs in. Email is required. FirstDistro derives the company account from the email domain server-side.

'use client'

import { useFirstDistroSetup } from '@firstdistro/sdk/react'

export function UserIdentifier({ user }: { user: User }) {
  useFirstDistroSetup({
    userId: user.id,
    userEmail: user.email,
    userName: user.name,
  })

  return null
}

4. required: identity on successful auth

Browser-only misses signed-in users. After every successful auth or session exchange, emit identity with @firstdistro/sdk/server (never from client code):

import { createServer } from '@firstdistro/sdk/server'

const track = createServer({
  apiKey: process.env.FIRSTDISTRO_API_KEY!,
})

// accountId = corporate email domain when valid, else user.id
track('$setup', {
  userId: user.id,
  accountId,
  properties: { userEmail: user.email },
})
await track.flush()

Put FIRSTDISTRO_API_KEY (sk_live_* / sk_test_*) in .env.local only. Tracking failures must never fail login.

5. page views are automatic

Once browser setup() runs, the SDK automatically captures a $pageview event on the initial load and on every SPA route change. No manual track('page_viewed'). Page views power Activity, Engagement, and Recency in your health scores.

Auto-capture is on by default. To turn it off, pass autoCapture={false} to the provider. See Privacy / URL capture below for how URLs are scrubbed.

6. optional: track product moments

Page views give you a fair health score on day one. Custom events with useTrack are optional. They feed Activity and Recency. They only move Milestones when the event name is a default or custom milestone.

'use client'

import { useTrack } from '@firstdistro/sdk/react'

function ExportButton() {
  const track = useTrack()

  const handleExport = () => {
    track('feature_used', { feature: 'export', format: 'pdf' })
    // ... export logic
  }

  return <button onClick={handleExport}>Export</button>
}

7. confirm it is working

Log in to your app once. Confirm a $setup (or equivalent identity) in the live feed on Settings → SDK Configuration. Then visit a couple of routes for page views. Accounts show up in Customer Insights once events are linked to users.

Browser-only is not a complete install. Want to watch events flow locally? Append ?fd_debug=true to any page to see the debug badge and live event count.

Privacy / url capture

Automatic $pageview capture strips the full query string from both the captured url and referrer by default, keeping PII and secrets (for example ?reset_token=…, ?email=…) out of FirstDistro. The pathname and hash are kept as-is.

Opt back in to specific query params with the captureQueryParams allowlist (exact, case-sensitive):

<FirstDistroProvider token="fd_..." captureQueryParams={['utm_source', 'utm_medium']}>
  {children}
</FirstDistroProvider>

For full control on code-based installs, the maskUrl hook runs after the default strip. Return a string to replace the url, or null to drop the $pageview entirely. maskUrl is not available via the script-tag install, and path-segment PII scrubbing is not performed.

Next steps

• Install: browser and server as one story (including sk_* server events)
• React hooks reference: all available hooks and options
• Event tracking guide: best practices for tracking events
• MCP (AI assistants): query customer health from Claude, Cursor, or Windsurf

Alternative: script tag

If you are not using a bundler, you can install via script tag instead.

See the Install page (Browser tab) for script tag instructions.