Zum Hauptinhalt springen
Version: Guardian v0.5.3

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():

PaymentScreen.tsx
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" />;
}
warnung

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.

TypAnwendungsfall
loginBenutzeranmeldung
sign_upNeues Konto erstellen
depositEinzahlung
withdrawalAuszahlung
Jeder andere StringEin 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 } an verify() übergeben, gewinnt dies unter iOS gegenüber dem Initialisierungswert. Unter Android wirkt es nur, wenn collectLocation auch bei der Initialisierung true war.
  • Wenn Sie { collectLocation: false } an verify() übergeben, wird GPS übersprungen, selbst wenn die Initialisierung true war.
  • Wenn Sie es weglassen, wird der Initialisierungsstandard aus GuardianProvider / initialize() verwendet.

In der Praxis bedeutet das:

Dashboard GPSIhr Code sagtErgebnis
aktivierttrue (Init oder Überschreibung)GPS erfasst
aktiviertfalse (Init oder Überschreibung)Kein GPS: Sie haben sich abgemeldet
deaktivierttrue (Init oder Überschreibung)Kein GPS: Dashboard hat es deaktiviert
deaktiviertfalse (Init oder Überschreibung)Kein GPS
Kernaussage

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​

App.tsx
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>
);
}