Google Fit — cos'è, architettura della piattaforma e API

Cos'è Google Fit?

Google Fit è una piattaforma di gestione della salute lanciata da Google nel 2014 alla conferenza I/O. La piattaforma fornisce un'API unificata per leggere e scrivere dati sull'attività fisica, consentendo alle applicazioni di scambiare informazioni attraverso un repository centrale nel cloud Google.

A differenza delle soluzioni proprietarie, Google Fit funziona sul sistema operativo Android e iOS tramite REST API. Gli utenti possono connettere braccialetti fitness, smartwatch e app di tracciamento dell'attività, e Google Fit aggrega tutti i dati in un unico profilo sanitario in Google Cloud.

Secondo Google I/O 2024, la piattaforma è utilizzata in oltre 5000 applicazioni in tutto il mondo e il numero di utenti attivi supera i 100 milioni. La piattaforma è integrata con Wear OS e supporta tutti i fitness tracker più popolari tramite applicazioni di terze parti.

Architettura di Google Fit

L'architettura di Google Fit è costruita su tre livelli: SDK client, archiviazione cloud Google Fitness Store e REST API per l'integrazione server. L'SDK client è disponibile per Android (Kotlin, Java) e iOS (Swift, Objective-C), ed è disponibile anche un client web tramite JavaScript.

I dati sono organizzati come sorgenti (DataSource) e punti dati (DataPoint). Ogni sorgente rappresenta un dispositivo o un'applicazione, e ogni punto dati rappresenta una singola misurazione con un timestamp. Gruppi di punti dati vengono combinati in sessioni — periodi continui di attività con un tipo e una durata.

val fitnessClient = Fitness.getClient(activity, GoogleSignIn
    .getAccountForExtension(activity, fitnessOptions))

val stepType = DataType.TYPE_STEP_COUNT_DELTA

val request = DataReadRequest.Builder()
    .read(stepType)
    .setTimeRange(
        startTime, endTime, TimeUnit.MILLISECONDS
    )
    .build()

fitnessClient.readData(request)
    .addOnSuccessListener { response ->
        for (bucket in response.buckets) {
            println(bucket.dataSets)
        }
    }

Come funziona Google Fit

Google Fit utilizza un modello di sincronizzazione attraverso Google Cloud con supporto per modalità online e offline. L'app registra i dati localmente e l'SDK di Google Fit li sincronizza automaticamente con l'archiviazione cloud quando è disponibile una connessione Internet. I conflitti vengono risolti in base al principio dell'ultima scrittura.

Ogni tipo di dato ha un formato standardizzato: passi — TYPE_STEP_COUNT_DELTA, calorie — TYPE_CALORIES_EXPENDED, frequenza cardiaca — TYPE_HEART_RATE_BPM, distanza — TYPE_DISTANCE_DELTA. Per i tipi personalizzati, è possibile creare DataType personalizzati tramite la console Google APIs con un namespace univoco.

La piattaforma supporta due modalità di registrazione: attiva — l'app chiama esplicitamente HistoryClient.insertData(), e passiva — tramite RecordingClient, che si abbona alla raccolta dati in background. La modalità passiva è comoda per le app fitness: l'utente avvia l'app una volta e Google Fit raccoglie automaticamente passi, calorie e distanza mentre l'app è ridotta a icona, senza uso costante della CPU.

Secondo Google, la piattaforma elabora oltre 2 miliardi di punti dati ogni giorno. La latenza media di sincronizzazione è di 5–10 secondi con una connessione attiva, mentre in modalità background la sincronizzazione avviene ogni 30 minuti per risparmiare batteria.

Consenso dell'utente e sicurezza

Google Fit utilizza OAuth 2.0 per l'autorizzazione con ambiti di accesso fitness.activity.read, fitness.activity.write, fitness.body.read e fitness.body.write. L'app richiede solo gli ambiti necessari e l'utente conferma l'accesso tramite il dialogo standard di Google Sign-In con selezione dell'account.

L'utente può revocare l'accesso in qualsiasi momento tramite Google Account Permissions o l'app Google Fit. Google vieta severamente la condivisione di dati sanitari con terze parti senza consenso esplicito, nonché l'utilizzo dei dati per scopi pubblicitari in conformità con la politica Restricted Scopes.

API di Google Fit

Google Fit fornisce tre API principali: Fitness API per leggere e scrivere dati storici, Sensors API per lo streaming in tempo reale dei dati dai sensori e Sessions API per gestire le sessioni di attività. Ogni API è disponibile sia tramite l'SDK Android che tramite richieste REST.

Fitness API è l'API principale per lavorare con i dati. Supporta operazioni batch: scrittura fino a 1000 punti dati in una singola chiamata, lettura con filtraggio per intervallo di tempo, tipo di dato e origine. Per l'aggregazione dei dati viene utilizzato DataSet con raggruppamento per metriche selezionate.

Sensors API consente di abbonarsi ai dati dei sensori in tempo reale — passi, frequenza cardiaca, accelerazione. I dati vengono ricevuti tramite SensorEventListener con una frequenza determinata dal tipo di sensore e dalle impostazioni dell'app.

Oltre alle tre API principali, Google Fit fornisce Recording API per la raccolta automatica dei dati senza dover mantenere l'app attiva. Questa API è particolarmente preziosa per Wear OS: gli smartwatch possono raccogliere dati sulla frequenza cardiaca e sull'attività, e l'app del telefono si sincronizza con essi quando connessa. Recording API utilizza Google Fit Background Services, ottimizzati per un consumo energetico minimo — fino al 2% di batteria al giorno con la raccolta passiva dei passi.

REST API di Google Fit è disponibile all'endpoint fitness.googleapis.com. REST API consente alle applicazioni server di leggere e scrivere dati per conto dell'utente dopo l'autorizzazione OAuth. Ciò è utile per dashboard di analisi web, programmi fitness aziendali e sistemi medici che richiedono l'archiviazione centralizzata dei dati sanitari dei dipendenti o dei pazienti.

val recordingClient = Fitness
    .getRecordingClient(activity, googleSignInAccount)

recordingClient.subscribe(DataType.TYPE_STEP_COUNT_DELTA)
    .addOnSuccessListener {
        println("Abbonamento attivo")
    }

// Recupero dati cronologia
val historyClient = Fitness
    .getHistoryClient(activity, googleSignInAccount)

val endTime = Calendar.getInstance().timeInMillis
val startTime = endTime - TimeUnit
    .DAYS.toMillis(7)

historyClient.readDailyTotal(DataType.TYPE_STEP_COUNT_DELTA)
    .addOnSuccessListener { total ->
        println("Passi oggi: $total")
    }

Integrare Google Fit in un'app

L'integrazione di Google Fit inizia con l'aggiunta delle dipendenze dell'SDK Google Fit tramite build.gradle: com.google.android.gms:play-services-fitness. Successivamente, è necessario configurare la console Google APIs — creare un progetto, abilitare Fitness API e aggiungere credenziali OAuth 2.0 con le impronte SHA-1 corrette.

Il processo di integrazione include: inizializzare GoogleSignIn con gli ambiti necessari, creare un FitnessClient tramite Fitness.getClient(), richiedere l'autorizzazione dell'utente ed eseguire operazioni di lettura o scrittura dei dati. Per la registrazione in background viene utilizzato RecordingClient, che raccoglie automaticamente i dati anche quando l'app è ridotta a icona. Google Fit gestisce automaticamente la frequenza di raccolta dati in base al livello della batteria e all'attività dell'utente.

Secondo Google, le app con integrazione Google Fit mostrano un tasso di fidelizzazione degli utenti superiore del 35%. Le categorie di app principali sono tracker fitness, app per corsa, ciclismo, yoga e controllo del peso.

È importante considerare i requisiti di privacy: Google Fit utilizza Restricted Scopes — ambiti di accesso speciali che richiedono una verifica separata dell'app tramite OAuth Verification. Lo sviluppatore deve descrivere quali dati vengono raccolti, come vengono utilizzati e per quanto tempo vengono conservati. Google richiede inoltre una politica sulla privacy e la conformità con API Services Terms of Service.

Esempio pratico di registrazione

Per registrare i dati, viene creato un DataSource specificando tipo, dispositivo e applicazione. Quindi viene creato un DataPoint con un timestamp e valori. Più DataPoints vengono combinati in un DataSet, che viene passato a HistoryClient.write().

val dataSource = DataSource.Builder()
    .setAppPackageName(activity)
    .setDataType(DataType.TYPE_STEP_COUNT_DELTA)
    .setType(DataSource.TYPE_RAW)
    .build()

val stepCount = DataPoint.builder(dataSource)
    .setTimestamp(now, TimeUnit.MILLISECONDS)
    .setField(Field.FIELD_STEPS, 500)
    .build()

val dataSet = DataSet.builder(dataSource)
    .add(stepCount)
    .build()

historyClient.insertData(dataSet)
    .addOnSuccessListener {
        println("Dati salvati")
    }