npm package: @openpanel/nuxt
Description: > 📖 **Full documentation:** [https://openpanel.dev/docs/sdks/nuxt](https://openpanel.dev/docs/sdks/nuxt)
Latest version: 0.3.0

# Nuxt

> 📖 **Full documentation:** [https://openpanel.dev/docs/sdks/nuxt](https://openpanel.dev/docs/sdks/nuxt)

---

Looking for a step-by-step tutorial? Check out the [Nuxt analytics guide](https://openpanel.dev/guides/nuxt-analytics).

## 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

### Install dependencies

```bash
pnpm install @openpanel/nuxt
```

### Initialize

Add the module to your `nuxt.config.ts`:

```typescript
export default defineNuxtConfig({
  modules: ['@openpanel/nuxt'],
  openpanel: {
    clientId: 'your-client-id',
    trackScreenViews: true,
    trackOutgoingLinks: true,
    trackAttributes: true,
  },
});
```

#### Options

##### Common options

- `apiUrl` - The url of the openpanel API or your self-hosted instance
- `clientId` - The client id of your application
- `clientSecret` - The client secret of your application (**only required for server-side events**)
- `filter` - A function that will be called before sending an event. If it returns false, the event will not be sent
- `disabled` - If true, the library will not send any events

##### Web options

- `trackScreenViews` - If true, the library will automatically track screen views (default: false)
- `trackOutgoingLinks` - If true, the library will automatically track outgoing links (default: false)
- `trackAttributes` - If true, you can trigger events by using html attributes (`<button type="button" data-track="your_event" />`) (default: false)
- `sessionReplay` - Session replay configuration object (default: disabled). See [session replay docs](https://openpanel.dev/docs/session-replay) for full options.
  - `enabled` - Enable session replay recording (default: false)
  - `maskAllInputs` - Mask all input field values (default: true)
  - `maskTextSelector` - CSS selector for text elements to mask (default: `[data-openpanel-replay-mask]`)
  - `blockSelector` - CSS selector for elements to replace with a placeholder (default: `[data-openpanel-replay-block]`)
  - `blockClass` - Class name that blocks elements from being recorded
  - `ignoreSelector` - CSS selector for elements excluded from interaction tracking
  - `flushIntervalMs` - How often (ms) recorded events are sent to the server (default: 10000)
  - `maxEventsPerChunk` - Maximum events per payload chunk (default: 200)
  - `maxPayloadBytes` - Maximum payload size in bytes (default: 1048576)
  - `scriptUrl` - Custom URL for the replay script (script-tag builds only)

##### Nuxt options

- `clientId` - Your OpenPanel client ID (required)
- `apiUrl` - The API URL to send events to (default: `https://api.openpanel.dev`)
- `trackScreenViews` - Automatically track screen views (default: `true`)
- `trackOutgoingLinks` - Automatically track outgoing links (default: `true`)
- `trackAttributes` - Automatically track elements with `data-track` attributes (default: `true`)
- `trackHashChanges` - Track hash changes in URL (default: `false`)
- `disabled` - Disable tracking (default: `false`)
- `proxy` - Enable server-side proxy to avoid adblockers (default: `false`)

## Usage

### Using the composable

The `useOpenPanel` composable is auto-imported, so you can use it directly in any component:

```vue
<script setup>
const op = useOpenPanel(); // Auto-imported!

function handleClick() {
  op.track('button_click', { button: 'signup' });
}
</script>

<template>
  <button @click="handleClick">Trigger event</button>
</template>
```

### Accessing via useNuxtApp

You can also access the OpenPanel instance directly via `useNuxtApp()`:

```vue
<script setup>
const { $openpanel } = useNuxtApp();

$openpanel.track('my_event', { foo: 'bar' });
</script>
```

### Tracking Events

You can track events with two different methods: by calling the `op.track()` method directly or by adding `data-track` attributes to your HTML elements.

```vue
<script setup>
const op = useOpenPanel();
op.track('my_event', { foo: 'bar' });
</script>
```

### Identifying Users

To identify a user, call the `op.identify()` method with a unique identifier.

```vue
<script setup>
const op = useOpenPanel();

op.identify({
  profileId: '123', // Required
  firstName: 'Joe',
  lastName: 'Doe',
  email: 'joe@doe.com',
  properties: {
    tier: 'premium',
  },
});
</script>
```

### Setting Global Properties

To set properties that will be sent with every event:

```vue
<script setup>
const op = useOpenPanel();

op.setGlobalProperties({
  app_version: '1.0.2',
  environment: 'production',
});
</script>
```

### 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.

```vue
<script setup>
const op = useOpenPanel();

op.increment({
  profileId: '1',
  property: 'visits',
  value: 1, // optional
});
</script>
```

### 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.

```vue
<script setup>
const op = useOpenPanel();

op.decrement({
  profileId: '1',
  property: 'visits',
  value: 1, // optional
});
</script>
```

### Clearing User Data

To clear the current user's data:

```vue
<script setup>
const op = useOpenPanel();

op.clear();
</script>
```

## Server side

If you want to track server-side events, you should create an instance of our Javascript SDK. Import `OpenPanel` from `@openpanel/sdk`

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.

```typescript
import { OpenPanel } from '@openpanel/sdk';

const opServer = new OpenPanel({
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
});

opServer.track('my_server_event', { ok: '✅' });

// Pass `profileId` to track events for a specific user
opServer.track('my_server_event', { profileId: '123', ok: '✅' });
```

### Serverless & Edge Functions

If you log events in a serverless environment, make sure to await the event call to ensure it completes before the function terminates.

```typescript
import { OpenPanel } from '@openpanel/sdk';

const opServer = new OpenPanel({
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
});

export default defineEventHandler(async (event) => {
  // Await to ensure event is logged before function completes
  await opServer.track('my_server_event', { foo: 'bar' });
  return { message: 'Event logged!' };
});
```

### Proxy events

With the `proxy` option enabled, you can proxy your events through your server, which ensures all events are tracked since many adblockers block requests to third-party domains.

```typescript title="nuxt.config.ts"
export default defineNuxtConfig({
  modules: ['@openpanel/nuxt'],
  openpanel: {
    clientId: 'your-client-id',
    proxy: true, // Enables proxy at /api/openpanel/*
  },
});
```

When `proxy: true` is set:
- The module automatically sets `apiUrl` to `/api/openpanel`
- A server handler is registered at `/api/openpanel/**`
- All tracking requests route through your server

This helps bypass adblockers that might block requests to `api.openpanel.dev`.