> ## Documentation Index
> Fetch the complete documentation index at: https://learn.biq.li/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js

> Capture attribution in a client component and send trusted events from a route handler.

A Next.js integration normally uses two packages:

* `@biqli/analytics` in client components to capture `bq_id`.
* `@biqli/sdk` in server-only modules to send trusted conversions.

```bash theme={null}
npm install @biqli/analytics @biqli/sdk
```

## Add the client provider

```tsx theme={null}
'use client';

import {BiqliProvider} from '@biqli/analytics/react';

const config = {
  publishableKey: process.env.NEXT_PUBLIC_BIQLI_PUBLISHABLE_KEY!,
};

export function Providers({children}: {children: React.ReactNode}) {
  return <BiqliProvider config={config}>{children}</BiqliProvider>;
}
```

Only the publishable key may use a `NEXT_PUBLIC_` variable.

## Create a server-only client

```ts theme={null}
// lib/biqli.server.ts
import 'server-only';
import {Biqli} from '@biqli/sdk';

export const biqli = new Biqli({
  apiKey: process.env.BIQLI_API_KEY!,
  clientName: 'acme-nextjs',
});
```

Do not import this module into a client component.

## Send a lead from a route handler

```ts theme={null}
// app/api/signup/route.ts
import {cookies} from 'next/headers';
import {biqli} from '@/lib/biqli.server';

export async function POST(request: Request) {
  const input = await request.json();
  const customer = await createCustomer(input);
  const cookieStore = await cookies();

  await biqli.track.lead({
    clickId: cookieStore.get('bq_id')?.value,
    eventId: `signup:${customer.id}`,
    eventName: 'Signed up',
    customerExternalId: customer.id,
    customerEmail: customer.email,
  });

  return Response.json({id: customer.id}, {status: 201});
}
```

Create the customer first. Track the lead only after the business action succeeds.

## Send sales from trusted code

Call `biqli.track.sale()` from a verified payment webhook, server action, route handler, or background job. Do not treat a client redirect to a success page as proof of payment.

<Warning>
  Keep `BIQLI_API_KEY` server-only. If it appears in a browser bundle, rotate it immediately.
</Warning>