iOS

1. 1

   Install dependency

   Required

   Install via Swift Package Manager:

   Package.swift

   swiftCopy

   dependencies: [
     .package(url: "https://github.com/PostHog/posthog-ios.git", from: "3.56.0")
   ]

   Or add PostHog to your Podfile:

   Podfile

   rubyCopy

   pod "PostHog", "~> 3.56"

2. 2

   Configure PostHog

   Required

   Initialize PostHog in your AppDelegate:

   AppDelegate.swift

   swiftCopy

   import Foundation
   import PostHog
   import UIKit
   
   class AppDelegate: NSObject, UIApplicationDelegate {
       func application(
   
   
   
   
   
   
   
   
   

3. 3

   Send events

   Recommended

   Once installed, PostHog will automatically start capturing events. You can also manually send events to test your integration:

   Swift

   swiftCopy

   PostHogSDK.shared.capture("button_clicked", properties: ["button_name": "signup"])

4. 4

   Set up exception autocapture

   Recommended

   Remote configuration

   Exception autocapture can also be managed remotely via the error tracking settings (opens in a new tab).

   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.autoCapture argument to true when initializing the PostHog SDK.

   Swift

   swiftCopy

   import PostHog
   
   let config =
   
   
   
   
   
   

5. 5

   Manually capture exceptions

   Optional

   Swift Error handling

   You can manually capture exceptions using the captureException method:

   Swift

   swiftCopy

   import PostHog
   
   do {
       try FileManager.default.removeItem(
   
   
   

6. 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

   swiftCopy

   import PostHog
   
   let config = PostHogConfig(
       projectToken: "<ph_project_token>",
       host: "https://us.i.posthog.com"
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   

7. 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.

   

   Check for exceptions in PostHog (opens in a new tab)

8. 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.

   Upload dSYMs (opens in a new tab)

Limitations:

• System symbols and frames are not symbolicated (UIKit, Foundation, etc.) (issue (opens in a new tab)).
• Swift crashes appear as SIGTRAP without the actual error message (issue (opens in a new tab)).

Still have questions?

Ask PostHog AI

Was this page useful?

HelpfulCould be better

When enabled, this automatically captures $exception events 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 $exception events with level “fatal” on the next app launch.

Objective-C NSException handling

For Objective-C code that uses NSException:

Objective-C

Adding custom properties

You can add custom properties to help with debugging, grouping, and analysis:

Swift

This is helpful if you’ve built your own error handling logic or want to capture exceptions that are handled by your application code.

Configuration options:

Default behavior:

• Your app’s bundle identifier and executable name are automatically included
• System frameworks (Foundation, UIKit, etc.) are automatically excluded