### Upload Release Build Mapping File

Source: https://doc.kotzilla.io/docs/settings/mappingFiles

Example command to upload the mapping file specifically for the release build flavor.

```bash
./gradlew uploadMappingFileRelease
```

--------------------------------

### Example Kotzilla Project File Structure

Source: https://doc.kotzilla.io/docs/settings/projectFile

This is an example of the kotzilla.json file structure, which stores API keys and application package names. The 'sdkVersion' field is deprecated and ignored in SDK 2.0.x.

```json
{
   "keys": [
      {
         "appId": "96d4e46b-45a6-4a26-95ab-566257551567",
         "applicationPackageName": "com.google.samples.apps.nowinandroid.demo.debug",
         "keyId": "01944f83-43d1-7492-927c-9abce560b5a4",
         "apiKey": "ktz-sdk-abd..."
      }
   ]
}
```

--------------------------------

### Simulate Slow App Startup

Source: https://doc.kotzilla.io/docs/detectIssues/startupIssue

Introduce a 10-second delay after Koin setup in the Application's onCreate function to simulate a slow startup. This helps in testing the detection of startup performance issues.

```kotlin
class NiaApplication : Application(), ImageLoaderFactory {
  
    val imageLoader: ImageLoader by inject()  
    val profileVerifierLogger: ProfileVerifierLogger by inject()  
  
    override fun onCreate() {
        super.onCreate()

        // Start Koin with Kotzilla Analytics  
        startKoin {
            androidContext(this@NiaApplication)
            analytics()
            modules(appModule)
            workManagerFactory()
        }
          
        Sync.initialize(context = this)
        profileVerifierLogger()
  
        // Simulate a slow startup time  
        Thread.sleep(10000)
  }

```

--------------------------------

### Start Kotzilla SDK with Koin

Source: https://doc.kotzilla.io/docs/getstartedCustom/setupKMP

Initialize the Kotzilla SDK in your shared module's Koin configuration. The `monitoring()` function is generated by the Kotzilla Gradle plugin and automatically reads configuration from `kotzilla.json`. Call `monitoring()` last in the `startKoin` block.

```kotlin
import io.kotzilla.generated.monitoring  

startKoin {
    // Your current Koin configuration
    ..
    // Add Kotzilla monitoring
    monitoring()
}

```

--------------------------------

### Setup Kotzilla Xcode Integration

Source: https://doc.kotzilla.io/docs/releaseNotes/whatsNew

Run this Gradle command once to set up the build phase script in your Xcode project. This automates the upload of dSYM files for iOS crash reporting symbolication on each build.

```bash
./gradlew setupKotzillaXcode

```

--------------------------------

### Setup Kotzilla Core SDK with Android Context

Source: https://doc.kotzilla.io/docs/releaseNotes/changelogSDK

Provides Android Application context for lifecycle instrumentation when Koin is not available. Use this when setting up the SDK manually.

```kotlin
KotzillaCoreSDK.setup(token, version).withAndroidContext(app).connect()
```

--------------------------------

### Install Kotzilla MCP Server with Claude

Source: https://doc.kotzilla.io/docs/fixIssues/koinMcp

Use this command to add the Kotzilla MCP Server to your Claude assistant. Ensure you have a Kotzilla account for authentication.

```bash
claude mcp add kotzilla --transport http https://mcp.kotzilla.io/mcp
```

--------------------------------

### Delayed SDK Start with Feature Flag

Source: https://doc.kotzilla.io/docs/settings/apiUse

Start the Kotzilla SDK after the Koin application is configured, useful for delayed initialization like feature flags.

```kotlin
override fun onCreate() {
  super.onCreate()

  val koinApp = startKoin {
    androidContext(this@MyApplication)
    modules(appModule)
  }

  // Start Kotzilla SDK after Koin is configured
  koinApp.monitoring()
}
```

--------------------------------

### Initialize Monitoring in KMP Shared Module

Source: https://doc.kotzilla.io/docs/releaseNotes/whatsNew

Add this line to your Koin setup in the commonMain module to enable unified monitoring across all Kotlin Multiplatform targets. The SDK automatically detects the platform at runtime.

```kotlin
import io.kotzilla.generated.monitoring

fun initApp() {
    startKoin {
        // Your Koin modules
        modules(appModule)
        // One line to monitor all targets
        monitoring()
    }
}

```

--------------------------------

### Example Koin Compile Error

Source: https://doc.kotzilla.io/docs/fixIssues/koinMcp

This is an example of a Koin compile error that can be fixed using the Kotzilla MCP Server. Copy the full error, including all indented lines, for accurate diagnosis.

```text
[Koin][KOIN-D001] Missing dependency: com.example.Repository qualified with @Named("prod")
  required by: Service (parameter 'repo')
  in module: appModule
  Hint: Found similar binding: Repository with qualifier @Named("test")
  → Fix with AI: set up Kotzilla MCP at https://kotzilla.io/mcp
```

--------------------------------

### Initialize Kotzilla SDK with Koin

Source: https://doc.kotzilla.io/docs/getstartedCustom/setupCMP

Initialize the Kotzilla SDK within your Koin configuration in the ComposeApp module. Call `monitoring()` last to ensure proper initialization.

```kotlin
import io.kotzilla.generated.monitoring

startKoin {
    // Your current Koin configuration
    ..
    // Add Kotzilla monitoring
    monitoring()
}
```

--------------------------------

### Initialize Kotzilla SDK in Android Application

Source: https://doc.kotzilla.io/docs/releaseNotes/versionUpgrades

In version 0.13.x, activate the Kotzilla platform by calling `KotzillaSDK.setup(this)` in your Android Application class's onCreate method.

```kotlin
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
        }
    }
}
```

--------------------------------

### Initialize Monitoring with monitoring() API

Source: https://doc.kotzilla.io/docs/releaseNotes/whatsNew

Use the `monitoring()` function for a simpler initialization approach. It's generated by the Kotzilla Gradle plugin and reads configuration from `kotzilla.json`.

```kotlin
import io.kotzilla.generated.monitoring

startKoin {
    monitoring()
}
```

--------------------------------

### Initialize Kotzilla SDK in Application Class

Source: https://doc.kotzilla.io/docs/getstartedCustom/setupAndroid

Initialize the Kotzilla SDK by calling `startKoin` and `monitoring()` in your app's main `Application` class. Ensure `monitoring()` is called last within the `startKoin` block.

```kotlin
import io.kotzilla.generated.monitoring  

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()  
        startKoin {  
            androidContext(this@MyApplication)  
            monitoring()  // Recommended for all platforms  
        }
    }
}
```

--------------------------------

### Initialize Kotzilla SDK in Application Class

Source: https://doc.kotzilla.io/docs/getstartedCustom/setupAndroidCompose

Initialize the Kotzilla SDK within your app's main Application class using `startKoin`. The `monitoring()` function is recommended for cross-platform consistency and should be called last.

```kotlin
import io.kotzilla.generated.monitoring

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidContext(this@MyApplication)
            monitoring()  
        }
    }
}
```

--------------------------------

### Configure Kotzilla Repository

Source: https://doc.kotzilla.io/docs/settings/repository

Use the Kotzilla repository for early access to pre-release versions. Add the repository URL to both the pluginManagement and dependencyResolutionManagement sections in your settings.gradle.kts file.

```gradle
// settings.gradle.kts  
repositories {
    mavenCentral()
    google()
    // Kotzilla repository (for pre-release versions)  
    maven {
        name = "kotzilla"
        url = uri("https://repository.kotzilla.io/repository/kotzilla-platform/")
    }
}

```

--------------------------------

### Initialize Kotzilla SDK Monitoring

Source: https://doc.kotzilla.io/docs/getstartedCustom/setupSDKLibrary

Call `monitoring()` last within your SDK's isolated Koin context, after all modules and includes, to ensure proper initialization. The plugin automatically supplies the API key from `kotzilla.json`.

```kotlin
import io.kotzilla.generated.monitoring  

koinApplication {                
    androidContext(application)
    modules(...)
    monitoring()                 
}
```

--------------------------------

### Run Specific Flavor Upload Task

Source: https://doc.kotzilla.io/docs/settings/mappingFiles

Execute the upload task for a specific build flavor from the main application module.

```bash
./gradlew uploadMappingFile<Flavour>
```

--------------------------------

### View Available Gradle Tasks

Source: https://doc.kotzilla.io/docs/settings/mappingFiles

Command to list all available Gradle tasks, including mapping file upload tasks.

```bash
./gradlew tasks
```

--------------------------------

### Add Kotzilla SDK to Version Catalog

Source: https://doc.kotzilla.io/docs/getstartedCustom/setupAndroidCompose

Add the Kotzilla SDK version and library definition to your `libs.versions.toml` file. Ensure you check for the latest version available.

```toml
[versions]
kotzilla = "2.2.0"  

[libraries]
kotzilla-sdk-compose = { group = "io.kotzilla", name = "kotzilla-sdk-compose", version.ref = "kotzilla" }

[plugins]
kotzilla = { id = "io.kotzilla.kotzilla-plugin", version.ref = "kotzilla" }
```

--------------------------------

### Apply Kotzilla Plugin with Version Catalog

Source: https://doc.kotzilla.io/docs/settings/pluginConfig

Apply the Kotzilla Gradle plugin in the root `build.gradle.kts` file using a Version Catalog. This ensures the plugin processes all modules in the project.

```gradle
// root build.gradle.kts (Version Catalog)
plugins {
    alias(libs.plugins.kotzilla) apply true
}
```

--------------------------------

### Manual Proguard Configuration for Kotzilla SDK

Source: https://doc.kotzilla.io/docs/settings/proguard

Add these rules to your Proguard file if manual configuration is needed. They ensure essential SDK classes are preserved.

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

--------------------------------

### Multiple Keys for Different Package Names

Source: https://doc.kotzilla.io/docs/settings/projectFile

Register each flavor as an app in the Console and combine keys in kotzilla.json when each flavor uses a different package name. The Kotzilla Gradle plugin selects the correct key based on the applicationPackageName being built.

```json
{
  "keys": [
    {
      "appId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "applicationPackageName": "com.example.app.dev",
      "keyId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "apiKey": "ktz-sdk-abc"
    },
    {
      "appId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "applicationPackageName": "com.example.app.staging",
      "keyId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "apiKey": "ktz-sdk-xyz"
    },
    {
      "appId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "applicationPackageName": "com.example.app",
      "keyId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "apiKey": "ktz-sdk-123"
    }
  ]
}
```

--------------------------------

### Build Release iOS Frameworks

Source: https://doc.kotzilla.io/docs/getstartedCustom/setupKMP

Execute Gradle tasks to build release versions of the iOS framework for different architectures (simulator and device).

```bash
./gradlew linkReleaseFrameworkIosSimulatorArm64
./gradlew linkReleaseFrameworkIosArm64
./gradlew linkReleaseFrameworkIosX64
```

--------------------------------

### Apply Kotzilla Plugin with Legacy Configuration

Source: https://doc.kotzilla.io/docs/settings/pluginConfig

Apply the Kotzilla Gradle plugin in the root `build.gradle.kts` file using the legacy configuration method with a specific version.

```gradle
// root build.gradle.kts (legacy)
plugins {
    id("io.kotzilla.kotzilla-plugin") version "2.2.0" apply true
}
```

--------------------------------

### Add Kotzilla SDK Dependencies to libs.versions.toml

Source: https://doc.kotzilla.io/docs/getstartedCustom/setupAndroid

Configure the Kotzilla SDK version and library in your Gradle Version Catalog file (`libs.versions.toml`). This is the recommended approach for managing dependencies.

```gradle
[versions]
kotzilla = "2.2.0"  

[libraries]
kotzilla-sdk = { group = "io.kotzilla", name = "kotzilla-sdk", version.ref = "kotzilla" }  

[plugins]
kotzilla = { id = "io.kotzilla.kotzilla-plugin", version.ref = "kotzilla" }
```

--------------------------------

### Generate Empty Kotzilla Project File

Source: https://doc.kotzilla.io/docs/settings/projectFile

Run this Gradle task to create a new, empty kotzilla.json project file in your application module directory. Ensure the Kotzilla Gradle plugin is configured.

```bash
./gradlew generateProjectFile
```

--------------------------------

### Simulate Slow Dependency Resolution

Source: https://doc.kotzilla.io/docs/detectIssues/dependencyPerformanceIssue

Introduces a 1-second delay in the constructor of a repository to simulate a slow dependency resolution. This helps in observing the performance impact.

```kotlin
internal class OfflineFirstUserDataRepository(
    private val niaPreferencesDataSource: NiaPreferencesDataSource,
    private val analyticsHelper: AnalyticsHelper,
) : UserDataRepository {

    // Simulate a slow dependency resolution with a 1-second delay
    init {
        Thread.sleep(1000)
    }

```

--------------------------------

### Apply Kotzilla Plugin for Compose Multiplatform (CMP) Module

Source: https://doc.kotzilla.io/docs/settings/gradleSetup

Apply the Kotzilla plugin in your module-level build.gradle.kts for Compose Multiplatform projects. Configure version name and manual dependency fallback is available.

```gradle
plugins {
    id("io.kotzilla.kotzilla-plugin")
}

kotzilla {
    versionName = "1.0.0" // Your app version
}

```

--------------------------------

### Configure Maven Central Repository

Source: https://doc.kotzilla.io/docs/settings/repository

Maven Central is the recommended repository for the Kotzilla SDK and is usually included by default in Gradle projects. No additional configuration is typically needed.

```gradle
// settings.gradle.kts - Maven Central is typically already included  
repositories {
    mavenCentral()  // SDK is available here  
    google()
}

```

--------------------------------

### Configure iOS Targets in Shared Module

Source: https://doc.kotzilla.io/docs/getstartedCustom/setupKMP

Define iOS targets (e.g., `iosX64`, `iosArm64`) and configure framework settings in your shared module's `build.gradle.kts`. This ensures the Kotzilla SDK is included in the iOS framework.

```kotlin
kotlin {
    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "SharedModule"
            isStatic = true
        }
    }

    androidTarget()
    
}

```

--------------------------------

### Replace analytics DSL with monitoring DSL

Source: https://doc.kotzilla.io/docs/releaseNotes/versionUpgrades

Migrate from the deprecated 'analytics {}' block to the new 'monitoring {}' block for non-Android platforms. Ensure the 'io.kotzilla.generated.monitoring' import is present.

```kotlin
// OLD
analytics { setApiKey("..."); setVersion("...") }

// NEW
import io.kotzilla.generated.monitoring

monitoring()

```

--------------------------------

### Build Debug iOS Frameworks

Source: https://doc.kotzilla.io/docs/getstartedCustom/setupKMP

Execute Gradle tasks to build debug versions of the iOS framework for different architectures (simulator and device).

```bash
./gradlew linkDebugFrameworkIosSimulatorArm64
./gradlew linkDebugFrameworkIosArm64
./gradlew linkDebugFrameworkIosX64
```

--------------------------------

### Configure Kotzilla Gradle Plugin

Source: https://doc.kotzilla.io/docs/releaseNotes/changelogSDK

Apply the Kotzilla Gradle plugin at the root for processing all modules. Module-level application remains unchanged.

```kotlin
apply true
```

--------------------------------

### ProGuard Rules for Ktor and Kotlinx

Source: https://doc.kotzilla.io/docs/releaseNotes/versionUpgrades

If needed, add ProGuard rules to keep specific classes for Ktor and Kotlinx libraries.

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

--------------------------------

### Simulate Slow Worker Initialization

Source: https://doc.kotzilla.io/docs/detectIssues/backgroundIssue

Introduce a 1-second delay in the initialization of a background worker to simulate a performance issue. This helps in observing how thread blockages impact background tasks.

```kotlin
class SyncWorker(  
    private val appContext: Context,  
    workerParams: WorkerParameters,  
    private val niaPreferences: NiaPreferencesDataSource,  
    private val topicRepository: TopicsRepository,  
    private val newsRepository: NewsRepository,  
    private val searchContentsRepository: SearchContentsRepository,  
    private val ioDispatcher: CoroutineDispatcher,  
    private val analyticsHelper: AnalyticsHelper,  
    private val syncSubscriber: SyncSubscriber,  
) : CoroutineWorker(appContext, workerParams), Synchronizer {  
  
    init {  
        // Simulate slow worker  
        Thread.sleep(1000)   
    }

```

--------------------------------

### Migrate from Ktor HTTP Client Dependency

Source: https://doc.kotzilla.io/docs/releaseNotes/versionUpgrades

Replace the 'kotzilla-sdk-ktor3' dependency with 'kotzilla-sdk' when upgrading to SDK 1.4.0 if you were previously using the Ktor variant.

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

```

--------------------------------

### Manual dSYM Upload

Source: https://doc.kotzilla.io/docs/getstartedCustom/setupKMP

Use this command for manual dSYM upload if the automatic upload fails.

```bash
./gradlew uploadDsymFile  

```