300 lines
7.8 KiB
Plaintext
300 lines
7.8 KiB
Plaintext
---
|
|
title: Next.js
|
|
---
|
|
|
|
import Link from 'next/link';
|
|
import { Step, Steps } from 'fumadocs-ui/components/steps';
|
|
|
|
import { DeviceIdWarning } from '@/components/device-id-warning';
|
|
import { PersonalDataWarning } from '@/components/personal-data-warning';
|
|
import { Callout } from 'fumadocs-ui/components/callout';
|
|
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
|
|
import WebSdkConfig from '@/components/web-sdk-config.mdx';
|
|
|
|
<Callout>
|
|
Looking for a step-by-step tutorial? Check out the [Next.js analytics guide](/guides/nextjs-analytics).
|
|
</Callout>
|
|
|
|
## Good to know
|
|
|
|
Keep in mind that all tracking here happens on the client!
|
|
|
|
Read more about server side tracking in the [Server Side Tracking](#track-server-events) section.
|
|
|
|
## Installation
|
|
|
|
<Steps>
|
|
### Install dependencies
|
|
|
|
```bash
|
|
pnpm install @openpanel/nextjs
|
|
```
|
|
|
|
### Initialize
|
|
|
|
Add `OpenPanelComponent` to your root layout component.
|
|
|
|
```tsx
|
|
import { OpenPanelComponent } from '@openpanel/nextjs';
|
|
|
|
export default function RootLayout({ children }) {
|
|
return (
|
|
<>
|
|
<OpenPanelComponent
|
|
clientId="your-client-id"
|
|
trackScreenViews={true}
|
|
// trackAttributes={true}
|
|
// trackOutgoingLinks={true}
|
|
// If you have a user id, you can pass it here to identify the user
|
|
// profileId={'123'}
|
|
/>
|
|
{children}
|
|
</>
|
|
)
|
|
}
|
|
```
|
|
|
|
#### Options
|
|
|
|
<CommonSdkConfig />
|
|
<WebSdkConfig />
|
|
|
|
##### NextJS options
|
|
|
|
- `profileId` - If you have a user id, you can pass it here to identify the user
|
|
- `cdnUrl` (deprecated) - The url to the OpenPanel SDK (default: `https://openpanel.dev/op1.js`)
|
|
- `scriptUrl` - The url to the OpenPanel SDK (default: `https://openpanel.dev/op1.js`)
|
|
- `filter` - This is a function that will be called before tracking an event. If it returns false the event will not be tracked. [Read more](#filter)
|
|
- `globalProperties` - This is an object of properties that will be sent with every event.
|
|
|
|
##### `filter`
|
|
|
|
This options needs to be a stringified function and cannot access any variables outside of the function.
|
|
|
|
```tsx
|
|
<OpenPanelComponent
|
|
clientId="your-client-id"
|
|
filter={`
|
|
function filter(event) {
|
|
return event.name !== 'my_event';
|
|
}
|
|
`}
|
|
/>
|
|
```
|
|
|
|
To take advantage of typescript you can do the following. _Note `toString`_
|
|
```tsx /.toString();/
|
|
import { type TrackHandlerPayload } from '@openpanel/nextjs';
|
|
|
|
const opFilter = ((event: TrackHandlerPayload) => {
|
|
return event.type === 'track' && event.payload.name === 'my_event';
|
|
}).toString();
|
|
|
|
<OpenPanelComponent
|
|
clientId="your-client-id"
|
|
filter={opFilter}
|
|
/>
|
|
```
|
|
|
|
</Steps>
|
|
|
|
## Usage
|
|
|
|
### Client components
|
|
|
|
For client components you can just use the `useOpenPanel` hook.
|
|
|
|
```tsx
|
|
import { useOpenPanel } from '@openpanel/nextjs';
|
|
|
|
function YourComponent() {
|
|
const op = useOpenPanel();
|
|
|
|
return <button type="button" onClick={() => op.track('my_event', { foo: 'bar' })}>Trigger event</button>
|
|
}
|
|
```
|
|
|
|
### Server components
|
|
|
|
Since you can't use hooks in server components, you need to create an instance of the SDK. This is exported from `@openpanel/nextjs`.
|
|
|
|
<Callout>Remember, your client secret is exposed here so do not use this on client side.</Callout>
|
|
|
|
```tsx title="utils/op.ts"
|
|
import { OpenPanel } from '@openpanel/nextjs';
|
|
|
|
export const op = new OpenPanel({
|
|
clientId: 'your-client-id',
|
|
clientSecret: 'your-client-secret',
|
|
});
|
|
|
|
// Now you can use `op` to track events
|
|
op.track('my_event', { foo: 'bar' });
|
|
```
|
|
|
|
Refer to the [Javascript SDK](/docs/sdks/javascript#usage) for usage instructions.
|
|
|
|
### Tracking Events
|
|
|
|
You can track events with two different methods: by calling the `op.track( directly or by adding `data-track` attributes to your HTML elements.
|
|
|
|
```ts title="index.ts"
|
|
useOpenPanel().track('my_event', { foo: 'bar' });
|
|
```
|
|
|
|
### Identifying Users
|
|
|
|
To identify a user, call the `op.identify( method with a unique identifier.
|
|
|
|
```js title="index.js"
|
|
useOpenPanel().identify({
|
|
profileId: '123', // Required
|
|
firstName: 'Joe',
|
|
lastName: 'Doe',
|
|
email: 'joe@doe.com',
|
|
properties: {
|
|
tier: 'premium',
|
|
},
|
|
});
|
|
```
|
|
|
|
#### For server components
|
|
|
|
For server components you can use the `IdentifyComponent` component which is exported from `@openpanel/nextjs`.
|
|
|
|
> This component is great if you have the user data available on the server side.
|
|
|
|
```tsx title="app/nested/layout.tsx"
|
|
import { IdentifyComponent } from '@openpanel/nextjs';
|
|
|
|
export default function Layout({ children }) {
|
|
const user = await getCurrentUser()
|
|
|
|
return (
|
|
<>
|
|
<IdentifyComponent
|
|
profileId={user.id}
|
|
firstName={user.firstName}
|
|
lastName={user.lastName}
|
|
email={user.email}
|
|
properties={{
|
|
tier: 'premium',
|
|
}}
|
|
/>
|
|
{children}
|
|
</>
|
|
)
|
|
}
|
|
```
|
|
|
|
|
|
### Setting Global Properties
|
|
|
|
To set properties that will be sent with every event:
|
|
|
|
```js title="index.js"
|
|
useOpenPanel().setGlobalProperties({
|
|
app_version: '1.0.2',
|
|
environment: 'production',
|
|
});
|
|
```
|
|
|
|
### Incrementing Properties
|
|
|
|
To increment a numeric property on a user profile.
|
|
|
|
- `value` is the amount to increment the property by. If not provided, the property will be incremented by 1.
|
|
|
|
```js title="index.js"
|
|
useOpenPanel().increment({
|
|
profileId: '1',
|
|
property: 'visits',
|
|
value: 1 // optional
|
|
});
|
|
```
|
|
|
|
### Decrementing Properties
|
|
|
|
To decrement a numeric property on a user profile.
|
|
|
|
- `value` is the amount to decrement the property by. If not provided, the property will be decremented by 1.
|
|
|
|
```js title="index.js"
|
|
useOpenPanel().decrement({
|
|
profileId: '1',
|
|
property: 'visits',
|
|
value: 1 // optional
|
|
});
|
|
```
|
|
|
|
### Clearing User Data
|
|
|
|
To clear the current user's data:
|
|
|
|
```js title="index.js"
|
|
useOpenPanel().clear()
|
|
```
|
|
|
|
## Server side
|
|
|
|
If you want to track server-side events, you should create an instance of our Javascript SDK. It's exported from `@openpanel/nextjs`
|
|
|
|
<Callout>
|
|
When using server events it's important that you use a secret to authenticate the request. This is to prevent unauthorized requests since we cannot use cors headers.
|
|
|
|
You can use the same clientId but you should pass the associated client secret to the SDK.
|
|
|
|
</Callout>
|
|
|
|
```typescript
|
|
import { OpenpanelSdk } from '@openpanel/nextjs';
|
|
|
|
const opServer = new OpenpanelSdk({
|
|
clientId: '{YOUR_CLIENT_ID}',
|
|
clientSecret: '{YOUR_CLIENT_SECRET}',
|
|
});
|
|
|
|
opServer.event('my_server_event', { ok: '✅' });
|
|
|
|
// Pass `profileId` to track events for a specific user
|
|
opServer.event('my_server_event', { profileId: '123', ok: '✅' });
|
|
```
|
|
|
|
### Serverless & Vercel
|
|
|
|
If you log events in a serverless environment like Vercel, you can use `waitUntil` to ensure the event is logged before the function is done.
|
|
|
|
Otherwise your function might close before the event is logged. Read more about it [here](https://vercel.com/docs/functions/functions-api-reference#waituntil).
|
|
|
|
```typescript
|
|
import { waitUntil } from '@vercel/functions';
|
|
import { opServer } from 'path/to/your-sdk-instance';
|
|
|
|
export function GET() {
|
|
// Returns a response immediately while keeping the function alive
|
|
waitUntil(opServer.event('my_server_event', { foo: 'bar' }));
|
|
return new Response(`You're event has been logged!`);
|
|
}
|
|
```
|
|
|
|
### Proxy events
|
|
|
|
With `createRouteHandler` you can proxy your events through your server, this will ensure all events are tracked since there is a lot of adblockers that block requests to third party domains. The handler automatically routes requests based on the path, supporting both API endpoints (like `/track` and `/track/device-id`) and the tracking script (`/op1.js`).
|
|
|
|
```typescript title="/app/api/[...op]/route.ts"
|
|
import { createRouteHandler } from '@openpanel/nextjs/server';
|
|
|
|
export const { GET, POST } = createRouteHandler();
|
|
```
|
|
|
|
Remember to change the `apiUrl` and `scriptUrl` in the `OpenPanelComponent` to your own server.
|
|
|
|
```tsx
|
|
<OpenPanelComponent
|
|
apiUrl="/api/op" // [!code highlight]
|
|
scriptUrl="/api/op/op1.js" // [!code highlight]
|
|
clientId="your-client-id"
|
|
trackScreenViews={true}
|
|
/>
|
|
```
|