Setting the file. One moment.
Skill 82 · Instrument Product Analytics
Subchapter 82.43
references/ios.mdMarkdown6 KBView on GitHub
AI agents: this is one page from PostHog’s docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt (opens in a new tab)
The PostHog iOS SDK is a library that you can use to track events, identify users, record session replays, evaluate feature flags, run experiments, build surveys, and more.
This page shows you how to install the SDK and get started with it. If you’ve already installed the SDK, you can skip ahead to learn about using the features (opens in a new tab) and configuring the SDK (opens in a new tab).
PostHog is available through CocoaPods (opens in a new tab) or you can add it as a Swift Package Manager based dependency.
Podfile
pod "PostHog", "~> 3.59.3"Add PostHog as a dependency in your Xcode project “Package Dependencies” and select the project target for your app, as appropriate.
For a Swift Package Manager based project, add PostHog as a dependency in your Package.swift file’s Package dependencies section:
Package.swift
dependencies: [
.package(url: "https://github.com/PostHog/posthog-ios.git", from: "3.59.3")
],and then as a dependency for the Package target utilizing PostHog:
Package.swift
.target(
name: "myApp",
dependencies: [.product(name: "PostHog", package: "posthog-ios")]),Configuration is done through the PostHogConfig object. Here’s a basic configuration example to get you started.
You can find more advanced configuration options in the configuration page (opens in a new tab).
Swift
import Foundation
import PostHog
import UIKit
class AppDelegate: NSObject, UIApplicationDelegate {
func application(_: UIApplication, didFinishLaunchingWithOptions _: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
let POSTHOG_PROJECT_TOKEN = "<ph_project_token>"
// usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
let POSTHOG_HOST = "https://us.i.posthog.com"
let config = PostHogConfig(projectToken: POSTHOG_PROJECT_TOKEN, host: POSTHOG_HOST)
PostHogSDK.shared.setup(config)
return true
}
}Swift
import SwiftUI
import PostHog
@main
struct YourGreatApp: App {
// Add PostHog to your app's initializer.
// If using UIApplicationDelegateAdaptor, see the UIKit tab.
init() {
let POSTHOG_PROJECT_TOKEN = "<ph_project_token>"
// usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
let POSTHOG_HOST = "https://us.i.posthog.com"
let config = PostHogConfig(projectToken: POSTHOG_PROJECT_TOKEN, host: POSTHOG_HOST)
PostHogSDK.shared.setup(config)
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}Identifying users is required. Call
posthog.identify('your-user-id')after login to link events to a known user. This is what connects frontend event captures, session replays (opens in a new tab), LLM traces (opens in a new tab), and error tracking (opens in a new tab) to the same person — and lets backend events link back too.Use a stable ID from your auth system when possible, not an email or display name. Send those as person properties instead. If your app has no other stable key, email works as a fallback if they are unique. Never a shared literal like
"anonymous"or"user", which pools many people onto one person and corrupts their data. When no ID is available at all, skip the identify and retain the anonymous distinct ID that’s automatically assigned.Call
posthog.reset()on logout, so the next person to use the browser doesn’t inherit the last one’s identity.See our guide on identifying users (opens in a new tab) for how to set this up.
The PostHog iOS SDK will continue to capture events when the device is offline. The events are stored in a queue in the device’s file storage and are flushed when the device is online.
maxQueueSize in the configuration.You can find the options for configuring the offline behavior in the configuration page (opens in a new tab).
PostHog supports sharing analytics data between your main app and application extensions (such as widgets, app clips, share extensions, and custom keyboards) through App Groups. This ensures that users maintain the same identity across all parts of your app ecosystem.
By default, each iOS app target stores its data in its own sandboxed directory. This means that if a user interacts with your main app and then uses a widget or extension, PostHog would treat them as two different anonymous users. This can lead to:
The PostHog iOS SDK uses method swizzling to intercept and modify method calls at runtime to provide advanced features like screen view tracking, element interactions, session replay, surveys, and more.
Method swizzling is particularly important for accurate session metrics tracking. When disabled, the SDK cannot capture optimal session metrics.
You can learn more about configuring method swizzling in the configuration page (opens in a new tab).
The iOS SDK can register a device for Workflows (opens in a new tab) push notifications and capture when a user opens one. For setup, including automatic and manual registration, capturing opens, and identity verification, see Push notifications (opens in a new tab).
Now that you’ve installed the SDK, explore the configuration and usage options:
Ask PostHog AI
HelpfulCould be better