200 lines
4.4 KiB
Plaintext
200 lines
4.4 KiB
Plaintext
---
|
|
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: 'joe@doe.com',
|
|
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> |