Next.js

Keep in mind that all tracking here happens on the client!

Read more about server side tracking in the Server Side Tracking section.

Installation

Install dependencies

pnpm install @openpanel/nextjs

Initialize

Add OpenpanelProvider to your root layout component.

import { OpenpanelProvider } from '@openpanel/nextjs';
 
export default RootLayout({ children }) {
  return (
    <>
      <OpenpanelProvider
        url="https://api.openpanel.dev"
        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}
    </>
  )
}

Config

url - The url of the openpanel API or your self-hosted instance
clientId - The client id of your application
trackScreenViews - If true, the library will automatically track screen views
trackOutgoingLinks - If true, the library will automatically track outgoing links
trackAttributes - If true, the library will automatically track attributes

Ready!

You're now ready to use the library.

import {
  decrement,
  increment,
  setProfile,
  setProfileId,
  trackEvent,
} from '@openpanel/nextjs';
 
// Sends an event with payload foo: bar
trackEvent('my_event', { foo: 'bar' });
 
// Identify with profile id
setProfileId('123');
 
// or with additional data
setProfile({
  profileId: '123',
  firstName: 'John',
  lastName: 'Doe',
  email: '[email protected]',
});
 
// Increment a property
increment('app_opened'); // increment by 1
increment('app_opened', 5); // increment by 5
 
// Decrement a property
decrement('app_opened'); // decrement by 1
decrement('app_opened', 5); // decrement by 5

Usage

Track event

import { trackEvent } from '@openpanel/nextjs';
trackEvent('my_event', { foo: 'bar' });

Identify

Set Profile Id

Keep track of your users by identifying them with a unique id. This is a good features if you have things behind a login and want to track user behavior.

⚠️

Keep in mind that this is considered personal data. Make sure you have the users consent before calling this!

import { setProfileId } from '@openpanel/nextjs';
 
const profileId = '123';
setProfileId(profileId);

Additional data

This method does the same as setProfileId but also allows you to update the profile with additional data.

⚠️

Keep in mind that this is considered personal data. Make sure you have the users consent before calling this!

import { setProfile } from '@openpanel/nextjs';
 
const profileId = '123';
setProfile({
  profileId,
  // firstName?: string;
  // lastName?: string;
  // email?: string;
  // avatar?: string;
  // properties?: Record<string, unknown>;
});

Increment property

Increment a property on the profile.

import { increment } from '@openpanel/nextjs';
 
// Increment by 1
increment('app_opened');
 
// Increment by 5
increment('app_opened', 5);

Decrement property

Decrement a property on the profile.

import { decrement } from '@openpanel/nextjs';
 
// Increment by 1
decrement('app_opened');
 
// Increment by 5
decrement('app_opened', 5);

Clear / Logout

Clear the profile id and all the data.

import { clear } from '@openpanel/nextjs';
 
clear();

Track server events

If you want to track server-side events, you should create an instance of our Javascript SDK. It's exported from @openpanel/nextjs

💡

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.

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: '✅' });

Proxy events

With createNextRouteHandler 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.

// file: /app/api/op/[...op]/route.ts
import { createNextRouteHandler } from '@openpanel/nextjs';
 
export const { POST } = createNextRouteHandler({
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
});

Remember to change the url in the OpenpanelProvider to your own server.

<OpenpanelProvider
  url="/api/op" // <---
  clientId="your-client-id"
  trackScreenViews={true}
/>

Script React