Saltar al contenido principal
Version: Guardian v0.5.3

iOS

Integración nativa en iOS del SDK Surt Guardian, distribuido mediante Swift Package Manager. El SDK recopila señales del dispositivo, ejecuta verificaciones de integridad del dispositivo y devuelve la decisión de riesgo del backend.

El SDK nunca maneja una clave de API de Surt. Tu backend tiene la clave sp_live_* (solo del lado del servidor) y la intercambia por un JWT de corta duración que la app pasa a verify().

Versión

Esta guía cubre el SDK v0.5.2.

Requisitos​

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

1. Autenticación​

Agrega tu token de acceso a ~/.netrc para que Xcode pueda clonar el repositorio privado:

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

Reemplaza <YOUR_TOKEN> con el token proporcionado por Surt.

tip

Si ~/.netrc no existe, créalo. Asegúrate de que tenga permisos restringidos:

chmod 600 ~/.netrc

2. Agrega el paquete​

  1. En Xcode, ve a File > Add Package Dependencies
  2. Ingresa la URL del repositorio: https://github.com/surtTech/surt-guardian-sdk
  3. Establece la regla de versión en "Up to Next Minor" desde 0.5.2
  4. Haz clic en Add Package
  5. Selecciona la biblioteca SurtGuardianSDK y agrégala a tu target

3. Configura los permisos en Info.plist​

Si habilitas la recopilación de ubicación, agrega esta clave a tu Info.plist:

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

El SDK solicita el permiso de ubicación durante verify() o collect() cuando la recopilación de ubicación está habilitada. El diálogo del sistema aparece sin código adicional. No se necesita ninguna otra clave en Info.plist.

4. Inicializa el SDK​

Llámalo una vez al iniciar la app, antes de cualquier otro método del SDK. El SDK no requiere ninguna clave de API: tu clave de API del lado del servidor nunca se envía al 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)
)
)

El SDK siempre apunta a producción en https://api.surt.com.

Opciones de recopilación de datos​

OpciónPredeterminadoDescripción
collectLocationfalseCoordenadas GPS. Requiere NSLocationWhenInUseUsageDescription en Info.plist.

GuardianOptions también acepta collectWifiInfo, collectSimCardInfo y collectCameraInfo. Aplican solo a Android y no tienen efecto en iOS.

Cuando collectLocation está habilitado, el SDK solicita al usuario el permiso de ubicación la primera vez que verify() o collect() lo necesita. Si el usuario lo deniega, el SDK continúa sin datos GPS.

5. Genera un JWT desde tu backend​

Antes de cada llamada a verify(), tu app debe obtener un JWT desde tu propio backend. Tu backend llama a POST /geolocation/preflight con su clave de API del lado del servidor y el contexto de la transacción, y luego devuelve el JWT a la app.

Ejemplo de llamada del backend (tu servidor, no la 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"
}

Solo transaction_type es obligatorio. Consulta Autenticación para ver todos los campos.

La respuesta de preflight devuelve el token que necesita tu app:

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

Tu app obtiene el JWT desde el endpoint de tu propio 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
}
Solicita un JWT nuevo para cada llamada

Solicita un JWT nuevo justo antes de llamar a verify(). Un JWT expira 30 minutos después de emitirse.

6. Verifica una transacción​

Llámalo en momentos sensibles para la seguridad (inicio de sesión, pago, etc.). Obtén un JWT desde tu backend justo antes de cada llamada.

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)
}

O con un 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)
}
}

Anulación de ubicación por llamada:

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 a servidor, opcional)​

collect() devuelve un payload cifrado para que tu backend lo reenvíe a Surt. collect() no envía el payload del dispositivo a Surt. Lo envía tu backend.

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
El JWT es opcional para collect

El JWT para collect() es opcional. Pásalo para resolver la IP pública del dispositivo e incluirla en el payload y para aplicar la frecuencia de atestación de tu organización. Sin él, el SDK atesta en cada llamada. App Attest solo se aprueba para los App IDs que registra tu organización: consulta Configuración de la atestación de dispositivo. Solicita un JWT nuevo para cada transacción.

Resultado de la verificación​

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
}

Consulta Diagnósticos del resultado para ver los campos de diagnostics.

Tipos de transacción​

Estos valores los establece tu backend en el campo transaction_type del preflight. No se pasan a verify() en la app.

transaction_typeCaso de uso
loginInicio de sesión del usuario
sign_upCreación de una cuenta nueva
depositAgregar fondos
withdrawalRetirar fondos
Cualquier otra cadenaUn tipo personalizado que tú defines, de hasta 64 caracteres

Consulta Tipos de transacción.

Solución de problemas​

ErrorCausaSolución
"Package resolution failed"Token no configurado o expiradoVerifica que ~/.netrc tenga el token correcto
.notInitializedverify() llamado antes de initialize()Llama a initialize() al iniciar la app
.networkErrorSin conexión, tiempo de espera agotado o un error HTTP de Surt. Un JWT faltante, malformado o expirado es una de las causas.Verifica la conectividad y solicita un JWT nuevo a tu backend para cada llamada