From 9e9aeefeaa4b0c85bb0d9a86debc678c90da6753 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 8 Oct 2026 16:35:23 +0200 Subject: [PATCH 1/4] docs(kmp): Update Kotlin Multiplatform docs for 0.28.0 Document the 0.28.0 changes: Sentry Cocoa is installed through SwiftPM (official Kotlin SwiftPM import or spm4Kmp) instead of CocoaPods, Apple deployment minimums are raised, watchosArm32 becomes a no-op target, and new trace continuation options are available. Co-Authored-By: Claude Co-authored-by: Cursor --- .../configuration/gradle.mdx | 141 +++++++++++++++--- .../configuration/options.mdx | 22 +++ .../kotlin-multiplatform/features/index.mdx | 52 ++++--- .../manual-setup/index.mdx | 75 ++++------ .../native-access-sdk.mdx | 26 +--- .../user-feedback/index.mdx | 6 + .../kotlin.compose-multiplatform.mdx | 16 +- .../kotlin.kotlin-multiplatform.mdx | 16 +- 8 files changed, 227 insertions(+), 127 deletions(-) diff --git a/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle.mdx b/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle.mdx index 348ad6c810497..bc98351136630 100644 --- a/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle.mdx +++ b/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle.mdx @@ -7,9 +7,10 @@ description: "Learn how to set up Sentry's Kotlin Multiplatform Gradle Plugin." The [Sentry Kotlin Multiplatform Gradle Plugin](https://github.com/getsentry/sentry-kotlin-multiplatform/tree/main/sentry-kotlin-multiplatform-gradle-plugin) is a plugin that simplifies the set up process. It can be used to configure the Sentry SDK for Kotlin Multiplatform projects. The Gradle Plugin supports the following features: + - Auto-installation of the Sentry Kotlin Multiplatform SDK. -- Auto-installation of the Sentry Cocoa SDK via Cocoapods (if the Kotlin Cocoapods plugin is applied). -- Automatic configuration of the Kotlin/Native linker for seamless usage with the Swift Package Manager. +- Auto-installation of the Sentry Cocoa SDK with Swift Package Manager (SwiftPM), through Kotlin's official SwiftPM import (Kotlin 2.4 and newer) or the [spm4Kmp](https://github.com/frankois944/spm4Kmp) plugin. +- Automatic configuration of the Kotlin/Native linker if you add the Sentry Cocoa SDK to your Xcode project yourself. ## Setup @@ -19,25 +20,29 @@ Using Gradle in your `shared/build.gradle.kts` add: ```kotlin {filename:shared/build.gradle.kts} plugins { - id("io.sentry.kotlin.multiplatform.gradle") version "{{@inject packages.version('sentry.kotlin.kmp', '0.9.0') }}" + id("io.sentry.kotlin.multiplatform.gradle") version "{{@inject packages.version('sentry.kotlin.kmp.gradle-plugin', '0.9.0') }}" } ``` +If you use spm4Kmp, apply the Sentry Gradle plugin before spm4Kmp in the `plugins` block. + ### Configure We expose the following configuration values: ```kotlin {filename:shared/build.gradle.kts} +import io.sentry.kotlin.multiplatform.gradle.AppleDependencyProvider + sentryKmp { // Configure auto-installation of Sentry components. autoInstall { // Enable auto-installation of Sentry components: // - Sentry Kotlin Multiplatform SDK - // - Sentry Cocoa SDK with Cocoapods if Kotlin Cocoapods plugin is applied. + // - Sentry Cocoa SDK with SwiftPM // Default is enabled. enabled = true - // Configure the commonMain source set - + // Configure the commonMain source set. commonMain { // Enable auto-installation of the Sentry Kotlin Multiplatform SDK in commonMain. // Default is enabled. @@ -48,29 +53,117 @@ sentryKmp { sentryKmpVersion = "{{@inject packages.version('sentry.kotlin.kmp', '0.9.0') }}" } - // Configure the Cocoapods plugin. - cocoapods { - // Enable auto-installation of the Sentry Cocoa SDK with Cocoapods. - // Default is enabled. - enabled = true + // Configure auto-installation of the Sentry Cocoa SDK for Apple targets. + apple { + // Select how the Sentry Cocoa SDK is installed: + // - AUTO: Use spm4Kmp if it's applied, install nothing if the Kotlin CocoaPods plugin + // is applied, and otherwise use Kotlin's official SwiftPM import on Kotlin 2.4+. + // - SWIFT_PM: Use Kotlin's official SwiftPM import. Requires Kotlin 2.4+. + // - SPM4KMP: Use the spm4Kmp plugin. Requires the spm4Kmp plugin to be applied. + // - NONE: Don't install the Sentry Cocoa SDK. + // Default is AUTO. + provider = AppleDependencyProvider.AUTO - // Specify the version of the Sentry Cocoa SDK to install. + // Specify the exact version of the Sentry Cocoa SDK to install. // Default is the Cocoa SDK version used in the Kotlin Multiplatform SDK. - sentryCocoaVersion = "8.38.0" + sentryCocoaVersion = "9.29.2" } + } - // Configure the linker. This is only relevant if you are using SPM. - linker { - // Path to the Xcode project that will be used to link the framework. - // This is used to find the derived data path in which the framework is stored for SPM. - // Default is the current project directory. - xcodeprojPath = "path/to/your/project.xcodeproj" - - // Path to the framework that will be linked. - // Takes precedence over xcodeprojPath if both are set. - // Default is null. - frameworkPath = "path/to/your/framework.framework" - } + // Configure linking of the Sentry Cocoa framework for Apple targets that don't + // get the Sentry Cocoa SDK through the plugin's SwiftPM installation. + linker { + // Enable linker configuration. + // Default is enabled. + enabled = true + + // Path to the Xcode project that will be used to link the framework. + // This is used to find the derived data path in which the framework is stored for SPM. + // Default is the current project directory. + xcodeprojPath = "path/to/your/project.xcodeproj" + + // Path to the framework that will be linked. + // Takes precedence over xcodeprojPath if both are set. + // Default is null. + frameworkPath = "path/to/your/Sentry.xcframework" + } +} +``` + +If you explicitly select a provider that isn't available (for example, `SWIFT_PM` on Kotlin versions older than 2.4), the build fails instead of falling back to another provider. + +## Apple Installation Methods + +### Official Kotlin SwiftPM Import + +On Kotlin 2.4 and newer, the plugin installs the Sentry Cocoa SDK through Kotlin's official SwiftPM import without additional `sentryKmp` configuration. + +Xcode links the Sentry Cocoa SDK through a Swift package that Kotlin generates for its SwiftPM dependencies. Run Kotlin's one-time [Xcode linkage package setup](https://kotlinlang.org/docs/multiplatform/multiplatform-spm-import.html#run-the-swiftpm-integration-task): + +```bash +XCODEPROJ_PATH='/path/to/iosApp/iosApp.xcodeproj' ./gradlew :shared:integrateLinkagePackage +``` + +Commit the generated `KotlinMultiplatformLinkedPackage` and the updated Xcode project. Don't also add `sentry-cocoa` to your Xcode project yourself. + +### spm4Kmp + +If you apply the [spm4Kmp](https://github.com/frankois944/spm4Kmp) plugin (`io.github.frankois944.spmForKmp`), the plugin installs the Sentry Cocoa SDK through spm4Kmp. Apply the Sentry Gradle plugin before spm4Kmp: + +```kotlin {filename:shared/build.gradle.kts} +plugins { + kotlin("multiplatform") + id("io.sentry.kotlin.multiplatform.gradle") version "{{@inject packages.version('sentry.kotlin.kmp.gradle-plugin', '0.9.0') }}" + id("io.github.frankois944.spmForKmp") +} +``` + +### Install the Sentry Cocoa SDK Yourself + +If you prefer to manage the Sentry Cocoa SDK yourself, set the provider to `NONE`. Use the exact Sentry Cocoa SDK version listed in the [version compatibility table](https://github.com/getsentry/sentry-kotlin-multiplatform?tab=readme-ov-file#cocoa-sdk-version-compatibility-table). + +If you add `sentry-cocoa` to your Xcode project with [Swift Package Manager](/platforms/apple/install/swift-package-manager/), keep the linker enabled so the plugin can find and link the framework: + +```kotlin {filename:shared/build.gradle.kts} +import io.sentry.kotlin.multiplatform.gradle.AppleDependencyProvider + +sentryKmp { + autoInstall.apple.provider = AppleDependencyProvider.NONE +} +``` + +If you declare the Sentry Cocoa SDK in Kotlin's `swiftPMDependencies` yourself, also disable the linker, since Kotlin links those packages itself: + +```kotlin {filename:shared/build.gradle.kts} +import io.sentry.kotlin.multiplatform.gradle.AppleDependencyProvider + +sentryKmp { + autoInstall.apple.provider = AppleDependencyProvider.NONE + linker.enabled = false +} + +kotlin { + swiftPMDependencies { + swiftPackage( + url = url("https://github.com/getsentry/sentry-cocoa.git"), + version = exact("9.29.2"), + products = listOf(product("Sentry")), + ) + // Only if you target macOS or tvOS. Use a higher version if your app needs it. + macosMinimumDeploymentTarget.set("12.0") + tvosMinimumDeploymentTarget.set("15.0") } } ``` + +## Migrate From CocoaPods + +Starting with version `0.28.0`, the SDK uses Sentry Cocoa 9, which doesn't support CocoaPods. The plugin no longer installs the Sentry pod, and the build fails if you still configure `sentryKmp.autoInstall.cocoapods`. + +To migrate: + +1. Remove the `sentryKmp.autoInstall.cocoapods` configuration. +2. Remove any `pod("Sentry")` declaration from your `cocoapods` block. Other CocoaPods dependencies can stay. +3. Install the Sentry Cocoa SDK with SwiftPM using one of the [Apple installation methods](#apple-installation-methods). + +The Kotlin CocoaPods plugin doesn't allow SwiftPM dependencies in the same module. If you keep the Kotlin CocoaPods plugin applied, the plugin doesn't install the Sentry Cocoa SDK. In that case, add `sentry-cocoa` to your Xcode project with Swift Package Manager and let the plugin link it, or [migrate your project from CocoaPods to SwiftPM](https://kotl.in/cocoapods-to-swiftpm-migration). diff --git a/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/options.mdx b/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/options.mdx index 67b214701dc45..54e5c05ca8c92 100644 --- a/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/options.mdx +++ b/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/options.mdx @@ -158,3 +158,25 @@ String entries do not have to be full matches, meaning the URL of a request is m If is not provided, trace data is attached to every outgoing request from the instrumented client. + + + +Controls whether the native SDKs on Apple, Android, and JVM attach a W3C `traceparent` header, in addition to the `sentry-trace` and `baggage` headers, to outgoing HTTP requests they instrument. This is useful when downstream services use OpenTelemetry or other W3C Trace Context-compatible tracing. The option still controls which requests receive the header. + + + + + +If set to `true`, the native SDKs on Apple, Android, and JVM only continue an incoming trace if the organization ID in the incoming `baggage` header matches the organization ID of the current Sentry client. If either organization ID is missing, the SDK starts a new trace. + +If set to `false`, the SDK tolerates missing organization IDs, but still starts a new trace if both organization IDs are present and different. + +The client's organization ID is extracted from the DSN or can be set with the option. This is useful to prevent traces of unknown third-party services from being continued in your application. + + + + + +The organization ID used for trace continuation. By default, the SDK extracts the organization ID from the DSN. Set this option if your DSN doesn't contain an organization ID, for example, when you use self-hosted Sentry or Relay. + + diff --git a/docs/platforms/kotlin/guides/kotlin-multiplatform/features/index.mdx b/docs/platforms/kotlin/guides/kotlin-multiplatform/features/index.mdx index 3b88dd54b5566..b903e2c380e0e 100644 --- a/docs/platforms/kotlin/guides/kotlin-multiplatform/features/index.mdx +++ b/docs/platforms/kotlin/guides/kotlin-multiplatform/features/index.mdx @@ -21,32 +21,46 @@ To access the native SDK init options, use the [Native Platform Options initiali The following guides cover features available for Kotlin Multiplatform apps: -- Session Replay records user sessions on Android and iOS. -- Size Analysis analyzes app builds for size regressions. -- Snapshots compares UI images across changes. -- ANR and App Hang detection reports unresponsive apps on Android and supported Apple platforms. -- Release Health tracks crash-free sessions and users across releases. +- Session Replay records user + sessions on Android and iOS. +- Size Analysis analyzes app + builds for size regressions. +- Snapshots compares UI images + across changes. +- + ANR and App Hang detection + + reports unresponsive apps on Android and supported Apple platforms. +- + Release Health + + tracks crash-free sessions and users across releases. ## Supported Platforms The table below lists supported platforms and their corresponding presets. -| Target Platform | Target Preset | -| --------------- | ------------------------------------------------------------------------------------------------------------ | -| Android |
  • `androidTarget`
| -| Kotlin/JVM |
  • `jvm`
| -| iOS |
  • `iosArm64`
  • `iosX64`
  • `iosSimulatorArm64`
| -| macOS |
  • `macosArm64`
  • `macosX64`
| -| watchOS |
  • `watchosArm32`
  • `watchosArm64`
  • `watchosX64`
  • `watchosSimulatorArm64`
| -| tvOS |
  • `tvosArm64`
  • `tvosX64`
  • `tvosSimulatorArm64`
| +| Target Platform | Target Preset | +| --------------- | ------------------------------------------------------------------------------------- | +| Android |
  • `androidTarget`
| +| Kotlin/JVM |
  • `jvm`
| +| iOS |
  • `iosArm64`
  • `iosX64`
  • `iosSimulatorArm64`
| +| macOS |
  • `macosArm64`
  • `macosX64`
| +| watchOS |
  • `watchosArm64`
  • `watchosX64`
  • `watchosSimulatorArm64`
| +| tvOS |
  • `tvosArm64`
  • `tvosX64`
  • `tvosSimulatorArm64`
| + +Starting with version `0.28.0`, Apple targets require iOS 15, tvOS 15, macOS 12, or watchOS 9 or newer. ## Stubbed Platforms (No-Op Implementations) You can add these targets to your project and they will compile and satisfy the API surface, but **do nothing at runtime**. -| Target Platform | Target preset | -| --------------- | ------------------------------------------------- | -| JS |
  • `js`
| -| Wasm JS |
  • `wasmJs`
| -| Linux |
  • `linuxx64`
  • `linuxarm64`
| -| Windows |
  • `mingwx64`
| +| Target Platform | Target preset | +| ---------------- | ------------------------------------------------- | +| JS |
  • `js`
| +| Wasm JS |
  • `wasmJs`
| +| Linux |
  • `linuxx64`
  • `linuxarm64`
| +| Windows |
  • `mingwx64`
| +| watchOS (32-bit) |
  • `watchosArm32`
| + +Starting with version `0.28.0`, `watchosArm32` is a no-op target because the Sentry Cocoa SDK no longer ships an `armv7k` slice. Builds for this target still succeed, but Sentry doesn't capture events, crashes, or logs on it. diff --git a/docs/platforms/kotlin/guides/kotlin-multiplatform/manual-setup/index.mdx b/docs/platforms/kotlin/guides/kotlin-multiplatform/manual-setup/index.mdx index fb216dfcf12fc..ccca5022344e1 100644 --- a/docs/platforms/kotlin/guides/kotlin-multiplatform/manual-setup/index.mdx +++ b/docs/platforms/kotlin/guides/kotlin-multiplatform/manual-setup/index.mdx @@ -10,57 +10,49 @@ If you can't (or prefer not to) use the [gradle plugin](/platforms/kotlin/guides Sentry captures data by using an SDK within your application’s runtime. -To install the Kotlin Multiplatform SDK, you need to add the following to your `build.gradle.kts` file in your shared module: +To install the Kotlin Multiplatform SDK, you need to add the following to your `build.gradle.kts` file in your shared module. For Apple targets, this installs the Sentry Cocoa SDK with Kotlin's official [SwiftPM import](https://kotlinlang.org/docs/multiplatform/multiplatform-spm-import.html), which requires Kotlin 2.4 or newer: ```kotlin {filename:shared/build.gradle.kts} plugins { - kotlin("multiplatform") - kotlin("native.cocoapods") - // .. your other plugins + kotlin("multiplatform") + // .. your other plugins } kotlin { - android() - iosX64() + androidTarget() iosArm64() iosSimulatorArm64() sourceSets { - val commonMain by getting { - dependencies { - implementation("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}") - } - } - - // Android target - val androidMain by getting { - dependsOn(commonMain) - } - - // Apple targets: - val iosMain by getting { - dependsOn(commonMain) + commonMain.dependencies { + implementation("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}") } } - cocoapods { - // rest of configuration - summary = "Some description for the Shared Module" - homepage = "Link to the Shared Module homepage" - ios.deploymentTarget = "14.1" - podfile = project.file("../iosApp/Podfile") - // Make sure you use the proper version according to our Cocoa SDK Version Compatibility Table. - // TODO: link to table in sentry-kotlin-multiplatform gh repo - pod("Sentry") { - // Check the version compatibility table for the correct version - version = "8.36.0" - linkOnly = true - extraOpts += listOf("-compiler-option", "-fmodules") - } + swiftPMDependencies { + swiftPackage( + url = url("https://github.com/getsentry/sentry-cocoa.git"), + // Use the exact version from the Cocoa SDK version compatibility table. + version = exact("9.29.2"), + products = listOf(product("Sentry")), + ) + // Only if you target macOS or tvOS. Use a higher version if your app needs it. + macosMinimumDeploymentTarget.set("12.0") + tvosMinimumDeploymentTarget.set("15.0") } } ``` +Make sure the Sentry Cocoa SDK version matches the one listed for your Kotlin Multiplatform SDK version in the [version compatibility table](https://github.com/getsentry/sentry-kotlin-multiplatform?tab=readme-ov-file#cocoa-sdk-version-compatibility-table). + +Then run Kotlin's one-time [Xcode linkage package setup](https://kotlinlang.org/docs/multiplatform/multiplatform-spm-import.html#run-the-swiftpm-integration-task) so Xcode links the Sentry Cocoa SDK into your app. + + + +Starting with version `0.28.0`, the SDK requires iOS 15, tvOS 15, macOS 12, or watchOS 9 or newer, and no longer supports installing the Sentry Cocoa SDK with CocoaPods. + + + ## Configure Configuration should happen as early as possible in your application's lifecycle. @@ -80,18 +72,3 @@ Learn more about manually capturing an error or message in our To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and select your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. - -## Apple Installation Methods - -### Swift Package Manager (SPM) - -Swift Package Manager (SPM) is a powerful tool for managing dependencies in Swift that allows developers to enjoy a more native integration experience with Xcode. -If you already use SPM or prefer it over other package managers on Apple platforms, this guide will show you how to install the Kotlin Multiplatform SDK while using Swift Package Manager. - -#### Install - -In order to install the Sentry Kotlin Multiplatform SDK, you need to use Cocoapods and Swift Package Manager simultaneously, which might seem unconventional at first, especially if you're accustomed to using SPM for all your dependencies. However, you can achieve a smooth integration by using the [Kotlin Cocoapods plugin](https://kotlinlang.org/docs/native-cocoapods-dsl-reference.html#cocoapods-block) specifically for compiling and building the shared framework. You can then continue to manage all other dependencies with SPM as usual. - -Follow the steps for our primary installation method [Cocoapods](/platforms/kotlin/guides/kotlin-multiplatform/manual-setup/#install) to install the Sentry Kotlin Multiplatform SDK. - -After you've consumed the shared framework in your application via Cocoapods, you can continue with SPM for other dependencies without disrupting your existing workflow. diff --git a/docs/platforms/kotlin/guides/kotlin-multiplatform/native-access-sdk.mdx b/docs/platforms/kotlin/guides/kotlin-multiplatform/native-access-sdk.mdx index 3dbbbb274560a..f2a1333430e14 100644 --- a/docs/platforms/kotlin/guides/kotlin-multiplatform/native-access-sdk.mdx +++ b/docs/platforms/kotlin/guides/kotlin-multiplatform/native-access-sdk.mdx @@ -16,34 +16,10 @@ val commonMain by getting { ## Export the Framework -If you have Apple targets, you also need to export the framework. - -### Cocoapods - -```kotlin {filename:shared/build.gradle.kts} -cocoapods { - summary = "Some description for the Shared Module" - homepage = "Link to the Shared Module homepage" - ios.deploymentTarget = "14.1" - podfile = project.file("../iosApp/Podfile") - // Make sure you use the proper version according to our Cocoa SDK Version Compatibility Table. - pod("Sentry") { - version = "~> 8.25" - linkOnly = true - extraOpts += listOf("-compiler-option", "-fmodules") - } - framework { - baseName = "shared" - export("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}") - } -} -``` - -### Swift Package Manager +If you have Apple targets, you also need to export the framework: ```kotlin {filename:shared/build.gradle.kts} listOf( - iosX64(), iosArm64(), iosSimulatorArm64() ).forEach { diff --git a/docs/platforms/kotlin/guides/kotlin-multiplatform/user-feedback/index.mdx b/docs/platforms/kotlin/guides/kotlin-multiplatform/user-feedback/index.mdx index 7fb9780c2313a..4fbde842891df 100644 --- a/docs/platforms/kotlin/guides/kotlin-multiplatform/user-feedback/index.mdx +++ b/docs/platforms/kotlin/guides/kotlin-multiplatform/user-feedback/index.mdx @@ -12,3 +12,9 @@ When a user experiences an error, Sentry provides the ability to collect additio The user feedback API allows you to collect user feedback while utilizing your own UI. You can use the same programming language you have in your app to send user feedback. In this case, the SDK creates the HTTP request so you don't have to deal with posting data via HTTP. + + + +Starting with version `0.28.0`, on Apple platforms, the SDK sends user feedback as a separate feedback event with its own event ID, which is linked to the original event. The API is the same on all platforms. + + diff --git a/platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx b/platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx index 7bf6dbf15ac4f..2ddadf7dfbad0 100644 --- a/platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx +++ b/platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx @@ -8,14 +8,20 @@ plugins { The plugin does the following: -- Automatically installs the Sentry KMP dependency to `commonMain`. -- If you use the Kotlin Cocoapods plugin, it installs the Sentry Cocoa dependency. -- If you use Swift Package Manager, it sets up linking to the Sentry Cocoa framework. +- Automatically installs the Sentry KMP dependency to `commonMain`. +- Installs the Sentry Cocoa dependency for Apple targets with Swift Package Manager (SwiftPM), using Kotlin's official SwiftPM import on Kotlin 2.4 and newer, or the [spm4Kmp](https://github.com/frankois944/spm4Kmp) plugin if you've applied it. +- If you added Sentry Cocoa to your Xcode project yourself, it sets up linking to the Sentry Cocoa framework. -If you use Swift Package Manager instead of Cocoapods, you need to install the [Sentry Cocoa dependency with Swift Package Manager](/platforms/apple/install/swift-package-manager/) in your Xcode project first before executing the Gradle plugin. +If you use Kotlin's official SwiftPM import, run Kotlin's one-time [Xcode linkage package setup](https://kotlinlang.org/docs/multiplatform/multiplatform-spm-import.html#run-the-swiftpm-integration-task) so Xcode links Sentry Cocoa into your app. -Make sure that you install the Sentry Cocoa SDK version compatible with the corresponding Sentry Kotlin Multiplatform SDK version. You can find the compatible versions in the [Sentry Kotlin Multiplatform SDK README](https://github.com/getsentry/sentry-kotlin-multiplatform?tab=readme-ov-file#cocoa-sdk-version-compatibility-table). +If you use spm4Kmp, apply the Sentry Gradle plugin before spm4Kmp in the `plugins` block. + + + + + +Starting with version `0.28.0`, the SDK requires iOS 15, tvOS 15, macOS 12, or watchOS 9 or newer, and no longer supports installing Sentry Cocoa with CocoaPods. Learn more in the [CocoaPods migration guide](/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle/#migrate-from-cocoapods). diff --git a/platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx b/platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx index b3671f4dcb7fe..9519effd7f94a 100644 --- a/platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx +++ b/platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx @@ -8,14 +8,20 @@ plugins { The plugin does the following: -- Automatically installs the Sentry KMP dependency to `commonMain`. -- If you use the Kotlin Cocoapods plugin, it installs the Sentry Cocoa dependency. -- If you use Swift Package Manager, it sets up linking to the Sentry Cocoa framework. +- Automatically installs the Sentry KMP dependency to `commonMain`. +- Installs the Sentry Cocoa dependency for Apple targets with Swift Package Manager (SwiftPM), using Kotlin's official SwiftPM import on Kotlin 2.4 and newer, or the [spm4Kmp](https://github.com/frankois944/spm4Kmp) plugin if you've applied it. +- If you added Sentry Cocoa to your Xcode project yourself, it sets up linking to the Sentry Cocoa framework. -If you use Swift Package Manager instead of Cocoapods, you need to install the [Sentry Cocoa dependency with Swift Package Manager](/platforms/apple/install/swift-package-manager/) in your Xcode project first before executing the Gradle plugin. +If you use Kotlin's official SwiftPM import, run Kotlin's one-time [Xcode linkage package setup](https://kotlinlang.org/docs/multiplatform/multiplatform-spm-import.html#run-the-swiftpm-integration-task) so Xcode links Sentry Cocoa into your app. -Make sure that you install the Sentry Cocoa SDK version compatible with the corresponding Sentry Kotlin Multiplatform SDK version. You can find the compatible versions in the [Sentry Kotlin Multiplatform SDK README](https://github.com/getsentry/sentry-kotlin-multiplatform?tab=readme-ov-file#cocoa-sdk-version-compatibility-table). +If you use spm4Kmp, apply the Sentry Gradle plugin before spm4Kmp in the `plugins` block. + + + + + +Starting with version `0.28.0`, the SDK requires iOS 15, tvOS 15, macOS 12, or watchOS 9 or newer, and no longer supports installing Sentry Cocoa with CocoaPods. Learn more in the CocoaPods migration guide. From 995dddbbce5e0003ec44dcb982717c18a0b89566 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 9 Oct 2026 10:08:45 +0200 Subject: [PATCH 2/4] docs(kmp): Address review feedback on 0.28.0 docs Clarify that strictTraceContinuation still continues a trace when both organization IDs are missing, and that the option has no effect on Apple. Tell readers who added Sentry Cocoa in Xcode to set the Apple provider to NONE so the plugin doesn't install it twice. Co-Authored-By: Claude Co-authored-by: Cursor --- .../guides/kotlin-multiplatform/configuration/options.mdx | 4 +++- .../getting-started-install/kotlin.compose-multiplatform.mdx | 2 +- .../getting-started-install/kotlin.kotlin-multiplatform.mdx | 2 +- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/options.mdx b/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/options.mdx index 54e5c05ca8c92..48e031e950110 100644 --- a/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/options.mdx +++ b/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/options.mdx @@ -167,12 +167,14 @@ Controls whether the native SDKs on Apple, Android, and JVM attach a W3C `tracep -If set to `true`, the native SDKs on Apple, Android, and JVM only continue an incoming trace if the organization ID in the incoming `baggage` header matches the organization ID of the current Sentry client. If either organization ID is missing, the SDK starts a new trace. +If set to `true`, the SDK only continues an incoming trace if the organization ID in the incoming `baggage` header matches the organization ID of the current Sentry client. If only one of the two organization IDs is missing, the SDK starts a new trace. If both are missing, the SDK still continues the trace. If set to `false`, the SDK tolerates missing organization IDs, but still starts a new trace if both organization IDs are present and different. The client's organization ID is extracted from the DSN or can be set with the option. This is useful to prevent traces of unknown third-party services from being continued in your application. +This option applies to incoming traces handled by the Android and JVM SDKs. On Apple platforms, the SDK passes the option to the Sentry Cocoa SDK, which doesn't continue incoming traces automatically, so the option has no effect there. + diff --git a/platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx b/platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx index 2ddadf7dfbad0..cee1c7e4a14a8 100644 --- a/platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx +++ b/platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx @@ -10,7 +10,7 @@ The plugin does the following: - Automatically installs the Sentry KMP dependency to `commonMain`. - Installs the Sentry Cocoa dependency for Apple targets with Swift Package Manager (SwiftPM), using Kotlin's official SwiftPM import on Kotlin 2.4 and newer, or the [spm4Kmp](https://github.com/frankois944/spm4Kmp) plugin if you've applied it. -- If you added Sentry Cocoa to your Xcode project yourself, it sets up linking to the Sentry Cocoa framework. +- If you added Sentry Cocoa to your Xcode project yourself, set the Apple provider to `NONE` to avoid installing it twice. The plugin then links your existing framework. Learn more in [Install the Sentry Cocoa SDK Yourself](/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle/#install-the-sentry-cocoa-sdk-yourself). diff --git a/platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx b/platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx index 9519effd7f94a..204adf1dffd44 100644 --- a/platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx +++ b/platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx @@ -10,7 +10,7 @@ The plugin does the following: - Automatically installs the Sentry KMP dependency to `commonMain`. - Installs the Sentry Cocoa dependency for Apple targets with Swift Package Manager (SwiftPM), using Kotlin's official SwiftPM import on Kotlin 2.4 and newer, or the [spm4Kmp](https://github.com/frankois944/spm4Kmp) plugin if you've applied it. -- If you added Sentry Cocoa to your Xcode project yourself, it sets up linking to the Sentry Cocoa framework. +- If you added Sentry Cocoa to your Xcode project yourself, set the Apple provider to `NONE` to avoid installing it twice. The plugin then links your existing framework. Learn more in [Install the Sentry Cocoa SDK Yourself](/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle/#install-the-sentry-cocoa-sdk-yourself). From 9e42b4c90160656cbb0cdd79055fe0df76b4b118 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 9 Oct 2026 10:26:08 +0200 Subject: [PATCH 3/4] docs(kmp): Raise version fallbacks to 0.28.0 Co-Authored-By: Claude Co-authored-by: Cursor --- .../guides/kotlin-multiplatform/configuration/gradle.mdx | 6 +++--- .../kotlin.compose-multiplatform.mdx | 2 +- .../getting-started-install/kotlin.kotlin-multiplatform.mdx | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle.mdx b/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle.mdx index bc98351136630..fef499e517584 100644 --- a/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle.mdx +++ b/docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle.mdx @@ -20,7 +20,7 @@ Using Gradle in your `shared/build.gradle.kts` add: ```kotlin {filename:shared/build.gradle.kts} plugins { - id("io.sentry.kotlin.multiplatform.gradle") version "{{@inject packages.version('sentry.kotlin.kmp.gradle-plugin', '0.9.0') }}" + id("io.sentry.kotlin.multiplatform.gradle") version "{{@inject packages.version('sentry.kotlin.kmp.gradle-plugin', '0.28.0') }}" } ``` @@ -50,7 +50,7 @@ sentryKmp { // Specify the version of the Sentry Kotlin Multiplatform SDK to use. // Default is the corresponding Kotlin Multiplatform SDK version. - sentryKmpVersion = "{{@inject packages.version('sentry.kotlin.kmp', '0.9.0') }}" + sentryKmpVersion = "{{@inject packages.version('sentry.kotlin.kmp', '0.28.0') }}" } // Configure auto-installation of the Sentry Cocoa SDK for Apple targets. @@ -113,7 +113,7 @@ If you apply the [spm4Kmp](https://github.com/frankois944/spm4Kmp) plugin (`io.g ```kotlin {filename:shared/build.gradle.kts} plugins { kotlin("multiplatform") - id("io.sentry.kotlin.multiplatform.gradle") version "{{@inject packages.version('sentry.kotlin.kmp.gradle-plugin', '0.9.0') }}" + id("io.sentry.kotlin.multiplatform.gradle") version "{{@inject packages.version('sentry.kotlin.kmp.gradle-plugin', '0.28.0') }}" id("io.github.frankois944.spmForKmp") } ``` diff --git a/platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx b/platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx index cee1c7e4a14a8..a88378a7fc662 100644 --- a/platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx +++ b/platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx @@ -2,7 +2,7 @@ To install the Kotlin Multiplatform SDK in your Compose Multiplatform project, y ```kotlin {filename:composeApp/build.gradle.kts} plugins { - id("io.sentry.kotlin.multiplatform.gradle") version "{{@inject packages.version('sentry.kotlin.kmp.gradle-plugin', '0.9.0') }}" + id("io.sentry.kotlin.multiplatform.gradle") version "{{@inject packages.version('sentry.kotlin.kmp.gradle-plugin', '0.28.0') }}" } ``` diff --git a/platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx b/platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx index 204adf1dffd44..50beabf3bb97e 100644 --- a/platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx +++ b/platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx @@ -2,7 +2,7 @@ To install the Kotlin Multiplatform SDK, you need to add the following to your ` ```kotlin {filename:shared/build.gradle.kts} plugins { - id("io.sentry.kotlin.multiplatform.gradle") version "{{@inject packages.version('sentry.kotlin.kmp.gradle-plugin', '0.9.0') }}" + id("io.sentry.kotlin.multiplatform.gradle") version "{{@inject packages.version('sentry.kotlin.kmp.gradle-plugin', '0.28.0') }}" } ``` From de3316e8d2db0d169bf18582a0f20ec585e36475 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 9 Oct 2026 10:36:17 +0200 Subject: [PATCH 4/4] docs(kmp): Raise remaining version fallbacks to 0.28.0 Co-Authored-By: Claude Co-authored-by: Cursor --- .../kotlin/guides/kotlin-multiplatform/manual-setup/index.mdx | 2 +- .../kotlin/guides/kotlin-multiplatform/native-access-sdk.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/kotlin/guides/kotlin-multiplatform/manual-setup/index.mdx b/docs/platforms/kotlin/guides/kotlin-multiplatform/manual-setup/index.mdx index ccca5022344e1..5c4c38a37c82a 100644 --- a/docs/platforms/kotlin/guides/kotlin-multiplatform/manual-setup/index.mdx +++ b/docs/platforms/kotlin/guides/kotlin-multiplatform/manual-setup/index.mdx @@ -25,7 +25,7 @@ kotlin { sourceSets { commonMain.dependencies { - implementation("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}") + implementation("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.28.0') }}") } } diff --git a/docs/platforms/kotlin/guides/kotlin-multiplatform/native-access-sdk.mdx b/docs/platforms/kotlin/guides/kotlin-multiplatform/native-access-sdk.mdx index f2a1333430e14..6d959f0bb8490 100644 --- a/docs/platforms/kotlin/guides/kotlin-multiplatform/native-access-sdk.mdx +++ b/docs/platforms/kotlin/guides/kotlin-multiplatform/native-access-sdk.mdx @@ -9,7 +9,7 @@ If you need to access the SDK directly in your native platform without the share ```kotlin {filename:shared/build.gradle.kts} val commonMain by getting { dependencies { - api("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}") + api("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.28.0') }}") } } ``` @@ -26,7 +26,7 @@ listOf( it.binaries.framework { baseName = "shared" isStatic = true - export("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}") + export("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.28.0') }}") } } ```