Kotzilla SDK version upgrades

note

this page is intended to help you migrate between major SDK updates that might require to go over some breaking changes

From 2.2.x to 2.3.0

No breaking changes

2.3.0 is a drop‑in upgrade from 2.2.x. Bump the version, rebuild, and everything keeps working — the new features are opt‑in or backward‑compatible defaults.

Update the plugin/SDK version in your libs.versions.toml:

[versions]
kotzilla = "2.3.0"

What's new and worth knowing

Change	Default	Action
Automatic start (early start)	On	The SDK now boots at process start. Nothing to do — keep your monitoring() call. Opt out with kotzilla { earlyStart = false } (or per platform). See Automatic start.
Universal consent gate	Off	Enable with kotzilla { consentRequired = true } if you need user opt‑in before collecting data. See Privacy & user consent.
Startup tracing	On (Android)	Automatic cold/warm startup metric; add mark(...) calls to time your own phases.

Android backup rules (only if you enable consent)

If you set consentRequired = true and your app already declares android:dataExtractionRules or android:fullBackupContent, AGP will report a manifest‑merger conflict. Resolve it by adding <exclude domain="sharedpref" path="KotzillaPrefs.xml"/> to your backup rules. See Privacy & user consent.

Tested Compatibility

Dependency	2.2.x	2.3.0
Kotlin	2.2.0 – 2.3.x ¹	2.2.0 – 2.4.x ¹ (2.5+ accepted with a warning)
AGP	8.4.0 – 8.13.0	8.4.0 – 9.2.1
Gradle	8.6 – 9.3	8.6 – 9.6.0
Koin	4.0.4+	4.0.4+

¹ Compose projects require Kotlin 2.2.0+ (compiler-plugin instrumentation). Non-Compose JVM/Android projects still build on Kotlin 2.1.0+; iOS/JS/WASM require Kotlin 2.2.0+.

From 2.1.x to 2.2.x

Breaking changes

2.2.x requires Kotlin 2.2.0+ if you use Compose (see item 1 below). It is also not a drop-in upgrade if you tracked Compose navigation manually, or if your app is below compileSdk 35. Review the items below before upgrading.

1. Kotlin 2.2.0+ is required for Compose instrumentation

SDK 2.2.0+ requires your project to compile with Kotlin 2.2.0 or newer when the Kotzilla Gradle plugin instruments Compose (the default for any Compose module). On Kotlin 2.1.x / 2.0.x the build fails during Kotlin compilation with a compiler error like:

e: java.lang.NoSuchMethodError: 'java.util.List org.jetbrains.kotlin.ir.declarations.IrSimpleFunction.getParameters()'
    at io.kotzilla.gradle.kcp.DefaultPluginContextUtils...
    at io.kotzilla.gradle.kcp.ComposeNavHostExtension.generate(...)

This is the Kotzilla Kotlin compiler plugin using a Kotlin 2.2 compiler API — it is not an error in your code.

What to do (pick one).

1. Bump your Kotlin version to 2.2.0+ (recommended):

   [versions]
   kotlin = "2.2.0" # or newer

2. Stay on Kotlin 2.1.x and disable Compose instrumentation:

   kotzilla { composeInstrumentation = false }

   This skips the Kotlin compiler plugin entirely, so the SDK builds fine on Kotlin 2.1.x. You keep Koin tracking, crash reporting, lifecycle, and config generation — you only lose automatic Compose screen/navigation tracking. A good option if you want SDK 2.2.x/2.3.0 now but can't move your Kotlin version yet.

3. If you need Compose auto-tracking and can't move Kotlin, stay on SDK 2.1.5 (the last release whose compiler plugin supports Kotlin 2.1.x).

The runtime library and Gradle config generation always work on Kotlin 2.1.0+ — this requirement is specific to Compose auto-instrumentation.

Kotlin Multiplatform targets

KMP native/web targets (iOS, JS, WASM) already required Kotlin 2.2.0+ since the 2.1 line (klib metadata format), so this aligns the JVM/Android floor with the rest of the ecosystem when using Compose.

2. Manual Compose navigation tracking was removed

The manual navigation-tracking API is gone in 2.2.0. If your code calls any of these, it will fail to compile with Unresolved reference:

• NavigationViewTrackingEffect(navController, …)
• ComponentPredicate / AcceptAllNavDestinations

What to do. Delete the manual call and predicate plumbing — navigation is now tracked automatically as long as the Kotzilla Gradle plugin is applied in the module that owns the route code (composeInstrumentation = true, the default). For a screen that is not a navigation destination, use KotzillaTrackScreen("name"). See Android Compose setup.

// OLD (2.1.x) — remove this
NavigationViewTrackingEffect(navController, trackArguments = true)

// NEW (2.2.x+) — nothing to call; auto-instrumented.
// For a non-destination screen only:
KotzillaTrackScreen("Checkout")

Multi-module Compose

If your routes are compiled in feature modules, apply the Kotzilla plugin in the root build (or in each route-owning module) — applying it only in :app will miss those screens. See Plugin application.

3. compileSdk requirements

Android consumers now need compileSdk 35+. Navigation 3 projects need compileSdk 36 and minSdk 23.

Also worth knowing

• kotzilla.json is required for SDK-host modules (introduced on the 2.1 line) — a host with no reachable kotzilla.json fails the build early. Add it to the module that starts the SDK, or set kotzilla { enabled = false }.
• Manual setup APIs deprecated — setApiKey(String), KotzillaCoreSDK.setup(token, version), and analytics(application). They still work; migrate to generated monitoring(). If you build with allWarningsAsErrors, these deprecations become hard errors.
• Compose artifact split — kotzilla-sdk-compose-navigation2 / -navigation3 are separate artifacts now (auto-added when autoAddDependencies = true).

Tested Compatibility

Dependency	2.1.x	2.2.x
Kotlin	2.1.0 – 2.3.x ¹	2.2.0 – 2.3.x ²
AGP	8.4.0 – 8.13.0	8.4.0 – 8.13.0
Gradle	8.6 – 9.3	8.6 – 9.3
Koin	4.0.4+	4.0.4+
Android compileSdk	—	35+ (36 for Nav 3)

¹ JVM/Android from Kotlin 2.1.0; iOS/JS/WASM (K/N targets) require Kotlin 2.2.0+. ² Compose projects require Kotlin 2.2.0+ on SDK 2.2.x (compiler-plugin instrumentation, see item 1). Non-Compose JVM/Android projects still build on Kotlin 2.1.0+; iOS/JS/WASM require Kotlin 2.2.0+.

From 1.4.x to 2.0.x

Koin 4.0.4 Required

SDK 2.0.x requires Koin 4.0.4 or higher. Projects using Koin 3.x must upgrade before updating to SDK 2.0.x.

Breaking Changes

Change	What to Do
Koin 4.0.4 required	Upgrade Koin before SDK
analytics {} deprecated (KMP/CMP/JVM/JS)	Use monitoring {} instead
keyGeneration removed	Delete from build.gradle.kts
composeInstrumentation default: true	Remove unless you want to disable
iOS crash reporting: enabled	Runs automatically; opt-out available
Build fails on missing API key	Add kotzilla.json to your module

Note on sdkVersion

The sdkVersion field in kotzilla.json is now ignored. You can remove it for cleanliness, but leaving it won't cause errors.

Step-by-Step Migration

1. Update Koin to 4.0.4+

2. Update SDK to 2.0.4 in your libs.versions.toml:

   [versions]
   kotzilla = "2.0.4"

3. Replace DSL (non-Android platforms):

   // OLD
   analytics { setApiKey("..."); setVersion("...") }
   
   // NEW
   import io.kotzilla.generated.monitoring
   
   monitoring()

   On Android, analytics() still works but monitoring() is recommended for consistency.

4. Remove deprecated options:

   • Delete keyGeneration from kotzilla block
   • Remove composeInstrumentation = true (now default)
   • Optionally remove Kotzilla ProGuard rules (now auto-included)
   • Optionally remove explicit SDK dependency (now auto-added; opt-out: kotzilla { autoAddDependencies = false })

5. iOS projects: Run ./gradlew setupKotzillaXcode to enable dSYM upload

6. Clean build recommended: Run ./gradlew clean to clear cached configs

Post-Upgrade Checklist

• Koin version ≥ 4.0.4
• SDK version = 2.0.4
• Build succeeds
• No keyGeneration in build.gradle.kts
• Compose navigation tracking works (if using Compose)
• iOS dSYM uploads succeed (if targeting iOS)

Tested Compatibility

Dependency	1.4.x	2.0.x
Kotlin	2.0.21 – 2.1.20	2.1.0 – 2.3.0
AGP	8.0 – 8.13	8.4.0 – 8.13.0
Gradle	8.0 – 8.13	8.6 – 9.3
Koin	3.5+	4.0.4+

Known Limitations

• AGP 9.0.0 incompatible — Use AGP 8.x
• Navigation 3 not supported — Navigation 2.x works; Nav 3 has different architecture

From 1.3.0 to 1.4.0

The Kotzilla SDK 1.4.0 introduces important breaking changes related to Kotlin version compatibility and HTTP client architecture. A complete changelog is available here.

Breaking Changes in 1.4.0

1. Minimum Kotlin version increased to 2.0.21

SDK version 1.4.0 and later require Kotlin 2.0.21 or higher due to binary compatibility changes.

If your project is using Kotlin 1.9.x or earlier, you need to upgrade to at least Kotlin 2.0.21 before using SDK 1.4.0.

If you need to stick with Kotlin 1.9.x, keep using the Kotzilla SDK 1.3.1.

2. Ktor HTTP Client Removed

The SDK no longer uses Ktor for HTTP communication. The kotzilla-sdk-ktor3 module has been removed (replaced with a native HTTP client implementation).

If you were using kotzilla-sdk-ktor3, you need to remove this dependency and keep only kotzilla-sdk.

Required Migration Steps

1. Update Kotlin Version

Update your Kotlin version in your project's gradle/libs.versions.toml or build.gradle.kts:

# In gradle/libs.versions.toml
[versions]
kotlin = "2.0.21"  # or higher (tested up to 2.1.20)

Or in your root build.gradle.kts:

plugins {
    kotlin("multiplatform") version "2.0.21" apply false
    kotlin("android") version "2.0.21" apply false
}

2. Update SDK Version and Migrate from Ktor (if applicable)

If you were using the Ktor variant, replace kotzilla-sdk-ktor3 with kotzilla-sdk:

dependencies {
    // BEFORE (1.3.x with Ktor):
    // implementation("io.kotzilla:kotzilla-sdk-ktor3:1.3.x")
    // implementation("io.kotzilla:kotzilla-sdk:1.3.x")

    // AFTER (1.4.0 with native HTTP):
    implementation("io.kotzilla:kotzilla-sdk:1.4.0")
}

If you were already using just the kotzilla-sdk, simply update the version:

dependencies {
    implementation("io.kotzilla:kotzilla-sdk:1.4.0")
}

For Compose Multiplatform projects:

dependencies {
    implementation("io.kotzilla:kotzilla-sdk-compose:1.4.0")
}

Tested Compatibility

The SDK 1.4.0 has been tested with:

• Kotlin: 2.0.21 through 2.1.20
• Android Gradle Plugin (AGP): 8.0.0 through 8.13.0
• Gradle: 8.0 through 8.13
• Koin: 3.5+ (no changes required)

From 0.13.x to 1.0.0

The Kotzilla SDK 1.0.0 introduces improvements to simplify the setup and enhance the reliability of the SDK. A complete changelog is available here.

If you're using version 0.13.x, you can simply update the SDK version in your build.gradle.kts files (both project and app levels) to benefit from the new improvements.

info

This version includes better support for different Ktor versions to avoid library conflicts with the version of Ktor your app is using. By default, the SDK uses Ktor2. If your app is using Ktor3, please update your build.gradle.kts file at the app level from:

implementation("io.kotzilla:kotzilla-sdk:1.0.0")

to

implementation("io.kotzilla:kotzilla-sdk-ktor3:1.0.0")

This version also simplifies the SDK setup thanks to the analytics() function. We encourage you to update your existing setup to use this one-line initialization directly in your Koin setup. You will find all the details in the dedicated guides for Android, KMP, and SDK libraries.

From 0.12.x to 0.13.x

This version 0.13.x brings important breaking changes such as renamings, and package move. Check the list of changes below

info

Going from 0.12.x to 0.13.x requires you to download a Kotzilla project, also known as kotzilla.json file.

See Kotzilla Project File page.

Maven Package Changes

See Latest Version to check for last version.

In your project Gradle file (build.gradle.kts) replace existing configuration by:

buildscript {
    repositories { ... }
    dependencies {
        // This part to copy paste
        classpath("io.kotzilla:kotzilla-plugin:0.13.6")
    }
}

In your application Gradle file (build.gradle.kts) replace existing configuration by:

// --- Plugins ---
plugins {
  // Add the Kotzilla Gradle plugin
  id("io.kotzilla.kotzilla-plugin")
}

// --- Dependencies ---
dependencies {
  // The Kotzilla SDK library dependency
  implementation("io.kotzilla:kotzilla-sdk:0.13.6")
}

note

• moved Maven package from io.kotzilla:cloud-inject to io.kotzilla:kotzilla-sdk
• moved Maven package from io.kotzilla:cloud-inject-gradle to io.kotzilla:kotzilla-plugin

SDK Setup

You can use the SDK now with the KotzillaSDK class. In your Android app Application class, you need to activate the Kotzilla platform with KotzillaSDK.setup(this):

class MainApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        // Start Kotzilla SDK
        KotzillaSDK.setup(this)
        
        // Start Koin
        startKoin {
            // replace your logger with Kotzilla Analytics
            analyticsLogger()

            // Your Koin config here
        }
    }
}

Still you need to start your Koin configuration, by using analyticsLogger() to activate SDK analytics.

note

• class CloudInjectSDK has nee renamed to KotzillaSDK

info

For more advanced SDK usage (like for Android library) look at Android Library Setup page

Gradle Plugin Configuration

The Kotzilla Gradle Plugin offers the following tasks to help manage your project:

• task uploadMappingFile to upload your build's mapping file to the Kotzilla server to help recognised your application symbols see more
• task generateAndroidAssetsKey to generate container key from kotzilla.json project file see more
• task generateProjectFile to generate empty kotzilla.json with all package see more

Besides that you may need to configure manually, like for versionName:

plugins {

  // Be sure to have the Kotzilla Gradle plugin
  id("io.kotzilla.kotzilla-plugin") version "0.13.6" apply false
}

//...

// Advanced Kotzilla SDK coniguration
kotzilla {
    versionName = "1.0"
}

ProGuard Rules

You can update your ProGuard rules file with the following rules:

-keep class io.kotzilla.json.** { *; }
-keep class io.kotzilla.data.json.** { *; }
-keep class io.kotzilla.sdk.** { *; }

note

The rule -keep class io.kotzilla.cloudinject.** { *; } has been replaced by -keep class io.kotzilla.sdk.** { *; }

Also, if needed be sure to keep classes for ktor & kotlin:

-keepclassmembers class kotlinx.** { volatile <fields>; }
-keepclassmembers class io.ktor.** { volatile <fields>; }