Cómo migrar Health Connect de Android 13 (APK) a Android 14 (framework)

Health Connect se empaquetará con Android 14 como una capa de almacenamiento de datos común para los datos de salud del consumidor, protegida por permisos detallados y accesible como una app del sistema Android (en este documento, conocida como el módulo "framework").

Los desarrolladores deben considerar el APK de Health Connect (Android 13) como una capa de retrocompatibilidad para el modelo de framework. El modelo de framework retendrá la paridad de funciones al 100% respecto de su predecesor de APK.

Durante la transición de Android de 13 a 14, es fundamental que la experiencia del usuario sea lo más intuitiva y fluida posible.

En este documento, se describe el plan de migración, se proporcionan algunas situaciones de ejemplo y se enumeran los cambios en el SDK de Jetpack (lo cual facilita el acceso a la API de Health Connect).

Plan de migración

  1. Una vez que se lance Android 14, Google comenzará a proporcionar Health Connect como una app del sistema de Android.
  2. Los datos se reabastecerán desde el APK una vez que se alcance la paridad de funciones.
  3. Todos los puntos de entrada se orientarán a la IU de la app del sistema.
  4. Comenzará la migración de datos. Mientras se completa la migración, se suspenderán las APIs del módulo con el estado “Migración en proceso”. Esto también será visible en la IU de Health Connect.
  5. Una vez que se complete la migración, se podrá desinstalar el APK.

Ejemplos de situaciones de migración

A continuación, se muestran algunas situaciones de ejemplo en las que se explica el proceso de migración para los tipos de datos interval y series:

Ejemplo 1: Correr (datos del intervalo)

Un usuario recopiló 10 años de registros de correr durante 1 hora todos los días. Esto equivale a lo siguiente:

  • Registros de sesión de ejercicio: 365 * 10 * 1
  • Pasos: 365 * 10 * 1
  • Calorías: 365 * 10 * 1
  • Total = 365 * 10 * 3 (365 * 30) = 10,150

Dado que 1 fragmento equivale a 3,000 registros, los datos anteriores suman alrededor de 4 fragmentos.

Nuestras pruebas internas confirmaron que un fragmento típico tarda aproximadamente un segundo en insertarse, por lo que los datos anteriores se migrarían en alrededor de 4 segundos.

Ejemplo 2: Frecuencia cardíaca (datos de la serie)

Un usuario recopiló 5 años de datos de la frecuencia cardíaca (con un registro creado cada minuto) que suman 2,628,000 registros.

A 3,000 registros por fragmento, los datos se distribuyen en 876 fragmentos. Dado que 1 fragmento tarda aproximadamente un segundo en insertarse, los datos se migrarán en menos de 15 minutos.

Flujo de migración propuesto

Decidimos optar por una migración instantánea. En términos prácticos, esto significa que el APK quedará inactivo en cuanto se actualice el dispositivo a Android 14, con una intervención mínima del usuario.

Veamos un flujo de migración de alto nivel:

  1. El usuario actualiza su dispositivo a Android 14.
  2. Jetpack 14 enruta al usuario a las APIs del módulo y las bloquea mientras se realiza la migración.
  3. El proceso de migración comienza cuando la versión del módulo es compatible con el APK, es decir, la versión del módulo contiene el mismo conjunto de atributos o más. Una vez que comienza el proceso de migración, el APK migra los permisos y los datos.
    1. Si las versiones no tienen atributos compatibles, se deberá actualizar la versión del módulo. Cuando se complete la actualización, comenzará el proceso de migración.
  4. Una vez que se complete la migración, el estado cambiará a "Migración completada" y se desbloquearán las APIs del módulo.
  5. Ahora se puede desinstalar el APK.

Elementos de la IU de migración

El módulo del framework muestra las siguientes pantallas con fines de educación del usuario, tanto antes como durante la migración:

Figura 1: Si el APK de Health Connect no reconoce la migración, se mostrará un mensaje en el que se le indicará al usuario que actualice el APK. Si el usuario rechaza la actualización, el módulo seguirá funcionando y comenzará a acumular permisos y datos:

Se requiere actualizar el teléfono


Figura 2: Si el módulo del framework requiere una actualización para que sea compatible con las funciones, se mostrará un mensaje en el que se le pedirá al usuario que realice la actualización y reinicie el dispositivo. Si el usuario rechaza la actualización, el módulo seguirá funcionando y comenzará a acumular permisos y datos:

Se debe actualizar el APK


Figura 3: Se muestra un ícono giratorio durante el proceso de migración con texto para explicar que se están sincronizando los datos:

Sincronización de datos

Datos sin duplicados

Si el módulo del framework comenzó a adquirir datos y permisos antes de que se realizara cualquier migración o restablecimiento basado en la nube, se aplican las siguientes reglas.

Permisos

Si los permisos están presentes en el módulo del framework, se ignorarán los permisos duplicados adquiridos del APK durante el proceso de migración.

Datos

Durante la migración, se ignoran los datos duplicados que se originan en el APK. Se da preferencia a datos más recientes del módulo.

Se eliminan los duplicados de los datos en clientRecordId si el cliente proporciona el ID de registro. Si no es así, los intervalos de tiempo (startTime y endTime para registros internos, y time para registros instantáneos) se tratan como clave, junto con el tipo de datos y el nombre de paquete de la app.

Cambios en el SDK de Jetpack

El SDK de Jetpack sirve como punto de integración común para el APK de Health Connect y las APIs del framework de Health Connect.

Los OEMs pueden comenzar a integrarse con Jetpack 13 para que, cuando Jetpack 14 esté disponible, puedas apropiarte de la nueva biblioteca y compilarla en Android 14.

Lanzaremos una nueva versión del SDK que admita la transición a Android 14. Deberás realizar algunos cambios en tu integración existente para garantizar una transición sin problemas.

Declaración de permisos

En Android 13, declaras los permisos con un formato de permisos personalizado, en un archivo de recursos vinculado al manifiesto:

#AndroidManifest.xml

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
    </intent-filter>
    <meta-data
        android:name="health_permissions"
        android:resource="@array/health_permissions"/>
</activity>

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

#health_permissions.xml

<resources>
  <array name="health_permissions">
    <item>androidx.health.permission.SleepSession.READ</item>
    <item>androidx.health.permission.SleepStage.READ</item>
    <item>androidx.health.permission.Weight.READ</item>
    <item>androidx.health.permission.Weight.WRITE</item>
  </array>
</resources>

Para admitir Android 14, los desarrolladores deben cambiar al formato de permisos estándar:

#AndroidManifest.xml

<uses-permission android:name=android.permission.health.READ_SLEEP />
<uses-permission android:name=android.permission.health.READ_WEIGHT />
<uses-permission android:name=android.permission.health.WRITE_WEIGHT />

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
</activity>

<queries>
    <package android:name="com.google.android.apps.healthdata"/>
</queries>

Cómo abrir Health Connect

La mayoría de las apps de terceros incluyen un botón que abre la app de Health Connect, como el botón "Administrar acceso" en Fitbit.

En Android 13, abre la app de Health Connect con el nombre del paquete o mediante la acción androidx.health.ACTION_HEALTH_CONNECT_SETTINGS.

En Android 14, debes usar una acción de intent, especificada en el SDK de Jetpack, que tiene valores diferentes según la versión de Android en la que actúa:

@get:JvmName("getHealthConnectSettingsAction") @JvmStatic val ACTION_HEALTH_CONNECT_SETTINGS

Cómo obtener el cliente de Health Connect

Creamos una sola API llamada sdkStatus, disponible en Jetpack 11, para reemplazar otras dos APIs obsoletas: IsSdkSupported() y isProviderAvailable().

Cambios en la API de registro de sesión

Se borraron cuatro subtipos de ExerciseSession como parte de la versión alfa10:

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

Al igual que con ExerciseSessionRecord, SleepStage se convertirá en un subtipo de SleepSession.

Los subtipos ExerciseSessionRecord y los cambios de SleepSession se lanzarán como parte de la actualización del SDK de abril.

Actualización del tipo de sesión de ejercicio

Los siguientes tipos de sesiones de ejercicio ya no serán compatibles y, en su lugar, se agregarán como tipos de segmentos más adelante:

  • EXERCISE_TYPE_BACK_EXTENSION
  • EXERCISE_TYPE_BARBELL_SHOULDER_PRESS
  • EXERCISE_TYPE_BENCH_PRESS
  • EXERCISE_TYPE_BENCH_SIT_UP
  • EXERCISE_TYPE_BURPEE
  • EXERCISE_TYPE_CRUNCH
  • EXERCISE_TYPE_DEADLIFT
  • EXERCISE_TYPE_DUMBBELL_CURL_LEFT_ARM
  • EXERCISE_TYPE_DUMBBELL_CURL_RIGHT_ARM
  • EXERCISE_TYPE_DUMBBELL_FRONT_RAISE
  • EXERCISE_TYPE_DUMBBELL_LATERAL_RAISE
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_LEFT_ARM
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_RIGHT_ARM
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_TWO_ARM
  • EXERCISE_TYPE_FORWARD_TWIST
  • EXERCISE_TYPE_JUMPING_JACK
  • EXERCISE_TYPE_JUMP_ROPE
  • EXERCISE_TYPE_LAT_PULL_DOWN
  • EXERCISE_TYPE_LUNGE
  • EXERCISE_TYPE_PLANK
  • EXERCISE_TYPE_SQUAT
  • EXERCISE_TYPE_UPPER_TWIST

Tipos de reemplazo:

  • EXERCISE_TYPE_HIGH_INTENSITY_INTERVAL_TRAINING
  • EXERCISE_TYPE_STRENGTH_TRAINING
  • EXERCISE_TYPE_CALISTHENICS

Manejo del registro de cambios

Los registros de cambios no se migrarán como parte del cambio de APK a Android 14.

Una vez que se complete la migración, comenzarás a recibir excepciones TOKEN_EXPIRED o TOKEN_INVALID. Se deben controlar de las siguientes maneras (en orden de preferencia):

1. Leer y anular la duplicación de todos los datos desde la marca de tiempo de "última lectura" o de los últimos 30 días

Almacena una marca de tiempo de la última vez que una app leyó datos de Health Connect. Cuando venza el token, los datos deben volver a leerse a partir de este valor o de los 30 días anteriores (lo que equivale al mínimo) y se debe anular la duplicación en función de los datos leídos previamente con el UUID.

2. Leer datos desde la marca de tiempo de "última lectura"

Establece una marca de tiempo que indique cuándo se leyeron por última vez los datos de Health Connect y, una vez que venza el token, lee todos los datos después de ese valor.

3. Borrar y volver a leer los datos de los últimos 30 días

Borra todos los datos leídos de Health Connect de los 30 días anteriores y vuelve a leerlos (por ejemplo, como se hace cuando las apps se integran por primera vez con Health Connect).

4. No hacer nada (es decir, volver a leer los datos de los últimos 30 días y no anular la duplicación)

Se debe usar como último recurso, con un riesgo asociado de mostrar datos duplicados. En su lugar, los desarrolladores deben explorar las opciones 1 a 3, dado que los UUIDs ya deben estar implementados.

Cómo probar las APIs de Android 14 con el SDK de Jetpack

El SDK de Jetpack para Android 14 se lanzará el 7 de junio de 2023, junto con la versión beta 3 de Android 14. Deberás comenzar a compilar tu app en Android 14 para poder usar el SDK de Jetpack para Android 14.

Si deseas probar tu solución con las compilaciones de la Versión preliminar para desarrolladores de Android antes del 7 de junio, comunícate con tu PDC de Google para obtener asistencia.

Si deseas probar tu solución con la versión beta 3, debes realizar los siguientes cambios en tu APK:

  1. Establece compileSDKPreview = UpsideDownCake.
  2. Actualiza el manifiesto e incluye un intent para Android 14:
# AndroidManifest.xml

<uses-permission android:name=android.permission.health.READ_SLEEP/>
<uses-permission android:name=android.permission.health.READ_WEIGHT/>
<uses-permission android:name=android.permission.health.WRITE_WEIGHT/>

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
    </intent-filter>
</activity>

<activity-alias>
      android:name="AndroidURationaleActivity"
      android:exported="true"
      android:targetActivity=".RationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
      <intent-filter>
        <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
        <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
      </intent-filter>
</activity-alias>

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

Personalización de OEM

En Android 14, los controles de privacidad y administración de datos de Health Connect se encuentran en Configuración del sistema.

Para que las pantallas de administración de datos y permisos se vean y se sientan parte del dispositivo, Health Connect ofrece temas de OEM mediante el uso de superposiciones personalizadas.

Para obtener documentación sobre el estilo de OEM, consulta la documentación de Servicios de Google para dispositivos móviles de Health Connect.