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.
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):
SURT_GITHUB_TOKEN=<YOUR_TOKEN>
Ersetzen Sie <YOUR_TOKEN> durch das von Surt bereitgestellte Token.
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:
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") ?: ""
}
}
}
}
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:
dependencies {
implementation 'com.surt.guardian:securitysdk:0.5.2'
}
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:
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:
<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:
<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.
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
| Option | Standard | Beschreibung |
|---|---|---|
collectLocation | false | GPS-Koordinaten. Erfordert Standortberechtigungen im Manifest. |
collectWifiInfo | false | WiFi-Netzwerkdetails. Erfordert ACCESS_FINE_LOCATION unter Android 10 und neuer. |
collectSimCardInfo | false | SIM-/Carrier-Informationen. Erfordert die Berechtigung READ_PHONE_STATE. |
collectCameraInfo | false | Kameraanzahl. 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:
override fun onResume() {
super.onResume()
GuardianSDK.getInstance().setActivity(this)
}
override fun onPause() {
super.onPause()
GuardianSDK.getInstance().setActivity(null)
}
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):
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:
{
"data": {
"token": "<jwt>"
}
}
Ihre App holt das JWT von Ihrem eigenen Backend-Endpoint:
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 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.
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:
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:
// 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.
// 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
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
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_type | Anwendungsfall |
|---|---|
login | Benutzeranmeldung |
sign_up | Neues Konto erstellen |
deposit | Einzahlung |
withdrawal | Auszahlung |
| Jeder andere String | Ein von Ihnen definierter eigener Typ mit bis zu 64 Zeichen |
Siehe Transaktionstypen.
Fehlerbehebung
| Fehler | Ursache | Lösung |
|---|---|---|
| "Could not resolve com.surt.guardian:securitysdk" | Token nicht konfiguriert oder Repository nicht hinzugefügt | Prüfen Sie gradle.properties und settings.gradle |
| "401 Unauthorized" von maven.pkg.github.com | Token abgelaufen oder ungültig | Fordern Sie ein neues Token von Surt an |
IllegalStateException von getInstance() | getInstance() wurde vor initialize() aufgerufen | Rufen Sie initialize() in Application.onCreate() auf |
IOException mit HTTP 401 oder HTTP 403 in der Meldung | JWT fehlt, ist fehlerhaft aufgebaut oder abgelaufen | Fordern Sie für jeden Aufruf ein neues JWT von Ihrem Backend an |