شناسایی و بهینه‌سازی موارد استفاده از قفل بیداری

این سند به شما کمک می‌کند موارد استفاده از قفل بیداری را در برنامه‌تان شناسایی و بهینه‌سازی کنید، و همچنین مشخص می‌کند که آیا قفل‌های بیداری توسط کتابخانه‌های دیگر یا میاناهای برنامه‌سازی کاربردی سیستم مرتبط با این مورد استفاده به‌دست آمده‌اند یا نه. ازآنجایی‌که این قفل‌های بیداری به برنامه شما نسبت داده می‌شوند، پیدا کردن منبع قفل بیداری مشکل‌ساز می‌تواند چالش‌برانگیز باشد. استفاده نادرست از میانای برنامه‌سازی کاربردی می‌تواند باعث شود برنامه‌تان به‌دلیل استفاده بیش‌ازحد از قفل بیداری پرچم‌گذاری شود، حتی اگر به‌طور صریح قفل بیداری دریافت نکنید.

این سند برخی‌از نام‌های رایج قفل بیداری را که ممکن است هنگام استفاده از ابزارهای اشکال‌زدایی قفل بیداری یا در گزارش‌های vitals با آن‌ها مواجه شوید فهرست می‌کند. این نام‌ها می‌توانند از کتابخانه یا میانای برنامه‌سازی کاربردی سیستم منشأ بگیرند، یا ممکن است مبهم‌سازی شده باشند. بااستفاده از ابزارهای اشکال‌زدایی برای شناسایی قفل‌های بیداری با رفتار نادرست و سپس جستجوی نام قفل بیداری در این سند، می‌توانید تعیین کنید کدام API ممکن است باعث مشکل شده باشد و توصیه‌هایی درباره نحوه بهینه‌سازی استفاده از آن پیدا کنید.

این سند موارد استفاده رایج برای دریافت قفل‌های بیداری را شرح می‌دهد، نام‌های قفل بیداری مورداستفاده توسط میاناهای برنامه‌سازی کاربردی و کتابخانه‌های مختلف را به‌تفصیل بیان می‌کند، و توصیه‌ها و روال‌های مطلوب را برای بهینه‌سازی و کاهش استفاده از قفل بیداری ارائه می‌دهد.

AlarmManager

AlarmManager قفل‌های بیداری را دریافت می‌کند و آن‌ها را به برنامه تماس‌گیرنده نسبت می‌دهد. AlarmManager قفل بیداری را هنگام به‌صدا درآمدن زنگ ساعت دریافت می‌کند و قفل را هنگام پایان اجرای روش onReceive() زنگ ساعت منتشرشده آزاد می‌کند.

نام‌های قفل بیداری

‫AlarmManager قفل‌های بیداری با نام *alarm* ایجاد می‌کند. (ستاره‌ها بخشی از نام قفل بیداری هستند و نشان‌دهنده نویسه عام نیستند.)

توصیه

برای بهینه‌سازی رفتار زنگ هشدار، روال‌های زیر را توصیه می‌کنیم:

  • برای تصمیم‌گیری بین زنگ ساعت دقیق یا غیردقیق، به انتخاب نوع زنگ ساعت مراجعه کنید. اگر لازم نیست زنگ ساعتتان دقیق باشد، از زنگ ساعت غیردقیق استفاده کنید تا سیستم انعطاف‌پذیری بیشتری در زمان‌بندی داشته باشد و عمر باتری بهبود یابد.
  • از سهمیه‌های زنگ هشدار تحمیل‌شده توسط سیستم آگاه باشید و برنامه‌تان را به‌گونه‌ای طراحی کنید که به آن‌ها احترام بگذارد.
  • از انجام کارهای طولانی در روش onReceive() اجتناب کنید و اگر پردازش بیشتری بعداز زنگ ساعت لازم است، کارگران را زمان‌بندی کنید.

صدا و رسانه

میاناهای برنامه‌سازی کاربردی رسانه می‌توانند هنگام ضبط یا پخش صدا، قفل‌های بیداری را دریافت کنند. قفل‌های بیداری به برنامه تماس‌گیرنده نسبت داده می‌شوند.

نام‌های قفل بیداری

میاناهای برنامه‌سازی کاربردی رسانه قفل‌های بیداری را با نام‌های مختلفی که با Audio شروع می‌شوند دریافت می‌کنند:

  • ‫AudioBitPerfect: برای بازپخش صدای USB بدون اتلاف استفاده می‌شود.
  • AudioDirectOut: برای بازپخش صدای بدون اتلاف در تلویزیون یا دستگاه خاص استفاده می‌شود.
  • AudioDup: برای بازپخش اعلان‌ها هنگام اتصال ازطریق بلوتوث یا USB استفاده می‌شود.
  • AudioIn: برای ضبط صدا در حالت دوربین فیلم‌برداری وقتی میکروفون فعال است استفاده می‌شود.
  • AudioMix: برای بازپخش صدا در دستگاهی معمولی استفاده می‌شود.
  • AudioOffload: برای بازپخش طولانی‌مدت فقط موسیقی، برای برنامه‌هایی که از این حالت پشتیبانی می‌کنند.
  • AudioSpatial: برای بازپخش فیلم چندکاناله یا صدای موسیقی در دستگاه‌هایی که از صدای فضایی پشتیبانی می‌کنند استفاده می‌شود.
  • AudioUnknown: زمانی استفاده می‌شود که شرایط دیگر اعمال نشود.
  • ‫MmapCapture: برای ضبط صدا با تأخیر کم استفاده می‌شود.
  • MmapPlayback: برای بازپخش با تأخیر کم، مثلاً برای بازی یا برای برنامه‌های صوتی حرفه‌ای، استفاده می‌شود.

توصیه

روال‌های زیر را توصیه می‌کنیم:

  • نام‌های قفل بیداری را که با Audio شروع می‌شوند اعلام نکنید.
  • اگر از میاناهای برنامه‌سازی کاربردی رسانه استفاده می‌کنید، نباید لازم باشد قفل‌های بیداری را مستقیماً دریافت کنید؛ می‌توانید به میاناهای برنامه‌سازی کاربردی تکیه کنید تا قفل‌های بیداری لازم را برای شما دریافت کنند.
  • وقتی از میاناهای برنامه‌سازی کاربردی رسانه استفاده می‌کنید، جلسه رسانه و سرویس پیش‌زمینه‌ای مرتبط را وقتی دیگر به آن نیاز ندارید پایان دهید.

بلوتوث

میاناهای برنامه‌سازی کاربردی بلوتوث پلاتفرم عمدتاً قفل‌های بیداری هسته را درحین انجام کنش‌های بلوتوث نگه می‌دارند که به برنامه نسبت داده نمی‌شود.

توصیه

  • از جفت‌سازی دستگاه همپا برای جفت کردن دستگاه‌های بلوتوث استفاده کنید تا از دریافت قفل بیداری دستی درطول جفت‌سازی بلوتوث جلوگیری شود.
  • برای درک نحوه برقراری ارتباط بلوتوث در پس‌زمینه، به راهنمای برقراری ارتباط در پس‌زمینه مراجعه کنید.
  • اگر تأخیر در ارتباط تأثیری بر کاربر نداشته باشد، استفاده از WorkManager اغلب کافی است. اگر قفل بیداری دستی ضروری تشخیص داده شد، قفل بیداری را فقط برای مدت فعالیت بلوتوث یا پردازش داده‌های فعالیت نگه دارید.

حسگرهای دستگاه

روش‌های مختلفی برای ردیابی داده‌های حسگر دستگاه مانند تعداد قدم‌ها، داده‌های شتاب‌سنج یا ژیروسکوپ وجود دارد.

در Wear OS، از خدمات سلامتی Wear برای دریافت داده‌های دستگاه مانند ارتفاع، ضربان قلب، و مسافت طی‌شده استفاده کنید.

اگر داده‌ها توسط برنامه‌های دیگر جمع‌آوری می‌شود، می‌توانید از Health Connect به‌همراه WorkManager برای بازیابی دوره‌ای داده‌ها استفاده کنید.

برای سناریوهایی مانند ردیابی دلتای گام‌ها یا مسافت طی‌شده، می‌توانید از Recording API در تلفن همراه همراه با WorkManager برای بازیابی دوره‌ای داده‌ها استفاده کنید. برای دسترسی به داده‌های سابقه تعداد قدم‌ها (مثل مجموع تعداد قدم‌های روزانه، یا تعداد قدم‌ها در ۶ ساعت گذشته)، Health Connect از ردگیری تعداد قدم‌ها در دستگاه نیز برای دستگاه‌های دارای Android 14 یا بالاتر پشتیبانی می‌کند.

در شرایط خاص، ممکن است لازم باشد ردیابی حسگر دستگاه سفارشی بااستفاده از SensorManager انجام شود. SensorManager قفل‌های بیداری را ازطرف برنامه دریافت نمی‌کند، مگراینکه حسگر از نوع حسگر بیدارباش باشد، که می‌توان آن را بااستفاده از میانای برنامه‌سازی کاربردی isWakeUpSensor شناسایی کرد.

توصیه

استفاده از حسگرها برای ضبط با نرخ نمونه‌برداری بالا می‌تواند باتری را به‌طور قابل‌توجهی خالی کند، در اینجا توصیه‌هایی برای کاهش مصرف باتری و استفاده از قفل بیداری ارائه شده است:

  • اگر تعداد قدم‌ها یا مسافت طی‌شده را ردیابی می‌کنید، از Recording API برای ضبط داده‌ها به‌شیوه‌ای با مصرف بهینه باتری استفاده کنید. برای دستگاه‌های دارای Android نسخه ۱۴ یا بالاتر، Health Connect را برای دسترسی به سابقه دستگاه و تعداد قدم‌های تجمیع‌شده درنظر بگیرید.
  • برای ردیابی حسگر منفعل در Wear OS، از خدمات سلامتی Wear برای بهینه‌سازی مصرف باتری استفاده کنید.
  • هنگام ثبت حسگر با SensorManager، maxReportLatencyUs را بیشتر از ۳۰ ثانیه تعریف کنید تا از منطق دسته‌بندی حسگر استفاده شود و تعداد وقفه‌هایی که برنامه دریافت می‌کند کاهش یابد. وقتی دستگاه متعاقباً با راه‌انداز دیگری مثل تعامل کاربر، بازیابی مکان، یا کار زمان‌بندی‌شده بیدار می‌شود، سیستم بلافاصله داده‌های حسگر ذخیره‌شده در حافظه نهان را ارسال می‌کند.
  • اگر برنامه‌تان هم به داده‌های مکان و هم به داده‌های حسگر نیاز دارد، بازیابی و پردازش رویداد آن‌ها را همگام‌سازی کنید. با ادغام خوانش‌های حسگر در قفل بیداری کوتاهی که سیستم برای به‌روزرسانی‌های مکان نگه می‌دارد، از نیاز به قفل بیداری برای بیدار نگه داشتن CPU جلوگیری می‌کنید. از یک کارگر یا قفل بیداری کوتاه‌مدت برای مدیریت بارگذاری و پردازش این داده‌های ترکیبی استفاده کنید.

پیام‌رسانی ابریِ Firebase‏ (FCM)

هنگام ارسال پیام همه‌فرستی «پیام‌رسانی ابری Firebase»‏ (FCM) به برنامه، قفل بیداری به‌دست می‌آید. وقتی اجرای روش onMessageReceived() همه‌فرستی FCM به‌پایان می‌رسد، قفل بیداری آزاد می‌شود.

نام‌های قفل بیداری

وقتی پیام FCM در دستگاه دریافت می‌شود، قفل بیداری کوتاهی با نام GOOGLE_C2DM نگه داشته می‌شود، در Android نسخه ۱۶ و بالاتر، نام قفل بیداری GCM_MESSAGE است.

توصیه

برای بهینه‌سازی رفتار FCM، روال‌های زیر را توصیه می‌کنیم:

  • بهینه‌سازی بسامد تحویل FCM.
  • از FCM با اولویت بالا استفاده نکنید، مگراینکه پیام واقعاً نیاز به ارسال فوری داشته باشد.
  • روش onMessageReceived() را در سریع‌ترین زمان ممکن تکمیل کنید یا اگر پردازش بیشتری لازم است، کارگری را برای ادامه کار زمان‌بندی کنید. برای اطلاعات بیشتر، راهنمای firebase را ببینید.

JobScheduler

کارهای JobScheduler هنگام اجرای تکالیف در پس‌زمینه، قفل‌های بیداری را به‌دست می‌آورند. قفل‌های بیداری به برنامه‌ای نسبت داده می‌شود که کارگران را ایجاد کرده است.

نام‌های قفل بیداری

نام‌های قفل بیداری که JobScheduler به‌دست می‌آورد به نسخه سیستم Android که درحال اجرا است و هدف کار بستگی دارد.

مواردی که با علامت‌های بزرگ‌تر و کوچک‌تر احاطه شده‌اند متغیر هستند. برای مثال، «<package_name>» نام بسته برنامه‌تان است، نه نوشتار تحت‌اللفظی <package name>. بااین‌حال، *job* دنباله نویسه *job* با ستاره است؛ از ستاره‌ها به‌عنوان نویسه عام استفاده نمی‌شود.

‫Android 15 و نسخه‌های پایین‌تر

کارهای شروع‌شده توسط کاربر قفل‌های بیداری با نام‌هایی ایجاد می‌کنند که از این الگو پیروی می‌کنند:

*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 از قفل‌های بیداری برای دریافت و ارائه مکان دستگاه استفاده می‌کنند. قفل‌های بیداری به برنامه‌ای نسبت داده می‌شود که آن APIها را فراخوانی کرده است.

نام‌های قفل بیداری

خدمات مکان از نام‌های زیر استفاده می‌کند:

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

توصیه

  • برای بهینه‌سازی استفاده از مکان، راهنمای ما را مطالعه کنید. اجرای زمان‌های استراحت، بهره‌برداری از دسته‌بندی درخواست‌های مکان، یا استفاده از به‌روزرسانی‌های مکان غیرفعال را درنظر بگیرید.
  • از دریافت قفل بیداری مجزا و پیوسته برای ذخیره موقت داده‌های مکان خودداری کنید، زیرا این کار زائد است و باید حذف شود. هنگام درخواست به‌روزرسانی مکان بااستفاده از میاناهای برنامه‌سازی کاربردی FusedLocationProvider یا LocationManager، سیستم به‌طور خودکار درطول فراخوانی رویداد مکان، بیدار شدن دستگاه را راه‌اندازی می‌کند. درعوض، رویدادهای مکان را در حافظه یا فضای ذخیره‌سازی ذخیره کنید، و رویدادهای مکان را به‌طور دوره‌ای بااستفاده از WorkManager پردازش کنید.

پیام‌رسانی از راه دور

این بخش سناریوهای مربوط به پیام‌رسانی از راه دور را مورد بحث قرار می‌دهد که در آن برنامه‌ها ممکن است نیاز به حفظ اتصالات یا واکنش به رویدادهای دستگاه‌های دیگر داشته باشند، که به‌طور بالقوه بر استفاده از قفل بیداری تأثیر می‌گذارد. موارد استفاده رایج عبارت‌اند از:

  • برنامه‌های همراه پایش ویدیو یا صدا که باید رویدادهای رخ‌داده در دستگاه خارجی متصل‌شده ازطریق شبکه محلی را پایش کنند.
  • برنامه‌های پیام‌رسانی که اتصال سوکت شبکه را با نسخه رایانه حفظ می‌کنند.

بیشتر بیدار شدن‌ها در این سناریوهای پیام‌رسانی ازراه‌دور، قفل‌های بیداری هسته هستند. ازآنجایی‌که قفل‌های بیداری هسته به برنامه نسبت داده نمی‌شوند، نام قفل بیداری مرتبطی برای فهرست کردن در اینجا وجود ندارد.

توصیه

  • اگر رویدادهای شبکه را بتوان در سمت سرور پردازش کرد، از FCM برای دریافت اطلاعات در کارخواه استفاده کنید. اگر پردازش بیشتر داده‌های FCM لازم باشد، می‌توانید کارگر تسریع‌شده را زمان‌بندی کنید.
  • اگر رویدادها باید در سمت کارخواه بااستفاده از اتصال سوکت پردازش شوند، برای گوش دادن به وقفه‌های رویداد به قفل بیداری نیازی نیست. وقتی بسته‌های داده به Wi-Fi یا رادیو سلولی می‌رسند، سخت‌افزار رادیو وقفه‌ای به‌شکل قفل بیداری هسته ایجاد می‌کند. سپس می‌توانید انتخاب کنید که یک کارگر را زمان‌بندی کنید یا یک قفل بیداری برای پردازش داده‌ها دریافت کنید.
  • برای مثال، اگر از ktor-network برای گوش دادن به بسته‌های داده در سوکت شبکه استفاده می‌کنید، فقط زمانی باید قفل بیداری را دریافت کنید که بسته‌ها به کارخواه تحویل داده شده باشند.

WorkManager

WorkManager هنگام اجرای تکالیف در پس‌زمینه، قفل‌های بیداری را دریافت می‌کند. قفل‌های بیداری به برنامه‌ای نسبت داده می‌شود که کارگران را ایجاد کرده است.

نام‌های قفل بیداری

نام‌های قفل بیداری که WorkManager دریافت می‌کند به نسخه‌ای از سیستم Android که روی آن اجرا می‌شود بستگی دارد.

‫Android 15 و نسخه‌های پایین‌تر

تکالیف 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 در worker استفاده کنید تا اطلاعات اشکال‌زدایی بیشتری اضافه شود، مثلاً اینکه کدام کلاس worker را زمان‌بندی کرده است.
  • اگر قفل‌های بیداری ایجادشده توسط WorkManager را با مصرف بالای قفل بیداری شناسایی کردید، ممکن است به این دلیل باشد که worker خود را به‌گونه‌ای پیکربندی کرده‌اید که در سناریوهای خاصی تکمیل نشود. دلایل توقف کارگر را تجزیه‌وتحلیل کنید، به‌ویژه اگر موارد زیادی از STOP_REASON_TIMEOUT را مشاهده می‌کنید.
  • علاوه‌بر ثبت دلایل توقف کارگر، به اسناد ما درباره اشکال‌زدایی کارگران مراجعه کنید. همچنین، جمع‌آوری و تجزیه‌وتحلیل ردگیری‌های سیستم را برای درک زمان دریافت و انتشار قفل‌های بیداری درنظر بگیرید.

_UNKNOWN

اگر ابزارهای اشکال‌زدایی تشخیص دهند که نام قفل بیداری حاوی اطلاعات شناساننده شخصی (PII) است، نام واقعی قفل بیداری را نمایش نمی‌دهند. درعوض، قفل بیداری را به‌عنوان _UNKNOWN برچسب‌گذاری می‌کنند. برای مثال، اگر نام قفل بیداری حاوی نشانی ایمیل باشد، ابزارها ممکن است این کار را انجام دهند.

توصیه

روال‌های مطلوب نام‌گذاری قفل بیداری را دنبال کنید و از استفاده از اطلاعات شناساننده شخصی در نام قفل بیداری خودداری کنید. اگر قفل بیداری‌ای با نام _UNKNOWN پیدا کردید که به برنامه‌تان نسبت داده شده است، سعی کنید آن قفل بیداری را شناسایی کنید و نام دیگری به آن بدهید.