Pular para o conteúdo principal
Versão: Guardian v0.5.3

Android

Integração nativa de Android para o Surt Guardian SDK, distribuída via Maven (GitHub Packages). 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().

Versão

Este guia cobre o SDK v0.5.2.

Requisitos​

  • Android SDK 24+ (Android 7.0+)
  • Kotlin 1.9+
  • Gradle 8+
  • Java 17

1. Autenticação​

Adicione seu token de acesso ao gradle.properties do seu projeto (ou ao ~/.gradle/gradle.properties para todos os projetos):

gradle.properties
SURT_GITHUB_TOKEN=<YOUR_TOKEN>

Substitua <YOUR_TOKEN> pelo token fornecido pela Surt.

aviso

Não faça commit do gradle.properties com tokens no controle de versão. Adicione-o ao .gitignore ou use o ~/.gradle/gradle.properties.

2. Adicionar o Repositório​

No settings.gradle (ou settings.gradle.kts) do seu projeto, adicione o repositório Maven da 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. Adicionar a Dependência​

No build.gradle (ou build.gradle.kts) do seu 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​

Se o seu app tem minSdk < 26, garanta que o core library desugaring esteja habilitado no build.gradle do seu app:

build.gradle
android {
compileOptions {
coreLibraryDesugaringEnabled true
}
}

dependencies {
coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.4'
}

4. Permissões do AndroidManifest​

Se você habilitar a coleta de localização, adicione estas permissões ao seu AndroidManifest.xml:

AndroidManifest.xml
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Se você habilitar a coleta de informações do cartão SIM, adicione esta permissão:

AndroidManifest.xml
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

O SDK solicita a permissão de localização durante verify() ou collect() quando collectLocation está habilitado e você definiu a Activity atual (veja a etapa 6). O diálogo de permissão padrão do Android aparece sem código adicional.

O SDK não espera a resposta do usuário ao diálogo de permissão, então a chamada que exibe o diálogo não leva localização. A localização é incluída a partir da chamada seguinte. O SDK reporta a última localização conhecida do dispositivo e não solicita uma nova posição.

5. Inicializar o SDK​

Chame uma vez na inicialização do app (normalmente na sua classe Application). Nenhuma chave de API é necessária no SDK - sua chave de API do lado do servidor nunca é enviada ao 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)
)
)
}
}

O SDK sempre aponta para produção em https://api.surt.com.

GuardianOptions também aceita logLevel, mas o SDK não o aplica na inicialização. Ele registra logs no nível INFO.

Opções de Coleta de Dados​

OpçãoPadrãoDescrição
collectLocationfalseCoordenadas de GPS. Requer as permissões de localização no manifest.
collectWifiInfofalseDetalhes da rede WiFi. Requer ACCESS_FINE_LOCATION no Android 10 e posteriores.
collectSimCardInfofalseInformações de SIM/operadora. Requer a permissão READ_PHONE_STATE.
collectCameraInfofalseQuantidade de câmeras. Nenhuma permissão necessária.

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.

6. Referência da Activity (para solicitações automáticas de permissão)​

Para que o SDK exiba o diálogo de permissão, ele precisa de uma referência à Activity atual. Chame setActivity() no ciclo de vida da sua Activity:

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

override fun onPause() {
super.onPause()
GuardianSDK.getInstance().setActivity(null)
}
observação

Se você não chamar setActivity(), o SDK continua funcionando, mas não consegue solicitar permissões automaticamente. Você precisaria solicitar as permissões por conta própria antes de chamar verify().

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

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

Apenas transaction_type é obrigatório. Veja Autenticação para todos os campos.

A resposta do preflight retorna o token de que seu app precisa:

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

Seu app obtém o JWT do endpoint do seu próprio 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
}
Solicite um novo JWT para cada chamada

Solicite um novo JWT imediatamente antes de chamar verify(). Um JWT expira 30 minutos após ser emitido.

8. 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.

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

Ou com um 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.
}
}

Substituição de localização por chamada:

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 em uma chamada só tem efeito quando collectLocation também era true na inicialização.

9. 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.

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
O JWT é opcional para collect

O JWT de collect() é opcional. Passe-o para resolver o IP público do dispositivo para dentro do payload e para aplicar as configurações de atestação da sua organização: com que frequência um dispositivo atesta e seu próprio projeto de Play Integrity. Sem ele, o SDK atesta em toda chamada com o projeto padrão. Para configurar essas opções, veja Configuração da atestação de dispositivo. Solicite um novo JWT para cada transação.

Resultado da Verificação​

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
)

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_typeCaso de uso
loginLogin do usuário
sign_upCriação de uma nova conta
depositAdição de fundos
withdrawalSaque de fundos
Qualquer outra stringUm tipo personalizado que você define, com até 64 caracteres

Veja Tipos de Transação.

Solução de Problemas​

ErroCausaSolução
"Could not resolve com.surt.guardian:securitysdk"Token não configurado ou repositório não adicionadoVerifique o gradle.properties e o settings.gradle
"401 Unauthorized" de maven.pkg.github.comToken expirado ou inválidoObtenha um novo token com a Surt
IllegalStateException em getInstance()getInstance() chamado antes de initialize()Chame initialize() em Application.onCreate()
IOException com HTTP 401 ou HTTP 403 na mensagemJWT ausente, malformado ou expiradoSolicite um novo JWT ao seu backend para cada chamada