A partire dal 2026, eseguiremo la transizione dalle API Google Fit. Per ulteriori informazioni sulla migrazione di Google Fit, consulta la guida alla migrazione.

Questa pagina è stata tradotta dall'API Cloud Translation.

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

Connessione Salute verrà incluso in Android 14 come livello di archiviazione dei dati comune per i dati relativi a salute e fitness dei consumatori, protetto da autorizzazioni granulari e accessibile come app di sistema Android (indicato in questo documento come modulo "framework").

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

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

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

Piano di migrazione

Una volta rilasciato Android 14, Google inizierà a fornire Connessione Salute come app di sistema Android.
I dati verranno poi compilati a partire dall'APK una volta raggiunta la parità delle funzionalità.
Tutti i punti di ingresso avranno come target la UI dell'app di sistema.
Inizierà la migrazione dei dati. Durante l'avanzamento della migrazione, le API del modulo verranno sospese con lo stato "Migrazione in corso". Queste informazioni saranno visibili anche nell'interfaccia utente di Connessione Salute.
Una volta completata la migrazione, l'APK può essere disinstallato.

Scenari di migrazione di esempio

Di seguito sono riportati alcuni scenari di esempio che spiegano la procedura di migrazione per i tipi di dati interval e series:

Esempio 1: corsa (dati sugli intervalli)

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

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

Dato che un blocco equivale a 3000 record, i dati totalizzano 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 nell'esempio richiederebbe circa 4 secondi.

Esempio 2: frequenza cardiaca (dati di 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 blocco richiede circa un secondo, la migrazione dei dati avverrà in meno di 15 minuti.

Flusso di migrazione proposto

Abbiamo deciso di optare per una migrazione istantanea. In termini pratici, ciò significa che l'APK diventerà inattivo non appena il dispositivo verrà aggiornato ad Android 14, con un intervento utente minimo.

Di seguito è riportato il flusso di migrazione di alto livello:

L'utente esegue l'upgrade del dispositivo ad Android 14.
Jetpack 14 indirizza l'utente alle API del modulo e le blocca mentre la migrazione è in corso.
Il processo di migrazione inizia quando la versione del modulo è compatibile con le funzionalità dell'APK, ovvero la versione del modulo 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 le due versioni non sono compatibili con le funzionalità, è necessario eseguire l'upgrade della versione del modulo. Una volta completato l'upgrade, inizierà il processo di migrazione.
Una volta completata la migrazione, lo stato cambia in "Migrazione completata" e le API del modulo vengono sbloccate.
Ora l'APK può essere disinstallato.

Elementi UI di migrazione

I seguenti schermi vengono visualizzati dal modulo del framework per scopi di formazione degli utenti, sia prima che durante la migrazione:

Figura 1. Se l'APK di Health Connect non è "migration aware", viene visualizzato un prompt 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.

Figura di aggiornamento dello smartphone richiesto — **Figura 1**: richiesta di aggiornamento dell'APK di Connessione Salute.

Figura 2. Se il modulo framework richiede un aggiornamento per diventare compatibile con le funzionalità, viene visualizzato un prompt 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.

Cifra dell'aggiornamento dell'APK necessario — **Figura 2**: prompt per aggiornare il modulo del framework.

Figura 3. Durante il processo di migrazione viene visualizzato un indicatore di caricamento con un testo che spiega che i dati vengono sincronizzati.

Figura della sincronizzazione dei dati — **Figura 3**: migrazione dei dati in corso.

Dati deduplicati

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

Autorizzazioni

Se le autorizzazioni sono presenti nel modulo del framework, le 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 preferenza ai dati più recenti del modulo.

I dati vengono deduplicati su clientRecordId se l'ID record viene fornito dal cliente. 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 Connessione Salute sia per le API del framework Connessione Salute.

Gli OEM possono iniziare l'integrazione con Jetpack 13 in modo che, quando Jetpack 14 diventerà disponibile, tu possa appropriarti della nuova libreria e compilarla in Android 14.

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

Dichiarazione delle autorizzazioni

In Android 13, le autorizzazioni vengono dichiarate 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 standard delle autorizzazioni:

#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 include 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 oppure 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 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 sessione di allenamento non saranno più supportati e verranno aggiunti come tipi di segmenti 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 eccezioni TOKEN_EXPIRED o TOKEN_INVALID. Questi devono essere gestiti nei seguenti modi (in ordine di preferenza):

1. Leggi ed elimina i duplicati di tutti i dati dall'ultimo timestamp di lettura o degli ultimi 30 giorni

Memorizza un timestamp dell'ultima volta che un'app ha letto i dati 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 periodo minimo) e deduplicati rispetto ai dati letti in precedenza utilizzando l'UUID.

2. Leggi i dati dall'ultimo timestamp di lettura

Stabilisci un timestamp che indichi l'ultima lettura dei dati da Connessione Salute e, alla scadenza del token, leggi tutti i dati successivi a questo valore.

3. Elimina e rileggi i dati degli ultimi 30 giorni

Elimina tutti i dati letti da Connessione Salute negli ultimi 30 giorni e rilegge tutti i dati (ad es. come avviene quando le app si integrano per la prima volta con Connessione Salute).

4. Non fare nulla (ovvero rileggi i dati degli ultimi 30 giorni e non deduplica)

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à presenti.

Testare le API Android 14 con l'SDK Jetpack

Il rilascio dell'SDK Jetpack per Android 14 è previsto per il 7 giugno 2023, insieme alla beta 3 di Android 14. Per poter utilizzare l'SDK Jetpack per Android 14, devi iniziare a compilare la tua app in base ad Android 14.

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

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

Imposta compileSDKPreview = UpsideDownCake.
Aggiorna il 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 nelle Impostazioni di sistema.

Per fare in modo che le schermate di gestione dei dati e delle autorizzazioni abbiano l'aspetto e la funzionalità di una 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 di Health Connect. Per visualizzare la pagina, potrebbe essere necessario accedere a Google Developers.