Kade Android Core SDK

Overview

GeoFenceClient.getInstance(context) is the high-level native entry point. It owns configuration, encryption, pings, continuous checks, and fingerprint submission while retaining only the application context.

Availability

The Android Core SDK is not currently distributed as a standalone public Maven artifact. There are no public Maven coordinates or repository installation commands to use.

The current source module is configured with minSdk 23, compileSdk 34, targetSdk 34, Java 17, and Kotlin JVM target 17. These facts describe the source module, not a public release.

Integration

After Kade supplies the native package, add it according to the delivery-specific instructions. Do not invent a remote dependency coordinate or include the React Native bridge in a native-only app.

Host build requirements

android {
  compileSdk 34

  defaultConfig {
    minSdk 23
  }

  compileOptions {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
  }

  kotlinOptions {
    jvmTarget = '17'
  }
}

When Kade supplies Core as source, its module declares coroutines, AndroidX Core, Security Crypto, Lifecycle Process, Google Play services Location and Block Store, Play Integrity, and OkHttp dependencies. Follow the supplied packaging instructions to determine whether your host must declare any of them directly.

Quick start

Obtain the singleton, start it asynchronously, and issue a ping only after the startup callback succeeds.

import com.videntrix.geofence.core.GeoFenceClient
import com.videntrix.geofence.core.GeoFenceConfig
import com.videntrix.geofence.core.PingOptions

val client = GeoFenceClient.getInstance(applicationContext)
val config = GeoFenceConfig(
    apiToken = "your-api-token",
    regionId = 123,
)

client.start(config) { startResult ->
    startResult.fold(
        onSuccess = {
            client.ping(
                options = PingOptions(
                    userId = "player-123",
                    source = "login",
                    email = "player@example.com",
                ),
            ) { pingResult ->
                pingResult.fold(
                    onSuccess = { response ->
                        if (response.blocked == true) {
                            println("Blocked: ${response.code ?: "unknown"}")
                        } else {
                            println("Inside: ${response.inside}")
                            println("Area: ${response.area?.name ?: "none"}")
                        }
                    },
                    onFailure = { error ->
                        println("Kade ping failed: $error")
                    },
                )
            }
        },
        onFailure = { error ->
            println("Kade startup failed: $error")
        },
    )
}

Permissions

Core declares network and foreground location permissions. Android still requires the host app to request dangerous location permissions at runtime.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
</manifest>

private val locationPermission =
    registerForActivityResult(
        ActivityResultContracts.RequestMultiplePermissions(),
    ) { grants ->
        val precise =
            grants[Manifest.permission.ACCESS_FINE_LOCATION] == true

        if (precise) {
            beginVerification()
        } else {
            showPreciseLocationRequired()
        }
    }

fun requestKadeLocation() {
    locationPermission.launch(
        arrayOf(
            Manifest.permission.ACCESS_FINE_LOCATION,
            Manifest.permission.ACCESS_COARSE_LOCATION,
        ),
    )
}

If your Kade policy permits a server-side check without device location, set skipLocation = true in PingOptions. Confirm that policy with Kade; this is not a network-estimate API.

Core API

These signatures are from the native Kotlin Core module, not its React Native bridge.

Fingerprint submission

val fingerprint = client.currentFingerprint()
println("Visitor ID: ${fingerprint.visitorId}")

client.sendFingerprintForTraining("player-123") { result ->
    result.fold(
        onSuccess = { json -> println("Server response: $json") },
        onFailure = { error -> println("Submission failed: $error") },
    )
}

Configuration

GeoFenceConfig

PingOptions

val options = PingOptions(
    userId = "player-123",
    silent = false,
    skipLocation = false,
    source = "deposit",
    regionId = 123,
    email = "player@example.com",
    firstName = "Player",
    lastName = "One",
)

Every option has a default. source is a free-form flow tag, regionId overrides configuration for that ping, and identity fields are associated with the server-side client record.

Lifecycle and continuous checks

Register handlers before starting continuous checks and stop them when the protected flow ends. Core includes AndroidX process lifecycle support for its continuous controller.

client.onPingResponse = { response ->
    runOnUiThread {
        updateAccessState(response)
    }
}

client.onPingError = { error ->
    runOnUiThread {
        showVerificationError(error)
    }
}

try {
    client.startContinuousPing(
        PingOptions(
            userId = "player-123",
            source = "session",
        ),
    )
} catch (error: GeoFenceSdkException) {
    handleLocationSetupError(error.errorCode)
}

// When the verified flow ends:
client.stopContinuousPing()

// When disposing the entire integration:
client.destroy()

• startContinuousPing returns before doing anything if startup has not completed.
• Starting again while a controller exists does nothing.
• Location validation can throw before the controller starts.
• Callbacks are not documented as main-thread callbacks. Marshal UI work to the main thread.
• destroy() leaves the singleton available for a later successful start.

Response handling

Branch on blocked first, tolerate nullable fields, and keep failed Result values separate from server verdicts.

fun handle(response: PingResponse) {
    if (response.blocked == true) {
        denyAccess(
            code = response.code,
            message = response.message,
        )
        return
    }

    if (response.inside) {
        allowAccess(response.area?.name)
    } else {
        showOutsideRegion(response.distanceToBorder)
    }

    if (response.requestLocation == true) {
        // Revisit permission and location services before the next check.
    }
}

Location setup errors

fun handleLocationSetupError(code: String) {
    when (code) {
        GeoFenceErrorCodes.LOCATION_PERMISSION_MISSING ->
            requestLocationPermission()
        GeoFenceErrorCodes.LOCATION_PERMISSION_PRECISE_REQUIRED ->
            explainPreciseLocation()
        GeoFenceErrorCodes.LOCATION_SERVICES_DISABLED ->
            promptToEnableLocationServices()
        else ->
            showVerificationUnavailable()
    }
}