Eseguire la migrazione di Connessione Salute da Android 13 (APK) ad Android 14 (framework)

Connessione Salute verrà pacchettizzato con Android 14 come livello di archiviazione dei dati comune per i dati sulla salute dei consumatori, protetto da autorizzazioni granulari e accessibile come app di sistema Android (indicata in tutto questo documento come modulo "framework").

Gli sviluppatori devono considerare l'APK Connessione Salute (Android 13) come un livello di compatibilità con le versioni precedenti per il modello del framework. Il modello del framework manterrà la parità di funzionalità al 100% rispetto al suo predecessore APK.

Durante la transizione da Android 13 ad Android 14, è di vitale importanza che l'esperienza utente rimanga il più fluida e intuitiva possibile.

Questo documento illustra il piano di migrazione, fornisce alcuni scenari di migrazione di esempio ed elenca le modifiche all'SDK Jetpack, che facilita l'accesso all'API Connessione Salute.

Piano di migrazione

  1. Una volta rilasciato Android 14, Google passerà a fornire Connessione Salute come app di sistema Android.
  2. Una volta raggiunta la parità di funzionalità, i dati verranno sottoposti a backfill dall'APK.
  3. Tutti i punti di contatto avranno come target l'interfaccia utente dell'app di sistema.
  4. Inizierà la migrazione dei dati. Durante la migrazione, le API del modulo verranno sospese con lo stato "Migrazione in corso". Questo verrà visualizzato anche nell'interfaccia utente di Connessione Salute.
  5. Una volta completata la migrazione, l'APK può essere disinstallato.

Scenari di migrazione di esempio

Ecco alcuni scenari di esempio che spiegano la procedura di migrazione per i tipi di dati interval e series:

Esempio 1: corsa (dati intervallari)

Un utente ha raccolto 10 anni di record di corsa per 1 ora ogni giorno. Ciò equivale a:

  • Record delle sessioni di allenamento: 365 * 10 * 1
  • Passaggi: 365 * 10 * 1
  • Calorie: 365 * 10 * 1
  • Totale = 365 * 10 * 3 (365 * 30) = 10.150

Poiché un chunk equivale a 3000 record, i dati riportati sopra totalizzano circa 4 chunk.

I nostri test interni hanno confermato che l'inserimento di un chunk tipico richiede circa un secondo, quindi la migrazione dei dati sopra indicati richiederebbe circa 4 secondi.

Esempio 2: frequenza cardiaca (dati delle serie)

Un utente ha raccolto 5 anni di dati sul battito cardiaco (con un record creato ogni minuto) per un totale di 2.628.000 record.

Con 3000 record per blocco, i dati vengono distribuiti su 876 blocchi. Dato che l'inserimento di un chunk richiede circa un secondo, la migrazione dei dati verrà eseguita in meno di 15 minuti.

Flusso di migrazione proposto

Abbiamo deciso di optare per una migrazione istantanea. In termini pratici, questo significa che l'APK diventerà inattivo non appena verrà eseguito l'upgrade del dispositivo ad Android 14, con un intervento minimo da parte dell'utente.

Diamo un'occhiata a un flusso di migrazione di alto livello:

  1. L'utente esegue l'upgrade del dispositivo ad Android 14.
  2. Jetpack 14 indirizza l'utente alle API del modulo e le blocca mentre la migrazione è in corso.
  3. Il processo di migrazione inizia quando la versione del modulo è compatibile con le funzionalità dell'APK, ovvero quando contiene lo stesso insieme di funzionalità o più. Una volta avviato il processo di migrazione, l'APK esegue la migrazione delle autorizzazioni e dei dati.
    1. Se entrambe le versioni non sono compatibili con le funzionalità, sarà necessario eseguire l'upgrade della versione del modulo. Al termine dell'upgrade, inizierà il processo di migrazione.
  4. Al termine della migrazione, lo stato diventa "Migrazione completata" e le API del modulo vengono sbloccate.
  5. Ora l'APK può essere disinstallato.

Elementi dell'interfaccia utente della migrazione

Il modulo del framework mostra le seguenti schermate per scopi di formazione degli utenti, sia prima che durante la migrazione:

Figura 1. Se l'APK di Connessione Salute non è "consapevole della migrazione", viene visualizzato un messaggio che chiede all'utente di aggiornare l'APK. Se l'utente rifiuta l'aggiornamento, il modulo continua a funzionare e inizia ad accumulare autorizzazioni e dati:

Aggiornamento dello smartphone necessario


Figura 2. Se il modulo del framework richiede un aggiornamento per essere compatibile con le funzionalità, viene visualizzato un messaggio che chiede all'utente di eseguire l'aggiornamento e di riavviare il dispositivo. Se l'utente rifiuta l'aggiornamento, il modulo continua a funzionare e inizia ad accumulare autorizzazioni e dati:

Aggiornamento dell'APK necessario


Figura 3. Durante il processo di migrazione viene visualizzato un indicatore di attesa con un testo che spiega che i dati sono in fase di sincronizzazione:

Sincronizzazione dei dati

Dati deduplicati

Se il modulo del framework ha iniziato ad acquisire dati e autorizzazioni prima di qualsiasi migrazione o ripristino basato su cloud, si applicano le seguenti regole.

Autorizzazioni

Se le autorizzazioni sono presenti nel modulo del framework, eventuali autorizzazioni duplicate acquisite dall'APK vengono ignorate durante il processo di migrazione.

Dati

Durante la migrazione, i dati duplicati provenienti dall'APK vengono ignorati. Viene data la priorità ai dati più recenti del modulo.

I dati vengono deduplicati su clientRecordId se l'ID record viene fornito dal client. In caso contrario, gli intervalli di tempo (startTime e endTime per i record interni e time per i record istantanei) vengono trattati come chiavi, insieme al tipo di dati e al nome del pacchetto dell'app.

Modifiche nell'SDK Jetpack

L'SDK Jetpack funge da punto di integrazione comune sia per l'APK Health Connect sia per le API del framework Health Connect.

Gli OEM possono iniziare a eseguire l'integrazione con Jetpack 13 in modo che, quando Jetpack 14 sarà disponibile, possano acquisire la nuova libreria e compilarla in Android 14.

Rilasceremo una nuova versione dell'SDK che supporta la transizione ad Android 14. Dovrai apportare alcune modifiche all'integrazione esistente per garantire una transizione senza problemi.

Dichiarazione delle autorizzazioni

In Android 13, le autorizzazioni vengono dichiarate utilizzando un formato delle autorizzazioni personalizzato in un file di risorse collegato al manifest:

#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>

Per supportare Android 14, gli sviluppatori devono passare al formato delle autorizzazioni standard:

#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>

Aprire Connessione Salute

La maggior parte delle app di terze parti dispone di un pulsante che apre l'app Connessione Salute, ad esempio il pulsante "Gestisci accesso" in Fitbit.

In Android 13, puoi aprire l'app Connessione Salute utilizzando il nome del pacchetto o tramite l'azione androidx.health.ACTION_HEALTH_CONNECT_SETTINGS.

In Android 14, devi utilizzare un'azione intent, specificata nell'SDK Jetpack, che ha valori diversi in base alla versione di Android su cui agisce:

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

Ottenere il client Connessione Salute

Abbiamo creato una singola API chiamata sdkStatus, disponibile in Jetpack 11, per sostituire altre due API ritirate: IsSdkSupported() e isProviderAvailable().

Modifiche all'API Session Record

Nell'ambito della release alpha10 sono stati eliminati quattro sottotipi di ExerciseSession:

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

Come per ExerciseSessionRecord, SleepStage diventerà un sottotipo di SleepSession.

Sia i sottotipi ExerciseSessionRecord sia le modifiche a SleepSession verranno rilasciate nell'ambito dell'aggiornamento dell'SDK di aprile.

Aggiornamento del tipo di sessione di allenamento

I seguenti tipi di sessioni di allenamento non saranno più supportati, ma verranno aggiunti come tipi di segmento in un secondo momento:

  • 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

Tipi di sostituzione:

  • EXERCISE_TYPE_HIGH_INTENSITY_INTERVAL_TRAINING
  • EXERCISE_TYPE_STRENGTH_TRAINING
  • EXERCISE_TYPE_CALISTHENICS

Gestione del log delle modifiche

La migrazione dei log delle modifiche non verrà eseguita durante il passaggio dall'APK ad Android 14.

Al termine della migrazione, inizierai a ricevere eccezioni TOKEN_EXPIRED o TOKEN_INVALID. Questi problemi devono essere gestiti nel seguente modo (in ordine di preferenza):

1. Leggi e deduplica tutti i dati dal timestamp "ultima lettura" o per gli ultimi 30 giorni

Memorizza un timestamp dell'ultima volta che un'app ha letto dati da Connessione Salute. Alla scadenza del token, i dati devono essere riletti da questo valore o dai 30 giorni precedenti (a seconda del valore minimo) e deduplicati rispetto ai dati letti in precedenza utilizzando l'UUID.

2. Leggi i dati dal timestamp "ultima lettura"

Stabilisci un timestamp che indichi l'ultima volta che i dati sono stati letti da Connessione Salute e, al momento della scadenza del token, leggi tutti i dati successivi a quel valore.

3. Eliminare e rileggere i dati degli ultimi 30 giorni

Eliminare tutti i dati letti da Connessione Salute nei 30 giorni precedenti e leggere di nuovo tutti i dati (ad esempio come avviene quando le app vengono integrate per la prima volta con Connessione Salute).

4. Non fare nulla (ad es. rileggi i dati degli ultimi 30 giorni e non eliminare le duplicazioni)

Questa opzione deve essere utilizzata come ultima risorsa, con il rischio associato di visualizzare dati duplicati. Gli sviluppatori dovrebbero invece esplorare le opzioni 1-3, dato che gli UUID dovrebbero essere già implementati.

Test delle API Android 14 con l'SDK Jetpack

L'SDK Jetpack per Android 14 verrà rilasciato il 7 giugno 2023, insieme alla release beta 3 di Android 14. Per poter utilizzare l'SDK Jetpack per Android 14, dovrai iniziare a compilare l'app per Android 14.

Se vuoi testare la tua soluzione con le build Android Developer Preview prima del 7 giugno, contatta il tuo punto di contatto Google per ricevere assistenza.

Se vuoi testare la tua soluzione con la release beta 3, devi apportare le seguenti modifiche all'APK:

  1. Imposta compileSDKPreview = UpsideDownCake.
  2. Aggiorna il file manifest in modo da includere un'intent per 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>

Personalizzazione OEM

In Android 14, i controlli per la gestione dei dati e la privacy di Connessione Salute si trovano nelle Impostazioni di sistema.

Per fare in modo che le schermate di gestione dei dati e delle autorizzazioni sembrino parte del dispositivo, Connessione Salute offre temi OEM tramite l'uso di overlay personalizzati.

Per la documentazione sullo stile OEM, consulta la documentazione di Google Mobile Services per Health Connect. Per visualizzare la pagina, potrebbe essere necessario accedere a Google Developers.