Integrate Luciq on KMP

This page covers how to install the Luciq KMP library in your Kotlin Multiplatform project for Android and iOS.

Installation

This installation process adds the Luciq KMP library that supports Bug Reporting, Crash Reporting, and App Performance Monitoring from shared Kotlin code.

1

Add the dependency

Gradle (Android & shared code)

In your Kotlin Multiplatform module, add the library to commonMain so it is available on all targets. The same artifact resolves to the correct variant for each platform:

Kotlin (build.gradle.kts)

    sourceSets {
        commonMain.dependencies {
            api("ai.luciq-library:luciq-kmp:x.x.x")
        }
}

Use the latest version from Maven Central

iOS

In your iOS App project add LuciqKMP dependency. See our iOS integration guide for instructions.Luciq iOS SDK

2

Initialize the SDK

Import Luciq in your code

We recommend placing your Luciq configuration code in a shared module and invoking it from the platform-specific initialization logic within each of your Kotlin Multiplatform applications.

In your commonMain Kotlin code:

Kotlin (Shared.kt)

import ai.luciq.kmp.modules.LuciqKmp
import ai.luciq.kmp.utils.InvocationEvents

object LuciqDefaults {
    const val APP_TOKEN = "APP_TOKEN"
    val invocationEvents = listOf(InvocationEvents.FloatingButton)
    val logLevel = LogLevel.Debug
   val appVariant:String? = null
}

fun initializeLuciq(configuration: LuciqConfiguration) {
   LuciqKmp.init(configuration)
}

Android

You need an Application instance and at least one invocation event:

Kotlin

val configuration = LuciqConfiguration(
    androidApplication = application,
    token = LuciqDefaults.APP_TOKEN,
    invocationEvents = LuciqDefaults.invocationEvents,
    logLevel = LuciqDefaults.logLevel,
    appVariant = LuciqDefaults.appVariant
)
Shared.initializeLuciq(configuration)

iOS

On iOS, LuciqConfiguration does not take an application parameter:

App.swift

val configuration = LuciqConfiguration(
   token: LuciqDefaults.shared.APP_TOKEN,
    invocationEvents: LuciqDefaults.shared.invocationEvents,
    logLevel: LuciqDefaults.shared.logLevel,
    appVariant: LuciqDefaults.shared.appVariant
)
Shared.initializeLuciq(configuration)

Replace APP_TOKEN with your application token from the Luciq dashboard (Settings → SDK Integration).

Initialize the SDK as early as possible in your app lifecycle (e.g. in Application.onCreate on Android or application(_:didFinishLaunchingWithOptions:) on iOS).

Configuration options

Parameter	Android	iOS	Description
token	✓	✓	Your app token (required).
invocationEvents	✓	✓	How the SDK is invoked (e.g. shake, screenshot, floating button).
logLevel	✓	✓	SDK debug log level (e.g. LogLevel.Debug).
appVariant	✓	✓	App variant (e.g. "beta", "production").
androidApplication	✓	-	Android Application instance (required on Android).
ignoreAndroidSecureFlag	✓	-	Whether to ignore FLAG_SECURE for screenshots.

Managing permissions

Permissions are required for attachments (images, videos, audio) and some invocation methods. The native Luciq SDK may add or require permissions on each platform.

Android

Relevant permissions (e.g. storage, microphone) are typically declared by the native Luciq SDK. You can remove any you do not need. If you use Screenshot as an invocation event, storage permission may be requested at launch.

iOS

Add usage descriptions to your Info.plist as required by the native SDK, for example:

• NSMicrophoneUsageDescription – for voice notes

• NSPhotoLibraryUsageDescription – for image attachments

Permission prompts appear when the user tries to use a feature that needs them (e.g. attaching a photo or recording audio).

Jetpack Compose (Android)

If your Android app uses Jetpack Compose, integrate the native Luciq Compose libraries so the SDK can track Compose screens, user interactions, and screen loading for APM. See Jetpack Compose Integration.

SwiftUI (iOS)

If your iOS app uses SwiftUI, use the native Luciq SwiftUI APIs so the SDK can track SwiftUI views and measure screen loading for APM. See Integrate SwiftUI.