Swift

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

Step 1: Add Package via Swift Package Manager

You can add OpenPanel to an Xcode project by adding it as a package dependency.

From the File menu, select Add Packages...
Enter https://github.com/Openpanel-dev/swift-sdk into the package repository URL text field
Click Add Package

Alternatively, if you have a Package.swift file, you can add OpenPanel as a dependency:

dependencies: [
    .package(url: "https://github.com/Openpanel-dev/swift-sdk")
]

Step 2: Import and Initialize

First, import the SDK in your Swift file:

import OpenPanel

Then, initialize the OpenPanel SDK with your client ID:

OpenPanel.initialize(options: .init(
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET"
))

Configuration Options

Common options

apiUrl - The url of the openpanel API or your self-hosted instance
clientId - The client id of your application
clientSecret - The client secret of your application (only required for server-side events)
filter - A function that will be called before sending an event. If it returns false, the event will not be sent
disabled - If true, the library will not send any events

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

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
    }
))

Usage

Tracking Events

To track an event:

OpenPanel.track(name: "Button Clicked", properties: ["button_id": "submit_form"])

Identifying Users

To identify a user:

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:

OpenPanel.setGlobalProperties([
    "app_version": "1.0.2",
    "environment": "production"
])

Incrementing Properties

To increment a numeric property:

OpenPanel.increment(payload: IncrementPayload(profileId: "user123", property: "login_count"))

Decrementing Properties

To decrement a numeric property:

OpenPanel.decrement(payload: DecrementPayload(profileId: "user123", property: "credits_remaining"))

Advanced Usage

Disabling Tracking

You can temporarily disable tracking during initialization:

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:

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:

OpenPanel.initialize(options: .init(
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
    automaticTracking: true
))

Thread Safety

The OpenPanel SDK is designed to be thread-safe. You can call its methods from any thread without additional synchronization.

Common options

On this page