Zum Hauptinhalt springen
Version: Guardian v0.5.3

Android

Native Android-Integration für das Surt Guardian SDK, verteilt über Maven (GitHub Packages). Das SDK erfasst Gerätesignale, führt Geräteintegritätsprüfungen durch und gibt die Risikoentscheidung des Backends zurück.

Das SDK hält niemals einen Surt-API-Schlüssel. Ihr Backend hält den sp_live_*-Schlüssel (nur serverseitig) und tauscht ihn gegen ein kurzlebiges JWT, das die App an verify() übergibt.

Version

Diese Anleitung behandelt das SDK v0.5.2.

Voraussetzungen​

  • Android SDK 24+ (Android 7.0+)
  • Kotlin 1.9+
  • Gradle 8+
  • Java 17

1. Authentifizierung​

Fügen Sie Ihr Zugriffstoken zur gradle.properties Ihres Projekts hinzu (oder zu ~/.gradle/gradle.properties für alle Projekte):

gradle.properties
SURT_GITHUB_TOKEN=<YOUR_TOKEN>

Ersetzen Sie <YOUR_TOKEN> durch das von Surt bereitgestellte Token.

warnung

Checken Sie gradle.properties mit Tokens nicht in die Versionskontrolle ein. Fügen Sie die Datei zu .gitignore hinzu oder verwenden Sie stattdessen ~/.gradle/gradle.properties.

2. Repository hinzufügen​

Fügen Sie in der settings.gradle (oder settings.gradle.kts) Ihres Projekts das Surt-Maven-Repository hinzu:

settings.gradle
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven {
url = uri("https://maven.pkg.github.com/surtTech/surt-guardian-sdk")
credentials {
username = "surt-customer"
password = settings.ext.find("SURT_GITHUB_TOKEN")
?: System.getenv("SURT_GITHUB_TOKEN") ?: ""
}
}
}
}
settings.gradle.kts
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven {
url = uri("https://maven.pkg.github.com/surtTech/surt-guardian-sdk")
credentials {
username = "surt-customer"
password = providers.gradleProperty("SURT_GITHUB_TOKEN").orNull
?: System.getenv("SURT_GITHUB_TOKEN")
}
}
}
}

3. Abhängigkeit hinzufügen​

In der build.gradle (oder build.gradle.kts) Ihrer App:

build.gradle
dependencies {
implementation 'com.surt.guardian:securitysdk:0.5.2'
}
build.gradle.kts
dependencies {
implementation("com.surt.guardian:securitysdk:0.5.2")
}

Core Library Desugaring​

Wenn Ihre App auf minSdk < 26 abzielt, stellen Sie sicher, dass Core Library Desugaring in der build.gradle Ihrer App aktiviert ist:

build.gradle
android {
compileOptions {
coreLibraryDesugaringEnabled true
}
}

dependencies {
coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.4'
}

4. AndroidManifest-Berechtigungen​

Wenn Sie die Standorterfassung aktivieren, fügen Sie diese Berechtigungen zu Ihrer AndroidManifest.xml hinzu:

AndroidManifest.xml
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Wenn Sie die SIM-Karten-Informationserfassung aktivieren, fügen Sie diese Berechtigung hinzu:

AndroidManifest.xml
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

Das SDK fordert die Standortberechtigung während verify() oder collect() an, wenn collectLocation aktiviert ist und Sie die aktuelle Activity gesetzt haben (siehe Schritt 6). Der Standard-Berechtigungsdialog von Android erscheint ohne zusätzlichen Code.

Das SDK wartet nicht auf die Antwort des Benutzers im Berechtigungsdialog, sodass der Aufruf, der den Dialog anzeigt, keinen Standort enthält. Der Standort ist ab dem nächsten Aufruf enthalten. Das SDK meldet den letzten bekannten Standort des Geräts und fordert keine neue Position an.

5. SDK initialisieren​

Einmal beim App-Start aufrufen (üblicherweise in Ihrer Application-Klasse). Im SDK ist kein API-Schlüssel erforderlich - Ihr serverseitiger API-Schlüssel gelangt nie auf das Gerät.

MyApplication.kt
import android.app.Application
import com.surt.guardian.GuardianSDK
import com.surt.guardian.core.FailurePolicy
import com.surt.guardian.core.GuardianOptions

class MyApplication : Application() {
override fun onCreate() {
super.onCreate()

GuardianSDK.initialize(
context = this,
options = GuardianOptions(
failurePolicy = FailurePolicy.Fail,
collectLocation = true // Enable GPS collection (optional)
)
)
}
}

Das SDK spricht immer die Produktion unter https://api.surt.com an.

GuardianOptions akzeptiert außerdem logLevel, aber das SDK wendet die Option bei der Initialisierung nicht an. Es protokolliert auf der Stufe INFO.

Datenerfassungsoptionen​

OptionStandardBeschreibung
collectLocationfalseGPS-Koordinaten. Erfordert Standortberechtigungen im Manifest.
collectWifiInfofalseWiFi-Netzwerkdetails. Erfordert ACCESS_FINE_LOCATION unter Android 10 und neuer.
collectSimCardInfofalseSIM-/Carrier-Informationen. Erfordert die Berechtigung READ_PHONE_STATE.
collectCameraInfofalseKameraanzahl. Keine Berechtigung erforderlich.

Wenn collectLocation aktiviert ist, fragt das SDK den Benutzer nach der Standortberechtigung, sobald verify() oder collect() sie zum ersten Mal benötigt. Lehnt der Benutzer ab, fährt das SDK ohne GPS-Daten fort.

6. Activity-Referenz (für automatische Berechtigungsanfragen)​

Damit das SDK den Berechtigungsdialog anzeigen kann, benötigt es eine Referenz auf die aktuelle Activity. Rufen Sie setActivity() im Lebenszyklus Ihrer Activity auf:

MainActivity.kt
override fun onResume() {
super.onResume()
GuardianSDK.getInstance().setActivity(this)
}

override fun onPause() {
super.onPause()
GuardianSDK.getInstance().setActivity(null)
}
hinweis

Wenn Sie setActivity() nicht aufrufen, funktioniert das SDK weiterhin, kann aber keine Berechtigungen automatisch anfordern. Sie müssten die Berechtigungen dann selbst anfordern, bevor Sie verify() aufrufen.

7. JWT von Ihrem Backend erzeugen​

Vor jedem verify()-Aufruf muss Ihre App ein JWT von Ihrem eigenen Backend holen. Ihr Backend ruft POST /geolocation/preflight mit seinem serverseitigen API-Schlüssel und dem Transaktionskontext auf und gibt dann das JWT an die App zurück.

Beispiel für den Backend-Aufruf (Ihr Server, nicht die App):

Backend preflight request
POST /geolocation/preflight
Authorization: Bearer sp_live_xxx
Content-Type: application/json

{
"customer_id": "user_abc123",
"transaction_type": "login",
"transaction_name": "User Login",
"name": "John Doe",
"email": "john@example.com"
}

Nur transaction_type ist erforderlich. Alle Felder finden Sie unter Authentifizierung.

Die Preflight-Antwort liefert das Token, das Ihre App benötigt:

Preflight response
{
"data": {
"token": "<jwt>"
}
}

Ihre App holt das JWT von Ihrem eigenen Backend-Endpoint:

Fetch JWT from your backend
suspend fun fetchVerifyJwt(): String {
// Call your OWN backend endpoint, not Surt directly
val response = httpClient.post("https://your-api.com/geolocation-jwt")
return response.body<YourJwtResponse>().jwt
}
Fordern Sie für jeden Aufruf ein neues JWT an

Fordern Sie unmittelbar vor dem Aufruf von verify() ein neues JWT an. Ein JWT läuft 30 Minuten nach der Ausstellung ab.

8. Eine Transaktion verifizieren​

Rufen Sie die Methode bei sicherheitssensiblen Momenten auf (Login, Zahlung usw.). Holen Sie unmittelbar vor jedem Aufruf ein JWT von Ihrem Backend.

Coroutines (recommended)
val jwt = fetchVerifyJwt()

// verifySuspend returns a Result. getOrThrow() throws when the call failed.
val result = GuardianSDK.getInstance().verifySuspend(jwt = jwt).getOrThrow()

if (result.allowed) {
// Proceed with the transaction
} else {
// Handle denied transaction (result.riskLevel has details)
}

Oder mit einem Callback:

Callback
val jwt = fetchVerifyJwt()

GuardianSDK.getInstance().verify(jwt = jwt) { result ->
result.onSuccess { verification ->
if (verification.allowed) { /* proceed */ }
}
result.onFailure { error ->
// error is an IOException or a SurtError. See Error Codes.
}
}

Standortüberschreibung pro Aufruf:

Per-call location override
// Skip location for this call, regardless of the init default
val result = GuardianSDK.getInstance().verifySuspend(
jwt = jwt,
collectLocation = false
).getOrThrow()

collectLocation = true bei einem Aufruf wirkt nur, wenn collectLocation auch bei der Initialisierung true war.

9. Collect (Server-zu-Server, optional)​

collect() gibt ein verschlüsseltes Payload zurück, das Ihr Backend an Surt weiterleitet. collect() sendet das Geräte-Payload nicht an Surt. Ihr Backend sendet es.

Collect payload
// Without JWT: no resolved public IP in the payload
val result = GuardianSDK.getInstance().collectSuspend().getOrThrow()

// With JWT: resolves the device public IP (GET /geolocation/client-ip)
// into the payload and applies your attestation settings
val jwtForCollect = fetchCollectJwt()
val resultWithIp = GuardianSDK.getInstance().collectSuspend(jwt = jwtForCollect).getOrThrow()

// Send result.payload to your backend
JWT ist für collect optional

Das JWT für collect() ist optional. Übergeben Sie es, damit die öffentliche IP des Geräts in das Payload aufgelöst und die Attestierungseinstellungen Ihrer Organisation angewendet werden: wie oft ein Gerät attestiert und Ihr eigenes Play-Integrity-Projekt. Ohne JWT attestiert das SDK bei jedem Aufruf mit dem Standardprojekt. Wie Sie diese Einstellungen konfigurieren, erfahren Sie unter Einrichtung der Geräte-Attestierung. Fordern Sie für jede Transaktion ein neues JWT an.

Verifizierungsergebnis​

VerificationResult
data class VerificationResult(
val allowed: Boolean, // Backend decision - true = proceed
val riskLevel: RiskLevel, // LOW / MEDIUM / HIGH / BLOCKED / UNKNOWN
val sessionId: String, // Transaction ID for support reference
val errors: List<String>?, // Error messages, if any
val timestamp: Long, // Response timestamp (ms)
val metadata: Map<String, Any>?, // Additional backend metadata
val diagnostics: GuardianDiagnostics // What the SDK observed during the call
)

Die diagnostics-Felder finden Sie unter Ergebnis-Diagnose.

Transaktionstypen​

Diese Werte werden von Ihrem Backend im Preflight-Feld transaction_type gesetzt. Sie werden in der App nicht an verify() übergeben.

transaction_typeAnwendungsfall
loginBenutzeranmeldung
sign_upNeues Konto erstellen
depositEinzahlung
withdrawalAuszahlung
Jeder andere StringEin von Ihnen definierter eigener Typ mit bis zu 64 Zeichen

Siehe Transaktionstypen.

Fehlerbehebung​

FehlerUrsacheLösung
"Could not resolve com.surt.guardian:securitysdk"Token nicht konfiguriert oder Repository nicht hinzugefügtPrüfen Sie gradle.properties und settings.gradle
"401 Unauthorized" von maven.pkg.github.comToken abgelaufen oder ungültigFordern Sie ein neues Token von Surt an
IllegalStateException von getInstance()getInstance() wurde vor initialize() aufgerufenRufen Sie initialize() in Application.onCreate() auf
IOException mit HTTP 401 oder HTTP 403 in der MeldungJWT fehlt, ist fehlerhaft aufgebaut oder abgelaufenFordern Sie für jeden Aufruf ein neues JWT von Ihrem Backend an