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().
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:
machine github.com
login surt-customer
password <YOUR_TOKEN>
Substitua <YOUR_TOKEN> pelo token fornecido pela Surt.
Se o ~/.netrc não existir, crie-o. Garanta que ele tenha permissões restritas:
chmod 600 ~/.netrc
2. Adicionar o Pacote
- No Xcode, vá em File > Add Package Dependencies
- Informe a URL do repositório:
https://github.com/surtTech/surt-guardian-sdk - Defina a regra de versão como "Up to Next Minor" a partir de 0.5.2
- Clique em Add Package
- 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:
<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.
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ção | Padrão | Descrição |
|---|---|---|
collectLocation | false | Coordenadas 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):
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:
{
"data": {
"token": "<jwt>"
}
}
Seu app obtém o JWT do endpoint do seu próprio 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 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.
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+):
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:
// 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.
// 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 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
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_type | 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.
Solução de Problemas
| Erro | Causa | Solução |
|---|---|---|
| "Package resolution failed" | Token não configurado ou expirado | Verifique se o ~/.netrc tem o token correto |
.notInitialized | verify() chamado antes de initialize() | Chame initialize() na inicialização do app |
.networkError | Sem 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 |