Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

4.4 KB
Raw Blame
---
title: Script Tag
description: The OpenPanel Web SDK allows you to track user behavior on your website using a simple script tag. This guide provides instructions for installing and using the Web SDK in your project.
---

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { PersonalDataWarning } from '@/components/personal-data-warning';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
import WebSdkConfig from '@/components/web-sdk-config.mdx';


## Installation

Just insert this snippet and replace `YOUR_CLIENT_ID` with your client id.

```html title="index.html" /clientId: 'YOUR_CLIENT_ID'/
<script>
  window.op=window.op||function(){var n=[];return new Proxy(function(){arguments.length&&n.push([].slice.call(arguments))},{get:function(t,r){return"q"===r?n:function(){n.push([r].concat([].slice.call(arguments)))}} ,has:function(t,r){return"q"===r}}) }();
  window.op('init', {
    clientId: 'YOUR_CLIENT_ID',
    trackScreenViews: true,
    trackOutgoingLinks: true,
    trackAttributes: true,
  });
</script>
<script src="https://openpanel.dev/op1.js" defer async></script>
```

#### Options

<CommonSdkConfig />
<WebSdkConfig />

## Usage

### Tracking Events

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

```html title="index.html"
<button type="button" onclick="window.op('track', 'my_event', { foo: 'bar' })">
  Track event
</button>
```

```html title="index.html"
<button type="button" data-track="my_event" data-foo="bar">Track event</button>
```

### Identifying Users

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

```js title="main.js"
window.op('identify', {
  profileId: '123', // Required
  firstName: 'Joe',
  lastName: 'Doe',
  email: '[email protected]',
  properties: {
    tier: 'premium',
  },
});
```

### Setting Global Properties

To set properties that will be sent with every event:

```js title="main.js"
window.op('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="main.js"
window.op('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="main.js"
window.op('decrement', {
  profileId: '1',
  property: 'visits',
  value: 1 // optional
});
```

### Clearing User Data

To clear the current user's data:

```js title="main.js"
window.op('clear');
```

## Advanced Usage

### Filtering events

You can filter out events by adding a `filter` property to the `init` method.

Below is an example of how to disable tracking for users who have a `disable_tracking` item in their local storage.

```js title="main.js"
window.op('init', {
  clientId: 'YOUR_CLIENT_ID',
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
  filter: () => localStorage.getItem('disable_tracking') === undefined,
});
```

### Using the Web SDK with NPM

<Steps>
#### Step 1: Install the SDK

```npm
npm install @openpanel/web
```

#### Step 2: Initialize the SDK

```js title="op.js"
import { OpenPanel } from '@openpanel/web';

const op = new OpenPanel({
  clientId: 'YOUR_CLIENT_ID',
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
});
```

#### Step 3: Use the SDK

```js title="main.js"
import { op } from './op.js';

op.track('my_event', { foo: 'bar' });
```
</Steps>

### Typescript

Getting ts errors when using the SDK? You can add a custom type definition file to your project.

#### Simple

Just paste this code in any of your `.d.ts` files.

```ts title="op.d.ts"
declare global {
  interface Window {
    op: {
      q?: string[][];
      (...args: [
        'init' | 'track' | 'identify' | 'setGlobalProperties' | 'increment' | 'decrement' | 'clear',
        ...any[]
      ]): void;
    };
  }
}
```

#### Strict typing (from sdk)

<Steps>
##### Step 1: Install the SDK

```npm
npm install @openpanel/web
```

##### Step 2: Create a type definition file

Create a `op.d.ts`file and paste the following code:

```ts title="op.d.ts"
/// <reference types="@openpanel/web" />
```
</Steps>