Saltar al contenido principal
Version: Guardian v0.5.3

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().

Versión

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

gradle.properties
SURT_GITHUB_TOKEN=<YOUR_TOKEN>

Reemplaza <YOUR_TOKEN> con el token proporcionado por Surt.

aviso

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:

settings.gradle
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") ?: ""
}
}
}
}
settings.gradle.kts
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:

build.gradle
dependencies {
implementation 'com.surt.guardian:securitysdk:0.5.2'
}
build.gradle.kts
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:

build.gradle
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:

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:

AndroidManifest.xml
<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.

MyApplication.kt
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ónPredeterminadoDescripción
collectLocationfalseCoordenadas GPS. Requiere los permisos de ubicación en el manifest.
collectWifiInfofalseDetalles de la red WiFi. Requiere ACCESS_FINE_LOCATION en Android 10 y posteriores.
collectSimCardInfofalseInformación de SIM/operador. Requiere el permiso READ_PHONE_STATE.
collectCameraInfofalseCantidad 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:

MainActivity.kt
override fun onResume() {
super.onResume()
GuardianSDK.getInstance().setActivity(this)
}

override fun onPause() {
super.onPause()
GuardianSDK.getInstance().setActivity(null)
}
nota

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

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
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 para cada llamada

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.

Coroutines (recommended)
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:

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:

Per-call location override
// 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.

Collect payload
// 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 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 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​

VerificationResult
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_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
"Could not resolve com.surt.guardian:securitysdk"Token no configurado o repositorio no agregadoRevisa gradle.properties y settings.gradle
"401 Unauthorized" desde maven.pkg.github.comToken expirado o inválidoSolicita 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 mensajeJWT faltante, malformado o expiradoSolicita un JWT nuevo a tu backend para cada llamada