Kotzilla project file & API keys

To simplify API key management, the Kotzilla SDK uses a project file (kotzilla.json) that centralizes configuration details, including the API key required for SDK operation. The following guide explains how to manually set up and manage this file, which is an alternative to the automatic process in the get started guide. It also includes steps for users migrating to SDK version 0.13.x or higher to ensure a smooth transition.

Migrate to SDK versions 0.13.x or higher

For users migrating to SDK versions 0.13.x, the following steps are required to update your project:

1. Download the Kotzilla Project File from your Application Settings page in the Kotzilla Console

2. Place the Kotzilla.json file in the app-level module directory of your Android Studio project (e.g., <project-root>/app).

Generate an empty kotzilla project File

1. Ensure that the Kotzilla Gradle plugin is configured in your project. For more information on setting up the plugin, refer to the section called Update Gradle files in the get started guide.

2. To create a new, empty kotzilla.json project file, run the following Gradle task from your application module (e.g., <project>/<app-module>):

   ./gradlew generateProjectFile

3. This command will generate the kotzilla.json file within the root of your application module folder (<project>/<app-module>/kotzilla.json).

Understanding the Kotzilla project file

The kotzilla.json file stores key configuration data for the Kotzilla SDK, including the SDK version and the API keys associated with your application packages. Here’s an example of what the kotzilla.json file might look like:

{
   "sdkVersion": "1.3.1",
   "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..."
      }
   ]
}

Understanding API key management

The kotzilla.json file allows the Kotzilla Gradle plugin to handle your application's API key, which is required for the Kotzilla SDK to operate.

The generateAndroidAssetsKey Gradle task generates a secured API key container for your Android application, which is stored in the /assets folder as the kotzilla.key file.

info

The generateAndroidAssetsKey task is automatically triggered during the preBuild Gradle phase, so manual execution is typically unnecessary.

Clean Kotzilla Platform Android Key File

To remove an existing kotzilla.json project file, run the following Gradle task from your application module (e.g., <project>/<app-module>):

./gradlew cleanKotzillaKey

Upon running this command, the kotzilla.json file will be securely deleted from the assets folder of your application module (<project>/<app-module>/src/main/assets/).

Specifying Kotzilla project file

By default, the Kotzilla Gradle plugin uses the kotzilla.json file to handle your project key configuration. If you need to move over several files in parallel to manage your keys, you can specify a Kotzilla section plugin, with property projectFile to specify what file to use.

info

If you handle several key with the same applicationPackageName, be sure to delete <app-module>/src/main/assets/kotzilla.key file that is generated for a given application package.

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

android { 
   // ...
}

// Specify your Kotzilla project file
kotzilla {
   projectFile = "kotzilla-prod.json"
}

Disable Automatic Mapping File Upload

By default, the Kotzilla Gradle plugin upload your mapping files since version 1.0.1. You can disable this behavior by using uploadMappingFile = false in Kotzilla gradle config

kotzilla {
   uploadMappingFile = false
}

Managing Multiple Keys with Build Flavors

Starting from SDK version 1.3.x, the Kotzilla Gradle plugin supports managing multiple API keys for the same application package when using Android build flavors or variants. This allows you to use different Kotzilla keys for different build configurations (e.g., debug, release, staging, production).

Using the flavor property

When you have multiple API keys with the same applicationPackageName, you can differentiate them by specifying the flavor property in your kotzilla.json file:

{
   "sdkVersion": "1.3.1",
   "keys": [
      {
         "appId": "96d4e46b-45a6-4a26-95ab-566257551567",
         "applicationPackageName": "com.example.app",
         "keyId": "01944f83-43d1-7492-927c-9abce560b5a4",
         "apiKey": "ktz-sdk-abc...",
         "flavor": "debug"
      },
      {
         "appId": "96d4e46b-45a6-4a26-95ab-566257551567",
         "applicationPackageName": "com.example.app",
         "keyId": "01944f83-43d1-7492-927c-9abce560b5a5",
         "apiKey": "ktz-sdk-xyz...",
         "flavor": "release"
      }
   ]
}

The plugin will automatically select the appropriate key based on the current build variant being built.

Using the isDefault property

When you have multiple keys, you can mark one as the default by setting isDefault: true. This key will be used when:

• No flavor-specific match is found
• The build variant doesn't match any of the specified flavors
• You're building for a platform that doesn't use flavors (e.g., Kotlin Multiplatform)

{
   "sdkVersion": "1.3.1",
   "keys": [
      {
         "appId": "96d4e46b-45a6-4a26-95ab-566257551567",
         "applicationPackageName": "com.example.app",
         "keyId": "01944f83-43d1-7492-927c-9abce560b5a4",
         "apiKey": "ktz-sdk-abc...",
         "flavor": "production",
         "isDefault": true
      },
      {
         "appId": "96d4e46b-45a6-4a26-95ab-566257551567",
         "applicationPackageName": "com.example.app",
         "keyId": "01944f83-43d1-7492-927c-9abce560b5a5",
         "apiKey": "ktz-sdk-xyz...",
         "flavor": "staging"
      }
   ]
}

Key Selection Logic

The Kotzilla Gradle plugin uses the following logic to select the appropriate key:

1. Single key: If only one key exists for the applicationPackageName, it's automatically used
2. Multiple keys with flavors:
   • First, the plugin tries to match the current build variant's flavor with the flavor property
   • If no match is found, it falls back to the key with isDefault: true
   • If neither is found, the build fails with an error
3. Multiple keys without flavors: The plugin selects the key with isDefault: true, otherwise the build fails

warning

When using multiple keys with the same applicationPackageName, you must either:

• Specify unique flavor values for each key, OR
• Set isDefault: true on one of the keys

Failure to do so will result in a build error when the plugin cannot determine which key to use.

info

After changing keys in your kotzilla.json file, make sure to delete the generated <app-module>/src/main/assets/kotzilla.key file to ensure the new key is properly generated during the next build. Use the clean Gradle task.