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().
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:
machine github.com
login surt-customer
password <YOUR_TOKEN>
Reemplaza <YOUR_TOKEN> con el token proporcionado por Surt.
Si ~/.netrc no existe, créalo. Asegúrate de que tenga permisos restringidos:
chmod 600 ~/.netrc
2. Agrega el paquete
- En Xcode, ve a File > Add Package Dependencies
- Ingresa la URL del repositorio:
https://github.com/surtTech/surt-guardian-sdk - Establece la regla de versión en "Up to Next Minor" desde 0.5.2
- Haz clic en Add Package
- 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:
<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.
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ón | Predeterminado | Descripción |
|---|---|---|
collectLocation | false | Coordenadas 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):
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:
{
"data": {
"token": "<jwt>"
}
}
Tu app obtiene el JWT desde el endpoint de tu propio 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 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.
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+):
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:
// 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.
// 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 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
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_type | Caso de uso |
|---|---|
login | Inicio de sesión del usuario |
sign_up | Creación de una cuenta nueva |
deposit | Agregar fondos |
withdrawal | Retirar fondos |
| Cualquier otra cadena | Un tipo personalizado que tú defines, de hasta 64 caracteres |
Consulta Tipos de transacción.
Solución de problemas
| Error | Causa | Solución |
|---|---|---|
| "Package resolution failed" | Token no configurado o expirado | Verifica que ~/.netrc tenga el token correcto |
.notInitialized | verify() llamado antes de initialize() | Llama a initialize() al iniciar la app |
.networkError | Sin 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 |