API Recording em dispositivos móveis

A API Recording em dispositivos móveis permite que seu app grave etapas, semelhante a um pedômetro que recupera dados de contagem de passos, de um dispositivo móvel de forma eficiente para a bateria. Essa API não usa contas, ou seja, não é necessário ter uma Conta do Google para usar o serviço, e os dados são armazenados no dispositivo.

Este guia mostra como usar a API Recording em dispositivos móveis nas suas experiências de saúde e fitness.

Consulte o exemplo da API Recording no dispositivo móvel no GitHub.

Detalhes importantes

Há vários recursos importantes exclusivos da API Recording em dispositivos móveis:

• Quando a assinatura de gravação começa ou é renovada, os dados desde a assinatura mais recente (por até 10 dias) ficam acessíveis.
• Os dados só ficam disponíveis quando há uma assinatura ativa. Se uma assinatura for removida chamando unsubscribe, os dados de etapas coletados não poderão ser acessados.

Tipos de dados

A API Recording em dispositivos móveis pode gravar os seguintes tipos de dados:

• TYPE_STEP_COUNT_DELTA

Primeiros passos

Para começar, adicione a seguinte dependência ao arquivo build.gradle:

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

...

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

apply plugin: 'com.android.application'

...

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

Solicitar permissões

Para gravar dados usando a API Recording em dispositivos móveis, seu app precisa solicitar a seguinte permissão:

• android.permission.ACTIVITY_RECOGNITION

Verificar a versão do Google Play Services

Para usar a API Recording em dispositivos móveis, o usuário precisa ter o Google Play Services atualizado para LOCAL_RECORDING_CLIENT_MIN_VERSION_CODE. É possível verificar isso usando o método 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

Caso contrário, se a versão do Google Play Services do usuário for muito baixa, o sistema gerará uma exceção ConnectionResult.SERVICE_VERSION_UPDATE_REQUIRED.

Assinar dados de fitness

Para solicitar a coleta em segundo plano de dados de etapas, use o método subscribe, conforme mostrado no snippet de código a seguir:

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

Ler e processar dados de condicionamento físico

Depois de se inscrever, solicite os dados usando o método readData. Em seguida, é possível extrair os LocalDataPoints do LocalDataSet resultante criando um LocalDataReadRequest, conforme mostrado no snippet de código a seguir:

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

A LocalRecordingClient atualiza continuamente a coleta de dados. É possível usar readData para extrair os números mais recentes a qualquer momento.

O LocalRecordingClient armazena até 10 dias de dados. Para reduzir o risco de perda de dados, use o WorkManager para coletar os dados periodicamente em segundo plano.

Cancelar inscrição nos dados de condicionamento físico

Para liberar recursos, cancele a inscrição na coleta de dados do sensor quando o app não precisar mais dela. Para cancelar a inscrição, use o método 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)
  }