cvb941/sentry-kotlin-multiplatform

Experimental SDK for Kotlin Multiplatform

Experimental Sentry SDK for Kotlin Multiplatform

This project is an experimental SDK for Kotlin Multiplatform. This SDK is a wrapper around different platforms such as JVM, Android, iOS, macOS, watchOS, tvOS that can be used on Kotlin Multiplatform.

Supported Platforms

Target Platform	Target preset
Android	android
Kotlin/JVM	jvm
iOS	iosArm64 iosX64 iosSimulatorArm64
macOS	macosArm64 macosX64
watchOS	watchosArm32 watchosArm64 watchosX64 watchosSimulatorArm64
tvOS	tvosArm64 tvosX64 tvosSimulatorArm64

Configure Repository

The Kotlin Multiplatform SDK is available only on mavenLocal. You can declare this repository in your build script as follows:

repositories {
  // Currently only supported locally
  mavenLocal()
}

and then run:

./gradlew publishToMavenLocal

Add dependency

For a multiplatform project, you need to add the sentry-kotlin-multiplatform artifact to the commonMain source set:

val commonMain by getting {
  dependencies {
    api("io.sentry:sentry-kotlin-multiplatform:0.0.1")
  }
}

Cocoa

If you are targeting Apple platforms (iOS, macOS, watchOS, tvOS), then you need to use CocoaPods to include Sentry Cocoa into this SDK. One way to achieve this is to include the Sentry Cocoa SDK via the Kotlin CocoaPods extension. Be aware that your Sentry Cocoa version has to match the SDK's version. Currently the supported version is ~> 7.21.0

cocoapods {
  // ...
  
  // Make sure Sentry Cocoa in your project matches this version
  pod("Sentry", "~> 7.21.0")

  framework {
    baseName = "shared"

    // Export the SDK in order to be able to access it directly in the iOS project
    export("io.sentry:sentry-kotlin-multiplatform:0.0.1")
  }
}

Initialization

There are two main strategies for initializing the SDK:

• Shared initializer
• Platform specific initializers

Shared initializer will initialize the SDK in your shared codebase but you will use the same configuration options for all platforms.

Platform specific initializers initialize the SDK directly in the target platform. The benefit is being able to customize the configuration options specific to the platforms.

It is also possible to mix those two strategies based on your needs and project setup.

Prerequisites (Android-only)

Both of the strategies require disabling auto-init on Android to not clash with the ContentProvider, which auto-initializes the Sentry Android SDK. To do so, add the following to the AndroidManifest.xml file under your androidMain source set:

<application>
    <meta-data android:name="io.sentry.auto-init" android:value="false" />
</application>

Shared Initializer

Create a Kotlin file in your commonMain e.g. AppSetup.kt or however you want to call it and create a function that will initialize the SDK.

import io.sentry.kotlin.multiplatform.Context
import io.sentry.kotlin.multiplatform.Sentry

// The context is needed for Android initializations
fun initializeSentry(context: Context?) {
  Sentry.init(context) {
    it.dsn = "__DSN__"
  }
}

Now call this function in an early lifecycle stage in your platforms.

Android

import your.kmp.app.initializeSentry

class YourApplication : Application() {
  override fun onCreate() {
    super.onCreate()
      // Make sure to add the context!
      initializeSentry(this)
   }
}

Cocoa

import shared

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
    ) -> Bool {
        AppSetupKt.initializeSentry(context = nil)
        return true        
    }
}

Platform Specific Initializers

Android

import io.sentry.kotlin.multiplatform.Sentry

class YourApplication : Application() {
  override fun onCreate() {
    super.onCreate()
      // Make sure to add the context!
      Sentry.init(this) {
        it.dsn = "___DSN___"
      }
   }
}

Cocoa

import shared

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
    ) -> Bool {
        Sentry.shared.doInit() { options in
          options.dsn = "__DSN__"
        }
        return true        
    }
}

Debug Symbols for Apple targets

A dSYM upload is required for Sentry to symbolicate your crash logs for viewing. The symbolication process unscrambles Apple’s crash logs to reveal the function, variables, file names, and line numbers of the crash. The dSYM file can be uploaded through the sentry-cli tool or through a Fastlane action. Please visit our sentry.io guide to get started on uploading debug symbols.

Troubleshooting

WARNING: CocoaPods requires your terminal to be using UTF-8 encoding. Consider adding the following to ~/.profile: export LANG=en_US.UTF-8

This is a known problem and can easily be fixed as described in this Stack Overflow post

Contribution

Please see the contribution guide before contributing