iOS Error Tracking installation
Install with the wizard
Run this command in your project directory to add PostHog to your iOS project. The wizard detects your framework, installs the SDK, and sets up your first events.
Or set it up manually by following the rest of this guide.
- 1
Install dependency
RequiredInstall via Swift Package Manager. PostHog requires Xcode 26 or later, and iOS 15, macOS 12, tvOS 15, watchOS 10, or visionOS 1 or later.
Package.swiftUsing CocoaPods?Version 4 is only published to Swift Package Manager. Version 3 stays on CocoaPods (
pod "PostHog", "~> 3.0"), but CocoaPods trunk becomes read-only on December 2, 2026. After that, existing 3.x versions stay installable, but new releases only ship through Swift Package Manager. To switch, see the iOS migration guide. - 2
Configure PostHog
RequiredInitialize PostHog in your AppDelegate:
AppDelegate.swift - 3
Send events
RecommendedOnce installed, PostHog will automatically start capturing events. You can also manually send events to test your integration:
Swift - 4
Set up exception autocapture
RecommendedRemote configurationException autocapture can also be managed remotely via the error tracking settings.
Platform supportException autocapture is available on iOS, macOS, and tvOS only. It is not available on watchOS or visionOS due to platform limitations.
You can still capture events manually on all platforms, including visionOS.
You can autocapture exceptions by setting the
errorTrackingConfig.autoCaptureargument totruewhen initializing the PostHog SDK.SwiftWhen enabled, this automatically captures
$exceptionevents for:- Mach exceptions (e.g.,
EXC_BAD_ACCESS,EXC_CRASH) - POSIX signals (e.g.,
SIGSEGV,SIGABRT,SIGBUS) - Uncaught NSExceptions
Crashes are persisted to disk and sent as
$exceptionevents with level "fatal" on the next app launch. - Mach exceptions (e.g.,
- 5
Manually capture exceptions
OptionalSwift Error handling
You can manually capture exceptions using the
captureExceptionmethod:SwiftObjective-C NSException handling
For Objective-C code that uses NSException:
Objective-CAdding custom properties
You can add custom properties to help with debugging, grouping, and analysis:
SwiftThis is helpful if you've built your own error handling logic or want to capture exceptions that are handled by your application code.
- 6
Configure in-app frames
OptionalBy default, PostHog marks frames from your app's executable as "in-app" in stack traces, so you can focus on your code rather than system and third-party frameworks. Code linked statically into your app, such as most Swift packages, is part of the executable.
You can customize this behavior with
errorTrackingConfig:SwiftConfiguration options:
Option Description inAppIncludesList of package/bundle identifiers to mark as in-app (takes precedence over excludes) inAppExcludesList of package/bundle identifiers to exclude from in-app inAppByDefaultWhether frames from a framework no other rule matches are in-app. Default is falseDefault behavior:
- Your app's executable and any framework whose name starts with your app's executable name or bundle identifier are in-app
- System frameworks (Foundation, UIKit, etc.) are not in-app
- From SDK version 4.0, other frameworks are not in-app. If your app ships its own code in another dynamic framework, add its name to
inAppIncludes
- 7







