Telemetría del SDK
Desde v0.5.3 el SDK Guardian puede enviar a Surt eventos de diagnóstico sobre su propio comportamiento: cuánto tardó cada fase de una llamada, errores internos y fallos de atestación. Surt los usa para detectar regresiones de latencia y de fallos por modelo de dispositivo y versión de SO. La telemetría está desactivada de forma predeterminada y no requiere cambios de código en tu app.
Eventos
| Evento | Se envía | Contenido |
|---|---|---|
sdk_timing | después de cada verify() y collect() | flujo (verify o collect), resultado (succeeded o failed), milisegundos por fase (collection, permission, attestation, client_ip, network_intel, total) y el tiempo de la petición en verify() o el tiempo de cifrado en collect() |
sdk_error | cuando una llamada falla dentro del SDK | el mensaje de error, la operación que falló y hasta diez líneas de la pila de llamadas |
attestation_failure | cuando App Attest o Play Integrity no produce un token | el motivo del fallo |
Cada evento incluye además la versión del SDK, la plataforma (ios o android), el modelo del dispositivo (por ejemplo iPhone15,2 o Google Pixel 8), la versión del SO, el nivel de API de Android, el ID de sesión de la llamada y una marca de tiempo.
Qué no se envía
- Ningún ID, nombre ni correo de cliente. Surt asocia el evento a tu organización y a la sesión a través del JWT.
- Ningún nombre de dispositivo definido por el usuario. El modelo es el identificador de hardware.
- Ningún dato de la transacción, ubicación ni ningún otro campo del payload de verificación.
Cómo se habilita
Surt habilita la telemetría por organización. Contacta con Surt para activarla o desactivarla en tu organización. No existe ninguna opción en GuardianOptions.
Cuando está habilitada:
- El JWT que tu backend recibe del endpoint de preflight incluye la configuración de telemetría. Surt puede aplicar muestreo, por lo que la configuración puede variar entre sesiones.
- El SDK lee la configuración una vez al inicio de cada llamada a
verify()ocollect(). - Si la configuración está desactivada, o la llamada no tiene JWT, el SDK no envía nada.
Efecto en tu app
- Los eventos se envían en un hilo en segundo plano después de que tu callback o promesa haya terminado. No añaden latencia al resultado.
- Cada evento es una única petición sin reintentos. Un envío fallido se descarta y se registra a nivel de depuración.
- Un fallo de telemetría no cambia el resultado de
verify()ni decollect(). - Los eventos ocupan unos pocos kilobytes como máximo.
Leer los mismos tiempos localmente
Las duraciones por fase de sdk_timing son los valores que devuelve diagnostics.timings en cada resultado de verify() y collect(), en Android desde v0.5.2 y en iOS desde v0.5.3. Consulta Diagnósticos del resultado.