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():
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" />;
}
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.
| Tipo | Caso de uso |
|---|---|
login | Login do usuário |
sign_up | Criação de uma nova conta |
deposit | Adição de fundos |
withdrawal | Saque de fundos |
| Qualquer outra string | Um 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 }paraverify(), isso prevalece sobre o valor da inicialização no iOS. No Android, só tem efeito quandocollectLocationtambém eratruena inicialização. - Se você passar
{ collectLocation: false }paraverify(), o GPS é ignorado mesmo que a inicialização fossetrue. - Se você omitir, é usado o padrão da inicialização de
GuardianProvider/initialize().
Na prática, isso significa:
| GPS no painel | Seu código diz | Resultado |
|---|---|---|
| habilitado | true (inicialização ou substituição) | GPS coletado |
| habilitado | false (inicialização ou substituição) | Sem GPS: você optou por não coletar |
| desabilitado | true (inicialização ou substituição) | Sem GPS: o painel o mantém desligado |
| desabilitado | false (inicialização ou substituição) | Sem GPS |
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
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>
);
}