feature(public,docs): new public website and docs
This commit is contained in:
Carl-Gerhard Lindesvärd
177
apps/public/content/docs/api/export.mdx
Normal file
177
apps/public/content/docs/api/export.mdx
Normal file
@@ -0,0 +1,177 @@
|
||||
---
|
||||
title: Export
|
||||
description: The Export API allows you to retrieve event data and chart data from your OpenPanel projects.
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
To authenticate with the Export API, you need to use your `clientId` and `clientSecret`. Make sure your client has `read` or `root` mode. The default client does not have access to the Export API.
|
||||
|
||||
Include the following headers with your requests:
|
||||
- `openpanel-client-id`: Your OpenPanel client ID
|
||||
- `openpanel-client-secret`: Your OpenPanel client secret
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
curl 'https://api.openpanel.dev/export/events' \
|
||||
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
||||
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
||||
```
|
||||
|
||||
## Events
|
||||
|
||||
Get events from a specific project within a date range.
|
||||
|
||||
Endpoint: `GET /export/events`
|
||||
|
||||
Parameters:
|
||||
- project_id (required): The ID of the project
|
||||
- event (optional): Filter by event name(s). Can be a single event or an array of events.
|
||||
- start (optional): Start date (format: YYYY-MM-DD)
|
||||
- end (optional): End date (format: YYYY-MM-DD)
|
||||
- page (optional, default: 1): Page number for pagination
|
||||
- limit (optional, default: 50, max: 50): Number of events per page
|
||||
- includes (optional): Additional fields to include in the response
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
curl 'https://api.openpanel.dev/export/events?project_id=abc&event=screen_view&start=2024-04-15&end=2024-04-18' \
|
||||
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
||||
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
||||
```
|
||||
|
||||
### Query Parameters
|
||||
|
||||
| Parameter | Type | Description | Example |
|
||||
|-----------|------|-------------|---------|
|
||||
| projectId | string | The ID of the project to fetch events from | `abc123` |
|
||||
| event | string or string[] | Event name(s) to filter | `screen_view` or `["screen_view","button_click"]` |
|
||||
| start | string | Start date for the event range (ISO format) | `2024-04-15` |
|
||||
| end | string | End date for the event range (ISO format) | `2024-04-18` |
|
||||
| page | number | Page number for pagination (default: 1) | `2` |
|
||||
| limit | number | Number of events per page (default: 50, max: 50) | `25` |
|
||||
| includes | string or string[] | Additional fields to include in the response | `profile` or `["profile","meta"]` |
|
||||
|
||||
### Example Request
|
||||
|
||||
```bash
|
||||
curl 'https://api.openpanel.dev/export/events?project_id=abc123&event=screen_view&start=2024-04-15&end=2024-04-18&page=1&limit=50&includes=profile,meta' \
|
||||
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
||||
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"meta": {
|
||||
"count": number,
|
||||
"totalCount": number,
|
||||
"pages": number,
|
||||
"current": number
|
||||
},
|
||||
"data": Array<Event>
|
||||
}
|
||||
```
|
||||
|
||||
## Charts
|
||||
|
||||
Retrieve chart data for a specific project.
|
||||
|
||||
### Endpoint
|
||||
|
||||
```
|
||||
GET /export/charts
|
||||
```
|
||||
|
||||
### Query Parameters
|
||||
|
||||
| Parameter | Type | Description | Example |
|
||||
|-----------|------|-------------|---------|
|
||||
| projectId | string | The ID of the project to fetch chart data from | `abc123` |
|
||||
| events | string[] | Array of event names to include in the chart | `["sign_up","purchase"]` |
|
||||
| breakdowns | object[] | Array of breakdown configurations | `[{"name":"country"}]` |
|
||||
| interval | string | Time interval for data points | `day` |
|
||||
| range | string | Predefined date range | `last_7_days` |
|
||||
| previous | boolean | Include data from the previous period | `true` |
|
||||
| startDate | string | Custom start date (ISO format) | `2024-04-01` |
|
||||
| endDate | string | Custom end date (ISO format) | `2024-04-30` |
|
||||
| chartType | string | Type of chart to generate | `linear` |
|
||||
| metric | string | Metric to use for calculations | `sum` |
|
||||
| limit | number | Limit the number of results | `10` |
|
||||
| offset | number | Offset for pagination | `0` |
|
||||
|
||||
### Example Request
|
||||
|
||||
```bash
|
||||
curl 'https://api.openpanel.dev/export/charts?projectId=abc123&events=["sign_up","purchase"]&interval=day&range=last_30_days&chartType=linear&metric=sum' \
|
||||
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
||||
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
The response will include chart data with series, metrics, and optional previous period comparisons based on the input parameters.
|
||||
|
||||
## Funnel
|
||||
|
||||
Retrieve funnel data for a specific project.
|
||||
|
||||
### Endpoint
|
||||
|
||||
```
|
||||
GET /export/funnel
|
||||
```
|
||||
|
||||
### Query Parameters
|
||||
|
||||
| Parameter | Type | Description | Example |
|
||||
|-----------|------|-------------|---------|
|
||||
| projectId | string | The ID of the project to fetch funnel data from | `abc123` |
|
||||
| events | object[] | Array of event configurations for the funnel steps | `[{"name":"sign_up","filters":[]}]` |
|
||||
| range | string | Predefined date range | `last_30_days` |
|
||||
| startDate | string | Custom start date (ISO format) | `2024-04-01` |
|
||||
| endDate | string | Custom end date (ISO format) | `2024-04-30` |
|
||||
|
||||
### Example Request
|
||||
|
||||
```bash
|
||||
curl 'https://api.openpanel.dev/export/funnel?projectId=abc123&events=[{"name":"sign_up"},{"name":"purchase"}]&range=last_30_days' \
|
||||
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
||||
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
The response will include funnel data with total sessions and step-by-step breakdown of the funnel progression.
|
||||
|
||||
```json
|
||||
{
|
||||
"totalSessions": number,
|
||||
"steps": [
|
||||
{
|
||||
"event": {
|
||||
"name": string,
|
||||
"displayName": string
|
||||
},
|
||||
"count": number,
|
||||
"percent": number,
|
||||
"dropoffCount": number,
|
||||
"dropoffPercent": number,
|
||||
"previousCount": number
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- All date parameters should be in ISO format (YYYY-MM-DD).
|
||||
- The `range` parameter accepts values like `today`, `yesterday`, `last_7_days`, `last_30_days`, `this_month`, `last_month`, `this_year`, `last_year`, `all_time`.
|
||||
- The `interval` parameter accepts values like `minute`, `hour`, `day`, `month`.
|
||||
- The `chartType` parameter can be `linear` or other supported chart types.
|
||||
- The `metric` parameter can be `sum`, `average`, `min`, or `max`.
|
||||
|
||||
Remember to replace `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` with your actual OpenPanel API credentials.
|
||||
4
apps/public/content/docs/api/meta.json
Normal file
4
apps/public/content/docs/api/meta.json
Normal file
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"title": "API",
|
||||
"pages": ["track", "export"]
|
||||
}
|
||||
145
apps/public/content/docs/api/track.mdx
Normal file
145
apps/public/content/docs/api/track.mdx
Normal file
@@ -0,0 +1,145 @@
|
||||
---
|
||||
title: Track
|
||||
description: This guide demonstrates how to interact with the OpenPanel API using cURL. These examples provide a low-level understanding of the API endpoints and can be useful for testing or for integrations where a full SDK isn't available.
|
||||
---
|
||||
|
||||
## Good to know
|
||||
|
||||
- If you want to track **geo location** you'll need to pass the `ip` property as a header `x-client-ip`
|
||||
- If you want to track **device information** you'll need to pass the `user-agent` property as a header `user-agent`
|
||||
|
||||
## Authentication
|
||||
|
||||
All requests to the OpenPanel API require authentication. You'll need to include your `clientId` and `clientSecret` in the headers of each request.
|
||||
|
||||
```bash
|
||||
-H "openpanel-client-id: YOUR_CLIENT_ID" \
|
||||
-H "openpanel-client-secret: YOUR_CLIENT_SECRET"
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Base URL
|
||||
|
||||
All API requests should be made to:
|
||||
|
||||
```
|
||||
https://api.openpanel.dev
|
||||
```
|
||||
|
||||
### Tracking Events
|
||||
|
||||
To track an event:
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.openpanel.dev/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "openpanel-client-id: YOUR_CLIENT_ID" \
|
||||
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
|
||||
-d '{
|
||||
"type": "track",
|
||||
"payload": {
|
||||
"name": "my_event",
|
||||
"properties": {
|
||||
"foo": "bar"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Identifying Users
|
||||
|
||||
To identify a user:
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.openpanel.dev/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "openpanel-client-id: YOUR_CLIENT_ID" \
|
||||
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
|
||||
-d '{
|
||||
"type": "identify",
|
||||
"payload": {
|
||||
"profileId": "123",
|
||||
"firstName": "Joe",
|
||||
"lastName": "Doe",
|
||||
"email": "joe@doe.com",
|
||||
"properties": {
|
||||
"tier": "premium"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Creating Aliases
|
||||
To create an alias for a user:
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.openpanel.dev/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "openpanel-client-id: YOUR_CLIENT_ID" \
|
||||
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
|
||||
-d '{
|
||||
"type": "alias",
|
||||
"payload": {
|
||||
"profileId": "1",
|
||||
"alias": "a1"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Incrementing Properties
|
||||
To increment a numeric property:
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.openpanel.dev/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "openpanel-client-id: YOUR_CLIENT_ID" \
|
||||
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
|
||||
-d '{
|
||||
"type": "increment",
|
||||
"payload": {
|
||||
"profileId": "1",
|
||||
"property": "visits",
|
||||
"value": 1
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Decrementing Properties
|
||||
To decrement a numeric property:
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.openpanel.dev/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "openpanel-client-id: YOUR_CLIENT_ID" \
|
||||
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
|
||||
-d '{
|
||||
"type": "decrement",
|
||||
"payload": {
|
||||
"profileId": "1",
|
||||
"property": "visits",
|
||||
"value": 1
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
The API uses standard HTTP response codes to indicate the success or failure of requests. In case of an error, the response body will contain more information about the error.
|
||||
Example error response:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Invalid client credentials",
|
||||
"status": 401
|
||||
}
|
||||
```
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
The API implements rate limiting to prevent abuse. If you exceed the rate limit, you'll receive a 429 (Too Many Requests) response. The response will include headers indicating your rate limit status.
|
||||
|
||||
Best Practices
|
||||
1. Always use HTTPS to ensure secure communication.
|
||||
2. Store your clientId and clientSecret securely and never expose them in client-side code.
|
||||
3. Implement proper error handling in your applications.
|
||||
4. Respect rate limits and implement exponential backoff for retries.
|
||||
59
apps/public/content/docs/index.mdx
Normal file
59
apps/public/content/docs/index.mdx
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: Introduction
|
||||
description: The OpenPanel SDKs provide a set of core methods that allow you to track events, identify users, and more. Here's an overview of the key methods available in the SDKs.
|
||||
---
|
||||
|
||||
<Callout>
|
||||
While all OpenPanel SDKs share a common set of core methods, some may have
|
||||
syntax variations or additional methods specific to their environment. This
|
||||
documentation provides an overview of the base methods and available SDKs.
|
||||
</Callout>
|
||||
|
||||
## Core Methods
|
||||
|
||||
### Set global properties
|
||||
|
||||
Sets global properties that will be included with every subsequent event.
|
||||
|
||||
### Track
|
||||
|
||||
Tracks a custom event with the given name and optional properties.
|
||||
|
||||
#### Tips
|
||||
|
||||
You can identify the user directly with this method.
|
||||
|
||||
```js filename="Example shown in JavaScript"
|
||||
track('your_event_name', {
|
||||
foo: 'bar',
|
||||
baz: 'qux',
|
||||
// reserved property name
|
||||
__identify: {
|
||||
profileId: 'your_user_id', // required
|
||||
email: 'your_user_email',
|
||||
firstName: 'your_user_name',
|
||||
lastName: 'your_user_name',
|
||||
avatar: 'your_user_avatar',
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Identify
|
||||
|
||||
Associates the current user with a unique identifier and optional traits.
|
||||
|
||||
### Alias
|
||||
|
||||
Creates an alias for a user identifier.
|
||||
|
||||
### Increment
|
||||
|
||||
Increments a numeric property for a user.
|
||||
|
||||
### Decrement
|
||||
|
||||
Decrements a numeric property for a user.
|
||||
|
||||
### Clear
|
||||
|
||||
Clears the current user identifier and ends the session.
|
||||
40
apps/public/content/docs/migration/beta-v1.mdx
Normal file
40
apps/public/content/docs/migration/beta-v1.mdx
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Beta to V1
|
||||
description: We are happy to announce the release of `v1` of the Openpanel SDK. This release includes a lot of improvements and changes to the SDK. This guide will help you migrate from the `beta` version to the `v1` version.
|
||||
---
|
||||
|
||||
## General
|
||||
|
||||
The `Openpanel` class is now called `OpenPanel`!
|
||||
|
||||
## Options
|
||||
|
||||
- Renamed: `api` to `apiUrl`
|
||||
- Added: `disabled`
|
||||
- Added: `filter`
|
||||
|
||||
## Methods
|
||||
- Renamed: `event` method is now called `track`
|
||||
- Renamed: `setProfile` and `setProfileId` is now called `identify` (and combined)
|
||||
- Changed: `increment('app_opened', 5)` is now `increment({ name: 'app_opened', value: 5, profileId: '123' })`. So profile ID is now required.
|
||||
- Changed: `decrement('app_opened', 5)` is now `decrement({ name: 'app_opened', value: 5, profileId: '123' })`. So profile ID is now required.
|
||||
- Improved: `screenView` method has 2 arguments now. This change is more aligned with `@openpanel/react-native`.
|
||||
```ts
|
||||
screenView(properties?: TrackProperties): void;
|
||||
screenView(path: string, properties?: TrackProperties): void;
|
||||
|
||||
// Example
|
||||
op.screenView('/home', { title: 'Home' }); // path will be "/home"
|
||||
op.screenView({ title: 'Home' }); // path will be what ever window.location.pathname is
|
||||
```
|
||||
|
||||
## Script tag
|
||||
|
||||
- New: `https://openpanel.dev/op1.js` should be used instead of `op.js` (note the filename)
|
||||
- Renamed: Tracking with attributes have changed. Use `data-track="my_event"` instead of `data-event="my_event"`
|
||||
|
||||
## @openpanel/nextjs
|
||||
|
||||
- Renamed: `OpenpanelProvider` to `OpenPanelComponent`
|
||||
- Removed: All exported methods (trackEvent etc). Use the `useOpenPanel` hook instead since these are client tracking only
|
||||
- Moved: `createNextRouteHandler` is moved to `@openpanel/nextjs/server`
|
||||
5
apps/public/content/docs/sdks/astro.mdx
Normal file
5
apps/public/content/docs/sdks/astro.mdx
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: Astro
|
||||
---
|
||||
|
||||
You can use [script tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) to track events in Astro.
|
||||
80
apps/public/content/docs/sdks/express.mdx
Normal file
80
apps/public/content/docs/sdks/express.mdx
Normal file
@@ -0,0 +1,80 @@
|
||||
---
|
||||
title: Express
|
||||
description: The Express middleware is a basic wrapper around Javascript SDK. It provides a simple way to add the SDK to your Express application.
|
||||
---
|
||||
|
||||
import Link from 'next/link';
|
||||
import { DeviceIdWarning } from '@/components/device-id-warning';
|
||||
import { PersonalDataWarning } from '@/components/personal-data-warning';
|
||||
|
||||
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pnpm install @openpanel/express
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
The default export of `@openpanel/express` is a function that returns an Express middleware. It will also append the Openpanel SDK to the `req` object.
|
||||
|
||||
You can access it via `req.op`.
|
||||
|
||||
```ts
|
||||
import express from 'express';
|
||||
|
||||
import createOpenpanelMiddleware from '@openpanel/express';
|
||||
|
||||
const app = express();
|
||||
|
||||
app.use(
|
||||
createOpenpanelMiddleware({
|
||||
clientId: 'xxx',
|
||||
clientSecret: 'xxx',
|
||||
// trackRequest(url) {
|
||||
// return url.includes('/v1')
|
||||
// },
|
||||
// getProfileId(req) {
|
||||
// return req.user.id
|
||||
// }
|
||||
})
|
||||
);
|
||||
|
||||
app.get('/sign-up', (req, res) => {
|
||||
// track sign up events
|
||||
req.op.track('sign-up', {
|
||||
email: req.body.email,
|
||||
});
|
||||
res.send('Hello World');
|
||||
});
|
||||
|
||||
app.listen(3000, () => {
|
||||
console.log('Server is running on http://localhost:3000');
|
||||
});
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
<CommonSdkConfig />
|
||||
|
||||
#### Express options
|
||||
|
||||
- `trackRequest` - A function that returns `true` if the request should be tracked.
|
||||
- `getProfileId` - A function that returns the profile ID of the user making the request.
|
||||
|
||||
## Typescript
|
||||
|
||||
If `req.op` is not typed you can extend the `Request` interface.
|
||||
|
||||
```ts
|
||||
import { OpenPanel } from '@openpanel/express';
|
||||
|
||||
declare global {
|
||||
namespace Express {
|
||||
export interface Request {
|
||||
op: OpenPanel;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
140
apps/public/content/docs/sdks/javascript.mdx
Normal file
140
apps/public/content/docs/sdks/javascript.mdx
Normal file
@@ -0,0 +1,140 @@
|
||||
---
|
||||
title: Javascript (Node / Generic)
|
||||
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
|
||||
|
||||
<Steps>
|
||||
### Step 1: Install
|
||||
|
||||
```bash
|
||||
npm install @openpanel/sdk
|
||||
```
|
||||
|
||||
### Step 2: Initialize
|
||||
|
||||
```js filename="op.ts"
|
||||
import { OpenPanel } from '@openpanel/sdk';
|
||||
|
||||
const op = new OpenPanel({
|
||||
clientId: 'YOUR_CLIENT_ID',
|
||||
clientSecret: 'YOUR_CLIENT_SECRET',
|
||||
});
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
<CommonSdkConfig />
|
||||
|
||||
### Step 3: Usage
|
||||
|
||||
```js filename="main.ts"
|
||||
import { op } from './op.js';
|
||||
|
||||
op.track('my_event', { foo: 'bar' });
|
||||
```
|
||||
</Steps>
|
||||
|
||||
## Usage
|
||||
|
||||
### Tracking Events
|
||||
|
||||
You can track events with two different methods: by calling the `op.track( directly or by adding `data-track` attributes to your HTML elements.
|
||||
|
||||
```ts filename="index.ts"
|
||||
import { op } from './op.ts';
|
||||
|
||||
op.track('my_event', { foo: 'bar' });
|
||||
```
|
||||
|
||||
### Identifying Users
|
||||
|
||||
To identify a user, call the `op.identify( method with a unique identifier.
|
||||
|
||||
```js filename="index.js"
|
||||
import { op } from './op.ts';
|
||||
|
||||
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 filename="index.js"
|
||||
import { op } from './op.ts'
|
||||
|
||||
op.setGlobalProperties({
|
||||
app_version: '1.0.2',
|
||||
environment: 'production',
|
||||
});
|
||||
```
|
||||
|
||||
### Creating Aliases
|
||||
|
||||
To create an alias for a user:
|
||||
|
||||
```js filename="index.js"
|
||||
import { op } from './op.ts'
|
||||
|
||||
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.
|
||||
|
||||
```js filename="index.js"
|
||||
import { op } from './op.ts'
|
||||
|
||||
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 filename="index.js"
|
||||
import { op } from './op.ts'
|
||||
|
||||
op.decrement({
|
||||
profileId: '1',
|
||||
property: 'visits',
|
||||
value: 1 // optional
|
||||
});
|
||||
```
|
||||
|
||||
### Clearing User Data
|
||||
|
||||
To clear the current user's data:
|
||||
|
||||
```js filename="index.js"
|
||||
import { op } from './op.ts'
|
||||
|
||||
op.clear()
|
||||
```
|
||||
5
apps/public/content/docs/sdks/meta.json
Normal file
5
apps/public/content/docs/sdks/meta.json
Normal file
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "SDKs",
|
||||
"pages": ["script", "web", "javascript", "node", "nextjs", "..."],
|
||||
"defaultOpen": true
|
||||
}
|
||||
303
apps/public/content/docs/sdks/nextjs.mdx
Normal file
303
apps/public/content/docs/sdks/nextjs.mdx
Normal file
@@ -0,0 +1,303 @@
|
||||
---
|
||||
title: Next.js
|
||||
---
|
||||
|
||||
import Link from 'next/link';
|
||||
import { Step, Steps } from 'fumadocs-ui/components/steps';
|
||||
|
||||
import { DeviceIdWarning } from '@/components/device-id-warning';
|
||||
import { PersonalDataWarning } from '@/components/personal-data-warning';
|
||||
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
|
||||
import WebSdkConfig from '@/components/web-sdk-config.mdx';
|
||||
|
||||
## 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
|
||||
|
||||
<Steps>
|
||||
### Install dependencies
|
||||
|
||||
```bash
|
||||
pnpm install @openpanel/nextjs
|
||||
```
|
||||
|
||||
### Initialize
|
||||
|
||||
Add `OpenPanelComponent` to your root layout component.
|
||||
|
||||
```tsx
|
||||
import { OpenPanelComponent } from '@openpanel/nextjs';
|
||||
|
||||
export default RootLayout({ children }) {
|
||||
return (
|
||||
<>
|
||||
<OpenPanelComponent
|
||||
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}
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
<CommonSdkConfig />
|
||||
<WebSdkConfig />
|
||||
|
||||
##### NextJS options
|
||||
|
||||
- `profileId` - If you have a user id, you can pass it here to identify the user
|
||||
- `cdnUrl` - The url to the OpenPanel SDK (default: `https://openpanel.dev/op1.js`)
|
||||
- `filter` - This is a function that will be called before tracking an event. If it returns false the event will not be tracked. [Read more](#filter)
|
||||
- `globalProperties` - This is an object of properties that will be sent with every event.
|
||||
|
||||
##### `filter`
|
||||
|
||||
This options needs to be a stringified function and cannot access any variables outside of the function.
|
||||
|
||||
```tsx
|
||||
<OpenPanelComponent
|
||||
clientId="your-client-id"
|
||||
filter={`
|
||||
function filter(event) {
|
||||
return event.name !== 'my_event';
|
||||
}
|
||||
`}
|
||||
/>
|
||||
```
|
||||
|
||||
To take advantage of typescript you can do the following. _Note `toString`_
|
||||
```tsx /.toString();/
|
||||
import { type OpenPanelOptions } from '@openpanel/nextjs';
|
||||
|
||||
const opFilter = ((event: TrackHandlerPayload) => {
|
||||
return event.type === 'track' && event.payload.name === 'my_event';
|
||||
}).toString();
|
||||
|
||||
<OpenPanelComponent
|
||||
clientId="your-client-id"
|
||||
filter={opFilter}
|
||||
/>
|
||||
```
|
||||
|
||||
</Steps>
|
||||
|
||||
## Usage
|
||||
|
||||
### Client components
|
||||
|
||||
For client components you can just use the `useOpenPanel` hook.
|
||||
|
||||
```tsx
|
||||
import { useOpenPanel } from '@openpanel/nextjs';
|
||||
|
||||
function YourComponent() {
|
||||
const op = useOpenPanel();
|
||||
|
||||
return <button type="button" onClick={() => op.track('my_event', { foo: 'bar' })}>Trigger event</button>
|
||||
}
|
||||
```
|
||||
|
||||
### Server components
|
||||
|
||||
Since you can't use hooks in server components, you need to create an instance of the SDK. This is exported from `@openpanel/nextjs`.
|
||||
|
||||
<Callout>Remember, your client secret is exposed here so do not use this on client side.</Callout>
|
||||
|
||||
```tsx filename="utils/op.ts"
|
||||
import { OpenPanel } from '@openpanel/nextjs';
|
||||
|
||||
export const op = new OpenPanel({
|
||||
clientId: 'your-client-id',
|
||||
clientSecret: 'your-client-secret',
|
||||
});
|
||||
|
||||
// Now you can use `op` to track events
|
||||
op.track('my_event', { foo: 'bar' });
|
||||
```
|
||||
|
||||
Refer to the [Javascript SDK](/docs/sdks/javascript#usage) for usage instructions.
|
||||
|
||||
### Tracking Events
|
||||
|
||||
You can track events with two different methods: by calling the `op.track( directly or by adding `data-track` attributes to your HTML elements.
|
||||
|
||||
```ts filename="index.ts"
|
||||
useOpenPanel().track('my_event', { foo: 'bar' });
|
||||
```
|
||||
|
||||
### Identifying Users
|
||||
|
||||
To identify a user, call the `op.identify( method with a unique identifier.
|
||||
|
||||
```js filename="index.js"
|
||||
useOpenPanel().identify({
|
||||
profileId: '123', // Required
|
||||
firstName: 'Joe',
|
||||
lastName: 'Doe',
|
||||
email: 'joe@doe.com',
|
||||
properties: {
|
||||
tier: 'premium',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
#### For server components
|
||||
|
||||
For server components you can use the `IdentifyComponent` component which is exported from `@openpanel/nextjs`.
|
||||
|
||||
> This component is great if you have the user data available on the server side.
|
||||
|
||||
```tsx filename="app/nested/layout.tsx"
|
||||
import { IdentifyComponent } from '@openpanel/nextjs';
|
||||
|
||||
export default function Layout({ children }) {
|
||||
const user = await getCurrentUser()
|
||||
|
||||
return (
|
||||
<>
|
||||
<IdentifyComponent
|
||||
profileId={user.id}
|
||||
firstName={user.firstName}
|
||||
lastName={user.lastName}
|
||||
email={user.email}
|
||||
properties={{
|
||||
tier: 'premium',
|
||||
}}
|
||||
/>
|
||||
{children}
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Setting Global Properties
|
||||
|
||||
To set properties that will be sent with every event:
|
||||
|
||||
```js filename="index.js"
|
||||
useOpenPanel().setGlobalProperties({
|
||||
app_version: '1.0.2',
|
||||
environment: 'production',
|
||||
});
|
||||
```
|
||||
|
||||
### Creating Aliases
|
||||
|
||||
To create an alias for a user:
|
||||
|
||||
```js filename="index.js"
|
||||
useOpenPanel().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.
|
||||
|
||||
```js filename="index.js"
|
||||
useOpenPanel().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 filename="index.js"
|
||||
useOpenPanel().decrement({
|
||||
profileId: '1',
|
||||
property: 'visits',
|
||||
value: 1 // optional
|
||||
});
|
||||
```
|
||||
|
||||
### Clearing User Data
|
||||
|
||||
To clear the current user's data:
|
||||
|
||||
```js filename="index.js"
|
||||
useOpenPanel().clear()
|
||||
```
|
||||
|
||||
## Server side
|
||||
|
||||
If you want to track server-side events, you should create an instance of our Javascript SDK. It's exported from `@openpanel/nextjs`
|
||||
|
||||
<Callout>
|
||||
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.
|
||||
|
||||
</Callout>
|
||||
|
||||
```typescript
|
||||
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: '✅' });
|
||||
```
|
||||
|
||||
### Serverless & Vercel
|
||||
|
||||
If you log events in a serverless environment like Vercel, you can use `waitUntil` to ensure the event is logged before the function is done.
|
||||
|
||||
Otherwise your function might close before the event is logged. Read more about it [here](https://vercel.com/docs/functions/functions-api-reference#waituntil).
|
||||
|
||||
```typescript
|
||||
import { waitUntil } from '@vercel/functions';
|
||||
import { opServer } from 'path/to/your-sdk-instance';
|
||||
|
||||
export function GET() {
|
||||
// Returns a response immediately while keeping the function alive
|
||||
waitUntil(opServer.event('my_server_event', { foo: 'bar' }));
|
||||
return new Response(`You're event has been logged!`);
|
||||
}
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
```typescript filename="/app/api/op/route.ts"
|
||||
import { createNextRouteHandler } from '@openpanel/nextjs/server';
|
||||
|
||||
export const POST = createNextRouteHandler();
|
||||
```
|
||||
|
||||
Remember to change the `apiUrl` in the `OpenPanelComponent` to your own server.
|
||||
|
||||
```tsx {2}
|
||||
<OpenPanelComponent
|
||||
apiUrl="/api/op"
|
||||
clientId="your-client-id"
|
||||
trackScreenViews={true}
|
||||
/>
|
||||
```
|
||||
115
apps/public/content/docs/sdks/react-native.mdx
Normal file
115
apps/public/content/docs/sdks/react-native.mdx
Normal file
@@ -0,0 +1,115 @@
|
||||
---
|
||||
title: React Native
|
||||
---
|
||||
|
||||
import Link from 'next/link';
|
||||
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
|
||||
import { Step, Steps } from 'fumadocs-ui/components/steps';
|
||||
import { DeviceIdWarning } from '@/components/device-id-warning';
|
||||
import { PersonalDataWarning } from '@/components/personal-data-warning';
|
||||
|
||||
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
|
||||
|
||||
## Installation
|
||||
|
||||
<Steps>
|
||||
### Install dependencies
|
||||
|
||||
We're dependent on `expo-application` for `buildNumber`, `versionNumber` (and `referrer` on android) and `expo-constants` to get the `user-agent`.
|
||||
|
||||
```bash
|
||||
npm install @openpanel/react-native
|
||||
npx expo install expo-application expo-constants
|
||||
```
|
||||
|
||||
### Initialize
|
||||
|
||||
On native we use a clientSecret to authenticate the app.
|
||||
|
||||
```typescript
|
||||
const op = new Openpanel({
|
||||
clientId: '{YOUR_CLIENT_ID}',
|
||||
clientSecret: '{YOUR_CLIENT_SECRET}',
|
||||
});
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
<CommonSdkConfig />
|
||||
</Steps>
|
||||
|
||||
## Usage
|
||||
|
||||
### Track event
|
||||
|
||||
```typescript
|
||||
op.track('my_event', { foo: 'bar' });
|
||||
```
|
||||
|
||||
### Navigation / Screen views
|
||||
|
||||
<Tabs items={['expo-router', 'react-navigation (simple)']}>
|
||||
<Tab value="expo-router">
|
||||
```typescript
|
||||
import { usePathname, useSegments } from 'expo-router';
|
||||
|
||||
const op = new Openpanel({ /* ... */ })
|
||||
|
||||
function RootLayout() {
|
||||
// ...
|
||||
const pathname = usePathname()
|
||||
// Segments is optional but can be nice to have if you
|
||||
// want to group routes together
|
||||
// pathname = /posts/123
|
||||
// segements = ['posts', '[id]']
|
||||
const segments = useSegments()
|
||||
|
||||
useEffect(() => {
|
||||
// Simple
|
||||
op.screenView(pathname)
|
||||
|
||||
// With extra data
|
||||
op.screenView(pathname, {
|
||||
// segments is optional but nice to have
|
||||
segments: segments.join('/'),
|
||||
// other optional data you want to send with the screen view
|
||||
})
|
||||
}, [pathname,segments])
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab value="react-navigation (simple)">
|
||||
```tsx
|
||||
import { createNavigationContainerRef } from '@react-navigation/native'
|
||||
import { Openpanel } from '@openpanel/react-native'
|
||||
|
||||
const op = new Openpanel({ /* ... */ })
|
||||
const navigationRef = createNavigationContainerRef()
|
||||
|
||||
export function NavigationRoot() {
|
||||
const handleNavigationStateChange = () => {
|
||||
const current = navigationRef.getCurrentRoute()
|
||||
if (current) {
|
||||
op.screenView(current.name, {
|
||||
params: current.params,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<NavigationContainer
|
||||
ref={navigationRef}
|
||||
onReady={handleNavigationStateChange}
|
||||
onStateChange={handleNavigationStateChange}
|
||||
>
|
||||
<Stack.Navigator />
|
||||
</NavigationContainer>
|
||||
)
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
For more information on how to use the SDK, check out the [Javascript SDK](/docs/sdks/javascript#usage).
|
||||
5
apps/public/content/docs/sdks/react.mdx
Normal file
5
apps/public/content/docs/sdks/react.mdx
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: React
|
||||
---
|
||||
|
||||
Use [script tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) for now. We'll add a dedicated react sdk soon.
|
||||
5
apps/public/content/docs/sdks/remix.mdx
Normal file
5
apps/public/content/docs/sdks/remix.mdx
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: Remix
|
||||
---
|
||||
|
||||
Use [script tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) for now. We'll add a dedicated remix sdk soon.
|
||||
211
apps/public/content/docs/sdks/script.mdx
Normal file
211
apps/public/content/docs/sdks/script.mdx
Normal file
@@ -0,0 +1,211 @@
|
||||
---
|
||||
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 filename="index.html" /clientId: '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
|
||||
|
||||
<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 filename="index.html"
|
||||
<button type="button" onclick="window.op('track', 'my_event', { foo: 'bar' })">
|
||||
Track event
|
||||
</button>
|
||||
```
|
||||
|
||||
```html filename="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 filename="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 filename="main.js"
|
||||
window.op('setGlobalProperties', {
|
||||
app_version: '1.0.2',
|
||||
environment: 'production',
|
||||
});
|
||||
```
|
||||
|
||||
### Creating Aliases
|
||||
|
||||
To create an alias for a user:
|
||||
|
||||
```js filename="main.js"
|
||||
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.
|
||||
|
||||
```js filename="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 filename="main.js"
|
||||
window.op('decrement', {
|
||||
profileId: '1',
|
||||
property: 'visits',
|
||||
value: 1 // optional
|
||||
});
|
||||
```
|
||||
|
||||
### Clearing User Data
|
||||
|
||||
To clear the current user's data:
|
||||
|
||||
```js filename="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 filename="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
|
||||
|
||||
```bash
|
||||
npm install @openpanel/web
|
||||
```
|
||||
|
||||
#### Step 2: Initialize the SDK
|
||||
|
||||
```js filename="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 filename="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 filename="op.d.ts"
|
||||
declare global {
|
||||
interface Window {
|
||||
op: {
|
||||
q?: string[][];
|
||||
(...args: [
|
||||
'init' | 'track' | 'identify' | 'setGlobalProperties' | 'alias' | 'increment' | 'decrement' | 'clear',
|
||||
...any[]
|
||||
]): void;
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Strict typing (from sdk)
|
||||
|
||||
<Steps>
|
||||
##### Step 1: Install the SDK
|
||||
|
||||
```bash
|
||||
npm install @openpanel/web
|
||||
```
|
||||
|
||||
##### Step 2: Create a type definition file
|
||||
|
||||
Create a `op.d.ts`file and paste the following code:
|
||||
|
||||
```ts filename="op.d.ts"
|
||||
/// <reference types="@openpanel/web" />
|
||||
```
|
||||
</Steps>
|
||||
5
apps/public/content/docs/sdks/vue.mdx
Normal file
5
apps/public/content/docs/sdks/vue.mdx
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: Vue
|
||||
---
|
||||
|
||||
Use [script tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) for now. We'll add a dedicated react sdk soon.
|
||||
49
apps/public/content/docs/sdks/web.mdx
Normal file
49
apps/public/content/docs/sdks/web.mdx
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: Javascript (Web)
|
||||
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
|
||||
|
||||
<Steps>
|
||||
### Step 1: Install
|
||||
|
||||
```bash
|
||||
npm install @openpanel/web
|
||||
```
|
||||
|
||||
### Step 2: Initialize
|
||||
|
||||
```js filename="op.ts"
|
||||
import { OpenPanel } from '@openpanel/web';
|
||||
|
||||
const op = new OpenPanel({
|
||||
clientId: 'YOUR_CLIENT_ID',
|
||||
trackScreenViews: true,
|
||||
trackOutgoingLinks: true,
|
||||
trackAttributes: true,
|
||||
});
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
<CommonSdkConfig />
|
||||
<WebSdkConfig />
|
||||
|
||||
### Step 3: Usage
|
||||
|
||||
```js filename="main.ts"
|
||||
import { op } from './op.js';
|
||||
|
||||
op.track('my_event', { foo: 'bar' });
|
||||
```
|
||||
</Steps>
|
||||
|
||||
## Usage
|
||||
|
||||
Refer to the [Javascript SDK](/docs/sdks/javascript#usage) for usage instructions.
|
||||
142
apps/public/content/docs/self-hosting/self-hosting.mdx
Normal file
142
apps/public/content/docs/self-hosting/self-hosting.mdx
Normal file
@@ -0,0 +1,142 @@
|
||||
---
|
||||
title: Self-hosting
|
||||
description: This is a simple guide how to get started with OpenPanel on your own VPS.
|
||||
---
|
||||
|
||||
import { Step, Steps } from 'fumadocs-ui/components/steps';
|
||||
|
||||
|
||||
|
||||
<Callout>OpenPanel is not stable yet. If you still want to self-host you can go ahead. Bear in mind that new changes might give a little headache to keep up with.</Callout>
|
||||
|
||||
|
||||
|
||||
## Instructions
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- VPS of any kind (only tested on Ubuntu 24.04)
|
||||
- 🙋♂️ This should work on any system if you have pre-installed docker, node and pnpm
|
||||
- [Clerk.com](https://clerk.com) account (they have a free tier)
|
||||
|
||||
### Quickstart
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Openpanel-dev/openpanel && cd openpanel/self-hosting && ./setup
|
||||
# After setup is complete run `./start` to start OpenPanel
|
||||
```
|
||||
|
||||
<Steps>
|
||||
|
||||
### Clone
|
||||
|
||||
Clone the repository to your VPS
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Openpanel-dev/openpanel.git
|
||||
```
|
||||
|
||||
### Run the setup script
|
||||
|
||||
The setup script will do 3 things
|
||||
|
||||
1. Install node (if you accept)
|
||||
2. Install docker (if you accept)
|
||||
3. Execute a node script that will ask some questions about your setup
|
||||
4. After this is done you'll need to point a webhook inside Clerk (https://your-domain.com/api/webhook/clerk)
|
||||
|
||||
> Setup takes 1-2 minutes depending on your VPS
|
||||
|
||||
```bash
|
||||
cd openpanel/self-hosting
|
||||
./setup
|
||||
```
|
||||
|
||||
⚠️ If the `./setup` script fails to run, you can do it manually.
|
||||
|
||||
1. Install docker
|
||||
2. Install node
|
||||
3. Install pnpm
|
||||
4. Run the `npx jiti ./quiz.ts` script inside the self-hosting folder
|
||||
|
||||
### Start 🚀
|
||||
|
||||
Run the `./start` script located inside the self-hosting folder
|
||||
|
||||
```bash
|
||||
./start
|
||||
```
|
||||
</Steps>
|
||||
|
||||
## Clerk.com
|
||||
|
||||
<Callout>
|
||||
Some might wonder why we use Clerk.com for authentication. The main reason for this is that Clerk have great support for iOS and Android apps. We're in the process of building an native app and we want to have a seamless experience for our users.
|
||||
|
||||
**next-auth** is great, but lacks good support for mobile apps.
|
||||
</Callout>
|
||||
|
||||
You'll need to create an account at [Clerk.com](https://clerk.com) and create a new project. You'll need the 3 keys that Clerk provides you with.
|
||||
|
||||
- **Publishable key** `pk_live_xxx`
|
||||
- **Secret key** `sk_live_xxx`
|
||||
- **Signing secret** `"whsec_xxx"`
|
||||
|
||||
### Webhooks
|
||||
|
||||
You'll also need to add a webhook to your domain. We listen on some events from Clerk to keep our database in sync.
|
||||
|
||||
#### URL
|
||||
|
||||
- **Path**: `/api/webhook/clerk`
|
||||
- **Example**: `https://your-domain.com/api/webhook/clerk`
|
||||
|
||||
#### Events we listen to
|
||||
|
||||
- `organizationMembership.created`
|
||||
- `user.created`
|
||||
- `organizationMembership.deleted`
|
||||
- `user.updated`
|
||||
- `user.deleted`
|
||||
|
||||
## Good to know
|
||||
|
||||
### Always use correct api url
|
||||
|
||||
When self-hosting you'll need to provide your api url when initializing the SDK.
|
||||
|
||||
The path should be `/api` and the domain should be your domain.
|
||||
|
||||
```html filename="index.html" {4}
|
||||
<script>
|
||||
window.op = window.op||function(...args){(window.op.q=window.op.q||[]).push(args);};
|
||||
window.op('init', {
|
||||
apiUrl: 'https://your-domain.com/api',
|
||||
clientId: 'YOUR_CLIENT_ID',
|
||||
trackScreenViews: true,
|
||||
trackOutgoingLinks: true,
|
||||
trackAttributes: true,
|
||||
});
|
||||
</script>
|
||||
<script src="https://openpanel.dev/op1.js" defer async></script>
|
||||
```
|
||||
|
||||
```js filename="op.ts" {4}
|
||||
import { OpenPanel } from '@openpanel/sdk';
|
||||
|
||||
const op = new OpenPanel({
|
||||
apiUrl: 'https://your-domain.com/api',
|
||||
clientId: 'YOUR_CLIENT_ID',
|
||||
trackScreenViews: true,
|
||||
trackOutgoingLinks: true,
|
||||
trackAttributes: true,
|
||||
});
|
||||
```
|
||||
|
||||
### Managed Redis
|
||||
|
||||
If you use a managed Redis service, you may need to set the `notify-keyspace-events` manually.
|
||||
|
||||
Without this setting we wont be able to listen for expired keys which we use for caluclating currently active vistors.
|
||||
|
||||
> You will see a warning in the logs if this needs to be set manually.
|
||||
Reference in New Issue
Block a user