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

Pacote NPM

@surtai/guardian-web · v0.5.0

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:

.npmrc
//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.

aviso

Adicione o .npmrc ao seu .gitignore para evitar o commit de tokens.

npm install @surtai/guardian-web
Web é apenas collect

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.

Reconhecimento durável no Safari

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​

Não limpe 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​

TypeScript
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çãoTipoObrigatórioPadrãoDescrição
collectLocationbooleanNãofalseQuando true, aciona a API de Geolocalização do navegador. É a única coisa em collect() que pode exibir um pedido de permissão.
geolocationJwtstringNã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ódigoSignificado
CRYPTO_UNAVAILABLEwindow.crypto.subtle está ausente. O SDK requer um contexto seguro (HTTPS ou localhost).
ENCRYPTION_FAILEDA etapa de criptografia falhou. Trate como bug: capture e reporte.
INVALID_OPTIONSO 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, localhost para desenvolvimento. O SDK lança CRYPTO_UNAVAILABLE fora de um contexto seguro.
  • Geolocalização, Battery Status, NetworkInformation e outras APIs opcionais são ignoradas sem erro quando indisponíveis.

Exemplos de frameworks​

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

Diferenças em relação aos SDKs nativos​

@surtai/guardian-web@surtai/guardian-rn / iOS / Android
Método verify()NãoSim
Método collect()Sim (única API)Sim
Inicialização no nível do appNenhumainitialize(options)
Contexto de cliente / transaçãoDefinido pelo seu backendCarregado nas claims do JWT gerado pelo backend
Chave de API no clienteNãoNão (usa um JWT gerado pelo backend, não uma chave de API)
Envia o payload do dispositivo à SurtNão, seu backend o enviaverify() sim, collect() não
Verificação de integridade do dispositivoNão (sem equivalente no navegador)Sim
Estado mantido no navegador ou no appUm install id por navegador no localStorageNenhum 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.