Kotlin Multiplatform SDK Integration Guide for Klaritics

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.

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.

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:

settings.gradle.kts

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") }
    }
}

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

Add the dependency

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

shared/build.gradle.kts

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:

shared/src/commonMain/kotlin/Analytics.kt

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:

MyApp.kt

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        initAnalytics(KlariticsContext(this)) // Application is required on Android
    }
}

Calling the no-arg KlariticsContext() on Android throws IllegalStateException. Always pass the Application.

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.

Emit a framework from your shared module

shared/build.gradle.kts

kotlin {
    listOf(iosArm64(), iosSimulatorArm64(), iosX64()).forEach {
        it.binaries.framework { baseName = "Shared" }
    }
}

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.

Initialize from Swift

In your AppDelegate, call the shared entry point. The iOS context is an empty marker:

AppDelegate.swift

import Shared

Analytics_iosKt.initAnalytics(context: KlariticsContext()) // iOS context is empty

API reference

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

import com.klaritics.kmp.Klaritics

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.

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?`	✅

“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.

Common recipes

Log events

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

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) 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.

Next steps

Verify your integration

Send test events from your app and watch them land on the Getting Started page.

Event and attribute naming

Learn the naming conventions Klaritics expects for events and attributes.

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

Get Started

User Management

Analysis

Dashboards

Widgets

Data

Templates

Alerts & Integrations

SDK Integration

Deployment

Reference

Sdk

Kotlin Multiplatform SDK Integration Guide for Klaritics

Requirements

Add repositories

Add the dependency

Initialize the SDK

`KlariticsConfig`

Android setup

iOS setup

API reference

Common recipes

Log events

Identify a user and set properties

Platform parity notes

Troubleshooting

Next steps

Verify your integration

Event and attribute naming

​Requirements

​Add repositories

​Add the dependency

​Initialize the SDK

​KlariticsConfig

​Android setup

​iOS setup

​API reference

​Common recipes

​Log events

​Identify a user and set properties

​Platform parity notes

​Troubleshooting

​Next steps

Verify your integration

Event and attribute naming

Requirements

Add repositories

Add the dependency

Initialize the SDK

`KlariticsConfig`

Android setup

iOS setup

API reference

Common recipes

Log events

Identify a user and set properties

Platform parity notes

Troubleshooting

Next steps