iOS
Native iOS-Integration für das Surt Guardian SDK, verteilt über Swift Package Manager. 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
- iOS 14.0+
- Xcode 14+
- Swift 5.7+
1. Authentifizierung
Fügen Sie Ihr Zugriffstoken zu ~/.netrc hinzu, damit Xcode das private Repository klonen kann:
machine github.com
login surt-customer
password <YOUR_TOKEN>
Ersetzen Sie <YOUR_TOKEN> durch das von Surt bereitgestellte Token.
Falls ~/.netrc nicht existiert, erstellen Sie die Datei. Stellen Sie sicher, dass sie eingeschränkte Berechtigungen hat:
chmod 600 ~/.netrc
2. Paket hinzufügen
- Gehen Sie in Xcode zu File > Add Package Dependencies
- Geben Sie die Repository-URL ein:
https://github.com/surtTech/surt-guardian-sdk - Setzen Sie die Versionsregel auf "Up to Next Minor" ab 0.5.2
- Klicken Sie auf Add Package
- Wählen Sie die Bibliothek SurtGuardianSDK aus und fügen Sie sie Ihrem Target hinzu
3. Info.plist-Berechtigungen konfigurieren
Wenn Sie die Standorterfassung aktivieren, fügen Sie diesen Schlüssel zu Ihrer Info.plist hinzu:
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location helps verify your identity and protect your account.</string>
Das SDK fordert die Standortberechtigung während verify() oder collect() an, wenn die Standorterfassung aktiviert ist. Der Systemdialog erscheint ohne zusätzlichen Code. Es ist kein weiterer Info.plist-Schlüssel nötig.
4. SDK initialisieren
Einmal beim App-Start aufrufen, vor jeder anderen SDK-Methode. Im SDK ist kein API-Schlüssel erforderlich - Ihr serverseitiger API-Schlüssel gelangt nie auf das Gerät.
import SurtGuardianSDK
// In your AppDelegate or App init:
GuardianSDK.initialize(
options: GuardianOptions(
failurePolicy: .fail,
logLevel: .warn,
collectLocation: true // Enable GPS collection (optional)
)
)
Das SDK spricht immer die Produktion unter https://api.surt.com an.
Datenerfassungsoptionen
| Option | Standard | Beschreibung |
|---|---|---|
collectLocation | false | GPS-Koordinaten. Erfordert NSLocationWhenInUseUsageDescription in der Info.plist. |
GuardianOptions akzeptiert außerdem collectWifiInfo, collectSimCardInfo und collectCameraInfo. Sie gelten nur für Android und haben unter iOS keine Wirkung.
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.
5. 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:
// In your app - call your OWN backend, not Surt directly
func fetchVerifyJwt() async throws -> String {
let response = try await URLSession.shared.data(
for: URLRequest(url: URL(string: "https://your-api.com/geolocation-jwt")!)
)
// Parse and return the JWT string from your backend response
let body = try JSONDecoder().decode(YourJwtResponse.self, from: response.0)
return body.jwt
}
Fordern Sie unmittelbar vor dem Aufruf von verify() ein neues JWT an. Ein JWT läuft 30 Minuten nach der Ausstellung ab.
6. 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.
let jwt = try await fetchVerifyJwt()
let result = try await GuardianSDK.shared.verify(jwt: jwt)
if result.allowed {
// Proceed with the transaction
} else {
// Handle denied transaction (result.riskLevel has details)
}
Oder mit einem Completion-Handler (iOS 14+):
let jwt = try await fetchVerifyJwt()
GuardianSDK.shared.verify(jwt: jwt) { result in
switch result {
case .success(let verification):
if verification.allowed { /* proceed */ }
case .failure(let error):
// error is a SurtError: .notInitialized or .networkError
print(error.localizedDescription)
}
}
Standortüberschreibung pro Aufruf:
// Request location for this call, regardless of the init default
let result = try await GuardianSDK.shared.verify(
jwt: jwt,
collectLocation: true
)
7. 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
let result = try await GuardianSDK.shared.collect()
// With JWT: resolves the device public IP (GET /geolocation/client-ip)
// into the payload and applies your attestation settings
let jwtForCollect = try await fetchCollectJwt()
let resultWithIp = try await GuardianSDK.shared.collect(jwt: jwtForCollect)
// 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 Attestierungskadenz Ihrer Organisation angewendet wird. Ohne JWT attestiert das SDK bei jedem Aufruf. App Attest besteht nur für die App-IDs, die Ihre Organisation registriert: siehe Einrichtung der Geräte-Attestierung. Fordern Sie für jede Transaktion ein neues JWT an.
Verifizierungsergebnis
struct VerificationResult {
let allowed: Bool // Backend decision - true = proceed
let riskLevel: RiskLevel // .low / .medium / .high / .blocked / .unknown
let sessionId: String // Transaction ID for support reference
let errors: [String]? // Error messages, if any
let timestamp: TimeInterval // Response timestamp
let metadata: [String: Any]? // Additional backend metadata
let 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 |
|---|---|---|
| "Package resolution failed" | Token nicht konfiguriert oder abgelaufen | Prüfen Sie, ob ~/.netrc das richtige Token enthält |
.notInitialized | verify() wurde vor initialize() aufgerufen | Rufen Sie initialize() beim App-Start auf |
.networkError | Keine Verbindung, eine Zeitüberschreitung oder ein HTTP-Fehler von Surt. Ein fehlendes, fehlerhaft aufgebautes oder abgelaufenes JWT ist eine mögliche Ursache. | Prüfen Sie die Verbindung und fordern Sie für jeden Aufruf ein neues JWT von Ihrem Backend an |