zias/stats
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: sdks and docs (#239)

Browse Source 
* init

* fix

* update docs

* bump: all sdks

* rename types test
This commit is contained in:
Carl-Gerhard Lindesvärd
2025-11-19 21:56:47 +01:00
committed by GitHub
parent 790801b728
commit 83e223a496
50 changed files with 793 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
apps/public/content/docs/(tracking)/sdks/astro.mdx Normal file
View File

@@ -0,0 +1,133 @@
---
title: Astro
---
import { Step, Steps } from 'fumadocs-ui/components/steps';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
import WebSdkConfig from '@/components/web-sdk-config.mdx';
## Installation
<Steps>
### Install dependencies
```bash
pnpm install @openpanel/astro
```
### Initialize
Add `OpenPanelComponent` to your root layout component.
```astro
---
import { OpenPanelComponent } from '@openpanel/astro';
---
<html>
<head>
<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'}
/>
</head>
<body>
<slot />
</body>
</html>
```
#### Options
<CommonSdkConfig />
<WebSdkConfig />
##### Astro 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.
```astro
<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`_
```ts
import { type TrackHandlerPayload } from '@openpanel/astro';
const opFilter = ((event: TrackHandlerPayload) => {
return event.type === 'track' && event.payload.name === 'my_event';
}).toString();
<OpenPanelComponent
clientId="your-client-id"
filter={opFilter}
/>
```
</Steps>
## Usage
### Client-side Tracking
You can track events with the global op function or you can use data attributes.
```astro
<button onclick="window.op('track', 'clicky')">Click me</button>
<button data-track="clicky" data-prop1="prop1" data-prop2="prop2">Click me</button>
```
### Identifying Users
To identify a user, you can use either the `identify` function or the `IdentifyComponent`.
```astro
---
import { IdentifyComponent } from '@openpanel/astro';
---
<IdentifyComponent
profileId="123"
firstName="Joe"
lastName="Doe"
email="joe@doe.com"
properties={{
tier: 'premium',
}}
/>
```
### Setting Global Properties
You can set global properties that will be sent with every event using either the `setGlobalProperties` function or the `SetGlobalPropertiesComponent`.
```astro
---
import { SetGlobalPropertiesComponent } from '@openpanel/astro';
---
<SetGlobalPropertiesComponent
properties={{
app_version: '1.0.2',
environment: 'production',
}}
/>
```

80
apps/public/content/docs/(tracking)/sdks/express.mdx Normal file
View 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;
}
}
}
```

143
apps/public/content/docs/(tracking)/sdks/index.mdx Normal file
View File

@@ -0,0 +1,143 @@
---
title: SDKs Overview
description: Choose the right OpenPanel SDK for your project. We support web, mobile, server-side, and framework-specific integrations.
---
import { Callout } from 'fumadocs-ui/components/callout';
OpenPanel provides SDKs for a wide range of platforms and frameworks, making it easy to integrate analytics into your application regardless of your tech stack.
## Quick Start
For most web projects, we recommend starting with one of these:
- **[Script Tag](/docs/sdks/script)** - The quickest way to get started, no build step required
- **[Web SDK](/docs/sdks/web)** - For TypeScript support and more control
- **[Next.js](/docs/sdks/nextjs)** - Optimized for Next.js applications
## Web & Browser SDKs
### Simple Integration
- **[Script Tag](/docs/sdks/script)** - Add analytics with a simple `<script>` tag
- ✅ No build step required
- ✅ Works with any website
- ✅ Automatic page view tracking
### JavaScript & TypeScript
- **[Web SDK](/docs/sdks/web)** - Full-featured browser SDK with TypeScript support
- ✅ Type-safe API
- ✅ Tree-shakeable
- ✅ Modern browsers support
- **[JavaScript (Node / Generic)](/docs/sdks/javascript)** - Universal JavaScript SDK
- ✅ Works in Node.js and browsers
- ✅ Framework agnostic
- ✅ Full API access
### Frontend Frameworks
- **[Next.js](/docs/sdks/nextjs)** - Optimized for Next.js
- ✅ Server and client side tracking
- ✅ App Router support
- ✅ Automatic route tracking
- **[Astro](/docs/sdks/astro)** - Astro framework integration
- ✅ Static and SSR support
- ✅ Component-based tracking
- ✅ Island architecture compatible
- **[React](/docs/sdks/react)** - React integration
- 📝 Use Script Tag or Web SDK for now
- **[Vue](/docs/sdks/vue)** - Vue.js integration
- 📝 Use Script Tag or Web SDK for now
- **[Remix](/docs/sdks/remix)** - Remix framework integration
- 📝 Use Script Tag or Web SDK for now
- **Svelte** - Svelte integration
- 📝 Use [Script Tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) for now
- **Angular** - Angular integration
- 📝 Use [Script Tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) for now
- **Solid.js** - Solid.js integration
- 📝 Use [Script Tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) for now
- **Nuxt** - Nuxt.js integration
- 📝 Use [Script Tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) for now
## Server-Side SDKs
- **[Node.js (Express)](/docs/sdks/express)** - Express.js middleware
- ✅ Request tracking
- ✅ Error tracking
- ✅ Custom middleware support
- **[Python](/docs/sdks/python)** - Python SDK for server-side tracking
- ✅ Thread-safe
- ✅ Async support
- ✅ Django and Flask compatible
## Mobile SDKs
- **[React Native](/docs/sdks/react-native)** - Cross-platform mobile analytics
- ✅ iOS and Android support
- ✅ Native performance
- ✅ Offline support
- **[Swift](/docs/sdks/swift)** - Native iOS, macOS, tvOS, and watchOS SDK
- ✅ Apple platform support
- ✅ Swift Package Manager
- ✅ Thread-safe API
- ✅ Automatic lifecycle tracking
- **[Kotlin / Android](/docs/sdks/kotlin)** - Native Android SDK
- ✅ Android support
- ✅ System information collection
- ✅ Thread-safe API
- ⚠️ Not yet published to Maven
## Need Help Choosing?
<Callout>
Not sure which SDK to use? Here are some recommendations:
- **Static website or HTML?** → Use [Script Tag](/docs/sdks/script)
- **React app?** → Use [Web SDK](/docs/sdks/web) or [Script Tag](/docs/sdks/script)
- **Next.js app?** → Use [Next.js SDK](/docs/sdks/nextjs)
- **Server-side tracking?** → Use [Python](/docs/sdks/python) or [Node](/docs/sdks/javascript)
- **Mobile app?** → Use [React Native](/docs/sdks/react-native), [Swift](/docs/sdks/swift), or [Kotlin](/docs/sdks/kotlin)
</Callout>
## Core Features
All OpenPanel SDKs support these core features:
### Event Tracking
Track custom events with properties to understand user behavior.
### User Identification
Associate events with specific users and build user profiles.
### Global Properties
Set properties that are automatically included with every event.
### Increment/Decrement
Update numeric properties on user profiles.
### Privacy First
All SDKs are built with privacy in mind - no cookies required, GDPR compliant.
## API Reference
For advanced integrations, check out our [API documentation](/docs/api/track) to track events directly via HTTP requests.
## Community & Support
- Join our [Discord community](https://go.openpanel.dev/discord)
- Report issues on [GitHub](https://github.com/Openpanel-dev/openpanel/issues)
- Email us at [hello@openpanel.dev](mailto:hello@openpanel.dev)

127
apps/public/content/docs/(tracking)/sdks/javascript.mdx Normal file
View File

@@ -0,0 +1,127 @@
---
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 title="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 title="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 title="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 title="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 title="index.js"
import { op } from './op.ts'
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="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 title="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 title="index.js"
import { op } from './op.ts'
op.clear()
```

205
apps/public/content/docs/(tracking)/sdks/kotlin.mdx Normal file
View File

@@ -0,0 +1,205 @@
---
title: Kotlin / Android
description: The OpenPanel Kotlin SDK allows you to track user behavior in your Kotlin and Android applications.
---
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
The OpenPanel Kotlin SDK allows you to track user behavior in your Kotlin applications. This guide provides instructions for installing and using the Kotlin SDK in your project.
## Installation
<Callout type="warn">
This package is not yet published. So you cannot install it with `gradle` yet.
</Callout>
<Steps>
### Step 1: Add Dependency
Add the OpenPanel SDK to your project's dependencies:
```gradle
dependencies {
implementation 'dev.openpanel:openpanel:0.0.1'
}
```
### Step 2: Initialize
First, import the SDK and initialize it with your client ID:
```kotlin
import dev.openpanel.OpenPanel
val op = OpenPanel.create(
context,
OpenPanel.Options(
clientId = "YOUR_CLIENT_ID",
clientSecret = "YOUR_CLIENT_SECRET"
)
)
```
### Configuration Options
#### `context`
- **Type**: `Context`
- **Required**: Yes
- **Description**: Android `Context` used for initializing the SDK.
#### `Options`
<CommonSdkConfig />
Additional Kotlin-specific options:
- `filter` - A function that will be called before tracking an event. If it returns false, the event will not be tracked
- `disabled` - Set to `true` to disable all event tracking
- `automaticTracking` - Set to `true` to automatically track app lifecycle events
- `verbose` - Set to `true` to enable verbose logging
#### Filter Example
```kotlin
val op = OpenPanel.create(
context,
OpenPanel.Options(
clientId = "YOUR_CLIENT_ID",
filter = { payload ->
// Your custom filtering logic here
true // or false to filter out the event
}
)
)
```
</Steps>
## Usage
### Tracking Events
To track an event:
```kotlin
op.track("button_clicked", mapOf("button_id" to "submit_form"))
```
### Identifying Users
To identify a user:
```kotlin
op.identify("user123", mapOf(
"firstName" to "John",
"lastName" to "Doe",
"email" to "john@example.com",
"customAttribute" to "value"
))
```
### Setting Global Properties
To set properties that will be sent with every event:
```kotlin
op.setGlobalProperties(mapOf(
"app_version" to "1.0.2",
"environment" to "production"
))
```
### Incrementing Properties
To increment a numeric property on a user profile:
```kotlin
op.increment("user123", "login_count", 1)
```
### Decrementing Properties
To decrement a numeric property on a user profile:
```kotlin
op.decrement("user123", "credits", 5)
```
### Clearing User Data
To clear the current user's data:
```kotlin
op.clear()
```
## Advanced Usage
### Custom Event Filtering
You can set up custom event filtering:
```kotlin
val op = OpenPanel.create(
context,
OpenPanel.Options(
clientId = "YOUR_CLIENT_ID",
filter = { payload ->
// Your custom filtering logic here
true // or false to filter out the event
}
)
)
```
### Disabling Tracking
You can temporarily disable tracking:
```kotlin
val op = OpenPanel.create(
context,
OpenPanel.Options(
clientId = "YOUR_CLIENT_ID",
disabled = true
)
)
```
### Automatic Tracking
The SDK can automatically track app lifecycle events if `automaticTracking` is set to `true`. This will track "app_opened" and "app_closed" events:
```kotlin
val op = OpenPanel.create(
context,
OpenPanel.Options(
clientId = "YOUR_CLIENT_ID",
automaticTracking = true
)
)
```
### System Information
The SDK automatically gathers system information and adds it to the properties of every tracking event. This includes:
- OS details (e.g., `os`, `os_version`)
- Device manufacturer, brand, and model (e.g., `manufacturer`, `brand`, `model`)
- Screen resolution and DPI (e.g., `screen_width`, `screen_height`, `screen_dpi`)
- App version (e.g., `app_version`, `app_build_number`)
- Network details (e.g., `wifi`, `carrier`, `bluetooth_enabled`)
## Thread Safety
<Callout>
The OpenPanel SDK is designed to be thread-safe. You can call its methods from any thread without additional synchronization.
</Callout>
## Support
For any issues or feature requests, please file an issue on our [GitHub repository](https://github.com/Openpanel-dev/openpanel/issues).

20
apps/public/content/docs/(tracking)/sdks/meta.json Normal file
View File

@@ -0,0 +1,20 @@
{
"title": "SDKs",
"pages": [
"script",
"web",
"javascript",
"nextjs",
"react",
"vue",
"astro",
"remix",
"express",
"python",
"react-native",
"swift",
"kotlin",
"..."
],
"defaultOpen": false
}

294
apps/public/content/docs/(tracking)/sdks/nextjs.mdx Normal file
View File

@@ -0,0 +1,294 @@
---
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 function 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 TrackHandlerPayload } 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 title="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 title="index.ts"
useOpenPanel().track('my_event', { foo: 'bar' });
```
### Identifying Users
To identify a user, call the `op.identify( method with a unique identifier.
```js title="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 title="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 title="index.js"
useOpenPanel().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="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 title="index.js"
useOpenPanel().decrement({
profileId: '1',
property: 'visits',
value: 1 // optional
});
```
### Clearing User Data
To clear the current user's data:
```js title="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. You'll also need to either host our tracking script or you can use `createScriptHandler` function which proxies this as well.
```typescript title="/app/api/[...op]/route.ts"
import { createNextRouteHandler, createScriptHandler } from '@openpanel/nextjs/server';
export const POST = createNextRouteHandler();
export const GET = createScriptHandler()
```
Remember to change the `apiUrl` and `cdnUrl` in the `OpenPanelComponent` to your own server.
```tsx
<OpenPanelComponent
apiUrl="/api/op" // [!code highlight]
cdnUrl="/api/op/op1.js" // [!code highlight]
clientId="your-client-id"
trackScreenViews={true}
/>
```

176
apps/public/content/docs/(tracking)/sdks/python.mdx Normal file
View File

@@ -0,0 +1,176 @@
---
title: Python
---
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
The OpenPanel Python SDK allows you to track user behavior in your Python applications. This guide provides instructions for installing and using the Python SDK in your project.
## Installation
<Steps>
### Install dependencies
```bash
pip install openpanel
```
### Initialize
Import and initialize the OpenPanel SDK with your credentials:
```python
from openpanel import OpenPanel
op = OpenPanel(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET"
)
```
### Configuration Options
<CommonSdkConfig />
Additional Python-specific options:
- `filter` - A function that will be called before tracking an event. If it returns false the event will not be tracked
- `disabled` - Set to `True` to disable all event tracking
- `global_properties` - Dictionary of properties that will be sent with every event
#### Filter Function Example
```python
def my_filter(event):
# Skip events named 'my_event'
return event.get('name') != 'my_event'
op = OpenPanel(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
filter=my_filter
)
```
</Steps>
## Usage
### Tracking Events
To track an event, use the `track` method:
```python
# Track a simple event
op.track("button_clicked")
# Track with properties
op.track("purchase_completed", {
"product_id": "123",
"price": 99.99,
"currency": "USD"
})
# Track for a specific user
op.track("login_successful", {
"method": "google"
}, profile_id="user_123")
```
### Identifying Users
To identify a user, use the `identify` method:
```python
op.identify({
"profile_id": "123", # Required
"first_name": "Joe",
"last_name": "Doe",
"email": "joe@doe.com",
"properties": {
"tier": "premium",
"company": "Acme Inc"
}
})
```
### Setting Global Properties
To set properties that will be sent with every event:
```python
op.set_global_properties({
"app_version": "1.0.2",
"environment": "production",
"deployment": "us-east-1"
})
```
### Incrementing Properties
To increment a numeric property on a user profile:
```python
op.increment({
"profile_id": "1",
"property": "visits",
"value": 1 # optional, defaults to 1
})
```
### Decrementing Properties
To decrement a numeric property on a user profile:
```python
op.decrement({
"profile_id": "1",
"property": "credits",
"value": 1 # optional, defaults to 1
})
```
### Clearing User Data
To clear the current user's data:
```python
op.clear()
```
## Advanced Usage
### Thread Safety
<Callout>
The OpenPanel SDK is thread-safe. You can safely use a single instance across multiple threads in your application.
</Callout>
### Error Handling
The SDK includes built-in error handling and will not raise exceptions during normal operation. However, you can wrap SDK calls in try-except blocks for additional safety:
```python
try:
op.track("important_event", {"critical": True})
except Exception as e:
logger.error(f"Failed to track event: {e}")
```
### Disabling Tracking
You can temporarily disable all tracking:
```python
# Disable during initialization
op = OpenPanel(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
disabled=True
)
# Or disable after initialization
op.disabled = True
```

115
apps/public/content/docs/(tracking)/sdks/react-native.mdx Normal file
View 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/(tracking)/sdks/react.mdx Normal file
View 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/(tracking)/sdks/remix.mdx Normal file
View 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.

200
apps/public/content/docs/(tracking)/sdks/script.mdx Normal file
View File

@@ -0,0 +1,200 @@
---
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=[],o=new Proxy((function(){arguments.length>0&&n.push(Array.prototype.slice.call(arguments))}),{get:function(o,t){return"q"===t?n:function(){n.push([t].concat(Array.prototype.slice.call(arguments)))}}});return o}();
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
```bash
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
```bash
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>

183
apps/public/content/docs/(tracking)/sdks/swift.mdx Normal file
View File

@@ -0,0 +1,183 @@
---
title: Swift
description: The OpenPanel Swift SDK allows you to integrate OpenPanel analytics into your iOS, macOS, tvOS, and watchOS applications.
---
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
The OpenPanel Swift SDK allows you to integrate OpenPanel analytics into your iOS, macOS, tvOS, and watchOS applications.
## Features
- Easy-to-use API for tracking events and user properties
- Automatic collection of app states
- Support for custom event properties
- Shared instance for easy access throughout your app
## Requirements
- iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+
- Xcode 12.0+
- Swift 5.3+
## Installation
<Steps>
### Step 1: Add Package via Swift Package Manager
You can add OpenPanel to an Xcode project by adding it as a package dependency.
1. From the **File** menu, select **Add Packages...**
2. Enter `https://github.com/Openpanel-dev/swift-sdk` into the package repository URL text field
3. Click **Add Package**
Alternatively, if you have a `Package.swift` file, you can add OpenPanel as a dependency:
```swift
dependencies: [
.package(url: "https://github.com/Openpanel-dev/swift-sdk")
]
```
### Step 2: Import and Initialize
First, import the SDK in your Swift file:
```swift
import OpenPanel
```
Then, initialize the OpenPanel SDK with your client ID:
```swift
OpenPanel.initialize(options: .init(
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET"
))
```
### Configuration Options
<CommonSdkConfig />
Additional Swift-specific options:
- `filter` - A closure that will be called before tracking an event. If it returns false, the event will not be tracked
- `disabled` - Set to `true` to disable all event tracking
- `automaticTracking` - Set to `true` to automatically track app lifecycle events
#### Filter Example
```swift
OpenPanel.initialize(options: .init(
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET",
filter: { payload in
// Your custom filtering logic here
return true // or false to filter out the event
}
))
```
</Steps>
## Usage
### Tracking Events
To track an event:
```swift
OpenPanel.track(name: "Button Clicked", properties: ["button_id": "submit_form"])
```
### Identifying Users
To identify a user:
```swift
OpenPanel.identify(payload: IdentifyPayload(
profileId: "user123",
firstName: "John",
lastName: "Doe",
email: "john@example.com",
properties: ["subscription": "premium"]
))
```
### Setting Global Properties
To set properties that will be sent with every event:
```swift
OpenPanel.setGlobalProperties([
"app_version": "1.0.2",
"environment": "production"
])
```
### Incrementing Properties
To increment a numeric property:
```swift
OpenPanel.increment(payload: IncrementPayload(profileId: "user123", property: "login_count"))
```
### Decrementing Properties
To decrement a numeric property:
```swift
OpenPanel.decrement(payload: DecrementPayload(profileId: "user123", property: "credits_remaining"))
```
## Advanced Usage
### Disabling Tracking
You can temporarily disable tracking during initialization:
```swift
OpenPanel.initialize(options: .init(
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET",
disabled: true
))
```
### Custom Event Filtering
You can set up custom event filtering during initialization:
```swift
OpenPanel.initialize(options: .init(
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET",
filter: { payload in
// Your custom filtering logic here
return true // or false to filter out the event
}
))
```
### Automatic Tracking
The SDK automatically tracks app lifecycle events (`app_opened` and `app_closed`) if `automaticTracking` is set to `true` during initialization:
```swift
OpenPanel.initialize(options: .init(
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET",
automaticTracking: true
))
```
## Thread Safety
<Callout>
The OpenPanel SDK is designed to be thread-safe. You can call its methods from any thread without additional synchronization.
</Callout>

5
apps/public/content/docs/(tracking)/sdks/vue.mdx Normal file
View 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 vue sdk soon.

49
apps/public/content/docs/(tracking)/sdks/web.mdx Normal file
View 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 title="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 title="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.