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

iOS

Integração nativa de iOS para o Surt Guardian SDK, distribuída via Swift Package Manager. O SDK coleta sinais do dispositivo, executa verificações de integridade do dispositivo e retorna a decisão de risco do backend.

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 de curta duração que o app passa para verify().

Versão

Este guia cobre o SDK v0.5.2.

Requisitos​

  • iOS 14.0+
  • Xcode 14+
  • Swift 5.7+

1. Autenticação​

Adicione seu token de acesso ao ~/.netrc para que o Xcode possa clonar o repositório privado:

~/.netrc
machine github.com
login surt-customer
password <YOUR_TOKEN>

Substitua <YOUR_TOKEN> pelo token fornecido pela Surt.

dica

Se o ~/.netrc não existir, crie-o. Garanta que ele tenha permissões restritas:

chmod 600 ~/.netrc

2. Adicionar o Pacote​

  1. No Xcode, vá em File > Add Package Dependencies
  2. Informe a URL do repositório: https://github.com/surtTech/surt-guardian-sdk
  3. Defina a regra de versão como "Up to Next Minor" a partir de 0.5.2
  4. Clique em Add Package
  5. Selecione a biblioteca SurtGuardianSDK e adicione-a ao seu target

3. Configurar as Permissões do Info.plist​

Se você habilitar a coleta de localização, adicione esta chave ao seu Info.plist:

Info.plist
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location helps verify your identity and protect your account.</string>

O SDK solicita a permissão de localização durante verify() ou collect() quando a coleta de localização está habilitada. O diálogo do sistema aparece sem código adicional. Nenhuma outra chave do Info.plist é necessária.

4. Inicializar o SDK​

Chame uma vez na inicialização do app, antes de qualquer outro método do SDK. Nenhuma chave de API é necessária no SDK - sua chave de API do lado do servidor nunca é enviada ao dispositivo.

AppDelegate.swift
import SurtGuardianSDK

// In your AppDelegate or App init:
GuardianSDK.initialize(
options: GuardianOptions(
failurePolicy: .fail,
logLevel: .warn,
collectLocation: true // Enable GPS collection (optional)
)
)

O SDK sempre aponta para produção em https://api.surt.com.

Opções de Coleta de Dados​

OpçãoPadrãoDescrição
collectLocationfalseCoordenadas de GPS. Requer NSLocationWhenInUseUsageDescription no Info.plist.

GuardianOptions também aceita collectWifiInfo, collectSimCardInfo e collectCameraInfo. Elas se aplicam apenas ao Android e não têm efeito no iOS.

Quando collectLocation está habilitado, o SDK pede ao usuário a permissão de localização na primeira vez que verify() ou collect() precisa dela. Se o usuário negar, o SDK continua sem os dados de GPS.

5. Gerar um JWT a Partir do Seu Backend​

Antes de cada chamada verify(), seu app deve obter um JWT do seu próprio backend. Seu backend chama POST /geolocation/preflight com sua chave de API do lado do servidor e o contexto da transação, e então retorna o JWT ao app.

Exemplo de chamada do backend (seu servidor, não o app):

Backend preflight request
POST /geolocation/preflight
Authorization: Bearer sp_live_xxx
Content-Type: application/json

{
"customer_id": "user_abc123",
"transaction_type": "login",
"transaction_name": "User Login",
"name": "John Doe",
"email": "john@example.com"
}

Apenas transaction_type é obrigatório. Veja Autenticação para todos os campos.

A resposta do preflight retorna o token de que seu app precisa:

Preflight response
{
"data": {
"token": "<jwt>"
}
}

Seu app obtém o JWT do endpoint do seu próprio backend:

Fetch JWT from your backend
// In your app - call your OWN backend, not Surt directly
func fetchVerifyJwt() async throws -> String {
let response = try await URLSession.shared.data(
for: URLRequest(url: URL(string: "https://your-api.com/geolocation-jwt")!)
)
// Parse and return the JWT string from your backend response
let body = try JSONDecoder().decode(YourJwtResponse.self, from: response.0)
return body.jwt
}
Solicite um novo JWT para cada chamada

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

6. Verificar uma Transação​

Chame em momentos sensíveis para a segurança (login, pagamento, etc.). Obtenha um JWT do seu backend logo antes de cada chamada.

async/await (iOS 15+)
let jwt = try await fetchVerifyJwt()

let result = try await GuardianSDK.shared.verify(jwt: jwt)

if result.allowed {
// Proceed with the transaction
} else {
// Handle denied transaction (result.riskLevel has details)
}

Ou com um completion handler (iOS 14+):

Completion handler (iOS 14+)
let jwt = try await fetchVerifyJwt()

GuardianSDK.shared.verify(jwt: jwt) { result in
switch result {
case .success(let verification):
if verification.allowed { /* proceed */ }
case .failure(let error):
// error is a SurtError: .notInitialized or .networkError
print(error.localizedDescription)
}
}

Substituição de localização por chamada:

Per-call location override
// Request location for this call, regardless of the init default
let result = try await GuardianSDK.shared.verify(
jwt: jwt,
collectLocation: true
)

7. Collect (Servidor para Servidor, Opcional)​

collect() retorna um payload criptografado para seu backend encaminhar à Surt. collect() não envia o payload do dispositivo à Surt. Seu backend o envia.

Collect payload
// Without JWT: no resolved public IP in the payload
let result = try await GuardianSDK.shared.collect()

// With JWT: resolves the device public IP (GET /geolocation/client-ip)
// into the payload and applies your attestation settings
let jwtForCollect = try await fetchCollectJwt()
let resultWithIp = try await GuardianSDK.shared.collect(jwt: jwtForCollect)

// Send result.payload to your backend
O JWT é opcional para collect

O JWT de collect() é opcional. Passe-o para resolver o IP público do dispositivo para dentro do payload e para aplicar a cadência de atestação da sua organização. Sem ele, o SDK atesta em toda chamada. O App Attest só passa para os App IDs que a sua organização registra: veja Configuração da atestação de dispositivo. Solicite um novo JWT para cada transação.

Resultado da Verificação​

VerificationResult
struct VerificationResult {
let allowed: Bool // Backend decision - true = proceed
let riskLevel: RiskLevel // .low / .medium / .high / .blocked / .unknown
let sessionId: String // Transaction ID for support reference
let errors: [String]? // Error messages, if any
let timestamp: TimeInterval // Response timestamp
let metadata: [String: Any]? // Additional backend metadata
let diagnostics: GuardianDiagnostics // What the SDK observed during the call
}

Veja Diagnóstico do resultado para os campos de diagnostics.

Tipos de Transação​

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

transaction_typeCaso 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.

Solução de Problemas​

ErroCausaSolução
"Package resolution failed"Token não configurado ou expiradoVerifique se o ~/.netrc tem o token correto
.notInitializedverify() chamado antes de initialize()Chame initialize() na inicialização do app
.networkErrorSem conexão, tempo esgotado ou um erro HTTP da Surt. Um JWT ausente, malformado ou expirado é uma das causas.Verifique a conectividade e solicite um novo JWT ao seu backend para cada chamada