Configuration

The SDK is configured by a JSON file bundled with your app. There is no builder API by default — the file is the single source of local configuration.

cimka_config.json

{
  "validation": {
    "licenseKey": "XXXX-XXXX-XXXX-XXXX",
    "apiKey": "cmk_your_derived_key_here",
    "applicationId": "your-app-id-here",
    "baseUrl": "https://your-cimka-backend/api/v1"
  },
  "clickLogger": { "maskSensitiveInputs": true },
  "deviceAudit": { "enabled": true }
}

Add the file to your app target’s resources (select it in Xcode → Target Membership → check your app, so it lands in Copy Bundle Resources). Cimka.initialize() loads it from Bundle.main.

To use a different file name or bundle:

Cimka.initialize(configFileName: "cimka_config_staging.json", bundle: .main)

Or build the configuration in code instead of shipping a file:

let config = CimkaConfig(
    validation: CimkaValidationConfig(
        licenseKey: "XXXX-XXXX-XXXX-XXXX",
        apiKey: "cmk_…",
        applicationId: "your-app-id",
        baseUrl: "https://your-cimka-backend/api/v1"
    )
)
Cimka.initialize(config: config)

validation (required)

All four fields are required.

Key	Type	Description
licenseKey	String	Secret used to sign every SDK request (HMAC-SHA256). It is never sent over the network.
apiKey	String	Your application’s API key, sent as the cimkaApiKey header.
applicationId	String	Your application id, sent as the cimkaAppId header.
baseUrl	String	Cimka API root, e.g. https://api.example.com/api/v1. A trailing / is trimmed.

You get all three credentials when you create an application in the dashboard. Register the app as iOS so its data is attributed to the right platform.

Caution

The config file lives in your app bundle and can be extracted. Treat the keys as app-scoped credentials: rotate them from the dashboard if they leak.

clickLogger

Key	Type	Default	Description
maskSensitiveInputs	Boolean	true	When true, taps on text fields are logged with text *** instead of the field content (UIKit module). Secure fields are always masked.

The batchSize, batchIntervalMillis, maxDiskQueueSize, retryMaxAttempts, retryBaseDelayMillis and enabled fields are accepted but reserved — they currently have no effect.

deviceAudit

Key	Type	Default	Description
enabled	Boolean	true	Run the device audit at all.
detectRoot / detectSimulator / detectCorrupted	Boolean	true	Toggle individual checks.
sendToBackend	Boolean	true	Upload the audit result.

Device audit can also be switched off per application from the dashboard.

Initialization sequence

Cimka.initialize() returns immediately; most of the work happens on a background task.

1. The config file is read. If it is missing or malformed, initialization fails and the SDK stays silent (an error is logged in debug builds).
2. License check — GET /sdk/v1/health/check with a 15 s timeout. If it fails, the SDK stays disabled for this launch.
3. Remote config — GET /sdk/v1/config/check. Returns which log types are enabled and whether the device is blocked.
4. Once ready, the SDK starts the session observer, installs the crash handler, runs the device audit, uploads the dependency list, loads masked properties, and replays any offline logs.

Note

Until step 4 completes, the network logger, screen tracker and click/lifecycle loggers are no-ops. Events and crashes during the first moments of app startup are therefore not captured.

Server-controlled settings

Each application has remote settings, managed in the dashboard, that the SDK fetches at init, every time the app returns to the foreground, and every 2 minutes while it stays in the foreground.

Setting	Effect
isSdkEnabled	Master kill switch for the SDK.
logConfig.click / screen / crash / network / trace / lifecycle / session / deviceAudit / dependencies	Turn individual log types on or off.
blocked + reason	Shows a full-screen blocked screen on this device (see Device gate).
Masked properties	Header names and JSON keys to replace with [MASKED] in network logs.

All remote settings fail open: if the backend can’t be reached, the SDK stays enabled with every log type on.