使用 Recording API 記錄健身資料

行動裝置上的 Recording API 可讓應用程式以省電的方式，記錄行動裝置的健身資料。舉例來說，您可以使用這項 API 記錄步數，就像計步器擷取步數資料一樣。這個 API 無須帳戶，也就是說，使用這項服務時不需要 Google 帳戶，資料會儲存在裝置上。

本指南說明如何在健康與健身服務中，透過行動裝置使用 Recording API。

如需範例，請參閱 GitHub 上的「Recording API on mobile sample」。

重要須知

行動版 Recording API 獨有的重要功能包括：

  • 開始或續訂錄影方案後，即可存取最新訂閱方案生效後最多 10 天的資料。
  • 只有在訂閱有效期間，系統才會提供資料。如果透過呼叫 unsubscribe 移除訂閱項目，您就無法存取收集到的資料。

資料類型

行動版 Recording 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'
}

要求權限

如要在行動裝置上使用 Recording API 記錄資料，應用程式必須要求下列權限：

  • android.permission.ACTIVITY_RECOGNITION

檢查 Play 服務版本

如要在行動裝置上使用 Recording 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)
  }