واجهة برمجة التطبيقات للتسجيل على الأجهزة الجوّالة

تسمح واجهة برمجة التطبيقات Record API على الأجهزة الجوّالة لتطبيقك بتسجيل الخطوات من جهاز جوّال بطريقة فعّالة من حيث استهلاك البطارية. وتُعد واجهة برمجة التطبيقات هذه غير محاسبة، أي أنها لا تتطلّب حسابًا على Google لاستخدام الخدمة، كما يتم تخزين البيانات على الجهاز.

يطلعك هذا الدليل على كيفية استخدام واجهة برمجة التطبيقات Record API على الأجهزة الجوّالة في تجارب الصحة واللياقة البدنية.

تفاصيل بارزة

هناك العديد من الميزات البارزة المرتبطة بواجهة برمجة التطبيقات للتسجيل على الأجهزة الجوّالة:

• بعد بدء اشتراك التسجيل، يتم تخزين ما يصل إلى 10 أيام من البيانات على الجهاز.
• لا تتوفّر البيانات إلا إذا كان هناك اشتراك نشِط. في حال إزالة اشتراك من خلال طلب الرقم unsubscribe، لن تتوفّر إمكانية الوصول إلى بيانات الخطوات التي تم جمعها.

أنواع البيانات

يمكن لواجهة Reporting 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'
}

طلب الأذونات

لتسجيل البيانات باستخدام واجهة برمجة تطبيقات التسجيل على الأجهزة الجوّالة، يجب أن يطلب تطبيقك الإذن التالي:

• android.permission.ACTIVITY_RECOGNITION

الاشتراك في بيانات اللياقة البدنية

لطلب جمع بيانات الخطوات أو المسافة أو السُعرات الحرارية في الخلفية، استخدِم طريقة subscribe كما هو موضّح في مقتطف الرمز التالي:

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

قراءة بيانات اللياقة البدنية ومعالجتها

بعد الاشتراك، اطلب البيانات باستخدام طريقة readData. يمكنك بعد ذلك الحصول على نقاط البيانات من مجموعة DataSet الناتجة من خلال إنشاء DataReadRequest كما هو موضّح في مقتطف الرمز التالي:

val endTime = LocalDateTime.now().atZone(ZoneId.systemDefault())
val startTime = endTime.minusWeeks(1)
val readRequest =
  DataReadRequest.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(DataType.AGGREGATE_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: DataSet) {
  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.getStartTimeString()}")
    Log.i(TAG,"\tEnd: ${dp.getEndTimeString()}")
    for (field in dp.dataType.fields) {
      Log.i(TAG,"\tField: ${field.name.toString()} Value: ${dp.getValue(field)}")
    }
  }
}

يتم تعديل مجموعة البيانات في "LocalRecordingClient" باستمرار. يمكنك استخدام readData لسحب أحدث الأرقام في أي وقت.

تجدر الإشارة إلى أنّ LocalRecordingClient يتم تخزين البيانات لمدة تصل إلى 10 أيام. للحد من خطر فقدان البيانات، يمكنك استخدام WorkManager لجمع البيانات بشكل دوري في الخلفية.

إلغاء الاشتراك في بيانات اللياقة البدنية

لتحرير الموارد، يجب أن تتأكد من إلغاء الاشتراك من مجموعة بيانات أداة الاستشعار عندما لا يكون تطبيقك بحاجة إليها. لإلغاء الاشتراك، استخدِم طريقة unsubscribe:

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