Core API

Everything in the core module is reached through the Cimka type.

import CimkaCore

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.

let sessionId: String? = Cimka.session.currentSessionId   // nil until the first session starts

Each session start reports the device model, OS version, screen size and app version.

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.

Cimka.trace.log("Payment started")

Cimka.trace.log(
    "Payment failed",
    level: .error,
    tag: "Checkout",
    extra: ["code": 500, "reason": "card_declined"]
)

Parameter	Type	Default
message	String	—
level	CimkaLogLevel (.debug, .info, .warn, .error)	.info
tag	String?	nil
extra	[String: Any]?	nil

Calls are fire-and-forget and safe from any thread.

Screens

With CimkaUIKit or CimkaSwiftUI, screens are tracked automatically. You can also log them manually:

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

Cimka.screenTracker.currentScreenName holds the last logged screen, used as the default screen for click logging.

Network monitoring

Network logging is implemented as a URLProtocol. Instrument the URLSessionConfiguration before you create the session.

let config = URLSessionConfiguration.default
Cimka.instrument(config)
let session = URLSession(configuration: config)

Or log the shared session:

Cimka.instrumentSharedSession()

This also works for any library that takes a URLSessionConfiguration (e.g. Alamofire’s Session). 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).
• Binary bodies are summarized by content type and size; bodies over 1 MB are replaced with "body too large".
• The SDK’s own API traffic is never logged, so logging never loops.

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 initializes. It captures uncaught Objective-C/Swift exceptions and fatal POSIX signals (SIGABRT, SIGSEGV, SIGBUS, …). Because a dying process can’t safely do networking, the crash is written to a pending file and delivered on the next launch, once the SDK is ready. With CimkaOffline, crashes that still can’t reach the server stay queued.

Note

If you use another crash reporter (e.g. Firebase Crashlytics), it coexists — Cimka chains to the previously installed exception handler. In the debugger, Xcode may catch signals first; test crash delivery without the debugger attached.

Push tokens

Register your APNs/FCM device token so the dashboard can reach the device:

func application(_ app: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    let token = deviceToken.map { String(format: "%02x", $0) }.joined()
    Cimka.registerPushToken(token)
}

Device audit

Once per launch the SDK checks whether the device is jailbroken (known paths, cydia://, sandbox-escape write), a simulator, or shows integrity tampering (a debugger attached to a release build), and reports the result. If your app already holds a location permission, the last known 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 overlay (CimkaBlockedScreen) 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.

Storage denylist

Remote storage commands can snapshot or modify UserDefaults suites. Prevent a suite from ever being read or written:

Cimka.denyStorageSuites("com.myapp.secure")

The SDK’s own suite is always denied.

API summary

Member	Description
initialize(configFileName:bundle:) / initialize(config:)	Starts the SDK. Call once at launch.
identify(_:) / clearUser()	Attach or clear the user identifier.
session.currentSessionId / session.userIdentifier	Current session id and identifier (read-only).
trace.log(_:level:tag:extra:)	Send a trace log.
screenTracker.logScreen(_:referrer:)	Log a screen view.
screenTracker.currentScreenName	Last logged screen name.
instrument(_:) / instrumentSharedSession()	Enable network logging on a session.
registerPushToken(_:)	Register an APNs/FCM token.
registerOfflineStore(_:)	Provide a custom offline store.
denyStorageSuites(_:)	Exclude UserDefaults suites from remote storage commands.
isReady / configuration / debugLoggingEnabled	SDK state and diagnostics.