Skip to content

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

docs: add swift and kotlin

Carl-Gerhard Lindesvärd49d2c7512ade
diff --git a/apps/public/content/docs/sdks/index.mdx b/apps/public/content/docs/sdks/index.mdx
new file mode 100644
index 000000000..c6ca11be4
--- /dev/null
+++ b/apps/public/content/docs/sdks/index.mdx
@@ -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 [[email protected]](mailto:[email protected])
+
diff --git a/apps/public/content/docs/sdks/kotlin.mdx b/apps/public/content/docs/sdks/kotlin.mdx
new file mode 100644
index 000000000..79fd25339
--- /dev/null
+++ b/apps/public/content/docs/sdks/kotlin.mdx
@@ -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 "[email protected]",
+ "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).
+
diff --git a/apps/public/content/docs/sdks/meta.json b/apps/public/content/docs/sdks/meta.json
index 8bf6780d9..0c4e11bf5 100644
--- a/apps/public/content/docs/sdks/meta.json
+++ b/apps/public/content/docs/sdks/meta.json
@@ -1,5 +1,5 @@
{
"title": "SDKs",
- "pages": ["script", "web", "javascript", "node", "nextjs", "..."],
+ "pages": ["script", "web", "javascript", "nextjs", "react", "vue", "astro", "remix", "express", "python", "react-native", "swift", "kotlin"],
"defaultOpen": true
}
diff --git a/apps/public/content/docs/sdks/swift.mdx b/apps/public/content/docs/sdks/swift.mdx
new file mode 100644
index 000000000..ecaa0bb4d
--- /dev/null
+++ b/apps/public/content/docs/sdks/swift.mdx
@@ -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: "[email protected]",
+ 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>
+