TrueClaradocs
GitHub
Reference/@trueclara/next

@trueclara/next

Runtime provider setup, public key behavior, consent handoff, and event delivery for Next.js apps.

@trueclara/next is the browser runtime for Next.js apps. It records route and transition signals for the project identified by NEXT_PUBLIC_TRUECLARA_KEY.

Install

Prefer the project setup command because it includes the correct public key:

Terminal
NEXT_PUBLIC_TRUECLARA_KEY=<project-public-key> npx @trueclara/install

The installer adds @trueclara/next and attempts to wrap the app shell. If it cannot edit safely, use the manual provider setup.

Provider

TSX
import { TrueClaraProvider } from "@trueclara/next";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <TrueClaraProvider publicKey={process.env.NEXT_PUBLIC_TRUECLARA_KEY!}>
          {children}
        </TrueClaraProvider>
      </body>
    </html>
  );
}

Place the provider around the App Router shell so it can observe client-side route transitions.

Public key

NEXT_PUBLIC_TRUECLARA_KEY is safe in the browser. It identifies the project for runtime event delivery. It cannot upload static graphs or deploy records.

Keep TRUECLARA_PROJECT_KEY in CI or server-side code only.

Your app owns consent UI. Bridge the result into TrueClara:

TSX
import { useEffect } from "react";
import { useTrueClara } from "@trueclara/next";

export function AnalyticsConsentBridge({ allowed }: { allowed: boolean }) {
  const trueclara = useTrueClara();

  useEffect(() => {
    trueclara.setConsent({ analytics: allowed });
  }, [allowed, trueclara]);

  return null;
}

Event delivery

The SDK sends route and transition events after consent allows delivery. Events are buffered and sent to the ingestion endpoint without blocking host app navigation.

If events do not appear:

  1. Confirm the provider wraps the app shell.
  2. Confirm the public key belongs to the project you are viewing.
  3. Confirm consent is not none.
  4. Confirm the browser can reach the ingestion endpoint.
  5. Use the project setup test event to isolate SDK configuration from backend delivery.

What the SDK does not do

  • It does not render a cookie banner.
  • It does not upload graphs or deploy records.
  • It does not replace product analytics.
  • It does not require persistent user identity for aggregate behavior health.