Transaktionen verifizieren
Rufen Sie verify() bei sicherheitssensiblen Momenten auf. Das SDK erfasst Gerätesignale, führt Geräteintegritätsprüfungen durch und gibt die Risikoentscheidung des Backends zurück.
verify() erfordert ein JWT, das Ihr Backend erzeugt. 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 JWT, das nach 30 Minuten abläuft.
Grundlegende Verwendung
Holen Sie zunächst ein frisches JWT von Ihrem eigenen Backend und übergeben Sie es dann an verify():
import { useGuardian } from '@surtai/guardian-rn';
// Your backend calls Surt's POST /geolocation/preflight with the
// sp_live_* API key and returns the minted JWT to the client.
async function fetchVerifyJwt(): Promise<string> {
const res = await fetch('https://your-api.com/guardian/jwt', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
transaction_type: 'withdrawal',
transaction_name: 'User Payment',
}),
});
const { token } = await res.json();
return token;
}
function PaymentScreen() {
const { verify } = useGuardian();
const handlePayment = async () => {
try {
const jwt = await fetchVerifyJwt();
const result = await verify(jwt);
if (result.allowed) {
// Proceed with payment
} else {
// Transaction denied - check result.riskLevel
}
} catch (error) {
// Handle SDK error (network, not initialized). See Error Codes.
}
};
return <Button onPress={handlePayment} title="Pay" />;
}
Fordern Sie unmittelbar vor jedem verify()-Aufruf ein neues JWT an. Ein JWT läuft 30 Minuten nach der Ausstellung ab.
Ergebnis-Diagnose
Ab v0.5.2 enthält das verify()-Ergebnis ein optionales diagnostics-Objekt, das beschreibt, was das SDK während der Transaktion beobachtet hat. Sie können es ignorieren.
const result = await verify(jwt);
if (result.diagnostics?.location === 'denied') {
// prompt the user to enable location
}
diagnostics.location ist collected · denied · unavailable · timeout · not_requested · error; diagnostics.attestation ist collected · failed · unavailable · not_supported · not_requested; diagnostics.networkIntel ist collected · unavailable · not_requested; diagnostics.warnings ist ein Array von { code, signal, detail? }; diagnostics.timings (nur Android) enthält Millisekunden pro Phase plus total. Die Bedeutung jedes Werts und die Warncodes finden Sie unter Fehlercodes → Ergebnis-Diagnose.
Woher Kunden- und Transaktionskontext stammen
Der Client übergibt weder einen Kunden noch einen Transaktionstyp an verify(). Ihr Backend setzt diesen Kontext, wenn es das JWT erzeugt.
Wenn Ihr Backend POST /geolocation/preflight aufruft, übergibt es transaction_type und optional customer_id, transaction_name, name, email und phone. Diese Werte werden in das JWT eingebacken, sodass der Client nur das Token übergeben muss:
const jwt = await fetchVerifyJwt(); // backend set customer + transaction context
const result = await verify(jwt);
Transaktionstypen
Diese Werte werden von Ihrem Backend im Preflight-Feld transaction_type gesendet. Sie werden im Client nicht an verify() übergeben.
| Typ | 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.
Standortüberschreibung pro Aufruf
Überschreiben Sie den collectLocation-Standard für einen einzelnen Aufruf:
// Skip location for this call
const result = await verify(jwt, { collectLocation: false });
// Request location for this call
const result = await verify(jwt, { collectLocation: true });
// Use init default
const result = await verify(jwt);
Die Überschreibung gilt nur einmalig. Sie betrifft nur diesen einzelnen verify()-Aufruf.
Wie die Standorterfassung entschieden wird
Die Standorterfassung hat zwei Kontrollebenen, die zusammen ausgewertet werden. Beide müssen übereinstimmen, damit GPS-Daten erfasst werden:
1. Surt-Dashboard: GPS aktiviert (höchste Priorität)
Die GPS-Erfassung muss in Ihrem Surt-Client-Panel aktiviert sein. Wenn GPS im Dashboard deaktiviert ist, wird der Standort niemals erfasst, unabhängig davon, was Sie im Code festlegen. Aktivieren Sie es unter Einstellungen > Entwickler oder kontaktieren Sie Ihren Surt-Account-Manager.
2. Client-seitige Einstellung (Ihr Code)
Diese wird wie folgt aufgelöst: Überschreibung pro Aufruf > Initialisierungsstandard.
- Wenn Sie
{ collectLocation: true }anverify()übergeben, gewinnt dies unter iOS gegenüber dem Initialisierungswert. Unter Android wirkt es nur, wenncollectLocationauch bei der Initialisierungtruewar. - Wenn Sie
{ collectLocation: false }anverify()übergeben, wird GPS übersprungen, selbst wenn die Initialisierungtruewar. - Wenn Sie es weglassen, wird der Initialisierungsstandard aus
GuardianProvider/initialize()verwendet.
In der Praxis bedeutet das:
| Dashboard GPS | Ihr Code sagt | Ergebnis |
|---|---|---|
| aktiviert | true (Init oder Überschreibung) | GPS erfasst |
| aktiviert | false (Init oder Überschreibung) | Kein GPS: Sie haben sich abgemeldet |
| deaktiviert | true (Init oder Überschreibung) | Kein GPS: Dashboard hat es deaktiviert |
| deaktiviert | false (Init oder Überschreibung) | Kein GPS |
Ihre client-seitige collectLocation-Einstellung kann die Standorterfassung nur ablehnen. Sie kann die GPS-Erfassung nicht erzwingen, wenn das Dashboard sie deaktiviert hat. Um die GPS-Erfassung zu aktivieren, schalten Sie sie zuerst in Ihrem Surt-Client-Panel ein und setzen Sie dann collectLocation: true in Ihrem Code.
Unter Android wartet das SDK 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. Android meldet den letzten bekannten Standort des Geräts und fordert keine neue Position an.
Verifizierungsergebnis
interface VerificationResult {
allowed: boolean; // Backend decision - true = proceed
riskLevel: RiskLevel; // 'low' | 'medium' | 'high' | 'blocked' | 'unknown'
sessionId: string; // Transaction ID for support reference
errors?: string[]; // Backend error messages, if any
timestamp: number; // Response timestamp (ms)
metadata?: Record<string, any>; // Additional backend metadata
diagnostics?: GuardianDiagnostics; // What the SDK observed (v0.5.2+)
}
Für Details zu Risikostufen siehe Risikostufen.
Vollständiges Beispiel
import React, { useState } from 'react';
import { View, Button, Text, Alert } from 'react-native';
import {
GuardianProvider,
useGuardian,
type VerificationResult,
} from '@surtai/guardian-rn';
// Your backend calls Surt's POST /geolocation/preflight with the
// sp_live_* API key and returns the minted JWT to the client.
async function fetchVerifyJwt(): Promise<string> {
const res = await fetch('https://your-api.com/guardian/jwt', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
transaction_type: 'login',
transaction_name: 'User Login',
}),
});
const { token } = await res.json();
return token;
}
function HomeScreen() {
const { verify, collect, isInitialized } = useGuardian();
const [result, setResult] = useState<VerificationResult | null>(null);
const handleLogin = async () => {
try {
const jwt = await fetchVerifyJwt();
const res = await verify(jwt);
setResult(res);
Alert.alert(res.allowed ? 'Approved' : 'Denied', `Risk: ${res.riskLevel}`);
} catch (e: any) {
Alert.alert('Error', e.message);
}
};
return (
<View style={{ padding: 20 }}>
<Text>SDK Ready: {isInitialized ? 'Yes' : 'No'}</Text>
<Button title="Login & Verify" onPress={handleLogin} />
{result && <Text>Allowed: {result.allowed ? 'Yes' : 'No'}</Text>}
</View>
);
}
export default function App() {
return (
<GuardianProvider collectLocation={true}>
<HomeScreen />
</GuardianProvider>
);
}