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

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

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

إعداد مشروعك

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

1. للإبلاغ عن اعتمادية واجهة برمجة التطبيقات، يجب إضافة إشارة إلى خبير Google المستودع وإضافة إدخال تنفيذ إلى 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());
        }
    }
);

مصادر إضافية

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

نماذج

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