SDK de Android: Domar el administrador de batería

Android es famoso por eliminar agresivamente los servicios en segundo plano. Los fabricantes de equipos originales chinos (como Xiaomi, Huawei) incluso tienen administradores de energía personalizados que rompen por completo los límites estándar de ejecución en segundo plano de Android.

Esta página explica por qué Android elimina su aplicación y cómo las configuraciones específicas de Android de Tracelet lo resuelven en el mundo real.

Dependencia opcional: ubicación GMS de alta precisión

El SDK de Android de Tracelet puede utilizar Ubicación de servicios de Google Play — FusedLocationProviderClient (mejor precisión y batería), hardware reconocimiento de actividad (caminar / conducir / quieto), y hardware geocercas. Para mantener el SDK liviano y utilizable en dispositivos sin Google, este la dependencia no está incluida. Lo agrega solo si desea la ruta de alta precisión:

// android/app/build.gradle.kts
dependencies {
    implementation("com.google.android.gms:play-services-location:21.3.0")
}

Dependencia opcional: Play Integrity (certificación de dispositivo)

Si utiliza la función certificación de dispositivo de Tracelet (AttestationConfig), Android El lado genera su token criptográfico a través de Google Play Integrity. al igual que play-services-location, esta dependencia no está incluida; la agregas solo cuando habilitar la atestación:

// android/app/build.gradle.kts
dependencies {
    implementation("com.google.android.play:integrity:1.6.0")
}

Permisos y configuración de manifiesto

Tracelet inyecta automáticamente los permisos necesarios en su AndroidManifest.xml cuando compila su aplicación. Por defecto solicita:

• ACCESS_COARSE_LOCATION & ACCESS_FINE_LOCATION (Requerido para seguimiento)
• ACCESS_BACKGROUND_LOCATION (Requerido para el seguimiento cuando la aplicación está cerrada)
• FOREGROUND_SERVICE & FOREGROUND_SERVICE_LOCATION (Requerido para ejecución continua en segundo plano)
• ACTIVITY_RECOGNITION (Requerido para el motor de detección de movimiento inteligente)
• POST_NOTIFICATIONS (Requerido para la interfaz de usuario del servicio de primer plano de Android 13+)
• SCHEDULE_EXACT_ALARM (Requerido para un seguimiento preciso del modo periódico)

Eliminación de permisos no utilizados (fusión de manifiesto)

Si su aplicación no necesita una característica específica (por ejemplo, su cliente no necesita detección de movimiento o no usa el modo periódico), puede eliminar el permiso por la fuerza usando la directiva tools:node="remove" de fusión de manifiesto de Android en su nivel de aplicación AndroidManifest.xml (android/app/src/main/AndroidManifest.xml).

El código nativo de Tracelet está completamente protegido con checkSelfPermission(). La falta de permisos provocará retrocesos elegantes, no bloqueos.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:tools="http://schemas.android.com/tools">
 
    <!-- Geofence-only / periodic-only app: no continuous foreground tracking -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" tools:node="remove" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" tools:node="remove" />
 
</manifest>

Ejemplo: eliminación de permisos de movimiento y fondo

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:tools="http://schemas.android.com/tools">
 
    <!-- Client doesn't want Activity/Motion tracking -->
    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" tools:node="remove" />
    
    <!-- Client only wants foreground tracking -->
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" tools:node="remove" />
 
    <!-- Remove Exact Alarms -->
    <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" tools:node="remove" />
    
</manifest>

Reglas automáticas de ProGuard / R8

Tracelet utiliza en gran medida servicios Kotlin en segundo plano, enlaces JNA para el núcleo de Rust y canales reflectantes de Pigeon. Si se ofuscan o se reducen incorrectamente, el seguimiento en segundo plano fallará silenciosamente cuando la aplicación se compile para su lanzamiento.

No es necesario configurar manualmente ProGuard para Tracelet.

El complemento tracelet_android se envía automáticamente con consumer-rules.pro integrado. Cuando creas tu aplicación Flutter en modo de lanzamiento, el reductor R8 de Android extrae automáticamente estas reglas y garantiza que todas las clases necesarias (como los enlaces HeadlessTaskService, BootReceiver y Rust uniffi) sobrevivan a la reducción.

Escenario 1: El repartidor (seguimiento continuo)

Conceptos explorados: Modo Doze, Servicios en primer plano, Wakelocks

El problema

Su usuario es un repartidor de pizzas. Se metieron el teléfono en el bolsillo y apagaron la pantalla. Después de 15 minutos, Android ingresa al Modo Doze. Cierra el acceso a la red, pospone trabajos en segundo plano y limita severamente las reactivaciones de la CPU para ahorrar batería. Si su aplicación se basa en un temporizador simple para obtener GPS, Android simplemente se negará a ejecutar el temporizador.

Cómo lo resuelve Tracelet: servicio en primer plano

Un servicio en primer plano le dice a Android: “Oye, estoy haciendo algo increíblemente importante en este momento y el usuario es plenamente consciente de ello. No me mates”.

android: tl.AndroidConfig(
  foregroundService: tl.ForegroundServiceConfig(
    enabled: true,
    channelName: 'Delivery Tracking',
    notificationText: 'Tracking your route to the customer',
    notificationOngoing: true, // User cannot swipe it away
    showNotificationOnPauseOnly: false, // Always visible — see the section below
    actions: ['Pause', 'Complete'], // Adds interactive buttons to the notification
  ),
)

Al mostrar una notificación persistente en la barra de estado, Tracelet eleva la prioridad de su aplicación casi al nivel de la interfaz de usuario de primer plano. Android permitirá que Tracelet se ejecute indefinidamente, evitando las restricciones del modo Doze.

Personalizar la apariencia de las notificaciones

Para que la notificación persistente coincida con la marca de su aplicación, puede personalizar los íconos y colores:

android: tl.AndroidConfig(
  foregroundService: tl.ForegroundServiceConfig(
    enabled: true,
    notificationTitle: 'Delivery Mode',
    notificationText: 'Tracking your route...',
    notificationColor: '#0F9D58', // Your brand hex color
    notificationSmallIcon: 'ic_tracelet_icon', // The icon name
    notificationLargeIcon: 'ic_large_logo',
  ),
)

Reglas de iconos importantes:

1. Ubicación del archivo: El archivo de imagen debe colocarse en la carpeta dibujable de su proyecto de Android (android/app/src/main/res/drawable/ic_tracelet_icon.png).
2. Restricciones de íconos pequeños: Android requiere que notificationSmallIcon sea completamente plano, transparente y solo blanco. Si utiliza un logotipo de color, Android simplemente lo representará como un cuadrado gris o blanco sólido.
3. Propiedad de color: La propiedad notificationColor teñirá el fondo de su pequeño ícono para que coincida con su marca.

Actualizar la notificación durante el seguimiento (updateNotification())

Es necesario cambiar la notificación después de que el seguimiento ya haya comenzado, p. ¿Actualizar el título de “En ruta” a “Llegando”, intercambiar el texto o cambiar los botones de acción a mitad del viaje? Llamar a setConfig() con un nuevo ForegroundServiceConfig mantiene los valores, pero un cambio de solo notificación no vuelve a publicar la notificación que Android ya está mostrando; el nuevo contenido solo aparecería después de un reinicio del servicio no relacionado o una transición en primer plano.

Desde v3.6.8, Tracelet.updateNotification() actualiza la notificación en vivo, sin reiniciar el proceso de seguimiento:

// 1. Apply the new notification content.
await Tracelet.setConfig(
  const tl.Config(
    android: tl.AndroidConfig(
      foregroundService: tl.ForegroundServiceConfig(
        notificationTitle: 'Arriving',
        notificationText: 'Your driver is 2 minutes away',
      ),
    ),
  ),
);
 
// 2. Repost the active notification with the new content.
await Tracelet.updateNotification();

Actualización silenciosa de la notificación (notificationOnlyAlertOnce)

Hay un problema en el patrón anterior. Android trata cada reenvío como una alerta nueva a menos que indiques lo contrario, por lo que una notificación que actualizas una vez por minuto reproduce el sonido de notificación una vez por minuto, mientras se ejecuta el seguimiento.

El canal de Tracelet se crea con la vibración y las luces desactivadas, por lo que es un sonido, no un zumbido, pero en el modo predeterminado notificationPriority es audible y los usuarios lo notan rápidamente.

Configure notificationOnlyAlertOnce para que solo las primeras alertas de publicación y todas las actualizaciones posteriores lleguen de forma silenciosa:

await Tracelet.setConfig(
  const tl.Config(
    android: tl.AndroidConfig(
      foregroundService: tl.ForegroundServiceConfig(
        notificationOnlyAlertOnce: true,
      ),
    ),
  ),
);

Vale la pena configurar esto para cualquier notificación cuyo contenido cambie mientras se ejecuta el seguimiento (un recuento de paradas restantes, cargas pendientes, la geocerca actual, precisión en vivo) no solo para el temporizador a continuación.

Ocultar la notificación mientras la aplicación está abierta (showNotificationOnPauseOnly)

showNotificationOnPauseOnly: true elimina la notificación de seguimiento mientras el usuario está mirando su aplicación y la devuelve cuando se va. Es una experiencia realmente mejor: la bandeja de notificaciones permanece limpia mientras la aplicación está en la pantalla, pero viene con una restricción estricta, y la restricción no es obvia.

Ocultar la notificación significa degradar el servicio. Android no tiene el concepto de servicio en primer plano sin una notificación, por lo que la única forma de ocultarlo es stopForeground(). El seguimiento continúa y el servicio continúa ejecutándose, pero mientras la notificación esté oculta, su proceso no mantendrá ningún servicio en primer plano.

Ese es exactamente el estado que Android elimina cuando el usuario elimina su aplicación de las recientes.

¿Por qué no se puede hacer que funcione?

Cuando se elimina una tarea, ActivityManager decide qué procesos eliminar de proc.foregroundServices y decide antes de enviar onTaskRemoved al subproceso principal de su aplicación. Por lo tanto, un SDK no puede solucionar la situación publicando la notificación en el momento de la eliminación; para entonces el veredicto ya está disponible. Tracelet tenía exactamente esa mitigación y no ayudó.

El resultado fue una carrera que nadie pudo ver. Desliza la aplicación en el espacio entre la salida de la pantalla y la notificación que regresa, y el proceso muere: no hay tareas sin cabeza, no hay eventos, no hay registros, nada de lo que stopOnTerminate: false existe para garantizar. Desliza un segundo después y todo funcionó perfectamente. La brecha se midió en 285 ms en un Pixel Fold y 700-1500 ms en un dispositivo con Android 15.

¿Qué hace Tracelet en su lugar?

La anulación no es silenciosa; eso fue la mitad de lo que encareció el error original. Se escribe una línea en el canal de registro del ciclo de vida siempre activo por start(), legible con Tracelet.getLogs() en cualquier nivel de registro, incluso desde una ejecución en estado interrumpido:

notification: showNotificationOnPauseOnly ignored because stopOnTerminate=false — hiding the
notification demotes the foreground service, and a swipe from recents in that window kills the
process (#378). Set stopOnTerminate=true to hide it while the app is open, or
showNotificationOnPauseOnly=false to stop asking.

getForegroundServiceHealth() informa lo mismo desde el otro lado. Cuando la notificación está legítimamente oculta (stopOnTerminate: true), serviceForeground es false y lastForegroundPromotionResult es suppressed: una degradación que usted solicitó, que es diferente de una promoción que el sistema operativo rechazó.

Eligiendo

Decide cuál necesitas realmente:

• El seguimiento debe sobrevivir al momento en que el usuario desliza la aplicación → mantenga stopOnTerminate: false y deje que se muestre la notificación. Este es el valor predeterminado correcto para aplicaciones de entrega, flotas, fuerza laboral y seguridad.
• Una bandeja de notificaciones limpia es más importante que sobrevivir al deslizamiento → configura stopOnTerminate: true. El seguimiento finaliza cuando la aplicación se elimina de las recientes, lo que para muchas aplicaciones de consumo es exactamente lo que el usuario espera de todos modos.

Tenga en cuenta que lo que obtiene en el segundo caso está limitado: en Android 14+, un servicio de ubicación en primer plano debe mostrar su notificación una vez que su aplicación está fuera de la pantalla, por lo que la ocultación solo se aplica mientras el usuario está en su aplicación.

Mostrar un temporizador transcurrido en la notificación

Para las aplicaciones creadas en torno a una sesión limitada (una entrega, un turno, un trabajo, un viaje), la notificación puede mostrar un reloj en marcha contando desde el momento que usted elija:

final shiftStartedAt = DateTime.now();
 
await Tracelet.setConfig(
  tl.Config(
    android: tl.AndroidConfig(
      foregroundService: tl.ForegroundServiceConfig(
        notificationTitle: 'Shift in progress',
        notificationStartedAt: shiftStartedAt.millisecondsSinceEpoch,
        notificationShowTimer: true,
        notificationOnlyAlertOnce: true,
      ),
    ),
  ),
);
 
await Tracelet.updateNotification();

Android procesa el reloj en sí. Llamas a esto una vez; el sistema operativo marca la pantalla en una segunda resolución durante la vida de la notificación. Su aplicación nunca se activa para volver a dibujarla y volver a publicar la notificación por un motivo no relacionado (texto nuevo, un cambio de configuración) no reinicia el recuento.

Usted proporciona notificationStartedAt en lugar de que Tracelet lo tome de start(), porque el período que le interesa a un usuario a menudo comienza antes que el seguimiento, o sobrevive a un reinicio del seguimiento. Para mostrar “desde que comenzó el seguimiento”, pase el momento en que llamó a start().

La contraparte de iOS es el temporizador de actividad en vivo, que toma los mismos dos campos en liveActivityConfig.

Escenario 2: La aplicación meteorológica (seguimiento periódico)

Conceptos explorados: WorkManager frente a Exact Alarms

El problema

Su usuario descargó su aplicación meteorológica local. Desea despertarse en segundo plano una vez cada 4 horas, obtener su ubicación y descargar el pronóstico local.

Usted no desea una notificación persistente del Servicio de primer plano. El usuario odiaría ver una notificación permanente de “Seguimiento del tiempo” en su cajón.

Cómo lo resuelve Tracelet: modo periódico

En lugar de un servicio continuo, Tracelet puede utilizar los programadores de trabajos de Android para despertarse brevemente, obtener una solución y volver a dormir.

android: tl.AndroidConfig(
  periodicUseForegroundService: false, 
  periodicUseExactAlarms: true, // Uses AlarmManager instead of WorkManager
)

Los dos programadores

1. Administrador de trabajo (periodicUseExactAlarms: false) El valor predeterminado. Es muy amigable con la batería. Sin embargo, Android decide cuándo ejecutarlo. Si le pide que se ejecute cada 15 minutos, Android podría esperar 45 minutos y ejecutarlo cuando el usuario desbloquee su teléfono para consultar Instagram (lo que se denomina “procesamiento por lotes”). Es muy inexacto.

2. Administrador de alarmas (periodicUseExactAlarms: true) Si es absolutamente NECESARIO activar el dispositivo exactamente a una hora específica, utilice esto. Requiere que declares el permiso SCHEDULE_EXACT_ALARM en tu android/app/src/main/AndroidManifest.xml:

   <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />

   Nota: Google Play revisa estrictamente este permiso. Úselo solo si su aplicación es un despertador, un calendario o si requiere absolutamente una hora exacta.

Escenario 3: La agresión OEM

Conceptos explorados: API de estado de configuración

El problema

Hiciste todo bien. Tienes un servicio en primer plano. Pero el usuario posee un teléfono Xiaomi. MIUI tiene un “Ahorro de batería” patentado que desactiva incluso los servicios en primer plano después de 5 minutos de tiempo de apagado de la pantalla.

Cómo lo resuelve Tracelet: mitigación automática y avisos

Tracelet aplica automáticamente mitigaciones internas siempre que sea posible, pero a veces el usuario tiene que incluir físicamente su aplicación en la lista blanca en el menú de configuración patentado del OEM.

final health = await tl.Tracelet.getSettingsHealth();
if (health['isAggressiveOem'] == true) {
  // Automatically opens the manufacturer-specific settings screen 
  // (e.g. Xiaomi Autostart, Huawei App Launch, Samsung Sleeping Apps)
  await tl.Tracelet.showPowerManager();
}

Para ver un ejemplo detallado de cómo implementar esto en su interfaz de usuario de Flutter, consulte la página Herramientas de diagnóstico y administración de energía.