Pianificare il rendimento

Ti consigliamo di attenerti alle seguenti linee guida sulle best practice, per assicurarti che la tua app funzioni correttamente insieme a Connessione Salute.

Scrittura di dati

Le app devono scrivere in Connessione Salute soltanto dati di provenienza.

Se i dati della tua app sono stati importati da un'altra app, la responsabilità di scrivere i propri dati in Connessione Salute ricade all'altra app.

È inoltre una buona idea implementare una logica che gestisca le eccezioni di scrittura, come i dati al di fuori dei limiti o un errore di sistema interno. Puoi applicare le strategie di backoff e riprovare a un meccanismo di pianificazione dei job. Se la scrittura su Connessione Salute non riesce, assicurati che la tua app possa proseguire oltre quel punto di esportazione. Non dimenticare di registrare e segnalare gli errori per facilitare la diagnosi.

Quando monitori i dati, ci sono un paio di suggerimenti che puoi seguire, a seconda del modo in cui la tua app scrive i dati.

Monitoraggio passivo

Sono incluse le app che eseguono il monitoraggio passivo dell'attività fisica o della salute, come la registrazione continua di passi o battito cardiaco in background.

La tua app deve scrivere periodicamente dati in Connessione Salute nei seguenti modi:

  • Ad ogni sincronizzazione, scrivi solo i nuovi dati e aggiorna quelli modificati dall'ultima sincronizzazione.
  • Richieste di blocco a un massimo di 1000 record per richiesta di scrittura.
  • Utilizza WorkManager per pianificare attività periodiche in background, con un periodo di tempo di almeno 15 minuti.

  • Limita le attività in modo che vengano eseguite solo quando il dispositivo è inattivo e la batteria non è in esaurimento.

    val constraints = Constraints.Builder()
    .requiresBatteryNotLow()
    .requiresDeviceIdle(true)
    .build()

val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
        15,
        TimeUnit.MINUTES,
        5,
        TimeUnit.MINUTES
    )
    .setConstraints(constraints)
    .build()

Monitoraggio attivo

Sono incluse app che eseguono il monitoraggio basato su eventi, come allenamento e sonno, o input manuale dell'utente, come l'alimentazione. Questi record vengono creati quando l'app è in primo piano o in rari eventi in cui viene utilizzata più volte al giorno.

Assicurati che la tua app non resti in esecuzione Connessione Salute per l'intera durata dell'evento.

I dati devono essere scritti in Connessione Salute in uno dei due seguenti modi:

  • Sincronizza i dati in Connessione Salute al termine dell'evento. Ad esempio, sincronizza i dati quando l'utente termina una sessione di allenamento rilevata.
  • Pianifica un'attività una tantum utilizzando WorkManager per sincronizzare i dati in un secondo momento.

Frequenza di campionamento

Quando scrivi dati in Connessione Salute, utilizza frequenze di campionamento appropriate per ridurre il carico dello spazio di archiviazione. Ad esempio, vale la pena pensare alla frequenza con cui i dati del conteggio dei passi devono essere registrati o al tipo di tipi di dati di frequenza di campionamento collegati a un esercizio attivo (come la velocità) richiesti.

Non tutti i tipi di dati richiedono la stessa frequenza di campionamento. L'aggiornamento dei dati sul conteggio dei passi ogni secondo offre pochi vantaggi rispetto a una cadenza meno frequente, ad esempio ogni 60 secondi. Tuttavia, frequenze di campionamento più elevate possono offrire agli utenti una visione più dettagliata e granulare dei dati su salute e fitness. Le frequenze di campionamento devono trovare un equilibrio tra dettagli e prestazioni.

Sincronizza dati

I seguenti fattori influiscono sul processo di sincronizzazione.

Scadenza del token

Poiché un token Modifiche inutilizzato scade entro 30 giorni, devi utilizzare una strategia di sincronizzazione che eviti di perdere informazioni. La strategia potrebbe includere i seguenti approcci:

  • Cerca nel datastore della tua app il record consumato più di recente che ha anche un id da Connessione Salute.
  • Richiedi a Connessione Salute i record che iniziano con un timestamp specifico, quindi li inserisci o li aggiorna nel datastore della tua app.
  • Richiedi un token Modifiche per prenotarlo per la prossima volta che sarà necessario.

Strategie consigliate per la gestione delle modifiche

Nel caso in cui la tua app riceva token Modifiche non validi o scaduti, ti consigliamo le seguenti strategie di gestione a seconda dell'applicazione nella tua logica:

  • Leggere e deduplicare tutti i dati. Questa è la strategia ideale.
    • Memorizza il timestamp dell'ultima volta che ha letto i dati da Connessione Salute.
    • Alla scadenza del token, rileggi tutti i dati del timestamp più recente o degli ultimi 30 giorni. Quindi, deduplicalo in base ai dati letti in precedenza utilizzando gli identificatori.
    • Idealmente, implementa gli ID client perché sono necessari per gli aggiornamenti dei dati.
  • Lettura solo dei dati a partire dall'ultimo timestamp di lettura. Questo comporta alcune discrepanze tra i dati al momento della scadenza del token Modifiche, ma il periodo di tempo è più breve, che potrebbe richiedere da alcune ore a un paio di giorni.
    • Memorizza il timestamp dell'ultima volta che ha letto i dati da Connessione Salute.
    • Alla scadenza del token, leggi tutti i dati a partire dal timestamp indicato.
  • Eliminare e leggere i dati degli ultimi 30 giorni. Questo è più in linea con ciò che accade con la prima integrazione.
    • Elimina tutti i dati letti dall'app da Connessione Salute per gli ultimi 30 giorni.
    • Una volta eliminati, leggi di nuovo tutti i dati.
  • Lettura dei dati degli ultimi 30 giorni senza deduplicazione. Questa è la strategia meno ideale e comporta la visualizzazione di dati duplicati agli utenti.
    • Elimina tutti i dati letti dall'app da Connessione Salute per gli ultimi 30 giorni.
    • Consenti voci duplicate.

Il tipo di dati cambia i token

Se la tua app consuma più di un tipo di dati in modo indipendente, utilizza token di modifica separati per ogni tipo di dati. Utilizza un elenco di più tipi di dati con l'API Changes Sync solo se questi tipi di dati vengono consumati insieme o non vengono utilizzati affatto.

Letture in primo piano

Le app possono leggere i dati di Connessione Salute soltanto quando sono in primo piano. Durante la sincronizzazione dei dati di Connessione Salute, l'accesso a Connessione Salute potrebbe essere interrotto in qualsiasi momento. Ad esempio, l'app deve gestire le interruzioni a metà di una sincronizzazione quando legge una grande quantità di dati da Connessione Salute e continuare all'apertura successiva.

Tempistiche di importazione

Dato che la tua app non può ricevere notifiche sui nuovi dati, controlla se ci sono nuovi dati in due momenti:

  • Ogni volta che l'app diventa attiva in primo piano. In questo caso, usa gli eventi del ciclo di vita.
  • Periodicamente, mentre l'app rimane in primo piano. Invia una notifica agli utenti quando sono disponibili nuovi dati, consentendo loro di aggiornare lo schermo in base alle modifiche.

Limiti di frequenza

In rare circostanze, Connessione Salute pone dei limiti di frequenza per le richieste provenienti dalla tua app. Questo viene fatto per limitare l'impatto sulla batteria e le prestazioni del dispositivo.

  • Ti consigliamo vivamente di seguire le linee guida delle best practice per evitare che le richieste della tua app vengano rifiutate a causa della limitazione della frequenza.
  • Le app devono essere resilienti alla limitazione della frequenza. Ad esempio, i dati in background possono essere scritti durante l'attività periodica successiva, in caso di richieste non riuscite a causa della limitazione di frequenza.

Onboarding dell'app

Molte app prevedono un flusso di onboarding personalizzato, come informazioni sulle funzionalità o la richiesta del consenso dell'utente. Agli sviluppatori consigliamo vivamente di esportare un'attività di onboarding avviata da Connessione Salute quando l'utente interagisce con l'app per la prima volta. Per farlo, aggiungi quanto segue nel file manifest:

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING"
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.ACTION_SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

Tieni presente che il supporto per questa funzionalità non è ancora disponibile per Android 14, ma lo sarà a breve.

Quando un utente tenta di connettere la tua app a Connessione Salute, viene avviata l'attività esportata. Questa attività deve:

  • Mostra qualsiasi informazione pertinente agli utenti, ad esempio spiegando quali dati vengono scritti o letti.
  • Chiedi all'utente di concedere il consenso, se necessario.
  • Invia una richiesta di autorizzazione a Connessione Salute.
  • Esegui qualsiasi altra logica specifica dell'applicazione, ad esempio la pianificazione di un worker periodico.
  • Al termine, consenti all'utente di ignorare l'attività.

Per le app che non esportano un'attività di onboarding, Connessione Salute mostra invece l'utente alla schermata Gestisci autorizzazioni quando l'utente tenta di connettere l'app. Questo può essere accettabile per le app in cui le autorizzazioni sono l'unico prerequisito per il funzionamento dell'integrazione.

Tieni presente che l'attività di onboarding potrebbe essere avviata più di una volta, ad esempio se in un secondo momento l'utente revoca le autorizzazioni per la tua app e poi la riconnette.