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().
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):
SURT_GITHUB_TOKEN=<YOUR_TOKEN>
Substitua <YOUR_TOKEN> pelo token fornecido pela Surt.
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:
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. Adicionar a Dependência
No build.gradle (ou build.gradle.kts) do seu app:
dependencies {
implementation 'com.surt.guardian:securitysdk:0.5.2'
}
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:
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:
<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:
<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.
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ção | Padrão | Descrição |
|---|---|---|
collectLocation | false | Coordenadas de GPS. Requer as permissões de localização no manifest. |
collectWifiInfo | false | Detalhes da rede WiFi. Requer ACCESS_FINE_LOCATION no Android 10 e posteriores. |
collectSimCardInfo | false | Informações de SIM/operadora. Requer a permissão READ_PHONE_STATE. |
collectCameraInfo | false | Quantidade 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:
override fun onResume() {
super.onResume()
GuardianSDK.getInstance().setActivity(this)
}
override fun onPause() {
super.onPause()
GuardianSDK.getInstance().setActivity(null)
}
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):
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:
{
"data": {
"token": "<jwt>"
}
}
Seu app obtém o JWT do endpoint do seu próprio 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 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.
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:
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:
// 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.
// 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 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
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_type | Caso de uso |
|---|---|
login | Login do usuário |
sign_up | Criação de uma nova conta |
deposit | Adição de fundos |
withdrawal | Saque de fundos |
| Qualquer outra string | Um tipo personalizado que você define, com até 64 caracteres |
Veja Tipos de Transação.
Solução de Problemas
| Erro | Causa | Solução |
|---|---|---|
| "Could not resolve com.surt.guardian:securitysdk" | Token não configurado ou repositório não adicionado | Verifique o gradle.properties e o settings.gradle |
| "401 Unauthorized" de maven.pkg.github.com | Token expirado ou inválido | Obtenha 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 mensagem | JWT ausente, malformado ou expirado | Solicite um novo JWT ao seu backend para cada chamada |