اكتشاف وقت بدء المستخدمين لنشاط أو إنهائه

قد يكون من الضروري تصميم تطبيقك لتحديد الوقت الذي يبدأ فيه المستخدم نشاطًا معيّنًا أو يوقفه، مثل المشي أو ركوب الدراجات أو القيادة. على سبيل المثال، يمكن لتطبيق تتبُّع المسافة المقطوعة أن يبدأ في تتبُّع الأميال عندما يبدأ المستخدم في القيادة، أو يمكن لتطبيق مراسلة يكتم صوت جميع المحادثات حتى يتوقف المستخدم عن القيادة.

يمكن استخدام واجهة برمجة تطبيقات Activity Recognitionion API لاكتشاف التغييرات في نشاط المستخدم. يشترك تطبيقك في عملية نقل في الأنشطة ذات الأهمية وترسل واجهة برمجة التطبيقات إشعارًا إلى تطبيقك عند الحاجة فقط. تعرض هذه الصفحة كيفية استخدام واجهة برمجة تطبيقات التعرّف على النشاط، والتي تسمى أيضًا واجهة برمجة تطبيقات Transition API باختصار.

إعداد المشروع

لاستخدام Transition API في تطبيقك، يجب الإعلان عن التبعية للإصدار 12.0.0 من واجهة برمجة التطبيقات Google Location and Activity Recognition أو الإصدارات الأحدث منه، مع تحديد إذن com.google.android.gms.permission.ACTIVITY_RECOGNITION في بيان التطبيق.

1. لإعلان تبعية لواجهة برمجة التطبيقات، أضِف مرجعًا إلى مستودع Google Maven وأضِف إدخال تنفيذ إلى com.google.android.gms:play-services-location:12.0.0 إلى قسم التبعيات في ملف build.gradle لتطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على إعداد "خدمات Google Play".

2. لتحديد إذن com.google.android.gms.permission.ACTIVITY_RECOGNITION، أضِف عنصر <uses-permission> في بيان التطبيق، كما هو موضّح في المثال التالي:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
            package="com.example.myapp">
   
      <uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" />
      …
    </manifest>
   

التسجيل للحصول على إشعارات نقل الأنشطة

لبدء تلقّي إشعارات حول عمليات نقل الأنشطة، عليك تنفيذ ما يلي:

• كائن ActivityTransitionRequest يحدد نوع النشاط والانتقال.
• هو معاودة الاتصال في PendingIntent حيث يتلقّى تطبيقك الإشعارات. لمزيد من المعلومات، يُرجى الاطّلاع على القسم استخدام نية في انتظار المراجعة.

لإنشاء الكائن ActivityTransitionRequest، عليك إنشاء قائمة بكائنات ActivityTransition التي تمثّل عملية النقل التي تريد تلقّي إشعارات بشأنها. يتضمن كائن ActivityTransition البيانات التالية:

• نوع نشاط يتم تمثيله بالفئة DetectedActivity. تتيح واجهة برمجة تطبيقات Transition API تنفيذ الأنشطة التالية:
  • IN_VEHICLE
  • ON_BICYCLE
  • RUNNING
  • STILL
  • WALKING
• نوع النقل ACTIVITY_TRANSITION_ENTER أو ACTIVITY_TRANSITION_EXIT. لمزيد من المعلومات، يُرجى الاطّلاع على الصف ActivityTransition.

يوضّح الرمز التالي كيفية إنشاء قائمة تضم عناصر ActivityTransition:

Kotlin

val transitions = mutableListOf<ActivityTransition>()

transitions +=
        ActivityTransition.Builder()
          .setActivityType(DetectedActivity.IN_VEHICLE)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_ENTER)
          .build()

transitions +=
        ActivityTransition.Builder()
          .setActivityType(DetectedActivity.IN_VEHICLE)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_EXIT)
          .build()

transitions +=
        ActivityTransition.Builder()
          .setActivityType(DetectedActivity.WALKING)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_EXIT)
          .build()

Java

List<ActivityTransition> transitions = new ArrayList<>();

transitions.add(
        new ActivityTransition.Builder()
          .setActivityType(DetectedActivity.IN_VEHICLE)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_ENTER)
          .build());

transitions.add(
        new ActivityTransition.Builder()
          .setActivityType(DetectedActivity.IN_VEHICLE)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_EXIT)
          .build());

transitions.add(
        new ActivityTransition.Builder()
          .setActivityType(DetectedActivity.WALKING)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_EXIT)
          .build());

يمكنك إنشاء كائن ActivityTransitionRequest من خلال تمرير قائمة ActivityTransitions إلى الفئة ActivityTransitionRequest، كما هو موضّح في المثال التالي:

Kotlin

val request = ActivityTransitionRequest(transitions)

Java

ActivityTransitionRequest request = new ActivityTransitionRequest(transitions);

يمكنك التسجيل للحصول على تحديثات نقل النشاط من خلال تمرير مثيل ActivityTransitionRequest وكائن PendingIntent إلى طريقة requestActivityTransitionUpdates(). تعرض الطريقة requestActivityTransitionUpdates() كائن Task يمكنك التحقق منه لمعرفة مدى نجاحه أو فشله، كما هو موضّح في مثال الرمز التالي:

Kotlin

// myPendingIntent is the instance of PendingIntent where the app receives callbacks.
val task = ActivityRecognition.getClient(context)
        .requestActivityTransitionUpdates(request, myPendingIntent)

task.addOnSuccessListener {
    // Handle success
}

task.addOnFailureListener { e: Exception ->
    // Handle error
}

Java

// myPendingIntent is the instance of PendingIntent where the app receives callbacks.
Task<Void> task = ActivityRecognition.getClient(context)
          .requestActivityTransitionUpdates(request, myPendingIntent);

task.addOnSuccessListener(
    new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void result) {
            // Handle success
        }
    }
);

task.addOnFailureListener(
    new OnFailureListener() {
        @Override
        public void onFailure(Exception e) {
            // Handle error
        }
    }
);

بعد التسجيل بنجاح للحصول على تحديثات نقل الأنشطة، سيتلقّى تطبيقك الإشعارات في PendingIntent المسجَّلة.

معالجة أحداث نقل النشاط

عند نقل النشاط المطلوب، يتلقّى التطبيق معاودة الاتصال بـ Intent. يمكن استخراج عنصر ActivityTransitionResult من Intent الذي يتضمن قائمة بالكائنات ActivityTransitionEvent. يتم ترتيب الأحداث بترتيب زمني، على سبيل المثال، إذا طلب تطبيق نوع النشاط IN_VEHICLE في انتقالي ACTIVITY_TRANSITION_ENTER وACTIVITY_TRANSITION_EXIT، سيحصل على عنصر ActivityTransitionEvent عند بدء المستخدم في القيادة وعنصر آخر عند انتقاله إلى أي نشاط آخر.

يمكنك تنفيذ معاودة الاتصال من خلال إنشاء فئة فرعية من BroadcastReceiver وتنفيذ طريقة onReceive() للحصول على قائمة أحداث انتقال النشاط. لمزيد من المعلومات، راجع عمليات البث. يوضّح المثال التالي كيفية تنفيذ طريقة onReceive():

Kotlin

override fun onReceive(context: Context, intent: Intent) {
    if (ActivityTransitionResult.hasResult(intent)) {
        val result = ActivityTransitionResult.extractResult(intent)!!
        for (event in result.transitionEvents) {
            // chronological sequence of events....
        }
    }
}

Java

@Override
public void onReceive(Context context, Intent intent) {
    if (ActivityTransitionResult.hasResult(intent)) {
        ActivityTransitionResult result = ActivityTransitionResult.extractResult(intent);
        for (ActivityTransitionEvent event : result.getTransitionEvents()) {
            // chronological sequence of events....
        }
    }
}

ملاحظة: قد يختلف وقت استجابة رصد الأحداث حسب الجهاز.

إلغاء التسجيل للحصول على تحديثات نقل الأنشطة

يمكنك إلغاء التسجيل للحصول على تحديثات نقل الأنشطة من خلال استدعاء طريقة removeActivityTransitionUpdates() في ActivityRecognitionClient وتمرير كائن PendingIntent كمَعلمة، كما هو موضّح في المثال التالي:

Kotlin

// myPendingIntent is the instance of PendingIntent where the app receives callbacks.
val task = ActivityRecognition.getClient(context)
        .removeActivityTransitionUpdates(myPendingIntent)

task.addOnSuccessListener {
    myPendingIntent.cancel()
}

task.addOnFailureListener { e: Exception ->
    Log.e("MYCOMPONENT", e.message)
}

Java

// myPendingIntent is the instance of PendingIntent where the app receives callbacks.
Task<Void> task = ActivityRecognition.getClient(context)
        .removeActivityTransitionUpdates(myPendingIntent);

task.addOnSuccessListener(
    new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void result) {
            myPendingIntent.cancel();
        }
    }
);

task.addOnFailureListener(
    new OnFailureListener() {
        @Override
        public void onFailure(Exception e) {
            Log.e("MYCOMPONENT", e.getMessage());
        }
    }
);

مراجع إضافية

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

عيّنات

نموذج لتوضيح أفضل الممارسات للتعرّف على نشاط المستخدم.