تحديد حالات استخدام قفل التنشيط وتحسينها

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

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

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

AlarmManager

يحصل AlarmManager على أقفال التنشيط وينسبها إلى تطبيق الاتصال. يحصل AlarmManager على قفل التنشيط عندما يرن المنبه، ويحرر القفل عند انتهاء تنفيذ طريقة onReceive() لبث المنبه.

أسماء أقفال التنشيط

ينشئ تطبيق "AlarmManager" أقفال تنشيط باسم "*alarm*". (تُعدّ علامات النجمة جزءًا من اسم قفل التنشيط، ولا تمثّل أحرف بدل).

الاقتراح

ننصحك باتّباع الممارسات التالية لتحسين سلوك المنبّه:

  • يُرجى الرجوع إلى قسم اختيار نوع المنبّه لتحديد ما إذا كنت تريد ضبط منبّه دقيق أو غير دقيق. إذا لم يكن المنبّه بحاجة إلى أن يكون دقيقًا، استخدِم المنبّهات غير المحدّدة الوقت لمنح النظام مرونة أكبر في الجدولة، ما قد يؤدي إلى تحسين عمر البطارية.
  • يُرجى الانتباه إلى الحصص التي يفرضها النظام على المنبّهات وتصميم تطبيقك بما يتوافق معها.
  • تجنَّب تنفيذ مهام طويلة في طريقة onReceive() وجدوِل العمال إذا كانت هناك حاجة إلى معالجة إضافية بعد المنبّه.

الصوت والوسائط

يمكن لواجهات برمجة التطبيقات Media API الحصول على أقفال التنشيط عند تسجيل الصوت أو تشغيله. ويتم تحديد مصدر أقفال التنشيط من خلال تطبيق الاتصال.

أسماء أقفال التنشيط

تحصل واجهات برمجة التطبيقات للوسائط على أقفال تنشيط بأسماء مختلفة تبدأ بـ Audio:

  • ‫AudioBitPerfect: يُستخدم لتشغيل الصوت عبر USB بدون فقدان البيانات.
  • ‫AudioDirectOut: يُستخدَم لتشغيل الصوت بدون فقدان البيانات على تلفزيون أو جهاز خاص.
  • AudioDup: يُستخدَم لتشغيل الإشعارات أثناء الاتصال باستخدام البلوتوث أو USB.
  • AudioIn: يُستخدَم لالتقاط الصوت في وضع كاميرا الفيديو عندما يكون الميكروفون نشطًا.
  • ‫AudioMix: يُستخدَم لتشغيل الصوت على جهاز مشترك.
  • ‫AudioOffload: يُستخدَم لتشغيل الموسيقى فقط على المدى الطويل، وذلك للتطبيقات التي تتيح هذا الوضع.
  • ‫AudioSpatial: يُستخدَم لتشغيل صوت الأفلام أو الموسيقى المتعدّد القنوات على الأجهزة التي تتيح ميزة "الصوت المكاني".
  • AudioUnknown: تُستخدَم هذه القيمة عندما لا تنطبق الحالات الأخرى.
  • ‫MmapCapture: يُستخدَم لتسجيل الصوت بزمن انتقال منخفض.
  • ‫MmapPlayback: يُستخدَم لتشغيل الصوت بزمن انتقال منخفض، مثل الألعاب أو تطبيقات الصوت الاحترافية.

الاقتراح

ننصحك باتّباع الممارسات التالية:

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

بلوتوث

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

الاقتراح

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

أدوات الاستشعار في الجهاز

هناك عدة طرق لتتبُّع بيانات أجهزة الاستشعار، مثل عدد الخطوات أو بيانات مقياس التسارع أو الجيروسكوب.

على Wear OS، استخدِم خدمات الصحة في Wear للحصول على بيانات الجهاز، مثل الارتفاع ومعدّل نبضات القلب والمسافة المقطوعة.

إذا تم جمع البيانات من خلال تطبيقات أخرى، يمكنك استخدام Health Connect مع WorkManager لاسترداد البيانات بشكل دوري.

في سيناريوهات مثل تتبُّع الفرق في عدد الخطوات أو المسافة المقطوعة، يمكنك استخدام Recording API على الأجهزة الجوّالة مع WorkManager لاسترداد البيانات بشكل دوري. للوصول إلى بيانات الخطوات السابقة (مثل إجمالي الخطوات اليومية أو الخطوات في آخر 6 ساعات)، يتيح Health Connect أيضًا تتبُّع الخطوات على الجهاز فقط للأجهزة التي تعمل بنظام التشغيل Android 14 أو الإصدارات الأحدث.

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

الاقتراح

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

  • في حال تتبُّع عدد الخطوات أو المسافة المقطوعة، استخدِم Recording API لتسجيل البيانات بطريقة موفّرة للبطارية. بالنسبة إلى الأجهزة التي تعمل بنظام التشغيل Android 14 أو الإصدارات الأحدث، ننصحك باستخدام Health Connect للوصول إلى سجلّ الجهاز وعدد الخطوات المجمّعة.
  • لتتبُّع أجهزة الاستشعار السلبية على Wear OS، استخدِم خدمات الصحة في Wear لتحسين استخدام البطارية.
  • عند تسجيل أداة استشعار باستخدام SensorManager، حدِّد maxReportLatencyUs لأكثر من 30 ثانية لاستخدام منطق تجميع بيانات أداة الاستشعار وتقليل عدد المقاطعات التي يتلقّاها التطبيق. عندما يتم تنشيط الجهاز لاحقًا بواسطة مشغّل آخر مثل تفاعل المستخدم أو استرداد الموقع الجغرافي أو مهمة مجدولة، سيرسل النظام على الفور بيانات جهاز الاستشعار المخزّنة مؤقتًا.
  • إذا كان تطبيقك يتطلّب بيانات الموقع الجغرافي وبيانات أجهزة الاستشعار، عليك مزامنة عملية استرداد الأحداث ومعالجتها. من خلال دمج قراءات أداة الاستشعار في قفل التنشيط القصير الذي يحتفظ به النظام لتحديثات الموقع الجغرافي، يمكنك تجنُّب الحاجة إلى قفل تنشيط لإبقاء وحدة المعالجة المركزية نشطة. استخدِم عاملاً أو قفل تنشيط قصير المدة للتعامل مع تحميل هذه البيانات المجمّعة ومعالجتها.

مراسلة Firebase السحابية (FCM)

يتم الحصول على قفل تنشيط أثناء تسليم بث "مراسلة Firebase السحابية" (FCM) إلى التطبيق. ويتم إلغاء قفل التنشيط بعد انتهاء تنفيذ طريقة بث onMessageReceived() في FCM.

أسماء أقفال التنشيط

عند تلقّي رسالة من خدمة "مراسلة Firebase السحابية" على الجهاز، يتم تفعيل قفل تنشيط لفترة قصيرة باسم GOOGLE_C2DM، وعلى الإصدار 16 من Android والإصدارات الأحدث، يكون اسم قفل التنشيط GCM_MESSAGE.

الاقتراح

ننصحك باتّباع الممارسات التالية لتحسين سلوك FCM:

  • تحسين معدّل تكرار التسليم في خدمة "مراسلة Firebase السحابية"
  • لا تستخدِم رسائل FCM ذات الأولوية القصوى إلا إذا كانت الرسالة بحاجة إلى التسليم على الفور.
  • يُرجى إكمال طريقة onMessageReceived() في أسرع وقت ممكن أو جدولة عامل لمواصلة المهمة إذا كانت هناك حاجة إلى معالجة إضافية. لمزيد من المعلومات، يُرجى الاطّلاع على إرشادات Firebase.

JobScheduler

تحصل مهام JobScheduler على أقفال تنشيط أثناء تنفيذ المهام في الخلفية. ويتم تحديد أقفال التنشيط للتطبيق الذي أنشأ المهام.

أسماء أقفال التنشيط

تعتمد أسماء أقفال التنشيط التي يحصل عليها JobScheduler على إصدار نظام Android الذي يتم تشغيلها عليه والغرض من المهمة.

العناصر المحاطة بأقواس معقوفة هي متغيرات. على سبيل المثال، "<package_name>" هو اسم حزمة تطبيقك، وليس النص الحرفي <package name>. ومع ذلك، فإنّ *job* هو تسلسل الأحرف *job*، مع علامات النجمة، ولا يتم استخدام علامات النجمة كأحرف بدل.

الإصدار 15 من نظام التشغيل Android والإصدارات الأقدم

تنشئ المهام التي يبدأها المستخدم أقفال تنشيط بأسماء تتبع النمط التالي:

*job*u/@<name_space>@/<package_name>/<classname>

تستخدم الوظائف الأخرى هذا النمط:

*job*/@<name_space>@/<package_name>/<classname>
الإصدار Android 16 QPR2 والإصدارات الأحدث

تنشئ المهام التي يبدأها المستخدم أقفال تنشيط بأسماء تتبع النمط التالي:

*job*u/@<name_space>@/#<trace_tag>#/<package_name>/<classname>

تستخدم المهام المُعجَّلة هذا النمط:

*job*e/@<name_space>@/#<trace_tag>#/<package_name>/<classname>

تستخدم الوظائف العادية هذا النمط:

*job*r/@<name_space>@/#<trace_tag>#/<package_name>/<classname>
مثال

لنفترض أنّ هناك مهمة مُعجَّلة تحمل مساحة الاسم backup وعلامة التتبُّع started. اسم الحزمة هو com.example.app، والفئة التي أنشأت المهمة هي com.backup.BackupFileService.

على الأجهزة التي تعمل بنظام التشغيل Android 15 أو إصدار أقدم، سيتم تسمية قفل التنشيط على النحو التالي:

*job*/@backup@/com.example.app/com.backup.BackupFileService

على الأجهزة التي تعمل بالإصدار Android 16 QPR2 أو إصدار أحدث، سيتم تسمية قفل التنشيط على النحو التالي:

*job*e/@backup@/#started#/com.example.app/com.backup.BackupFileService

الاقتراح

  • لا تحصل على قفل تنشيط يدوي لحالات استخدام التنزيل أو التحميل التي يبدأها المستخدم. بدلاً من ذلك، استخدِم واجهة برمجة التطبيقات نقل البيانات التي بدأها المستخدم (UIDT). هذا هو المسار المخصّص لمهام نقل البيانات الطويلة التي يبدأها المستخدم.
  • إذا حدّدت عمليات قفل تنشيط أنشأتها واجهة JobScheduler مع استخدام عالٍ لقفل التنشيط، قد يرجع ذلك إلى أنّك أعددت مهمتك بشكل خاطئ لعدم إكمالها في سيناريوهات معيّنة. ننصحك بتحليل أسباب توقُّف المهام، خاصةً إذا كنت تلاحظ تكرارًا كبيرًا لـ STOP_REASON_TIMEOUT.
  • راجِع استخدامك لمهام JobScheduler. وعلى وجه الخصوص، يُرجى اتّباع إرشاداتنا حول تحسين استخدام البطارية لواجهات برمجة التطبيقات الخاصة بجدولة المهام.

الموقع الجغرافي

يستخدم LocationManager وFusedLocationProviderClient أقفال التنشيط للحصول على الموقع الجغرافي للجهاز وإرساله. ويتم تحديد مصدر أقفال التنشيط بأنّه التطبيق الذي طلب واجهات برمجة التطبيقات هذه.

أسماء أقفال التنشيط

تستخدم الخدمات المستندة إلى الموقع الجغرافي الأسماء التالية:

  • CollectionLib-SigCollector
  • NetworkLocationLocator
  • NetworkLocationScanner
  • NlpCollectorWakeLock
  • NlpWakeLock
  • *location*

الاقتراح

  • يمكنك مراجعة إرشاداتنا حول تحسين استخدام الموقع الجغرافي. يمكنك استخدام المهلات أو تجميع طلبات الموقع الجغرافي أو استخدام التحديثات السلبية للموقع الجغرافي.
  • تجنَّب الحصول على قفل تنشيط منفصل ومستمر لتخزين بيانات الموقع الجغرافي مؤقتًا، لأنّ ذلك زائد عن الحاجة ويجب إزالته. عند طلب تحديثات الموقع الجغرافي باستخدام واجهات برمجة التطبيقات FusedLocationProvider أو LocationManager، يشغّل النظام تلقائيًا تنشيط الجهاز أثناء معاودة الاتصال بحدث الموقع الجغرافي. بدلاً من ذلك، يمكنك تخزين أحداث الموقع الجغرافي في الذاكرة أو مساحة التخزين، ومعالجة أحداث الموقع الجغرافي بشكل دوري باستخدام WorkManager.

المراسلة عن بُعد

يتناول هذا القسم سيناريوهات تتضمّن المراسلة عن بُعد، حيث قد تحتاج التطبيقات إلى الحفاظ على الاتصالات أو الاستجابة للأحداث من الأجهزة الأخرى، ما قد يؤثر في استخدام قفل التنشيط. تشمل حالات الاستخدام الشائعة ما يلي:

  • التطبيقات المصاحبة لمراقبة الفيديو أو الصوت التي تحتاج إلى مراقبة الأحداث التي تقع على جهاز خارجي متصل عبر شبكة محلية
  • تطبيقات المراسلة التي تحتفظ باتصال مقبس الشبكة مع إصدار متوافق مع أجهزة الكمبيوتر المكتبي

تكون معظم عمليات التنشيط في سيناريوهات المراسلة عن بُعد هذه عبارة عن أقفال تنشيط للنواة. بما أنّ أقفال التنشيط في النواة لا تُنسب إلى التطبيق، لا توجد أسماء أقفال تنشيط مرتبطة بها لإدراجها هنا.

الاقتراح

  • إذا كان من الممكن معالجة أحداث الشبكة من جهة الخادم، استخدِم FCM لتلقّي المعلومات على العميل. يمكنك اختيار جدولة عامل معجَّل إذا كانت هناك حاجة إلى معالجة إضافية لبيانات FCM.
  • إذا كان يجب معالجة الأحداث من جهة العميل باستخدام اتصال مأخذ توصيل، لن تحتاج إلى قفل التنشيط للاستماع إلى مقاطعات الأحداث. عندما تصل حِزم البيانات إلى شبكة Wi-Fi أو الراديو الخلوي، تُصدر أجهزة الراديو إشارة مقاطعة على شكل قفل تنشيط للنواة. يمكنك بعد ذلك اختيار جدولة عامل أو الحصول على قفل تنشيط لمعالجة البيانات.
  • على سبيل المثال، إذا كنت تستخدم ktor-network للاستماع إلى حِزم البيانات على مقبس شبكة، يجب الحصول على قفل تنشيط فقط عند تسليم الحِزم إلى العميل.

WorkManager

تحصل مهام WorkManager على أقفال التنشيط أثناء تنفيذ المهام في الخلفية. ويتم تحديد أقفال التنشيط للتطبيق الذي أنشأ المهام.

أسماء أقفال التنشيط

تعتمد أسماء أقفال التنشيط التي يحصل عليها WorkManager على إصدار نظام Android الذي يتم تشغيلها عليه.

الإصدار 15 من نظام التشغيل Android والإصدارات الأقدم

تنشئ مهام WorkManager أقفال تنشيط بأسماء تتبع النمط التالي:

*job*/<package_name>/androidx.work.impl.background.systemjob.SystemJobService
الإصدار Android 16 QPR2 والإصدارات الأحدث

تنشئ المهام العاجلة أقفال تنشيط بأسماء تتبع النمط التالي:

*job*e/#<trace_tag>#/<package_name>/androidx.work.impl.background.systemjob.SystemJobService

تتّبع المهام العادية النمط التالي:

*job*r/#<trace_tag>#/<package_name>/androidx.work.impl.background.systemjob.SystemJobService

يكون <trace_tag> هو اسم العامل تلقائيًا.

مثال

لنفترض أنّ هناك عاملاً سريعًا اسمه BackupFileWorker. اسم الحزمة هو com.example.app.

على الأجهزة التي تعمل بنظام التشغيل Android 15 أو إصدار أقدم، سيتم تسمية قفل التنشيط على النحو التالي:

*job*/com.example.app/androidx.work.impl.background.systemjob.SystemJobService

على الأجهزة التي تعمل بالإصدار Android 16 QPR2 أو إصدار أحدث وتستخدم WorkManager 2.10.0+، سيتم تسمية قفل التنشيط على النحو التالي:

*job*e/#BackupFileWorker#/com.example.app/androidx.work.impl.background.systemjob.SystemJobService

الاقتراح

  • يُرجى ترقية إصدار WorkManager إلى أحدث إصدار ثابت لجعل علامات قفل التنشيط أكثر تفصيلاً على Android 16 QPR2 أو الإصدارات الأحدث.
  • راجِع استخدامك لعمّال WorkManager. وعلى وجه الخصوص، تأكَّد من اتّباع إرشاداتنا بشأن تحسين استخدام البطارية لواجهات برمجة التطبيقات الخاصة بجدولة المهام. لجعل علامات قفل التنشيط أكثر تفصيلاً في الإصدار Android 16 QPR2 أو الإصدارات الأحدث، استخدِم طريقة setTraceTag في العامل لإضافة المزيد من معلومات تصحيح الأخطاء، مثل الفئة التي حدّدت موعد العامل.
  • إذا حدّدت عمليات قفل التنشيط التي أنشأتها WorkManager مع استخدام عالٍ لقفل التنشيط، قد يكون السبب هو أنّك أخطأت في ضبط العامل لعدم إكمال العمل في سيناريوهات معيّنة. ننصحك بتحليل أسباب توقّف العامل، خاصةً إذا كنت تلاحظ تكرارًا كبيرًا لـ STOP_REASON_TIMEOUT.
  • بالإضافة إلى تسجيل أسباب توقُّف العامل، يُرجى الرجوع إلى مستنداتنا حول تصحيح أخطاء العاملين. ننصحك أيضًا بجمع سجلّات تتبّع النظام وتحليلها لمعرفة وقت الحصول على عمليات قفل التنشيط ووقت إطلاقها.

_UNKNOWN

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

الاقتراح

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