Google Fit — 是什么、平台架构及 API

什么是 Google Fit？

Google Fit 是 Google 于 2014 年在 I/O 大会上推出的健康管理平台。该平台提供统一的 API 用于读写身体活动数据，允许应用程序通过 Google 云中的中央存储库交换信息。

与专有解决方案不同，Google Fit 在 Android 操作系统和 iOS 上通过 REST API 运行。用户可以连接健身手环、智能手表和活动追踪应用，Google Fit 将在 Google Cloud 中将所有数据整合到统一的健康档案中。

根据 Google I/O 2024 的数据，该平台在全球 超过 5000 个应用中使用，活跃用户数超过 1 亿。该平台已与 Wear OS 集成，并通过第三方应用支持所有流行的健身追踪器。

Google Fit 架构

Google Fit 的架构建立在 三个层面上：客户端 SDK、Google Fitness Store 云存储和用于服务器集成的 REST API。客户端 SDK 适用于 Android（Kotlin、Java）和 iOS（Swift、Objective-C），还有通过 JavaScript 的 Web 客户端。

数据以 数据源（DataSource）和数据点（DataPoint）的形式组织。每个数据源代表一个设备或应用，每个数据点代表一个带时间戳的测量值。数据点组被合并为会话——具有类型和持续时间的连续活动期间。

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)
        }
    }

Google Fit 如何工作

Google Fit 使用通过 Google Cloud 的同步模型，支持在线和离线模式。应用在本地写入数据，Google Fit SDK 在有互联网连接时自动将其与云存储同步。冲突按照最后写入原则解决。

每种数据类型都有 标准格式：步数 — TYPE_STEP_COUNT_DELTA，卡路里 — TYPE_CALORIES_EXPENDED，心率 — TYPE_HEART_RATE_BPM，距离 — TYPE_DISTANCE_DELTA。对于自定义类型，可以通过 Google APIs 控制台创建具有唯一命名空间的自有 DataType。

该平台支持两种写入模式：主动模式 — 应用显式调用 HistoryClient.insertData()，和被动模式 — 通过 RecordingClient 订阅后台数据收集。被动模式适用于健身应用：用户只需启动一次应用，Google Fit 就会在应用最小化时自动收集步数、卡路里和距离，无需处理器持续工作。

据 Google 称，该平台每天处理 超过 20 亿个数据点。平均同步延迟在活动连接下为 5–10 秒，在后台模式下每 30 分钟同步一次以节省电量。

用户同意和安全

Google Fit 使用 OAuth 2.0 进行授权，访问范围为 fitness.activity.read、fitness.activity.write、fitness.body.read 和 fitness.body.write。应用仅请求必要的范围，用户通过带有账户选择的 Standard Google Sign-In 对话框确认访问权限。

用户可以随时通过 Google Account Permissions 或 Google Fit 应用撤销访问权限。Google 严格禁止未经明确同意向第三方传输健康数据，以及根据 Restricted Scopes 政策将数据用于广告目的。

Google Fit API

Google Fit 提供三个主要 API：用于读写历史数据的 Fitness API，用于从传感器实时传输数据的 Sensors API，以及用于管理活动会话的 Sessions API。每个 API 都可以通过 Android SDK 和 REST 请求访问。

Fitness API — 处理数据的主要 API。它支持批处理操作：一次调用写入最多 1000 个数据点，按时间范围、数据类型和来源过滤读取。数据聚合使用 DataSet 按所选指标进行分组。

Sensors API 允许订阅实时传感器数据 — 步数、心率、加速度。数据通过 SensorEventListener 以传感器类型和应用设置确定的频率传输。

除了三个主要 API 之外，Google Fit 还提供 Recording API，用于自动收集数据而无需保持应用活动状态。该 API 对 Wear OS 尤其有价值：智能手表可以收集心率和活动数据，手机上的应用在连接时与其同步。Recording API 使用针对最低能耗进行了优化的 Google Fit Background Services — 被动收集步数时每天仅消耗 2% 的电量。

REST API Google Fit 可通过端点 fitness.googleapis.com 访问。REST API 允许服务器应用程序在 OAuth 授权后代表用户读取和写入数据。这对于网络分析面板、企业健身计划和需要集中存储员工或患者健康数据的医疗系统非常有用。

val recordingClient = Fitness
    .getRecordingClient(activity, googleSignInAccount)

recordingClient.subscribe(DataType.TYPE_STEP_COUNT_DELTA)
    .addOnSuccessListener {
        println("订阅已激活")
    }

// 获取历史数据
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("今日步数：$total")
    }

将 Google Fit 集成到应用中

Google Fit 的集成从通过 build.gradle 添加 Google Fit SDK 依赖项开始：com.google.android.gms:play-services-fitness。之后需要配置 Google APIs 控制台 — 创建项目、启用 Fitness API 并添加具有正确 SHA-1 指纹的 OAuth 2.0 凭据。

集成过程包括：使用所需范围初始化 GoogleSignIn，通过 Fitness.getClient() 创建 FitnessClient，向用户请求授权并执行数据读取或写入操作。对于后台写入，使用 RecordingClient，即使应用最小化也能自动收集数据。Google Fit 根据电池电量和用户活动自动管理数据收集频率。

据 Google 称，集成 Google Fit 的应用的用户留存率高出 35%。主要应用类别包括健身追踪器、跑步应用、骑行、瑜伽和体重控制应用。

考虑 隐私要求很重要：Google Fit 使用 Restricted Scopes — 需要通过 OAuth Verification 进行单独应用验证的特殊访问范围。开发者必须描述收集哪些数据、如何使用以及保留多长时间。Google 还要求拥有隐私政策并遵守 API Services Terms of Service 计划。

写入的实际示例

要写入数据，需要创建 DataSource，指定类型、设备和应用。然后形成带有时间戳和值的 DataPoint。多个 DataPoint 合并到一个 DataSet 中，传递给 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("数据已保存")
    }