CyberCinch Shield — SDK Configuration Reference

For developers integrating the Android SDK into their apps. Covers every ShieldConfig field with usage guidance and two complete example configurations.

New to the SDK? Start with the Developer Manual — this page is the deep-dive reference for tuning ShieldConfig once you're already integrated.

1. Quick Start (zero-config)

CyberCinchShield.initialize(
    context = this,
    apiKey  = "cc_live_your_key_here"
)

All fields default to production-safe values. The sections below explain when and why you would override them.

2. Backend URLs

Four fields, all defaulting to https://api.cybercinch.in. Override all four together when targeting a staging environment or a self-hosted deployment:

No trailing slash. All four accept http:// for local or emulator testing (android:usesCleartextTraffic must be enabled in your debug manifest).

3. Detection Modules

Disable individual detectors only if you have a specific reason (for example, your CI pipeline runs on emulators and you want emulator signals suppressed in test results). Disabling enableRootDetection or enableRuntimeProtection meaningfully reduces the SDK's ability to detect compromised devices.

4. Telemetry Behaviour

4.1 Enabling / disabling (enableTelemetry)

Set false to disable all telemetry network activity. Local scanning continues normally; detected events are discarded rather than queued. Use this when:

• You are waiting for explicit user consent before transmitting data.
• Your app has a strict "no background network" policy.
• You are running automated tests that must not produce backend traffic.

Call CyberCinchShield.setTelemetryConsent(true) at runtime to re-enable after consent is obtained.

4.2 Dispatch mode (telemetryMode)

AUTO_IMMEDIATE (default)
Dispatches events on a background IO coroutine immediately after each scan(). scan() returns without waiting — the HTTP call is fire-and-forget. Choose this when you scan infrequently (e.g. once per session) and want the lowest possible delay between detection and backend visibility.

AUTO_BATCHED
Queues events after each scan; a background coroutine flushes them every telemetryBatchIntervalMs milliseconds. No immediate dispatch after scan(). Choose this when you scan frequently (e.g. once per screen transition) or want to amortise network cost across multiple scans.

MANUAL
Queues events and never dispatches automatically. You call CyberCinchShield.flushTelemetry() at a time of your choosing — for example at app foreground, before a sensitive transaction, or via WorkManager on a schedule. Choose this when your app prohibits any background network activity or you need delivery tied to a specific user action.

CyberCinchShield.flushTelemetry() is available as an immediate flush in any mode.

4.3 Batch interval (telemetryBatchIntervalMs)

Only relevant in AUTO_BATCHED. Default: 60,000 ms (1 minute).

Values below 15,000 ms provide little batching benefit over AUTO_IMMEDIATE. Prefer AUTO_IMMEDIATE for sub-15-second delivery requirements.

5. License Validation Behaviour

5.1 Fail-open vs fail-closed (licenseValidationFailOpen)

Controls what happens when initialize() cannot reach the license server.

true (default — fail-open / high availability)
The SDK continues with local-only operation using your ShieldConfig flags. Scans run, telemetry fires, and the device stays protected even if the license server is temporarily unreachable. ScanResult.serverVerified will be false until connectivity is restored.

false (fail-closed / strict)
initialize() fails and scan() throws until a successful license validation has completed. The SDK is fully inoperable during license server outages.

When to choose each:

Most apps should use true. A brief license server outage should not disable device protection for your users.

Banking, fintech, or regulated apps that must guarantee the SDK is operating under an active, current license should consider false — but weigh this carefully against the availability risk. An outage means the SDK stops working entirely until the server recovers, which may affect user-facing features that depend on a scan result.

5.2 Attestation failure handling (failOnAttestationFailure)

When false (default), scan() returns the local result immediately. When true, scan() throws on attestation failure.

6. Other Settings

6.1 Logging (logLevel)

ProGuard strips DEBUG and VERBOSE log calls in release builds, but set NONE explicitly in your release build config to be safe.

6.2 SSL pinning (enableSslPinning)

7. Example Configurations

7.1 High-security app (banking / fintech)

Priorities: strict license enforcement, real-time threat visibility, all detectors on, no tolerance for unverified SDK operation.

CyberCinchShield.initialize(
    context = this,
    apiKey  = "cc_live_your_key_here",
    config  = ShieldConfig(
        // Strict license enforcement — SDK unusable if the license server is
        // unreachable. Acceptable for fintech where unlicensed operation is a
        // compliance risk. Ensure your architecture tolerates this availability
        // dependency before enabling.
        licenseValidationFailOpen = false,

        // Real-time telemetry: dispatch immediately after every scan.
        enableTelemetry = true,
        telemetryMode   = TelemetryMode.AUTO_IMMEDIATE,

        // All detectors on. Runtime protection gated by license feature flag.
        enableRootDetection     = true,
        enableEmulatorDetection = true,
        enableRuntimeProtection = true,
        enableIntegrityCheck    = true,

        // Block scan() on attestation failure — do not allow unverified devices
        // to proceed to sensitive flows.
        failOnAttestationFailure = true,

        logLevel = LogLevel.NONE
    )
)

7.2 Low-overhead app (casual game)

Priorities: minimal battery and network impact. The primary lever here is AUTO_BATCHED with a long interval — not disabling detectors. Root detection stays on because it provides a meaningful fraud signal (device manipulation, cheat engines) even in gaming contexts. Disabling enableRuntimeProtection and enableIntegrityCheck is an optional further reduction for apps on mid-range devices where the native overhead is measurable.

CyberCinchShield.initialize(
    context = this,
    apiKey  = "cc_live_your_key_here",
    config  = ShieldConfig(
        // Fail-open — a license server blip should never interrupt gameplay.
        licenseValidationFailOpen = true,

        // Batch telemetry every 5 minutes. This is the primary overhead reduction:
        // network calls are amortised across all scans in the session rather than
        // firing after each one.
        enableTelemetry          = true,
        telemetryMode            = TelemetryMode.AUTO_BATCHED,
        telemetryBatchIntervalMs = 300_000,

        // Root detection stays on — relevant for cheat-engine and device
        // manipulation signals.
        enableRootDetection     = true,
        enableEmulatorDetection = true,

        // Optional: disable the heavier native detectors if profiling shows
        // measurable CPU cost on low-end target devices.
        enableRuntimeProtection = false,
        enableIntegrityCheck    = false,

        failOnAttestationFailure = false,

        logLevel = LogLevel.NONE
    )
)