references/ios.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
iOS Error Tracking installation
Canonical URL: https://posthog.com/docs/error-tracking/installation/ios
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install with the wizard
- Install dependency
- Configure PostHog
- Send events
- Set up exception autocapture
- Manually capture exceptions
- Configure in-app frames
- Verify error tracking
- Upload dSYMs
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.
npx @posthog/wizard
Or set it up manually by following the rest of this guide.
-
1
Install dependency
Required
Install via Swift Package Manager:
Package.swift
dependencies: [ .package(url: "https://github.com/PostHog/posthog-ios.git", from: "3.56.0") ]Or add PostHog to your Podfile:
Podfile
pod "PostHog", "~> 3.56" -
2
Configure PostHog
Required
Initialize PostHog in your AppDelegate:
AppDelegate.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>" let POSTHOG_HOST = "https://us.i.posthog.com" let config = PostHogConfig(projectToken: POSTHOG_PROJECT_TOKEN, host: POSTHOG_HOST) PostHogSDK.shared.setup(config) return true } } -
3
Send events
Recommended
Once installed, PostHog will automatically start capturing events. You can also manually send events to test your integration:
Swift
PostHogSDK.shared.capture("button_clicked", properties: ["button_name": "signup"]) -
4
Set up exception autocapture
Recommended
Remote configuration
Exception autocapture can also be managed remotely via the error tracking settings.
Platform support
Exception 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.Swift
import PostHog let config = PostHogConfig( projectToken: "<ph_project_token>", host: "https://us.i.posthog.com" ) config.errorTrackingConfig.autoCapture = true PostHogSDK.shared.setup(config)When 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
Optional
Swift Error handling
You can manually capture exceptions using the
captureExceptionmethod:Swift
import PostHog do { try FileManager.default.removeItem(at: badFileUrl) } catch { PostHogSDK.shared.captureException(error) }Objective-C NSException handling
For Objective-C code that uses NSException:
Objective-C
@import PostHog; @try { [self riskyOperation]; } @catch (NSException *exception) { [[PostHogSDK shared] captureExceptionWithNSException:exception properties:nil]; }Adding custom properties
You can add custom properties to help with debugging, grouping, and analysis:
Swift
do { try performNetworkRequest() } catch { PostHogSDK.shared.captureException(error, properties: [ "endpoint": "/api/users", "retry_count": 3 ]) }This 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
Optional
By default, PostHog automatically marks your app's code as "in-app" in stack traces to help you focus on your code rather than system frameworks.
You can customize this behavior with
errorTrackingConfig:Swift
import PostHog let config = PostHogConfig( projectToken: "<ph_project_token>", host: "https://us.i.posthog.com" ) // Mark additional packages as in-app config.errorTrackingConfig.inAppIncludes = [ "MySharedFramework", "MyUtilityLib" ] // Exclude specific packages from being marked as in-app config.errorTrackingConfig.inAppExcludes = [ "Alamofire", "SDWebImage" ] // Control default behavior for unknown packages config.errorTrackingConfig.inAppByDefault = true // default PostHogSDK.shared.setup(config)Configuration options:
| Option | Description | | --- | --- | |
inAppIncludes| List of package/bundle identifiers to mark as in-app (takes precedence over excludes) | |inAppExcludes| List of package/bundle identifiers to exclude from in-app | |inAppByDefault| Whether frames are considered in-app by default when origin cannot be determined |Default behavior:
- Your app's bundle identifier and executable name are automatically included
- System frameworks (Foundation, UIKit, etc.) are automatically excluded
-
Verify error tracking
Recommended
Confirm events are being sent to PostHog
Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.
Activity feed with events
-
7
Upload dSYMs
Required
Great, you're capturing exceptions! The next step is to upload dSYM files so PostHog can symbolicate your crash reports and generate accurate stack traces.
Let's continue to the next section.