قد يكون من الضروري تصميم تطبيقك لتحديد الوقت الذي يبدأ فيه المستخدم نشاطًا معيّنًا أو يوقفه، مثل المشي أو ركوب الدراجات أو القيادة. على سبيل المثال، يمكن لتطبيق تتبُّع المسافة المقطوعة أن يبدأ في تتبُّع الأميال عندما يبدأ المستخدم في القيادة، أو يمكن لتطبيق مراسلة يكتم صوت جميع المحادثات حتى يتوقف المستخدم عن القيادة.
يمكن استخدام واجهة برمجة تطبيقات Activity Recognitionion API لاكتشاف التغييرات في نشاط المستخدم. يشترك تطبيقك في عملية نقل في الأنشطة ذات الأهمية وترسل واجهة برمجة التطبيقات إشعارًا إلى تطبيقك عند الحاجة فقط. تعرض هذه الصفحة كيفية استخدام واجهة برمجة تطبيقات التعرّف على النشاط، والتي تسمى أيضًا واجهة برمجة تطبيقات Transition API باختصار.
إعداد المشروع
لاستخدام Transition API في تطبيقك، يجب الإعلان عن التبعية للإصدار 12.0.0 من واجهة برمجة التطبيقات
Google Location and Activity Recognition أو الإصدارات الأحدث منه، مع تحديد إذن com.google.android.gms.permission.ACTIVITY_RECOGNITION
في بيان التطبيق.
- لإعلان تبعية لواجهة برمجة التطبيقات، أضِف مرجعًا إلى مستودع Google Maven وأضِف إدخال تنفيذ إلى
com.google.android.gms:play-services-location:12.0.0
إلى قسم التبعيات في ملفbuild.gradle
لتطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على إعداد "خدمات Google Play". لتحديد إذن
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 تنفيذ الأنشطة التالية: - نوع النقل
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()); } } );
مراجع إضافية
لمعرفة المزيد من المعلومات عن استخدام واجهة برمجة التطبيقات للتعرف على نشاط المستخدم، يمكنك الاطّلاع على المواد التالية:
عيّنات
نموذج لتوضيح أفضل الممارسات للتعرّف على نشاط المستخدم.