NSExceptionKt

When developing for Apple platforms with Kotlin Native, unhandled Kotlin exceptions (those without a @Throws annotation) cause the program to terminate immediately. This often results in generic EXC_CRASH (SIGABRT) reports in crash reporting tools, which lack the useful Kotlin stacktrace.

NSExceptionKt solves this by allowing you to log unhandled Kotlin exceptions before the app is terminated, ensuring that the stacktrace and any 'caused by' exceptions are captured in your crash reporting tool (like Crashlytics or Bugsnag).

Bugsnag can store multiple fatal exceptions, which would normally trigger a fatal Kotlin termination. To prevent these redundant terminations from being logged as new fatal errors, NSExceptionKt uses a feature flag mechanism.

After an unhandled Kotlin exception is logged, NSExceptionKt sets a feature flag. An addOnSendError filter is then used to drop any subsequent errors that contain this specific feature flag, ensuring the crash reporting flow remains clean.

After installing the dependencies, you must register the NSExceptionKt reporter with your Bugsnag configuration in your AppDelegate.

Use NSExceptionKt.addReporter(.bugsnag(config)) before calling Bugsnag.start(with: config). This ensures that Kotlin exceptions are correctly reported through the Bugsnag pipeline.

import Bugsnag
import NSExceptionKtBugsnag
import shared // This is your shared Kotlin module

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
    ) -> Bool {
        let config = BugsnagConfiguration.loadConfig()
        NSExceptionKt.addReporter(.bugsnag(config))
        Bugsnag.start(with: config)
        return true
    }
}

NSExceptionKt installation depends on which crash reporting SDK you are using. Follow the implementation-specific guides for your chosen provider:

• Crashlytics: See NSExceptionKtCrashlytics/README.md for setup.
• Bugsnag: See NSExceptionKtBugsnag/README.md for setup.

To run the sample application with functional crash reporting, you must provide configuration files for Google Services, Sentry, and Bugsnag.

1. Google Services: Place your GoogleService-Info.plist at NSExceptionKtSample/GoogleService-Info.plist.
2. Sentry & Bugsnag: Create a configuration file at NSExceptionKtSample/NSExceptionKtSample.xcconfig and populate it with your specific credentials.

SENTRY_ORG = YOUR_ORG
SENTRY_PROJECT = YOUR_PROJECT
SENTRY_AUTH_TOKEN = YOUR_AUTH_TOKEN
SENTRY_DSN = YOUR_DSN

BUGSNAG_API_KEY = YOUR_API_KEY

To enable crash reporting, import Firebase, NSExceptionKtCrashlytics, and your shared Kotlin module. Call NSExceptionKt.addReporter within your AppDelegate after FirebaseApp.configure().

import Firebase
import NSExceptionKtCrashlytics
import shared // This is your shared Kotlin module

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
    ) -> Bool {
        FirebaseApp.configure()
        NSExceptionKt.addReporter(.crashlytics(causedByStrategy: .append))
        return true
    }
}