移动设备上的录制 API

移动设备上的录制 API 允许您的应用以省电的方式从移动设备记录步数，类似于计步器检索步数数据。此 API 无需帐号，这意味着使用该服务不需要 Google 帐号，并且数据存储在设备上。

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

有关示例，请参阅 GitHub 上的移动设备上的录制 API 示例。

值得注意的详情

移动设备上的录制 API 具有几个独特的值得注意的功能

一旦录制订阅开始或续订，自上次订阅以来的数据（最长可达 10 天）即可访问。
数据仅在存在有效订阅时可用。如果通过调用 unsubscribe 移除订阅，则无法访问收集到的步数数据。

数据类型

移动设备上的录制 API 可以记录以下数据类型

TYPE_STEP_COUNT_DELTA

开始

要开始使用，请在您的 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)
  }