移动端录制 API

移动端录制 API 允许您的应用以节能的方式记录来自移动设备的步数。此 API 无需帐户，这意味着它无需使用 Google 帐户即可使用该服务，并且数据存储在设备上。

本指南将向您展示如何在您的健康与健身体验中使用移动端录制 API。

值得注意的细节

移动端录制 API 有几个独特的值得注意的功能

  • 录制订阅开始或续订后，即可访问自上次订阅以来的数据 - 最多 10 天。
  • 数据仅在存在活动订阅时可用。如果通过调用 unsubscribe 移除订阅，则无法访问收集的步数数据。

数据类型

移动端录制 API 可以记录以下数据类型

开始使用

要开始使用，请在您的 build.gradle 文件中添加以下依赖项

Kotlin DSL

plugin {
  id("com.android.application")
}

...

dependencies {
  implementation("com.google.android.gms:play-services-fitness:21.2.0")
}

Groovy DSL

apply plugin: 'com.android.application'

...

dependencies {
  implementation 'com.google.android.gms:play-services-fitness:21.2.0'
}

请求权限

要使用移动端录制 API 记录数据，您的应用需要 请求以下权限

  • android.permission.ACTIVITY_RECOGNITION

执行 Play 服务版本检查

要使用移动端录制 API，用户必须将 Google Play 服务更新到 LOCAL_RECORDING_CLIENT_MIN_VERSION_CODE。您可以使用 isGooglePlayServicesAvailable 方法进行检查

val hasMinPlayServices = isGooglePlayServicesAvailable(context, LocalRecordingClient.LOCAL_RECORDING_CLIENT_MIN_VERSION_CODE)

if(hasMinPlayServices != ConnectionResult.SUCCESS) {
  // Prompt user to update their device's Google Play services app and return
}

// Continue with Recording API functions

否则，如果用户的 Google Play 服务版本过低，系统将抛出 ConnectionResult.SERVICE_VERSION_UPDATE_REQUIRED 异常。

订阅健身数据

要请求步数数据的后台收集，请使用 subscribe 方法，如下面的代码片段所示

val localRecordingClient = FitnessLocal.getLocalRecordingClient(this)
// Subscribe to steps data
localRecordingClient.subscribe(LocalDataType.TYPE_STEP_COUNT_DELTA)
  .addOnSuccessListener {
    Log.i(TAG, "Successfully subscribed!")
  }
  .addOnFailureListener { e ->
    Log.w(TAG, "There was a problem subscribing.", e)
  }

读取和处理健身数据

订阅后，请使用 readData 方法请求数据。然后，您可以通过创建 LocalDataReadRequest 从结果 LocalDataSet 中获取 LocalDataPoints，如下面的代码片段所示

val endTime = LocalDateTime.now().atZone(ZoneId.systemDefault())
val startTime = endTime.minusWeeks(1)
val readRequest =
  LocalDataReadRequest.Builder()
    // The data request can specify multiple data types to return,
    // effectively combining multiple data queries into one call.
    // This example demonstrates aggregating only one data type.
    .aggregate(LocalDataType.TYPE_STEP_COUNT_DELTA)
    // Analogous to a "Group By" in SQL, defines how data should be
    // aggregated. bucketByTime allows bucketing by time span.
    .bucketByTime(1, TimeUnit.DAYS)
    .setTimeRange(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
    .build()

  localRecordingClient.readData(readRequest).addOnSuccessListener { response ->
    // The aggregate query puts datasets into buckets, so flatten into a
    // single list of datasets.
    for (dataSet in response.buckets.flatMap { it.dataSets }) {
      dumpDataSet(dataSet)
    }
  }
  .addOnFailureListener { e ->
    Log.w(TAG,"There was an error reading data", e)
  }

fun dumpDataSet(dataSet: LocalDataSet) {
  Log.i(TAG, "Data returned for Data type: ${dataSet.dataType.name}")
  for (dp in dataSet.dataPoints) {
    Log.i(TAG,"Data point:")
    Log.i(TAG,"\tType: ${dp.dataType.name}")
    Log.i(TAG,"\tStart: ${dp.getStartTime(TimeUnit.HOURS)}")
    Log.i(TAG,"\tEnd: ${dp.getEndTime(TimeUnit.HOURS)}")
    for (field in dp.dataType.fields) {
      Log.i(TAG,"\tLocalField: ${field.name.toString()} LocalValue: ${dp.getValue(field)}")
    }
  }
}

LocalRecordingClient 会持续更新其数据集合。您可以随时使用 readData 获取最新的数字。

请注意，LocalRecordingClient 会存储最多 10 天的数据。为了降低丢失数据的风险，您可以使用 WorkManager 定期在后台收集数据。

取消订阅健身数据

为了释放资源，您应该确保在您的应用不再需要时取消订阅传感器数据的收集。要取消订阅，请使用 unsubscribe 方法

val localRecordingClient = FitnessLocal.getLocalRecordingClient(this)
// Unsubscribe from steps data
localRecordingClient.unsubscribe(LocalDataType.TYPE_STEP_COUNT_DELTA)
  .addOnSuccessListener {
    Log.i(TAG, "Successfully unsubscribed!")
  }
  .addOnFailureListener { e ->
    Log.w(TAG, "There was a problem unsubscribing.", e)
  }