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.

Learn more

Or set it up manually by following the rest of this guide.

  1. Install dependency

    Required

    Install 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.swift
    dependencies: [
    .package(url: "https://github.com/PostHog/posthog-ios.git", from: "4.0.0")
    ]
    Using 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

    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.autoCapture argument to true when 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 $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.

  5. Manually capture exceptions

    Optional

    Swift Error handling

    You can manually capture exceptions using the captureException method:

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

    Swift
    import PostHog
    let config = PostHogConfig(
    projectToken: "<ph_project_token>",
    host: "https://us.i.posthog.com"
    )
    // Mark your own dynamic frameworks as in-app.
    // Append, so your app's own entries stay in the list.
    config.errorTrackingConfig.inAppIncludes += [
    "MySharedFramework",
    "MyUtilityLib"
    ]
    // Exclude specific packages from being marked as in-app
    config.errorTrackingConfig.inAppExcludes = [
    "Alamofire",
    "SDWebImage"
    ]
    // Whether frames from other frameworks are in-app.
    config.errorTrackingConfig.inAppByDefault = false
    PostHogSDK.shared.setup(config)

    Configuration options:

    OptionDescription
    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 false

    Default 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. 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
    Check for exceptions in PostHog
  8. 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

Limitations:

  • System symbols and frames are not symbolicated (UIKit, Foundation, etc.) (issue).
  • Before SDK version 3.57.3, Swift crashes appear as SIGTRAP without the actual error message (issue).

Still have questions?

Was this page useful?