Pacote NPM
O SDK @surtai/guardian-web executa o fluxo collect() do Guardian em qualquer navegador moderno. Ele coleta sinais do dispositivo, criptografa-os no navegador e retorna um payload opaco que seu backend envia ao endpoint evaluate da Surt. collect() não envia o payload do dispositivo à Surt, e o SDK não guarda nenhuma chave de API. Quando você passa um geolocationJwt opcional, collect() chama GET /geolocation/client-ip para resolver o IP público do navegador e embuti-lo no payload. O JWT é um token gerado pelo seu backend que expira após 30 minutos. Não é uma chave de API.
Instalação
@surtai/guardian-web é um pacote npm privado. Adicione seu token de acesso ao .npmrc na raiz do projeto:
//registry.npmjs.org/:_authToken=<YOUR_NPM_TOKEN>
Substitua <YOUR_NPM_TOKEN> pelo token fornecido pela Surt. Esse token serve apenas para instalar o pacote. Ele é independente da chave de API da Surt que seu backend usa.
Adicione o .npmrc ao seu .gitignore para evitar o commit de tokens.
npm install @surtai/guardian-web
Diferente dos SDKs nativos (iOS / Android / React Native), o SDK web não expõe um método verify(). Todas as decisões de risco acontecem no lado do servidor assim que seu backend encaminha o payload. Veja Collect (Servidor para Servidor) para o fluxo completo do backend.
Reconhecimento de dispositivos (v0.5.0)
A partir da v0.5.0, o SDK adiciona dois sinais ao payload criptografado automaticamente - sem mudança de código do seu lado:
- Reconhecimento estável de dispositivos - o SDK gera e persiste um install id por navegador e
o inclui em
collect(). A Surt o utiliza para reconhecer um dispositivo que retorna entre visitas, de modo que o mesmo navegador resolve para o mesmo dispositivo mesmo quando sua impressão digital bruta colide com outras máquinas do mesmo modelo. - Relatório da versão do SDK - o SDK reporta sua própria versão de build, para que a Surt possa atribuir cada transação à versão exata do SDK.
Ambos viajam dentro do payload criptografado - você nunca os lê nem define. Atualizar o pacote é tudo o que é necessário para se beneficiar; veja Migrando v0.4 → v0.5.
Navegadores como o Safari removem o armazenamento gravável por script após ~7 dias, o que rotaciona o install id. Para manter o reconhecimento estável ali, seu backend pode persistir o id em um cookie first-party repassado pelo preflight - uma mudança opcional de ~5 linhas coberta no guia de migração.
Mantenha o armazenamento do SDK
O SDK guarda o install id no localStorage sob a chave surt_guardian_install_id, e o sinal de
inteligência de rede também guarda ali o seu próprio estado. Se o seu app limpa o armazenamento no
login ou no logout, cada login vira um dispositivo novo. Remova as suas próprias chaves pelo nome em
vez de chamar localStorage.clear(), e deixe surt_guardian_install_id e qualquer chave que você
não escreveu no lugar. Se não puder evitar uma limpeza completa, o repasse do cookie first-party
descrito abaixo é a única coisa que mantém o reconhecimento estável.
Uso
import { collect } from '@surtai/guardian-web';
// Variant 1: no IP lookup.
const { payload } = await collect({ collectLocation: false });
// Variant 2: resolve the browser's public IP into the payload.
// Your backend mints the short-lived JWT via preflight.
const { payload: payloadWithIp } = await collect({
collectLocation: false,
geolocationJwt: jwt,
});
// Forward the payload to your backend.
await fetch('https://your-api.com/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userId: 'user_123', payload }),
});
Seu backend gera o geolocationJwt chamando o preflight com sua chave sp_live_*. Veja Autenticação. Passe o JWT para collect() quando quiser resolver o IP público ou quando repassar o install id por um cookie first-party. Solicite um novo JWT para cada transação. Um JWT expira 30 minutos após ser emitido.
Opções
| Opção | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
collectLocation | boolean | Não | false | Quando true, aciona a API de Geolocalização do navegador. É a única coisa em collect() que pode exibir um pedido de permissão. |
geolocationJwt | string | Não | (nenhum) | Quando fornecido, collect() resolve o IP público do navegador via GET /geolocation/client-ip e o embute no payload. Omita-o para pular a busca de IP. |
CollectResult
interface CollectResult {
/** Base64 payload. Pass as `payload.data` in the evaluate request shown below. */
payload: string;
/** What the SDK observed while collecting. Safe to ignore. */
diagnostics: {
location?: 'collected' | 'denied' | 'unavailable' | 'timeout' | 'not_requested' | 'error';
networkIntel?: 'collected' | 'unavailable' | 'not_requested';
warnings: { code: string; signal: string; detail?: string }[];
};
}
O objeto diagnostics informa o que aconteceu no dispositivo - por exemplo, se a localização foi coletada ou se o usuário a negou - para que você reaja na sua interface:
const { payload, diagnostics } = await collect({ collectLocation: true });
if (diagnostics.location === 'denied') {
// prompt the user to enable location, then retry
}
Veja Diagnóstico do resultado para o significado de cada valor e os códigos de aviso. O SDK web não retorna attestation nem timings.
Backend: encaminhar para a Surt
Seu backend recebe o payload do navegador e o envia ao endpoint evaluate da Surt:
POST https://api.surt.com/geolocation/transactions/evaluate
Content-Type: application/json
Authorization: Bearer YOUR_SURT_API_KEY
{
"customer_id": "user_123",
"transaction_type": "login",
"transaction_name": "Sign in",
"payload": {
"type": "encrypted",
"data": "<payload from collect()>"
},
"config": {
"response": {
"address": { "type": "include" }
}
}
}
O formato da requisição, os valores de transaction_type, as opções de config e o esquema de resposta são os mesmos em todos os SDKs do Guardian. Apenas transaction_type e payload são obrigatórios. Veja Collect (Servidor para Servidor) para a referência completa, incluindo o event_id opcional para novas tentativas seguras e exemplos em Node / Java / Python.
Erros
collect() lança um único GuardianError em três condições:
import { collect, GuardianError } from '@surtai/guardian-web';
try {
const { payload } = await collect();
} catch (err) {
if (err instanceof GuardianError) {
switch (err.code) {
case 'CRYPTO_UNAVAILABLE': /* not in a secure context */ break;
case 'ENCRYPTION_FAILED': /* encryption failed (rare) */ break;
case 'INVALID_OPTIONS': /* bad arguments */ break;
}
}
}
| Código | Significado |
|---|---|
CRYPTO_UNAVAILABLE | window.crypto.subtle está ausente. O SDK requer um contexto seguro (HTTPS ou localhost). |
ENCRYPTION_FAILED | A etapa de criptografia falhou. Trate como bug: capture e reporte. |
INVALID_OPTIONS | O argumento de collect() não é um objeto. |
Os coletores individuais (impressão digital, bateria, geolocalização, rede, etc.) nunca lançam: falham silenciosamente. Uma permissão revogada ou uma API não suportada significa apenas que o campo correspondente é omitido do payload. A busca do IP público também é de melhor esforço: se a chamada GET /geolocation/client-ip falhar ou o JWT for rejeitado, o campo de IP é omitido e collect() ainda retorna um payload. O backend tolera payloads incompletos.
Suporte de navegador
- Qualquer navegador atualizado com
window.crypto.subtle(Chrome, Edge, Firefox, Safari, Opera). - Contexto seguro obrigatório: HTTPS em produção,
localhostpara desenvolvimento. O SDK lançaCRYPTO_UNAVAILABLEfora de um contexto seguro. - Geolocalização, Battery Status, NetworkInformation e outras APIs opcionais são ignoradas sem erro quando indisponíveis.
Exemplos de frameworks
- React
- Next.js
- Vue
- Svelte
- Vanilla JS
import { useState } from 'react';
import { collect } from '@surtai/guardian-web';
export function VerifyButton({ userId }: { userId: string }) {
const [loading, setLoading] = useState(false);
const handleClick = async () => {
setLoading(true);
try {
const { payload } = await collect({ collectLocation: false });
await fetch('/api/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userId, payload }),
});
} finally {
setLoading(false);
}
};
return (
<button onClick={handleClick} disabled={loading}>
{loading ? 'Verifying...' : 'Continue'}
</button>
);
}
'use client';
import { collect } from '@surtai/guardian-web';
export function SignInForm() {
async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
e.preventDefault();
const { payload } = await collect();
await fetch('/api/sign-in', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: new FormData(e.currentTarget).get('email'),
payload,
}),
});
// Your /api/sign-in route forwards `payload` to Surt's /evaluate.
}
return (
<form onSubmit={handleSubmit}>
<input name="email" type="email" required />
<button type="submit">Sign in</button>
</form>
);
}
<script setup lang="ts">
import { ref } from 'vue';
import { collect } from '@surtai/guardian-web';
const loading = ref(false);
const props = defineProps<{ userId: string }>();
async function verify() {
loading.value = true;
try {
const { payload } = await collect();
await fetch('/api/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userId: props.userId, payload }),
});
} finally {
loading.value = false;
}
}
</script>
<template>
<button :disabled="loading" @click="verify">
{{ loading ? 'Verifying...' : 'Continue' }}
</button>
</template>
<script>
import { collect } from '@surtai/guardian-web';
export let userId;
let loading = false;
async function verify() {
loading = true;
try {
const { payload } = await collect();
await fetch('/api/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userId, payload }),
});
} finally {
loading = false;
}
}
</script>
<button on:click={verify} disabled={loading}>
{loading ? 'Verifying...' : 'Continue'}
</button>
<button id="verify">Continue</button>
<script type="module" src="./main.js"></script>
import { collect } from '@surtai/guardian-web';
document.getElementById('verify').addEventListener('click', async () => {
const { payload } = await collect({ collectLocation: false });
await fetch('/api/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userId: 'user_123', payload }),
});
});
O pacote é privado, então uma CDN pública não consegue servi-lo. Instale-o pelo npm e gere o main.js com um bundler como Vite, webpack ou esbuild.
Diferenças em relação aos SDKs nativos
@surtai/guardian-web | @surtai/guardian-rn / iOS / Android | |
|---|---|---|
Método verify() | Não | Sim |
Método collect() | Sim (única API) | Sim |
| Inicialização no nível do app | Nenhuma | initialize(options) |
| Contexto de cliente / transação | Definido pelo seu backend | Carregado nas claims do JWT gerado pelo backend |
| Chave de API no cliente | Não | Não (usa um JWT gerado pelo backend, não uma chave de API) |
| Envia o payload do dispositivo à Surt | Não, seu backend o envia | verify() sim, collect() não |
| Verificação de integridade do dispositivo | Não (sem equivalente no navegador) | Sim |
| Estado mantido no navegador ou no app | Um install id por navegador no localStorage | Nenhum estado por cliente |
Web é intencionalmente enxuto: uma única função estática que produz um payload criptografado. A associação ao cliente, os metadados da transação e as decisões acontecem no seu backend.