> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insightsecure.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Android SDK — Integration Guide
> Installing and integrating the InsightAI RASP SDK for Android
github.com/InsightAI-Pinnacle-Technologies/di-sdk-android-rasp-v1.0.2
## Requirements
* `minSdk 24` (Android 7.0+)
* NDK r26+ and CMake 3.22+ — required for the native ptrace/TracerPid layer that makes debugger/Frida detection resistant to Java-layer hooking
* A GitHub Personal Access Token with `read:packages` scope (this SDK is distributed privately via GitHub Packages while pre-GA — see [Authentication](/api-reference/authentication) for your tenant credentials, which are separate from your GitHub PAT)
## Install
```groovy settings.gradle theme={null}
dependencyResolutionManagement {
repositories {
maven {
url = uri("https://maven.pkg.github.com/InsightAI-Pinnacle-Technologies/di-sdk-android-rasp-v1.0.2")
credentials {
username = "your-github-username"
password = "your-github-personal-access-token"
}
}
}
}
```
```groovy app/build.gradle theme={null}
dependencies {
implementation 'ai.insight:rasp-sdk:1.0.0'
}
```
Android Studio → Tools → SDK Manager → SDK Tools tab → check "NDK (Side by side)" and "CMake". Without this, the native detection layer won't link — see [Testing](#testing-each-control) for how to confirm it did.
## Initialize
```kotlin theme={null}
// Application.onCreate()
InsightAiSdk.init(
context = this,
config = InsightAiConfig(
tenantId = "your_tenant_id",
ingestUrl = "https://ingest.insightsecure.ai/v1/rasp/ingest",
hmacSecretKey = BuildConfig.INSIGHTAI_HMAC_SECRET, // from your tenant credentials — see Authentication
expectedApkSignatureHashes = setOf(""),
maliciousPackageList = RemoteThreatList.current(), // fetch from your backend, don't hardcode
)
)
```
## Gate a sensitive action
```kotlin theme={null}
val evaluation = InsightAiSdk.evaluate(context)
when (evaluation.raspAction) {
"BLOCK" -> showBlockedScreen()
"REVIEW" -> proceedWithStepUpAuth()
else -> proceedNormally()
}
```
## Protect a sensitive screen
```kotlin theme={null}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
InsightAiSdk.protectScreen(this) // FLAG_SECURE — blocks screenshots, recording, mirroring
}
// Also forward touch events for active overlay detection:
override fun dispatchTouchEvent(event: MotionEvent): Boolean {
InsightAiSdk.forwardTouchEvent(event)
return super.dispatchTouchEvent(event)
}
```
## MITM detection
Wire your network layer's pin-mismatch callback:
```kotlin theme={null}
try {
val response = client.newCall(request).execute()
} catch (e: SSLPeerUnverifiedException) {
InsightAiSdk.reportSslPinMismatch(host = request.url.host)
throw e
}
```
2+ mismatches in one session sets `MITM_SUSPECTED` and hard-blocks — same tier as a signature mismatch.
## Device binding (Play Integrity)
```kotlin theme={null}
val token = PlayIntegrityBridge.requestIntegrityToken(
context = this,
cloudProjectNumber = YOUR_CLOUD_PROJECT_NUMBER, // Play Console → App Integrity
requestHash = sha256("$transactionId:$amount:$timestamp"),
)
```
This token must be verified **server-side** against Google's decode API. The SDK cannot verify it locally — a compromised client could fake a local "verified" result, which defeats the entire point of the check.
## SIM binding
Not bundled — this requires a paid third-party provider (tru.ID, Twilio Verify). The SDK ships the integration interface only:
```kotlin theme={null}
SimBindingConfig.provider = YourChosenProvider(apiKey = BuildConfig.SIM_PROVIDER_KEY)
// Gate to high-value transactions or REVIEW-tier events — per-verify
// cost compounds fast at volume if called on every evaluate().
val swapDetected = SimBindingConfig.provider?.checkSimSwap(user.phoneNumber)
```
## OTP-less authentication
```kotlin theme={null}
val response = OtpLessAuthManager.respondToChallenge(challengeNonce, deviceId)
if (response == null) {
// No binding key yet — fall back to OTP for this session
} else {
// Send response.signature to your backend for verification
}
```
## Testing each control
| Control | How to test |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Root detection | Rooted physical device (Magisk) or `adb root` on an AVD |
| Frida/debugger | `frida-server` on a rooted device, attach with `frida -U -f ` |
| Tamper (signature mismatch) | Re-sign the APK with a different keystore, reinstall |
| MITM | Route traffic through Burp Suite/mitmproxy with its CA trusted — the connection should fail before reaching the proxy |
| Overlay | Grant a test app `SYSTEM_ALERT_WINDOW`, have it draw over your app during a touch |
| Native ptrace layer specifically | Confirm the NDK actually linked — attach a debugger and check `nativeTracerNonzero` reads `true`, not just the Java-layer `debuggerConnected` |
## Known limitations
* SIM binding needs your own provider integration — not included
* Play Integrity verdict decoding is a backend responsibility, not something this SDK does
* No iOS equivalent to Android's signature-hash tamper check exists — if you also integrate InsightAI's iOS SDK, its tamper detection is a weaker sideload heuristic by platform necessity, not an oversight
## Next steps