Web (Script Tag)

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.

Installation

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

<script>
  window.op = window.op||function(...args){(window.op.q=window.op.q||[]).push(args);};
  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

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
• waitForProfile - If true, the library will wait for the profile to be set before sending 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 data-track="your_event" />) (default: false)

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.

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

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

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:

window.op('setGlobalProperties', {
  app_version: '1.0.2',
  environment: 'production',
});

Creating Aliases

To create an alias for a user:

window.op('alias', {
  alias: 'a1',
  profileId: '1'
});

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.

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.

window.op('decrement', {
  profileId: '1',
  property: 'visits',
  value: 1 // optional
});

Clearing User Data

To clear the current user's data:

window.op('clear');

Advanced Usage

Using the Web SDK with NPM

npm install @openpanel/web

import { OpenPanel } from '@openpanel/web';
 
const op = new OpenPanel({
  clientId: 'YOUR_CLIENT_ID',
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
});

import { op } from './op.js';
 
op.track('my_event', { foo: 'bar' });

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.

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

Strict typing (from sdk)

npm install @openpanel/web

/// <reference types="@openpanel/web" />