Skip to main content

Kotzilla SDK API

This page describes Kotzilla SDK API and provides examples of how to use it to track events, manage session data, and capture performance metrics in your application.

info

Usage differs slightly between Android and Kotlin Multiplatform (KMP) projects. See setup instructions below for both environments.

SDK Setup​

Android apps​

Simply call analytics() function in your startKoin block

import io.kotzilla.sdk.KotzillaSDK
...
startKoin {
    androidContext(this@MyApplication)
    analytics()
    ...
}

That's it, the SDK will automatically use the values from your kotzilla.json file configuration (API key and version). Once initialized, you can directly use the KotzillaSDK API.

In KMP projects​

Manual setup is required to use the API in your shared code configuration for Koin (i.e, Koin.kt in commonMain)

import io.kotzilla.sdk.KotzillaCoreSDK
...
val sdk = KotzillaCoreSDK
    .setup(apiToken = "your-api-key", version = "your-version")
    .attachKoin()
    .connect()

Then use the sdk instance to call the API

info

Replace any call to KotzillaSDK in the examples below with your sdk instance. You should perform this setup and use the instance from your commonMain code.

Logging Messages​

You can add custom log messages to your app's timeline to provide additional context and track important events using the log function. This is useful for capturing information about specific actions or states in your app.

  • Function: KotzillaSDK.log(message: String)

Example:

KotzillaSDK.log("a message ...")

This will add the message to your timeline, helping you track events in the app.

Capture crashes​

To capture exceptions and add them to your timeline for later debugging, you can log them using the log function, along with the exception.

  • Function: KotzillaSDK.log(message: String, exception: Throwable)

Example:

KotzillaSDK.log("an error occurred", exception)

This will record both the message and exception, making it easier to debug issues that happen in production.

Trace code performance​

To measure the performance of specific code blocks, you can use the trace function. This allows you to benchmark the execution time of certain operations and track their performance within your app.

  • Function: KotzillaSDK.trace(name: String, block: () -> Unit)

Example:

KotzillaSDK.trace("my_code_block") {
    // My code to benchmark here ...
    myComponent.MyHeavyCall()
}

This will track the performance of the specified code block and record the execution time in your timeline.

Add session properties​

You can add custom properties to the current session to enrich the context of your app's data. This can include anything from user preferences to current app settings.

  • Function: KotzillaSDK.setProperties(vararg properties: Pair<String, Any>)

Example:

KotzillaSDK.setProperties(
    "my_string" to "a_string",
    "my_int" to 1,
    "my_double" to 1.0,
    "my_bool" to true,
)

This will add the provided properties to the session data, helping you track custom context during a user's session.

Set user Id properties​

To track sessions for specific users, you can set a unique user ID. This allows you to correlate the session data with a particular user, enabling more granular analysis.

  • Function: KotzillaSDK.setUserId(userId: String)

Example:

KotzillaSDK.setUserId("user_123")

This will associate the current session with the specified user ID and add it to the session data for tracking purposes.