feat(kmp): add new init strategy & update versions (#10078)

* Update kotlin-multiplatform.mdx

* Add init strategies and update index.mdx

* Apply suggestions from code review

Co-authored-by: vivianyentran <20403606+vivianyentran@users.noreply.github.com>

---------

Co-authored-by: vivianyentran <20403606+vivianyentran@users.noreply.github.com>

Author: buenaflor

docs/platforms/kotlin-multiplatform/initialization-strategies.mdx

@@ -4,36 +4,17 @@ description: "Strategies for initializing the Kotlin Multiplatform SDK."
 sidebar_order: 3
 ---
 
-When it comes to initializing a Kotlin Multiplatform SDK, there are three strategies to consider:
+When it comes to initializing a Kotlin Multiplatform SDK, there are multiple strategies to consider:
 
+- [Use native platform options directly](#native-platform-options)
 - [Shared initializer](#shared-initializer)
 - [Platform specific initializers](#platform-specific-initializers)
 - [Hybrid approach](#hybrid-approach)
 
-## Shared Initializer
-
-The shared initializer approach involves initializing the SDK in your shared codebase, using the same configuration options for all platforms. This approach is ideal for projects that prioritize consistency across platforms and do not require platform-specific customizations.
+## Where to Place Initialization Code
 
-Using a shared initializer provides a single source of truth for your SDK's configuration options. This can simplify maintenance and debugging efforts, as you only need to update one codebase for all platforms.
-
-To initialize the SDK, create a Kotlin file in your `commonMain` e.g. `AppSetup.kt`, (or whatever you decide to call it), and create an initialization function. You'll then be able to call it in an early lifecycle stage in your platforms.
-
-<SignInNote />
-
-```kotlin {filename:AppSetup.kt}
-import io.sentry.kotlin.multiplatform.Sentry
-
-// Application context is only needed for Android targets
-fun initializeSentry() {
-  val configuration: (SentryOptions) -> Unit = {
-    it.dsn = "___PUBLIC_DSN___"
-    // Add common configuration here
-  }
-  Sentry.init(configuration)
-}
-```
-
-Now you can use that shared function to initialize the SDK.
+Regardless of the initialization strategy you choose, it's important to place the initialization code at an early lifecycle stage of your application to ensure the SDK is set up correctly before it is used.
+Here are general guidelines for placing the initialization code for different platforms:
 
 ### Android
 
@@ -62,11 +43,89 @@ func application(
 }
 ```
 
+## Native Platform Options
+
+<Note>
+Requires Sentry SDK version `0.7.1` or higher.
+</Note>
+
+This approach involves initializing the SDK with the platform's specific options directly, using `PlatformOptionsConfiguration`. This strategy is ideal for projects that require configuring options that are not yet supported by the KMP SDK, such as experimental options.
+For example, if you configure your KMP application for Android, you will have access to every option that the Android SDK provides.
+
+### Apple Target Requirements
+
+In order to be able to use the native platform options with Apple targets, you need to opt-in to `ExperimentalForeignApi`.
+
+```kotlin {filename:build.gradle.kts}
+kotlin {
+    // other configuration ...
+  sourceSets {
+    all {
+        languageSettings.optIn("kotlinx.cinterop.ExperimentalForeignApi")
+    }
+  }
+}
+```
+
+### Usage
+
+```kotlin {filename:SentrySetup.kt}{tabTitle: commonMain}
+import io.sentry.kotlin.multiplatform.Sentry
+import io.sentry.kotlin.multiplatform.PlatformOptionsConfiguration
+
+fun initializeSentry() {
+  Sentry.initWithPlatformOptions(platformOptionsConfiguration())
+}
+
+expect fun platformOptionsConfiguration(): PlatformOptionsConfiguration
+```
+
+```kotlin {filename:SentrySetup.ios.kt}{tabTitle: iosMain}
+import io.sentry.kotlin.multiplatform.PlatformOptionsConfiguration
+
+actual fun platformOptionsConfiguration(): PlatformOptionsConfiguration = {
+    it.dsn = "___PUBLIC_DSN___"
+}
+```
+
+```kotlin {filename:SentrySetup.android.kt}{tabTitle: androidMain}
+import io.sentry.kotlin.multiplatform.PlatformOptionsConfiguration
+
+actual fun platformOptionsConfiguration(): PlatformOptionsConfiguration = {
+    it.dsn = "___PUBLIC_DSN___"
+}
+```
+
+## Shared Initializer
+
+The shared initializer approach involves initializing the SDK in your shared codebase, using the same configuration options for all platforms. This approach is ideal for projects that prioritize consistency across platforms and do not require platform-specific customizations.
+
+Using a shared initializer provides a single source of truth for your SDK's configuration options. This can simplify maintenance and debugging efforts, as you only need to update one codebase for all platforms.
+
+To initialize the SDK, create a Kotlin file in your `commonMain` (such as `AppSetup.kt` or whatever you decide to call it), and write an initialization function. You'll then be able to call it in an early lifecycle stage in your platforms.
+
+<SignInNote />
+
+```kotlin {filename:AppSetup.kt}
+import io.sentry.kotlin.multiplatform.Sentry
+
+// Application context is only needed for Android targets
+fun initializeSentry() {
+  val configuration: (SentryOptions) -> Unit = {
+    it.dsn = "___PUBLIC_DSN___"
+    // Add common configuration here
+  }
+  Sentry.init(configuration)
+}
+```
+
 ## Platform-Specific Initializers
 
 Platform-specific initializers allow for customization of the SDK's configuration options on a per-platform basis. This approach can be particularly useful when your SDK requires platform-specific functionality or performance optimizations.
 
 This approach gives you the flexibility to fine-tune the SDK's behavior to meet the unique needs of each platform.
+However, the available options are limited to what the KMP SDK has implemented.
+If you need to use the respective platform's options directly, you should use the [native platform options](#native-platform-options) approach.
 
 ### Common
 
@@ -108,37 +167,8 @@ actual fun initializeSentry() {
 }
 ```
 
-Now you can use that shared function to initialize the SDK.
-
-### Android
-
-```kotlin {filename:MainActivity.kt}
-import your.kmp.app.initializeSentry
-
-class YourApplication : Application() {
-  override fun onCreate() {
-    super.onCreate()
-      initializeSentry()
-   }
-}
-```
-
-### iOS
-
-```swift {filename:AppDelegate.swift}
-import shared
-
-func application(
-    _ application: UIApplication,
-    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
-) -> Bool {
-    AppSetupKt.initializeSentry()
-    return true
-}
-```
-
 ## Hybrid Approach
 
-It's also possible to mix the two initialization strategies by creating [intermediate sourceSets](https://kotlinlang.org/docs/multiplatform-hierarchy.html) that only target specific platforms. This allows you to use a shared initializer for some platforms while utilizing platform-specific initializers for others.
+It's also possible to mix the initialization strategies by creating [intermediate sourceSets](https://kotlinlang.org/docs/multiplatform-hierarchy.html) that target specific platforms. This allows you to use a shared initializer for some platforms, while utilizing platform-specific initializers for others.
 
-For example, you may choose to use a shared initializer for Android and iOS platforms, while using a platform-specific initializer for the watchOS and tvOS platform. This approach provides a balance between consistency and customization.
+For example, you may choose to use a shared initializer for Android and iOS platforms, while using a platform-specific initializer for the watchOS and tvOS platforms. This approach provides a balance between consistency and customization.

docs/platforms/kotlin-multiplatform/native-access-sdk.mdx

@@ -29,6 +29,7 @@ cocoapods {
   // 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 {

platform-includes/getting-started-install/kotlin-multiplatform.mdx

@@ -39,6 +39,7 @@ kotlin {
     // 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 {

platform-includes/getting-started-primer/kotlin-multiplatform.mdx

@@ -18,9 +18,9 @@ Use the Kotlin Multiplatform and Cocoa SDK combinations listed in the table belo
 | Up to 0.3.0                      | 8.4.0             |
 | 0.4.0                            | 8.17.2            |
 | 0.5.0                            | 8.21.0            |
-| 0.6.0                            | 8.25.0            |
+| >= 0.6.0                         | ~> 8.25           |
 
 <Note>
-Starting May 1, 2024, Apple requires all apps submitted to the App Store to provide a list of privacy-related APIs they use. Use Sentry Cocoa SDK version `8.25.0` to ensure compliance with these requirements.
+Starting May 1, 2024, Apple requires all apps submitted to the App Store to provide a list of privacy-related APIs they use. Use Sentry Cocoa SDK version `8.25.0` or higher to ensure compliance with these requirements.
 Follow our [Apple Privacy Manifest](/platforms/kotlin-multiplatform/data-management/apple-privacy-manifest) guide to learn more.
 </Note>