قد يكون من الضروري تصميم تطبيقك لتحديد متى يبدأ المستخدم نشاطًا معيّنًا أو يتوقف عنه، مثل المشي أو ركوب الدراجات أو القيادة. على سبيل المثال، يمكن لتطبيق تتبُّع الأميال أن يبدأ في تتبُّع الأميال عندما يبدأ المستخدم في القيادة، أو يمكن لتطبيق المراسلة كتم صوت جميع المحادثات إلى أن يتوقف المستخدم عن القيادة.
يمكن استخدام Activity Recognition 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يتلقّى تطبيقك الإشعارات من خلالها لمزيد من المعلومات، يُرجى الاطّلاع على استخدام intent مؤجّلة.
لإنشاء عنصر 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());
}
}
);
مراجع إضافية
لمزيد من المعلومات حول استخدام واجهة برمجة التطبيقات للتعرّف على نشاط المستخدم، يُرجى الاطّلاع على المراجع التالية:
نماذج
نموذج لتوضيح أفضل الممارسات للتعرّف على نشاط المستخدم