اختيار واجهة برمجة التطبيقات المناسبة لإبقاء الجهاز نشطًا
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
عندما يترك المستخدم جهاز Android في وضع السكون، ينتقل الجهاز بسرعة إلى حالة
التعليق لتجنُّب استنزاف البطارية. ومع ذلك، هناك أوقات يحتاج فيها
التطبيق إلى منع وحدة المعالجة المركزية من الانتقال إلى حالة التعليق. في بعض الحالات، قد يحتاج
التطبيق إلى إبقاء الشاشة مضاءة أثناء تشغيله. وفي حالات أخرى، لا يحتاج التطبيق
إلى إبقاء الشاشة قيد التشغيل، ولكن لا يزال بحاجة إلى أن تكون وحدة المعالجة المركزية نشطة.
يعتمد النهج الذي تتّبعه على احتياجات تطبيقك. ومع ذلك، تنطبق القاعدة العامة التالية:
يجب استخدام النهج الأقل استهلاكًا للموارد قدر الإمكان، لتقليل أثر
تطبيقك في موارد النظام. يساعدك هذا المستند في اختيار تكنولوجيا Android المناسبة لحالتك.
اختيار التكنولوجيا المناسبة
يعتمد الخيار الأفضل لإبقاء جهازك في وضع "التشغيل" على احتياجات تطبيقك. يساعدك
هذا القسم في اختيار النهج المناسب.
هل يحتاج تطبيقك إلى إبقاء الشاشة مُضاءة؟
إذا كانت الإجابة نعم، اطّلِع على إبقاء الشاشة مُضاءة. قد تتوفّر واجهة برمجة تطبيقات تهدف إلى غرض معيّن وتؤدي ما تحتاجه. على سبيل المثال، إذا كنت بصدد تنفيذ واجهة مستخدم للمكالمات الهاتفية، يمكنك استخدام إطار عمل الاتصالات السلكية واللاسلكية في Android الذي يحافظ على تشغيل الشاشة عند الحاجة. إذا لم تتوفّر واجهة برمجة تطبيقات
مخصّصة لحالتك، يمكنك استخدام واجهة برمجة تطبيقات keepScreenOn.
هل يشغّل تطبيقك خدمة تعمل في المقدّمة، وهل تحتاج إلى إبقاء الجهاز despierto (مفعّلاً) عندما تكون الشاشة مطفأة أثناء تشغيل الخدمة؟
إذا كانت الإجابة لا، ليس عليك إبقاء الجهاز مشغّلاً. إذا كان المستخدم يتفاعل
بنشاط مع التطبيق، سيظل الجهاز مفعّلاً. إذا كان العميل
لا يتفاعل مع تطبيقك ولم تكن تشغّل
خدمة في المقدّمة، يجب السماح للجهاز بالتوقّف مؤقتًا عند
الضرورة. إذا كنت بحاجة فقط إلى التأكّد من إنجاز بعض الأعمال أثناء
بقاء المستخدم خارج التطبيق، يمكنك الاطّلاع على مستندات المهام التي تعمل في الخلفية
للعثور على الخيار الأفضل.
إذا كانت الإجابة نعم، تأكَّد أولاً من أنّك بحاجة فعلاً إلى استخدام
خدمة تعمل في المقدّمة. استنادًا إلى حالتك، قد تكون هناك بعض واجهتَي برمجة تطبيقات مخصّصَتَين للقيام بمهام معيّنة بدلاً من استخدام خدمة تعمل في المقدّمة.
يمكنك العثور على معلومات حول هذه الخدمات في مستندات "الخدمة التي تعمل في المقدّمة". على سبيل المثال، إذا كنت بحاجة إلى تتبُّع
الموقع الجغرافي للمستخدم، قد تتمكّن من استخدام واجهة برمجة التطبيقات لميزة وضع حدود جغرافية بدلاً من
location خدمة تعمل في المقدّمة.
هل سيؤثّر ذلك سلبًا في تجربة المستخدم إذا تم تعليق الجهاز أثناء
تشغيل الخدمة التي تعمل في المقدّمة وكانت شاشة الجهاز مُطفأة؟ (على سبيل المثال، إذا كنت تستخدم خدمة تعمل في المقدّمة لتعديل الإشعارات، لن تكون تجربة المستخدم سيئة في حال تعليق الجهاز).
إذا كانت الإجابة لا، لا تستخدِم أداة قفل التنشيط. ويستأنف الإجراء
تلقائيًا بعد تفاعل المستخدم مع جهازه، ما يؤدي إلى
إيقاف التعليق.
إذا كانت الإجابة نعم، قد تحتاج إلى استخدام قفل تنبيه. ومع ذلك،
يجب التحقّق ممّا إذا كنت تستخدِم واجهة برمجة تطبيقات أو تُنفِّذ
إجراءً يُعلِن عن قفل التنشيط نيابةً عنك، كما هو موضّح في الإجراءات التي تحافظ على تنشيط الجهاز.
الإجراءات التي تحافظ على تشغيل الجهاز
إذا كان تطبيقك ينفّذ أيًا مما يلي، لن تحتاج إلى ضبط قفل تنشيط
بنفسك. تحافظ الإجراءات وواجهات برمجة التطبيقات التالية على إبقاء الجهاز في وضع "التشغيل".
في حال تشغيل الصوت، يضبط نظام الصوت قفلاً لتنشيط الشاشة ويدير ذلك بدلاً منك، ولا تحتاج إلى إجراء ذلك بنفسك.
إذا كنت تستخدم واجهات برمجة تطبيقات أو مكتبات لتحديد المهام، مثل WorkManager أو
JobScheduler أو DownloadManager، يكتسب النظام أو المكتبة
قفل تنشيط منسَبًا إلى تطبيقك.
بعض أدوات استشعار الجهاز هي أدوات استشعار للتنشيط، ويمكنك استخدام SensorManager
لتنشيط الجهاز عندما تتوفر لهذه الأدوات بيانات للإبلاغ عنها. للتحقّق مما إذا كان أحد أجهزة الاستشعار هو جهاز استشعار للتنشيط، يُرجى الاتصال برقم Sensor.isWakeUpSensor.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Choose the right API to keep the device awake\n\nWhen the user leaves their Android-powered device idle, it quickly goes into the\nsuspend state to avoid draining the battery. However, there are times when an\napp needs to prevent the CPU from going to the suspend state. In some cases, the\napp may need to keep the screen on while it's working. In other cases, the app\ndoesn't need to keep the screen on but still needs the CPU to be active.\n\nThe approach you take depends on the needs of your app. However, a general rule\nis that you should use the most lightweight approach possible, to minimize your\napp's impact on system resources. This document helps you choose the correct\nAndroid technology for your situation.\n| **Note:** You may be familiar with **wake locks**. An app can set a wake lock to keep the device from suspending. However, using a wake lock can quickly drain the device battery. You should only use a wake lock if there's no other option that will do what you need. If you do use a wake lock, you should release it as soon as possible.\n\nChoose the right technology\n---------------------------\n\nThe best option for keeping your device awake depends on your app's needs. This\nsection helps you choose the right approach.\n\n- Does your app need to keep the screen on?\n - If **Yes** , see [Keep the screen on](/develop/background-work/background-tasks/awake/screen-on). There may be a special-purpose API that does what you need; for example, if you're implementing a phone-call UI, you can use the [Android telecom\n framework](/reference/android/telecom/package-summary), which keeps the screen on when needed. If there's no special purpose API for your situation, you can use the `keepScreenOn` API.\n- Is your app running a foreground service, and you need to keep the device awake when screen is off while the service is running?\n - If **No** , you do not need to keep the device awake. If the user is actively interacting with the app, the device will stay awake. If the user is not interacting with your app and you are not running a foreground service, you should let the device go into suspend mode when necessary. If you just need to make sure some work gets done while the user is away from the app, see the [background tasks](/develop/background-work/background-tasks) documentation to find the best option.\n - If **Yes** , first confirm that you actually need to use a foreground service. Depending on your situation, there may be some special-purpose API you can use to accomplish your need instead of a foreground service. You can find information about these [in the Foreground Service\n documentation](/develop/background-work/services/fgs/service-types). For example, if you need to track the user's location, you might be able to use the [geofencing API](/develop/sensors-and-location/location/geofencing) instead of a `location` foreground service.\n- Would it be detrimental to the user experience if the device suspends while the foreground service is running and the device screen is off? (For example, if you're using a foreground service to update notifications, it wouldn't be a bad user experience if the device is suspended.)\n - If **No**, do not use a wakelock. The action resumes automatically once the user engages with their device, which takes it out of suspend.\n - If **Yes** , you might need to [use a wake lock](/develop/background-work/background-tasks/awake/wakelock). However, you should still check to see if you're already using an API or doing an action that declares a wake lock on your behalf, as discussed in [Actions that keep the device awake](#actions-keep).\n\nActions that keep the device awake\n----------------------------------\n\nIf your app is doing any of the following, you don't need to set a wake lock\nyourself. The following actions and APIs all keep the device awake for you.\n\n- If you're playing audio, the audio system sets and manages a wake lock for you; you don't need to do it yourself.\n- If you're using task scheduling APIs or libraries such as [WorkManager](/develop/background-work/background-tasks/persistent), [`JobScheduler`](/reference/android/app/job/JobScheduler), or [`DownloadManager`](/reference/android/app/DownloadManager), the system or library acquires a wake lock that is attributed to your app.\n- If you're using [Media3 ExoPlayer](/media/media3/exoplayer), you can use [`ExoPlayer.setWakeMode()`](/reference/androidx/media3/exoplayer/ExoPlayer#setWakeMode(int)) to have the player set a wake lock for you.\n- Certain device sensors are wake-up sensors; you can use [`SensorManager`](/reference/android/hardware/SensorManager) to have those sensors wake up the device when they have data to report. To check if a sensor is a wake-up sensor, call [`Sensor.isWakeUpSensor`](/reference/android/hardware/Sensor#isWakeUpSensor())).\n\nSee also\n--------\n\n- [Use wake locks](/develop/background-work/background-tasks/awake/wakelock)\n- [Keep the screen on](/develop/background-work/background-tasks/awake/screen-on)"]]
