Android SDK

Same dashboard and API as the web SDKs. The Android SDK collects device signals with a public key and returns an eventId. Your backend verifies with a secret key.

Requirements

Min SDK 21, Target SDK 36
Kotlin 1.9+ (Java 11 bytecode)
Internet access on device

Install

Maven Central:

dependencies {
    implementation("com.keverd:fraud-sdk:1.0.0")
}

Private GitHub Packages publishing is also supported for internal builds — use the same com.keverd:fraud-sdk coordinates when configured.

API keys

Use a public key only (kv_pk_test_… / kv_pk_live_…).

Never put a secret key (kv_sk_…) in the Android app. Secret keys are for server verify only.

Get keys at dashboard.keverd.com → Integrate → API keys. See API keys.

Permissions

Merged from the library manifest:

Permission	Required	Purpose
`INTERNET`	Yes	API calls
`ACCESS_NETWORK_STATE`	Yes	Network signals
`READ_PHONE_STATE`	Optional	Richer SIM / mobile signals (request at runtime)

Initialize

Call once — typically in Application.onCreate:

import com.keverd.sdk.Config
import com.keverd.sdk.Keverd

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Keverd.init(
            this,
            Config(
                apiKey = BuildConfig.KEVERD_PUBLIC_KEY, // kv_pk_…
                endpoint = "https://api.keverd.com",   // optional
                consentRequired = true,                // default true
                debug = BuildConfig.DEBUG,             // optional
            ),
        )
    }
}

`Config`

Field	Required	Default	Notes
`apiKey`	Yes	—	Public key (`kv_pk_…`)
`endpoint`	No	`https://api.keverd.com`	API base URL
`userId`	No	`null`	Optional integrator id
`consentRequired`	No	`true`	When `true`, call `setConsent(true)` before collect
`debug`	No	`false`	Logs OkHttp request/response

When consentRequired = true (default):

Keverd.setConsent(true)

Without consent, getVisitorData() fails with KeverdError.Code.CONSENT_REQUIRED (or returns Result.ConsentRequired on the callback API).

Collect

Kotlin (suspend)

lifecycleScope.launch {
    try {
        val data = Keverd.getVisitorData()
        // Send data.eventId to your backend
        Log.d("Keverd", "visitor=${data.visitorId} risk=${data.riskScore} action=${data.action}")
    } catch (e: KeverdError) {
        Log.e("Keverd", "${e.code}: ${e.message}")
    }
}

Callback (Java-friendly)

Keverd.getVisitorData { result ->
    when (result) {
        is Result.Success -> {
            val data = result.data
            // data.eventId → your backend
        }
        is Result.ConsentRequired -> { /* show consent UI */ }
        is Result.Error -> {
            Log.e("Keverd", "${result.error.code}: ${result.error.message}")
        }
    }
}

getVisitorData() calls POST /v2/fingerprint with header X-API-Key (and X-SDK-Source: android).

Response (`VisitorData`)

Field	Type	Notes
`visitorId`	`String`	Stable device id (`kvd_…`, from API `fingerprint`)
`eventId`	`String`	Send this to your server for verify
`requestId`	`String`	Same id family as `eventId`
`sessionId`	`String`	Session id
`riskScore`	`Int`	0–100 style score from collect
`score`	`Double`	Normalized score
`action`	`Action`	`ALLOW`, `SOFT_CHALLENGE`, `HARD_CHALLENGE`, `BLOCK`
`reasons`	`List<String>`	Reason codes
`similarity`	`Double?`	Optional
`isNew` / `timesSeen` / `firstSeen` / `lastSeen`	optional	Device history hints
`adaptiveResponse`	optional	Challenge hints when present

Send the event id to your backend:

{
  "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Your server then calls POST /v2/verify with { "event_id": "…" } using a secret key. See Server SDKs.

There is no separate getVisitorId() API. Use VisitorData.visitorId after getVisitorData().

Attaches login context to the collect request (POST /fingerprint/verify/login). This still uses the public key and does not replace server verify().

import com.keverd.sdk.util.LoginIdentifierHash
import com.keverd.sdk.verify.AuthMethod
import com.keverd.sdk.verify.LoginContext
import com.keverd.sdk.verify.LoginResult
import com.keverd.sdk.verify.VerifyLoginOptions

val data = Keverd.verifyLogin(
    VerifyLoginOptions(
        login = LoginContext(
            identifierHash = LoginIdentifierHash.fromIdentifier(email),
            result = LoginResult.SUCCESS, // or FAILURE
            authMethod = AuthMethod.PASSWORD,
            mfaUsed = true,
        ),
    ),
)
// Still send data.eventId to your backend for authoritative verify

LoginIdentifierHash.fromIdentifier(identifier) produces sha256:<hex> of the lowercased identifier (optional salt). Never send raw emails/phones as the hash input if your policy forbids it — hash client-side first.

`LoginContext`

Field	Type	Notes
`identifierHash`	`String`	Prefer `LoginIdentifierHash.fromIdentifier(...)`
`result`	`LoginResult`	`SUCCESS` \| `FAILURE`
`failureReason`	`String?`	Optional
`authMethod`	`AuthMethod`	e.g. `PASSWORD`, `SSO`, `PASSKEY`, `UNKNOWN`
`mfaUsed`	`Boolean?`	Optional
`attemptId`	`String?`	Optional

Behavioral signals (optional)

Improve signal quality by attaching listeners on screens where users interact:

// Activity — touch kinematics
Keverd.attachBehavioralMonitoring(this)

// Login / form fields — keystroke timing
Keverd.attachToEditText(binding.emailEditText)
Keverd.attachToEditText(binding.passwordEditText)

// Or a custom touch listener
view.setOnTouchListener(Keverd.createTouchListener())

Preview signals (debug)

val snapshot = Keverd.previewCollectedSignals()
// Local signals only — does not call the API

Useful in the sample app / debug builds. Do not use as a substitute for getVisitorData().

Errors

Suspend APIs throw KeverdError. The callback API returns Result.Error(KeverdError).

`KeverdError.Code`	When
`NOT_INITIALIZED`	`Keverd.init` not called
`CONSENT_REQUIRED`	Consent gate blocked collect
`UNAUTHORIZED`	HTTP 401 (bad / missing public key)
`INVALID_REQUEST`	HTTP 400
`NETWORK_ERROR`	Timeout / connectivity
`SERVER_ERROR`	HTTP 5xx
`PARSE_ERROR`	Unexpected / incomplete API payload
`UNKNOWN`	Other failures

try {
    Keverd.getVisitorData()
} catch (e: KeverdError) {
    when (e.code) {
        KeverdError.Code.CONSENT_REQUIRED -> { /* prompt user */ }
        KeverdError.Code.UNAUTHORIZED -> { /* check kv_pk_ key */ }
        KeverdError.Code.NETWORK_ERROR -> { /* retry */ }
        else -> Log.e("Keverd", e.message, e)
    }
}

ProGuard / R8

The published AAR ships consumer ProGuard rules that keep the public SDK surface (Keverd, Config, VisitorData, Result*, KeverdError, Action, verify types, and API DTOs). Extra keep rules are usually unnecessary.

Deprecated API

KeverdFingerprint.init / submit(...) remains as a thin 1.0.x migration wrapper. Prefer:

Keverd.init(context, config)
Keverd.setConsent(true)
Keverd.getVisitorData()

End-to-end flow

App calls Keverd.getVisitorData() with kv_pk_…
App sends eventId to your backend
Backend calls POST /v2/verify with kv_sk_… and { "event_id": "…" }
Enforce returned action: allow | soft_challenge | hard_challenge | block

Optional: subscribe to webhooks after verify.

Getting started

Client Side SDKs

Server Side SDKs

API Reference

Android SDK

Android SDK

Requirements

Install

API keys

Permissions

Initialize

`Config`

Collect

Kotlin (suspend)

Callback (Java-friendly)

Response (`VisitorData`)

`LoginContext`

Behavioral signals (optional)

Preview signals (debug)

Errors

ProGuard / R8

Deprecated API

End-to-end flow

Next

​Android SDK

​Requirements

​Install

​API keys

​Permissions

​Initialize

​Config

​Consent

​Collect

​Kotlin (suspend)

​Callback (Java-friendly)

​Response (VisitorData)

​Login verification (collect with login context)

​LoginContext

​Behavioral signals (optional)

​Preview signals (debug)

​Errors

​ProGuard / R8

​Deprecated API

​End-to-end flow

​Next

Android SDK

Requirements

Install

API keys

Permissions

Initialize

`Config`

Consent

Collect

Kotlin (suspend)

Callback (Java-friendly)

Response (`VisitorData`)

Login verification (collect with login context)

`LoginContext`

Behavioral signals (optional)

Preview signals (debug)

Errors

ProGuard / R8

Deprecated API

End-to-end flow

Next