Integrate Luciq on KMP

Add the Luciq KMP library to your Kotlin Multiplatform project for Android and iOS, either with an AI coding agent or by wiring the dependency by hand.

Get started in seconds

Option 1 — Set up with an AI coding agent (recommended)

In your AI editor, paste:

Set up Luciq SDK in this project in one shot!
1. Install the Luciq agent skills: `npx luciq-skills install`
2. Setup and authenticate Luciq MCP server to this project
3. Add the Luciq SDK to this project

Check the skills and MCP docs for more details.

Option 2 — Install manually

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

Automatic Approach (Luciq KMP Gradle Plugin)

The Luciq KMP Gradle plugin handles all platform-specific dependency wiring automatically for Kotlin Multiplatform projects.

To install the Kotlin Multiplatform SDK, you need to add the following to your build.gradle.kts file in your shared module:

shared/build.gradle.kts

plugins {                                                                                                                                                                
      id("ai.luciq.kmp") version "0.0.9"                                                                                                                                  
  }

The plugin automatically:

• Adds the ai.luciq.library:luciq-kmp dependency to commonMain.
• Exports Luciq KMP types from iOS framework binaries so they are visible in Swift/ObjC.
• Configures the iOS native SDK via one of two paths:

  • CocoaPods: If the Kotlin CocoaPods plugin is applied, it adds pod("Luciq") with the correct version and compiler options.
  • Swift Package Manager (SPM): it applies linker flags automatically.

iOS

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

Manual Approach

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

Each Luciq KMP release pins a specific native Luciq SDK / LuciqSDK pod version. Use the table below to match the Luciq KMP version with the required pod version:

Luciq KMP Version	Required Luciq Pod Version
0.0.9	19.7.0
0.0.8	19.5.0
0.0.7	19.5.0
0.0.6	19.5.0
0.0.5	19.5.0
0.0.4	19.5.0
0.0.2	19.3.0

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.