React and Next.js quickstart

The React adapter initializes core, adds automatic page-view events, and resolves frustration events to React components. It supports React and React DOM 18 or later through peer dependencies.

Install

$ npm install @askdepth/react @askdepth/core

Your application must already have compatible react and react-dom packages. Install @askdepth/replay separately if you enable replay.

Create a client provider

'use client';

import type { ReactNode } from 'react';
import { AskdepthProvider } from '@askdepth/react';

export function AnalyticsProvider({ children }: { children: ReactNode }) {
  return (
    <AskdepthProvider
      writeKey="YOUR_BROWSER_WRITE_KEY"
      endpoint="https://YOUR_COLLECTOR/v1/telemetry"
      consent="unknown"
      environment="production"
    >
      {children}
    </AskdepthProvider>
  );
}

For Next.js App Router, wrap the relevant children with this client component from your server layout. The provider initializes core in an effect, so it does not start browser listeners during server rendering.

Do not initialize core independently with different options inside child components. The runtime is a singleton shared across providers. Use one stable application-level provider.

Send events from a component

'use client';

import { useAskdepth } from '@askdepth/react';

export function ExportButton() {
  const { track } = useAskdepth();

  return (
    <button
      type="button"
      onClick={() => track('export_requested', { format: 'pdf' })}
    >
      Export report
    </button>
  );
}

Connect consent choices to setConsent from @askdepth/core, or update the provider's consent prop from your application state. Events remain inactive while consent is unknown. Read consent and lifecycle before integrating your consent interface.

Provider options

The provider accepts core initialization options and children. Supply writeKey; apiKey is a supported alias for the same browser write key. If both exist, writeKey takes precedence. There is no separate server API key involved.

endpoint is optional in the type but required to start core. projectId is deprecated and does not authorize ingestion. See the full configuration reference.

Server rendering and router verification

The runtime entry declares 'use client'. Hooks and the provider belong in client components; the compiler plugin belongs in your build configuration. Browser collection does not run in Server Components or API handlers.

The adapter observes pushState, replaceState, and popstate. Next.js App Router navigation has not been validated end to end by the published package's application checks. Verify initial load, client navigation, back/forward, consent changes, and hydration in your own deployed Next.js version. See hooks and page views.