Core API

Everything in the core module is reached through the com.xhonaldo.cimka.core.Cimka object.

import com.xhonaldo.cimka.core.Cimka

Sessions

Sessions are fully automatic. A session starts when your app comes to the foreground, sends a heartbeat every 5 minutes, is paused when the app goes to the background, and is closed by the server after inactivity.

val sessionId: String? = Cimka.session.currentSessionId   // null until the first session starts

Each session start reports the device model, OS version, screen size, app version and the list of permissions your app requests (and whether each is granted).

Identify users

Attach your own user id to the session so you can search for it in the dashboard.

// after login
Cimka.identify("user_123")

// on logout
Cimka.clearUser()

The identifier is stored locally and attached to every future session until clearUser() is called. clearUser() only clears it on the device; past sessions keep their identifier.

Tip

Prefer an opaque internal id over an email address or phone number.

Trace logs

Send your own log lines, with a level, an optional tag and structured data.

import com.xhonaldo.cimka.components.trace_logger.CimkaLogLevel

Cimka.trace.log("Payment started")

Cimka.trace.log(
    message = "Payment failed",
    level   = CimkaLogLevel.error,
    tag     = "Checkout",
    extra   = mapOf("code" to 500, "reason" to "card_declined")
)

Parameter	Type	Default
message	String	—
level	CimkaLogLevel (debug, info, warn, error)	info
tag	String?	null
extra	Map<String, Any>?	null

Calls are fire-and-forget and safe from any thread. From Java, use Cimka.getTrace().log(...) — overloads are generated.

Screens

With cimka-xml or cimka-compose, screens are tracked automatically. You can also log them manually:

Cimka.screenTracker.logScreen("Checkout", referrer = "Cart")

If you use the AndroidX Navigation component with Views, attach the tracker to your NavController to log every destination change (the destination label is used, falling back to its route):

Cimka.screenTracker.attachToNavController(navController)

Network monitoring

Add the Cimka interceptor to your OkHttp client (and therefore Retrofit) to log every request and response.

val client = OkHttpClient.Builder()
    .addInterceptor(Cimka.interceptor)
    .build()

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .client(client)
    .build()

For each call it records the URL, method, status, duration, and request/response headers and bodies.

• Authorization, cimkaApiKey and cimkaAppId headers are always removed.
• Headers and JSON keys listed as masked properties in the dashboard are replaced with [MASKED] (case-insensitive, at any depth).
• Gzip responses are decompressed; binary bodies are summarized by content type and size; bodies over 1 MB are replaced with "body too large".

Caution

Request and response bodies are captured in full. Before going live, add every sensitive field your API uses (password, token, cardNumber, …) to the masked properties of your application.

Crash reporting

There’s nothing to call — crash reporting is installed automatically when the SDK is ready. On an uncaught exception, Cimka captures the stack trace, message and thread details, marks crashes on the main thread as fatal, sends the report (waiting up to 5 s), and then hands over to the previously installed handler. With cimka-offline, unsent crashes are delivered on the next launch.

Note

If you use another crash reporter (e.g. Firebase Crashlytics), initialize it before Cimka.initialize(). Cimka chains to it; a handler installed afterwards would replace Cimka’s.

Device audit

Once per launch the SDK checks whether the device is rooted, an emulator, or has a tampered system (writable /system, permissive SELinux, debug build with test keys) and reports the result. If your app holds a location permission, the last known coarse location is attached. Audit can be switched off per application in the dashboard.

Device gate

From the dashboard you can block a device. A blocked device sees a full-screen CimkaBlockedActivity showing the reason and your organization’s contact details (logo, email, phone, website). The status is re-checked on every foreground and every 2 minutes, so unblocking takes effect quickly.

API summary

Member	Description
initialize(app, configFileName = "cimka_config.json")	Starts the SDK. Call once in Application.onCreate.
identify(username) / clearUser()	Attach or clear the user identifier.
session.currentSessionId / session.userIdentifier	Current session id and identifier (read-only).
trace.log(message, level, tag, extra)	Send a trace log.
screenTracker.logScreen(name, referrer)	Log a screen view.
screenTracker.attachToNavController(navController)	Auto-log Navigation destinations.
screenTracker.currentScreenName	Last logged screen name.
interceptor	OkHttp Interceptor for network monitoring.
registerOfflineStore(store)	Provide a custom offline store.
registerActivityPlugin(plugin)	Hook into Activity lifecycle (advanced).