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

Connessione Salute sarà inclusa in Android 14 come livello di archiviazione dati comune per i dati sanitari dei consumatori, protetto da autorizzazioni granulari e accessibile come app di sistema Android (in tutto questo documento, chiamato modulo "framework").

Gli sviluppatori dovrebbero considerare l'APK di Connessione Salute (Android 13) come un livello di compatibilità con le versioni precedenti per il modello di framework. Il modello framework manterrà una parità di funzionalità del 100% con il 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 descrive il piano di migrazione, fornisce alcuni scenari di migrazione di esempio ed elenca le modifiche all'SDK Jetpack che facilitano l'accesso all'API Health Connect.

Piano di migrazione

  1. Dopo il rilascio di Android 14, Google passerà a Connessione Salute come app di sistema Android.
  2. Verrà quindi eseguito il backfill dei dati dall'APK una volta raggiunta la parità di funzionalità.
  3. Tutti i punti di ingresso avranno come target l'UI dell'app di sistema.
  4. Verrà avviata la migrazione dei dati. Durante l'avanzamento della migrazione, le API del modulo verranno sospese con lo stato "Migrazione in elaborazione". Sarà visibile anche nell'interfaccia utente di Connessione Salute.
  5. Al termine della migrazione è possibile disinstallare l'APK.

Scenari di migrazione di esempio

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

Esempio 1 - In esecuzione (dati a intervalli)

Un utente ha raccolto 10 anni di record di esecuzione per un'ora ogni giorno. Ciò equivale a:

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

Dato che 1 blocco equivale a 3000 record, i dati precedenti corrispondono a circa 4 blocchi.

I nostri test interni hanno confermato che l'inserimento di un blocco tipico richiede circa un secondo, quindi la migrazione dei dati precedenti viene eseguita in circa quattro secondi.

Esempio 2 - Battito cardiaco (dati della serie)

Un utente ha raccolto 5 anni di dati sulla frequenza cardiaca (con un record creato ogni minuto) per un totale di 2.628.000 record.

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

Flusso di migrazione proposto

Abbiamo deciso di optare per la migrazione immediata. In pratica, ciò significa che l'APK diventerà inattivo non appena verrà eseguito l'upgrade del dispositivo ad Android 14, con un intervento minimo 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 lo blocca mentre è in corso la migrazione.
  3. Il processo di migrazione inizia quando la versione del modulo è compatibile con l'APK, ovvero la versione del modulo contiene lo stesso set di funzionalità o altre. 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. Una volta completato l'upgrade, inizierà il processo di migrazione.
  4. Al termine della migrazione, lo stato viene modificato in "Migrazione completata" e le API del modulo vengono sbloccate.
  5. Ora l'APK può essere disinstallato.

Elementi UI migrazione

Le seguenti schermate vengono visualizzate dal modulo del framework per scopi formativi per l'utente, sia prima che durante la migrazione:

Figura 1. Se l'APK di Connessione Salute non supporta la migrazione, viene visualizzato un messaggio che invita l'utente ad aggiornare l'APK. Se l'utente rifiuta l'aggiornamento, il modulo continua a funzionare e inizia ad accumulare autorizzazioni e dati:

Aggiornamento del telefono richiesto


Figura 2. Se il modulo del framework richiede un aggiornamento affinché diventi compatibile con le funzionalità, viene visualizzato un messaggio che chiede all'utente di eseguire l'aggiornamento e 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 visualizzata una rotellina che indica che i dati sono in fase di sincronizzazione:

Sincronizzazione dati

Dati deduplicati

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

Autorizzazioni

Se sono presenti autorizzazioni all'interno del 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. È stata data la preferenza a dati più recenti provenienti dal modulo.

I dati vengono deduplicati su clientRecordId se l'ID record è 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 chiave, insieme al tipo di dati e al nome del pacchetto dell'app.

Modifiche all'SDK Jetpack

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

Gli OEM possono iniziare l'integrazione con Jetpack 13 in modo che, quando Jetpack 14 sarà disponibile, tu sia in grado di appropriarsi della 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, dichiari le autorizzazioni utilizzando un formato 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 di 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>

Apri Connessione Salute

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

In Android 13, apri 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 deprecate: IsSdkSupported() e isProviderAvailable().

Modifiche all'API Session Record

Nella release alpha10 sono stati eliminati quattro sottotipi ExerciseSession:

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

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

Sia i sottotipi ExerciseSessionRecord che le modifiche SleepSession verranno rilasciati 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 e verranno invece 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

I log delle modifiche non verranno migrati nell'ambito del passaggio dall'APK ad Android 14.

Al termine della migrazione, inizierai a ricevere TOKEN_EXPIRED o TOKEN_INVALID eccezioni. Dovrebbero essere gestiti nei modi seguenti (in ordine di preferenza):

1. Leggere e deduplicare tutti i dati a partire dal timestamp dell'ultima lettura o degli ultimi 30 giorni.

Memorizza il timestamp dell'ultima lettura dei dati da parte di un'app da Connessione Salute. Alla scadenza del token, i dati devono essere riletti da questo valore o dai 30 giorni precedenti (a seconda di quale sia il numero minimo) e deduplicarli in base ai dati letti in precedenza utilizzando l'UUID.

2. Dati letti a partire dal timestamp dell'ultima lettura

Definisci un timestamp che indichi quando è stata l'ultima lettura dei dati da Connessione Salute e, alla scadenza del token, leggi tutti i dati dopo quel valore.

3. Elimina e rileggi i dati degli ultimi 30 giorni

Elimina tutti i dati letti da Connessione Salute dei 30 giorni precedenti e leggi di nuovo tutti i dati (ad esempio, come avviene quando le app si integrano per la prima volta con Connessione Salute).

4. Non fare nulla (ad es. rileggere i dati degli ultimi 30 giorni e non eseguire la deduplicazione)

Questa dovrebbe essere l'ultima risorsa, con il rischio associato di visualizzare dati duplicati. Gli sviluppatori dovrebbero esplorare le opzioni 1-3, dato che gli UUID dovrebbero essere già presenti.

Test delle API Android 14 con l'SDK Jetpack

Il rilascio dell'SDK Jetpack per Android 14 è previsto per il 7 giugno 2023, insieme alla release Beta 3 di Android 14. Dovrai iniziare a compilare la tua app su Android 14 per poter usare l'SDK Android 14 Jetpack.

Se vuoi testare la tua soluzione rispetto alle build di Anteprima per gli sviluppatori Android prima del 7 giugno, contatta il tuo POC di Google per ricevere assistenza.

Se vuoi testare la tua soluzione rispetto alla 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 privacy e la gestione dei dati di Connessione Salute si trovano in Impostazioni di sistema.

Per far sì che le schermate di gestione dei dati e autorizzazioni siano integrate nel dispositivo, Connessione Salute offre temi OEM tramite l'uso di overlay personalizzati.

Per la documentazione sullo stile OEM, consulta la documentazione relativa a Connessione Salute Google Mobile Services.