הקלטה API בנייד

Recording API לנייד מאפשר לאפליקציה שלכם לתעד צעדים, בדומה למד לחיזוי צעדים שמאחזר נתונים של מספר הצעדים, ממכשיר נייד בצורה חסכונית בסוללה. ממשק ה-API הזה לא מחייב חשבון, כלומר לא נדרש חשבון Google כדי להשתמש בשירות, והנתונים מאוחסנים במכשיר.

במדריך הזה נסביר איך להשתמש ב-Recording API בנייד בתכונות שקשורות לבריאות ולכושר.

לדוגמה, אפשר לעיין בדוגמה ל-Recording API בנייד ב-GitHub.

פרטים מיוחדים

יש כמה תכונות ייחודיות ל-Recording API בנייד:

• אחרי התחלת המינוי לתיעוד או אחרי חידוש המינוי, תוכלו לגשת לנתונים מ-10 הימים האחרונים מאז המינוי האחרון.
• הנתונים זמינים רק כשיש מינוי פעיל. אם תסירו את המינוי באמצעות קריאה ל-unsubscribe, לא תוכלו לגשת לנתוני השלבים שנאספו.

סוגי הנתונים

באמצעות Recording API בנייד אפשר לתעד את סוגי הנתונים הבאים:

• TYPE_STEP_COUNT_DELTA

שנתחיל?

כדי להתחיל, מוסיפים את התלות הבאה לקובץ 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'
}

בקשת הרשאות

כדי לתעד נתונים באמצעות Recording API בנייד, האפליקציה תצטרך לבקש את ההרשאה הבאה:

• android.permission.ACTIVITY_RECOGNITION

בדיקת הגרסה של Play Services

כדי להשתמש ב-Recording API בנייד, המשתמש צריך לעדכן את Google Play Services לגרסה 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 Services של המשתמש נמוכה מדי, המערכת תוציא חריגה מסוג 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. לאחר מכן, אפשר לקבל את LocalDataPoints מה-LocalDataSet שנוצר על ידי יצירה של LocalDataReadRequest, כפי שמוצג בקטע הקוד הבא:

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