First Distro
FirstDistro

Quick start (npm)

Install the FirstDistro SDK with npm install @firstdistro/sdk. React and Next.js. Free plan. Get running in under 5 minutes.

Get FirstDistro running in your React or Next.js app in under 5 minutes. New here? Sign up for free (no credit card required).

1. install

bash
npm install @firstdistro/sdk

2. add the provider

Wrap your app with FirstDistroProvider and pass your installation token.

tsx
// 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>
  )
}
tsx
// 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.

tsx
'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
}

Note: Only pass accountId if you need to override server-side account derivation (e.g. multi-domain org). Typical B2B installs need user id + email only.

4. page views are automatic

That's the whole install. Once setup() runs, the SDK automatically captures a $pageview event on the initial load and on every SPA route change — no manual track('page_viewed') and no "verify" step. Page views power Activity, Engagement, and Recency in your health scores out of the box.

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.

5. optional: track product moments

Page views give you a fair health score on day one. Custom events with useTrack are optional — they sharpen the Milestones signal for the moments that matter (activation, key feature adoption).

tsx
'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>
}

6. confirm it's working

Log in to your app and visit a couple of routes. Your events appear in the Customer Insights dashboard within seconds — that first logged-in session is the proof your install works.

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 (e.g. ?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):

tsx
<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

Alternative: script tag

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

See the Installation Guide for script tag instructions.