> ## Documentation Index
> Fetch the complete documentation index at: https://guides.klaritics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kotlin Multiplatform SDK Integration Guide for Klaritics

> Integrate the Klaritics Kotlin Multiplatform SDK once in shared Kotlin and ship analytics to both Android and iOS from one API.

The Klaritics Kotlin Multiplatform (KMP) SDK is a thin wrapper that delegates to the native Klaritics Android and iOS SDKs, so you get native batching, queueing, and session handling behind a single Kotlin API. Write your integration once in shared Kotlin; the only platform-specific line is the context you pass at setup.

**Artifact:** `com.deeptaai.klaritics:klaritics-kmp:1.0.0`

## Requirements

| Requirement           | Value                                            |
| --------------------- | ------------------------------------------------ |
| Kotlin                | 2.4.0 or newer (SDK is built with Kotlin 2.4.10) |
| Android `minSdk`      | 21+                                              |
| iOS deployment target | 13.0+                                            |
| Xcode (for iOS)       | 15+                                              |

You need an **App ID** and a **Host URL** from the Klaritics dashboard.

<Warning>
  Kotlin compatibility matters. A Kotlin/Native klib can only be consumed by an equal-or-newer Kotlin compiler. If your app is on Kotlin \< 2.4, upgrade the app's Kotlin *before* adding this dependency.
</Warning>

## Add repositories

The SDK and its native Android dependency live in two public GCP Artifact Registry Maven repos. Both allow anonymous read, so no credentials are required. Add both to your app's `settings.gradle.kts`:

```kotlin settings.gradle.kts theme={null}
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()

        // Klaritics KMP SDK
        maven { url = uri("https://asia-south1-maven.pkg.dev/org-infra-471907/klaritics-kmp-sdk") }

        // Native Klaritics Android SDK (pulled transitively on the Android target)
        maven { url = uri("https://asia-south1-maven.pkg.dev/org-infra-471907/klaritics-android-sdk") }
    }
}
```

<Note>
  Repositories are **not** transitive. Even though the native Android SDK is a transitive dependency, your app must declare its repo explicitly.
</Note>

## Add the dependency

Add it once to your shared module's `commonMain`, not per platform:

```kotlin shared/build.gradle.kts theme={null}
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.deeptaai.klaritics:klaritics-kmp:1.0.0")
        }
    }
}
```

Gradle Module Metadata selects the correct variant per target automatically (`-android`, `-iosarm64`, `-iosx64`, `-iossimulatorarm64`).

## Initialize the SDK

Call `Klaritics.setup(config, context)` once at app startup, before any other Klaritics call. The config is identical on both platforms; only the context differs.

Expose a small entry point from your shared module so each platform passes its own context:

```kotlin shared/src/commonMain/kotlin/Analytics.kt theme={null}
import com.klaritics.kmp.Klaritics
import com.klaritics.kmp.KlariticsConfig
import com.klaritics.kmp.KlariticsContext

fun initAnalytics(context: KlariticsContext) {
    Klaritics.setup(
        KlariticsConfig(
            appId = "YOUR_PROJECT_ID",
            host = "https://server.example.klaritics.com", // no trailing slash
        ),
        context,
    )
}
```

### `KlariticsConfig`

| Property | Type      | Default      | Description                                                               |
| -------- | --------- | ------------ | ------------------------------------------------------------------------- |
| `appId`  | `String`  | — (required) | Your `project_id` from the Klaritics dashboard (Getting Started page).    |
| `host`   | `String`  | — (required) | Server URL to send data to, no trailing slash.                            |
| `debug`  | `Boolean` | `false`      | Verbose native debug logging. **Android only** (ignored on iOS v1.0.0).   |
| `optOut` | `Boolean` | `false`      | Start with analytics opted out. **Android only** (ignored on iOS v1.0.0). |

## Android setup

Nothing beyond the repositories is needed; the native `klaritics-android-sdk` AAR is pulled transitively. Android requires the `Application` context:

```kotlin MyApp.kt theme={null}
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        initAnalytics(KlariticsContext(this)) // Application is required on Android
    }
}
```

<Warning>
  Calling the no-arg `KlariticsContext()` on Android throws `IllegalStateException`. Always pass the `Application`.
</Warning>

## iOS setup

The SDK links the native Klaritics framework via Kotlin's SwiftPM integration, which pulls the Klaritics Swift package (binary xcframework) from `github.com/deeptaai/klaritics-ios-sdk` at version `1.0.0`. The framework linkage propagates to your build automatically. CocoaPods is not required and you add no `-framework` flags yourself.

<Steps>
  <Step title="Emit a framework from your shared module">
    ```kotlin shared/build.gradle.kts theme={null}
    kotlin {
        listOf(iosArm64(), iosSimulatorArm64(), iosX64()).forEach {
            it.binaries.framework { baseName = "Shared" }
        }
    }
    ```
  </Step>

  <Step title="Add the generated SwiftPM linkage package to Xcode">
    Building for an iOS target generates a SwiftPM linkage package (`KotlinMultiplatformLinkedPackage`) that includes the transitive Klaritics dependency. Add that package to your Xcode app project using Kotlin's direct SwiftPM integration. This resolves the Klaritics symbols.
  </Step>

  <Step title="Initialize from Swift">
    In your `AppDelegate`, call the shared entry point. The iOS context is an empty marker:

    ```swift AppDelegate.swift theme={null}
    import Shared

    Analytics_iosKt.initAnalytics(context: KlariticsContext()) // iOS context is empty
    ```
  </Step>
</Steps>

## API reference

All methods are called on the `Klaritics` object (`com.klaritics.kmp.Klaritics`) from shared code.

```kotlin theme={null}
import com.klaritics.kmp.Klaritics
```

<Note>
  Attributes are `Map<String, Any?>`. Entries with `null` values are **dropped** before dispatch, so both platforms send the same shape. A map that becomes empty is treated as no attributes.
</Note>

| Method                 | Signature                                                    | iOS (v1.0.0) |
| ---------------------- | ------------------------------------------------------------ | ------------ |
| `setup`                | `(config: KlariticsConfig, context: KlariticsContext)`       | ✅            |
| `logAppEvent`          | `(eventName: String, attributes: Map<String, Any?>? = null)` | ✅            |
| `logAggregateEvent`    | `(eventName: String, attributes: Map<String, Any?>? = null)` | ✅            |
| `logClientEvent`       | `(eventName: String, attributes: Map<String, Any?>? = null)` | ✅            |
| `setUserIdentifier`    | `(userIdentifier: String)`                                   | ✅            |
| `setUserCustomInfo`    | `(userCustomInfo: Map<String, Any?>)`                        | ✅            |
| `setSessionCustomInfo` | `(attributes: Map<String, Any?>)`                            | ✅            |
| `trackScreen`          | `(screenName: String)`                                       | ✅            |
| `logRedirectionEvent`  | `(url: String)`                                              | ✅            |
| `reportCustomError`    | `(key: String, errorInfo: Map<String, String>? = null)`      | ✅            |
| `getDeviceId`          | `(): String?`                                                | ✅            |

<Tip>
  "No-op" on iOS means the method is safe to call but does nothing; the native iOS SDK v1.0.0 doesn't expose it. See [Platform parity notes](#platform-parity-notes).
</Tip>

## Common recipes

### Log events

```kotlin theme={null}
Klaritics.logAppEvent("button_clicked", mapOf("button_name" to "submit"))

// Aggregate events are counted/batched server-side rather than stored individually
Klaritics.logAggregateEvent("purchase_completed", mapOf("value" to 1299))

// Client-side event
Klaritics.logClientEvent("soft_back_pressed", mapOf("screen" to "Home"))
```

### Identify a user and set properties

```kotlin theme={null}
Klaritics.setUserIdentifier("user_123")

Klaritics.setUserCustomInfo(mapOf(
    "email" to "user@example.com",
    "plan" to "pro",
))

// Session-scoped properties
Klaritics.setSessionCustomInfo(mapOf("network" to "4G"))
```

## Platform parity notes

The Klaritics iOS SDK v1.0.0 exposes a smaller public surface than Android. The following methods are **safe no-ops on iOS** (they run normally on Android):

* `logMetaEvent`
* `resetUserCustomInfo`
* `resetSessionCustomInfo`
* `setCurrentScreenName`
* `setPushRegistrationToken`
* `setDynamicConfig`
* `flushEventsIfAny`
* `optOut`

Also, `KlariticsConfig.debug` and `KlariticsConfig.optOut` are honored on **Android only**.

You can call these from shared code without guards; they simply do nothing on iOS. Avoid relying on them for iOS-critical behavior until the native iOS SDK adds support.

## Troubleshooting

| Symptom                                                                     | Fix                                                                                                                                   |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `was compiled with an incompatible version of Kotlin` / klib metadata error | Your app is on Kotlin \< 2.4. Upgrade the app's Kotlin to 2.4.x.                                                                      |
| Android `klaritics-android-sdk` not found                                   | The native Android registry (second `maven {}` in [Add repositories](#add-repositories)) is missing. Repositories are not transitive. |
| iOS `Undefined symbols for Klaritics`                                       | The SwiftPM linkage package wasn't added to Xcode, or you're on an older SDK. Use `1.0.0`.                                            |
| `IllegalStateException: Android requires Application context`               | You called `KlariticsContext()` on Android. Use `KlariticsContext(application)`.                                                      |
| An iOS call "does nothing"                                                  | It's likely a no-op on iOS v1.0.0. See [Platform parity notes](#platform-parity-notes).                                               |

## Next steps

<CardGroup cols={2}>
  <Card title="Verify your integration" icon="circle-check" href="/sdk/overview#verify-your-integration">
    Send test events from your app and watch them land on the Getting Started page.
  </Card>

  <Card title="Event and attribute naming" icon="tag" href="/sdk/event-naming">
    Learn the naming conventions Klaritics expects for events and attributes.
  </Card>
</CardGroup>

***

**Artifact:** `com.deeptaai.klaritics:klaritics-kmp:1.0.0` · **Kotlin:** 2.4.0+ · **Targets:** Android (minSdk 21), iOS (13.0+) · **License:** MIT