First DistroFirstDistro

Quick start (npm)

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

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

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 (for example a multi-domain org). Typical B2B installs need user id + email only.

4. page views are automatic

That is 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 separate 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 feed Activity and Recency. They only move Milestones when the event name is a default or custom milestone.

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 is working

Log in to your app and visit a couple of routes. Watch the live feed on Settings → SDK Configuration. Accounts show up in Customer Insights once events are linked to users. 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 (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):

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 are not using a bundler, you can install via script tag instead.

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