Pular para o conteúdo principal
Versão: Guardian v0.5.3

Verificar Transações

Chame verify() em momentos sensíveis para a segurança. O SDK coleta sinais do dispositivo, executa verificações de integridade do dispositivo e retorna a decisão de risco do backend.

verify() requer um JWT que seu backend gera. O SDK nunca guarda uma chave de API da Surt. Seu backend guarda a chave sp_live_* (somente no lado do servidor) e a troca por um JWT que expira após 30 minutos.

Uso Básico​

Primeiro, obtenha um JWT novo do seu próprio backend e depois passe-o para 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" />;
}
aviso

Solicite um novo JWT imediatamente antes de cada chamada verify(). Um JWT expira 30 minutos após ser emitido.

Diagnóstico do resultado​

A partir da v0.5.2, o resultado de verify() inclui um objeto diagnostics opcional que descreve o que o SDK observou durante a transação. Você pode ignorá-lo.

const result = await verify(jwt);
if (result.diagnostics?.location === 'denied') {
// prompt the user to enable location
}

diagnostics.location é collected · denied · unavailable · timeout · not_requested · error; diagnostics.attestation é collected · failed · unavailable · not_supported · not_requested; diagnostics.networkIntel é collected · unavailable · not_requested; diagnostics.warnings é um array de { code, signal, detail? }; diagnostics.timings (somente Android) traz os milissegundos por fase mais total. Veja Códigos de Erro → Diagnóstico do resultado para o significado de cada valor e os códigos de aviso.

De Onde Vem o Contexto de Cliente e Transação​

O cliente não passa um cliente nem um tipo de transação para verify(). Seu backend define esse contexto quando gera o JWT.

Quando seu backend chama POST /geolocation/preflight, ele inclui transaction_type e, opcionalmente, customer_id, transaction_name, name, email e phone. Esses valores ficam embutidos no JWT, então o cliente só precisa passar o token:

const jwt = await fetchVerifyJwt(); // backend set customer + transaction context
const result = await verify(jwt);

Tipos de Transação​

Esses valores são enviados pelo seu backend no campo transaction_type do preflight. Eles não são passados para verify() no cliente.

TipoCaso de uso
loginLogin do usuário
sign_upCriação de uma nova conta
depositAdição de fundos
withdrawalSaque de fundos
Qualquer outra stringUm tipo personalizado que você define, com até 64 caracteres

Veja Tipos de Transação.

Substituição de Localização por Chamada​

Substitua o padrão de collectLocation em uma única chamada:

// 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);

A substituição vale uma única vez. Ela afeta apenas aquela chamada verify().

Como a Coleta de Localização É Decidida​

A coleta de localização tem dois níveis de controle, avaliados em conjunto. Os dois precisam concordar para que os dados de GPS sejam coletados:

1. Surt Dashboard: GPS habilitado (prioridade mais alta)

A coleta de GPS precisa estar habilitada no seu painel de cliente da Surt. Se o GPS estiver desabilitado no painel, a localização nunca é coletada, independentemente do que você definir no código. Habilite-a em Settings > Developer ou entre em contato com seu gerente de conta da Surt.

2. Configuração no lado do cliente (seu código)

Ela é resolvida assim: substituição por chamada > padrão da inicialização.

  • Se você passar { collectLocation: true } para verify(), isso prevalece sobre o valor da inicialização no iOS. No Android, só tem efeito quando collectLocation também era true na inicialização.
  • Se você passar { collectLocation: false } para verify(), o GPS é ignorado mesmo que a inicialização fosse true.
  • Se você omitir, é usado o padrão da inicialização de GuardianProvider / initialize().

Na prática, isso significa:

GPS no painelSeu código dizResultado
habilitadotrue (inicialização ou substituição)GPS coletado
habilitadofalse (inicialização ou substituição)Sem GPS: você optou por não coletar
desabilitadotrue (inicialização ou substituição)Sem GPS: o painel o mantém desligado
desabilitadofalse (inicialização ou substituição)Sem GPS
Conclusão principal

Sua configuração collectLocation no lado do cliente só pode desativar a coleta de localização. Ela não pode forçar a coleta de GPS se o painel a tiver desabilitada. Para habilitar a coleta de GPS, ative-a primeiro no seu painel de cliente da Surt e depois defina collectLocation: true no seu código.

No Android, o SDK não espera a resposta do usuário ao diálogo de permissão, então a chamada que exibe o diálogo não leva localização. A localização é incluída a partir da chamada seguinte. O Android reporta a última localização conhecida do dispositivo e não solicita uma nova posição.

Resultado da Verificação​

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+)
}

Para detalhes sobre os níveis de risco, veja Níveis de Risco.

Exemplo Completo​

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>
);
}