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 frisches 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 kurzlebiges JWT.

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';

// Ihr Backend ruft Surts POST /geolocation/preflight mit dem
// sp_live_*-API-Schlüssel auf und gibt das erzeugte JWT an den Client zurück.
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) {
        // Mit Zahlung fortfahren
      } else {
        // Transaktion abgelehnt - result.riskLevel prüfen
      }
    } catch (error) {
      // SDK-Fehler behandeln (Netzwerk, nicht initialisiert, ungültiges jwt usw.)
    }
  };

  return <Button onPress={handlePayment} title="Pay" />;
}

warnung

Holen Sie immer ein frisches JWT unmittelbar vor jedem verify()-Aufruf. Jedes JWT ist einmalig verwendbar - die Wiederverwendung eines JWT wird vom Backend abgelehnt.

Ergebnis-Diagnose

Das verify()-Ergebnis enthält ein optionales diagnostics-Objekt, das beschreibt, was das SDK während der Transaktion beobachtet hat. Es ist additiv - lies es für mehr Einblick aus oder ignoriere es.

const result = await verify(jwt);
if (result.diagnostics?.location === 'denied') {
  // den Nutzer auffordern, den Standort zu aktivieren
}

diagnostics.location ist collected · denied · unavailable · timeout · not_requested; diagnostics.networkIntel ist collected · unavailable; diagnostics.warnings ist ein Array von { code, signal }; diagnostics.timings (nur Android, v0.5.2+) enthält Millisekunden pro Phase plus total. Siehe Fehlercodes → Ergebnis-Diagnose.

Woher Kunden- und Transaktionskontext stammen

In v0.3.0 ruft der Client nicht mehr setCustomer() auf und übergibt auch keinen Transaktionstyp mehr an verify(). Stattdessen setzt Ihr Backend diesen gesamten Kontext, wenn es das JWT erzeugt.

Wenn Ihr Backend POST /geolocation/preflight aufruft, übergibt es customer_id, transaction_type und optional transaction_name, name und email. Diese Werte werden in das JWT eingebacken, sodass der Client nur das Token übergeben muss:

const jwt = await fetchVerifyJwt(); // Backend hat Kunden- + Transaktionskontext gesetzt
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

Standortüberschreibung pro Aufruf

Überschreiben Sie den collectLocation-Standard für einen einzelnen Aufruf:

// Standort für diesen Aufruf überspringen
const result = await verify(jwt, { collectLocation: false });

// Standort für diesen Aufruf anfordern
const result = await verify(jwt, { collectLocation: true });

// Initialisierungsstandard verwenden
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 gegenüber dem Initialisierungswert.
• 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 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

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.

Verifizierungsergebnis

interface VerificationResult {
  allowed: boolean;               // Backend-Entscheidung - true = fortfahren
  riskLevel: RiskLevel;           // 'low' | 'medium' | 'high' | 'blocked' | 'unknown'
  sessionId: string;              // Transaktions-ID für Support-Referenz
  errors?: string[];              // Backend-Fehlermeldungen, falls vorhanden
  timestamp: number;              // Antwortzeitstempel (ms)
  metadata?: Record<string, any>; // Zusätzliche Backend-Metadaten
}

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';

// Ihr Backend ruft Surts POST /geolocation/preflight mit dem
// sp_live_*-API-Schlüssel auf und gibt das erzeugte JWT an den Client zurück.
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 environment="production" collectLocation={true}>
      <HomeScreen />
    </GuardianProvider>
  );
}