Skip to main content

React and Next.js Integration

Install​

npm install @drivemetadata-ai/sdk

React​

Wrap your application once:

import { DmdProvider } from '@drivemetadata-ai/sdk/react';

export function App() {
  return (
    <DmdProvider
      config={{
        clientId: 'client_xxx',
        workspaceId: 'workspace_xxx',
        appId: 'app_xxx',
        token: 'public_token',
        consent: { analytics: 'granted', advertising: 'denied' }
      }}
    >
      <Routes />
    </DmdProvider>
  );
}

Track events:

import { useTrackEvent } from '@drivemetadata-ai/sdk/react';

export function CTAButton() {
  const track = useTrackEvent();

  return (
    <button onClick={() => track('CTA Clicked', { location: 'pricing' })}>
      Start
    </button>
  );
}

Use the complete browser client surface from hooks:

import {
  useAlias,
  useDmdFlush,
  useGroup,
  useIdentify,
  usePage,
  useReset,
  useTrackEvent
} from '@drivemetadata-ai/sdk/react';

export function AnalyticsActions() {
  const track = useTrackEvent();
  const page = usePage();
  const identify = useIdentify();
  const group = useGroup();
  const alias = useAlias();
  const flush = useDmdFlush();
  const reset = useReset();

  async function onCheckout() {
    identify('user_123', { plan: 'enterprise' });
    group('account_123', { tier: 'enterprise' });
    alias('anonymous_123', 'user_123');
    page('Checkout');
    track('Checkout Started', { source: 'cart' });
    await flush();
  }

  return (
    <>
      <button onClick={onCheckout}>Track checkout</button>
      <button onClick={reset}>Reset</button>
    </>
  );
}

Next.js App Router​

Create a client provider:

'use client';

import { DmdProvider, useDmdAppRouterPageTracking } from '@drivemetadata-ai/sdk/next';
import { usePathname, useSearchParams } from 'next/navigation';

export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useDmdAppRouterPageTracking(pathname, searchParams.toString(), {
    name: 'Route Viewed'
  });

  return (
    <DmdProvider
      config={{
        clientId: process.env.NEXT_PUBLIC_DMD_CLIENT_ID!,
        workspaceId: process.env.NEXT_PUBLIC_DMD_WORKSPACE_ID!,
        appId: process.env.NEXT_PUBLIC_DMD_APP_ID!,
        token: process.env.NEXT_PUBLIC_DMD_TOKEN!,
        consent: { analytics: 'granted', advertising: 'denied' }
      }}
    >
      {children}
    </DmdProvider>
  );
}

Use it in app/layout.tsx:

import { AnalyticsProvider } from './AnalyticsProvider';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AnalyticsProvider>{children}</AnalyticsProvider>
      </body>
    </html>
  );
}

Next.js Pages Router​

Use a provider in _app.tsx:

import type { AppProps } from 'next/app';
import { useRouter } from 'next/router';
import { DmdProvider, useDmdPagesRouterPageTracking } from '@drivemetadata-ai/sdk/next';

function AnalyticsPageTracking() {
  const router = useRouter();
  useDmdPagesRouterPageTracking(router);
  return null;
}

export default function App({ Component, pageProps }: AppProps) {
  return (
    <DmdProvider config={config}>
      <AnalyticsPageTracking />
      <Component {...pageProps} />
    </DmdProvider>
  );
}

SSR Safety​

@drivemetadata-ai/sdk/react and @drivemetadata-ai/sdk/next can be imported during server rendering, but SDK initialization must run in the browser. In Next.js App Router, place DmdProvider inside a file that starts with 'use client'.

If consent is omitted, analytics defaults to pending; call consent.update() or pass an explicit consent object after your consent manager resolves.