Android
Integración nativa en Android del SDK Surt Guardian, distribuido mediante Maven (GitHub Packages). 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
- Android SDK 24+ (Android 7.0+)
- Kotlin 1.9+
- Gradle 8+
- Java 17
1. Autenticación
Agrega tu token de acceso al gradle.properties de tu proyecto (o a ~/.gradle/gradle.properties para todos los proyectos):
SURT_GITHUB_TOKEN=<YOUR_TOKEN>
Reemplaza <YOUR_TOKEN> con el token proporcionado por Surt.
No subas gradle.properties con tokens al control de versiones. Agrégalo a .gitignore, o usa ~/.gradle/gradle.properties en su lugar.
2. Agrega el repositorio
En el settings.gradle (o settings.gradle.kts) de tu proyecto, agrega el repositorio Maven de Surt:
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven {
url = uri("https://maven.pkg.github.com/surtTech/surt-guardian-sdk")
credentials {
username = "surt-customer"
password = settings.ext.find("SURT_GITHUB_TOKEN")
?: System.getenv("SURT_GITHUB_TOKEN") ?: ""
}
}
}
}
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven {
url = uri("https://maven.pkg.github.com/surtTech/surt-guardian-sdk")
credentials {
username = "surt-customer"
password = providers.gradleProperty("SURT_GITHUB_TOKEN").orNull
?: System.getenv("SURT_GITHUB_TOKEN")
}
}
}
}
3. Agrega la dependencia
En el build.gradle (o build.gradle.kts) de tu app:
dependencies {
implementation 'com.surt.guardian:securitysdk:0.5.2'
}
dependencies {
implementation("com.surt.guardian:securitysdk:0.5.2")
}
Core Library Desugaring
Si tu app apunta a minSdk < 26, asegúrate de que core library desugaring esté habilitado en el build.gradle de tu app:
android {
compileOptions {
coreLibraryDesugaringEnabled true
}
}
dependencies {
coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.4'
}
4. Permisos en AndroidManifest
Si habilitas la recopilación de ubicación, agrega estos permisos a tu AndroidManifest.xml:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
Si habilitas la recopilación de información de la tarjeta SIM, agrega este permiso:
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
El SDK solicita el permiso de ubicación durante verify() o collect() cuando collectLocation está habilitado y ya estableciste la Activity actual (consulta el paso 6). El diálogo de permisos estándar de Android aparece sin código adicional.
El SDK no espera la respuesta del usuario al diálogo de permiso, por lo que la llamada que muestra el diálogo no lleva ubicación. La ubicación se incluye a partir de la siguiente llamada. El SDK reporta la última ubicación conocida del dispositivo y no solicita una posición nueva.
5. Inicializa el SDK
Llámalo una vez al iniciar la app (normalmente en tu clase Application). El SDK no requiere ninguna clave de API: tu clave de API del lado del servidor nunca se envía al dispositivo.
import android.app.Application
import com.surt.guardian.GuardianSDK
import com.surt.guardian.core.FailurePolicy
import com.surt.guardian.core.GuardianOptions
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
GuardianSDK.initialize(
context = this,
options = GuardianOptions(
failurePolicy = FailurePolicy.Fail,
collectLocation = true // Enable GPS collection (optional)
)
)
}
}
El SDK siempre apunta a producción en https://api.surt.com.
GuardianOptions también acepta logLevel, pero el SDK no lo aplica en la inicialización. Registra en el nivel INFO.
Opciones de recopilación de datos
| Opción | Predeterminado | Descripción |
|---|---|---|
collectLocation | false | Coordenadas GPS. Requiere los permisos de ubicación en el manifest. |
collectWifiInfo | false | Detalles de la red WiFi. Requiere ACCESS_FINE_LOCATION en Android 10 y posteriores. |
collectSimCardInfo | false | Información de SIM/operador. Requiere el permiso READ_PHONE_STATE. |
collectCameraInfo | false | Cantidad de cámaras. No requiere permiso. |
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.
6. Referencia a la Activity (para solicitudes de permisos automáticas)
Para que el SDK muestre el diálogo de permisos, necesita una referencia a la Activity actual. Llama a setActivity() en el ciclo de vida de tu Activity:
override fun onResume() {
super.onResume()
GuardianSDK.getInstance().setActivity(this)
}
override fun onPause() {
super.onPause()
GuardianSDK.getInstance().setActivity(null)
}
Si no llamas a setActivity(), el SDK sigue funcionando pero no puede solicitar permisos automáticamente. Tendrías que solicitar los permisos tú mismo antes de llamar a verify().
7. 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:
suspend fun fetchVerifyJwt(): String {
// Call your OWN backend endpoint, not Surt directly
val response = httpClient.post("https://your-api.com/geolocation-jwt")
return response.body<YourJwtResponse>().jwt
}
Solicita un JWT nuevo justo antes de llamar a verify(). Un JWT expira 30 minutos después de emitirse.
8. 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.
val jwt = fetchVerifyJwt()
// verifySuspend returns a Result. getOrThrow() throws when the call failed.
val result = GuardianSDK.getInstance().verifySuspend(jwt = jwt).getOrThrow()
if (result.allowed) {
// Proceed with the transaction
} else {
// Handle denied transaction (result.riskLevel has details)
}
O con un callback:
val jwt = fetchVerifyJwt()
GuardianSDK.getInstance().verify(jwt = jwt) { result ->
result.onSuccess { verification ->
if (verification.allowed) { /* proceed */ }
}
result.onFailure { error ->
// error is an IOException or a SurtError. See Error Codes.
}
}
Anulación de ubicación por llamada:
// Skip location for this call, regardless of the init default
val result = GuardianSDK.getInstance().verifySuspend(
jwt = jwt,
collectLocation = false
).getOrThrow()
collectLocation = true en una llamada solo tiene efecto cuando collectLocation también era true en la inicialización.
9. 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
val result = GuardianSDK.getInstance().collectSuspend().getOrThrow()
// With JWT: resolves the device public IP (GET /geolocation/client-ip)
// into the payload and applies your attestation settings
val jwtForCollect = fetchCollectJwt()
val resultWithIp = GuardianSDK.getInstance().collectSuspend(jwt = jwtForCollect).getOrThrow()
// 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 configuración de atestación de tu organización: con qué frecuencia atesta un dispositivo, y tu propio proyecto de Play Integrity. Sin él, el SDK atesta en cada llamada con el proyecto predeterminado. Para configurar estos ajustes, consulta Configuración de la atestación de dispositivo. Solicita un JWT nuevo para cada transacción.
Resultado de la verificación
data class VerificationResult(
val allowed: Boolean, // Backend decision - true = proceed
val riskLevel: RiskLevel, // LOW / MEDIUM / HIGH / BLOCKED / UNKNOWN
val sessionId: String, // Transaction ID for support reference
val errors: List<String>?, // Error messages, if any
val timestamp: Long, // Response timestamp (ms)
val metadata: Map<String, Any>?, // Additional backend metadata
val 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 |
|---|---|---|
| "Could not resolve com.surt.guardian:securitysdk" | Token no configurado o repositorio no agregado | Revisa gradle.properties y settings.gradle |
| "401 Unauthorized" desde maven.pkg.github.com | Token expirado o inválido | Solicita un token nuevo a Surt |
IllegalStateException desde getInstance() | getInstance() llamado antes de initialize() | Llama a initialize() en Application.onCreate() |
IOException con HTTP 401 o HTTP 403 en el mensaje | JWT faltante, malformado o expirado | Solicita un JWT nuevo a tu backend para cada llamada |