דף זה תורגם על ידי Cloud Translation API.

סוגי השירותים שפועלים בחזית

החל מ-Android 14 (רמת API 34), צריך להצהיר על סוג שירות מתאים לכל שירות שפועל בחזית. כלומר, צריך להצהיר על סוג השירות במניפסט של האפליקציה, וגם לבקש את ההרשאה המתאימה לשירות שפועל בחזית לסוג הזה (בנוסף לבקשת ההרשאה FOREGROUND_SERVICE). בנוסף, בהתאם לסוג השירות שפועל בחזית, יכול להיות שתצטרכו לבקש הרשאות בתחילת ההפעלה לפני שתשיקו את השירות.

מצלמה

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע android:foregroundServiceType: camera
הרשאה להצהרה במניפסט: FOREGROUND_SERVICE_CAMERA
אני רוצה להעביר אל startForeground(): FOREGROUND_SERVICE_TYPE_CAMERA
דרישות מוקדמות בסביבת זמן הריצה: מבקשים את הרשאת זמן הריצה CAMERA ומקבלים אותה

הערה: ההרשאה CAMERA בסביבת זמן הריצה כפופה להגבלות במהלך השימוש. לכן אי אפשר ליצור שירות camera שפועל בחזית בזמן שהאפליקציה פועלת ברקע, ואי אפשר להפעיל שירות שפועל בחזית camera ממקלט של BOOT_COMPLETED, עם כמה יוצאים מן הכלל. מידע נוסף זמין במאמר הגבלות על הפעלת שירותים שפועלים בחזית שצריכים הרשאות לשימוש.
תיאור: ממשיכים לגשת למצלמה מהרקע, למשל אפליקציות וידאו צ'אט שמאפשרות ריבוי משימות.

המכשיר המחובר

Foreground service type to declare in manifest under

android:foregroundServiceType

connectedDevice

Permission to declare in your manifest

FOREGROUND_SERVICE_CONNECTED_DEVICE

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE

Runtime prerequisites

At least one of the following conditions must be true:

Declare at least one of the following permissions in your manifest:
Request and be granted at least one of the following runtime permissions:
Call UsbManager.requestPermission()

Description

Interactions with external devices that require a Bluetooth, NFC, IR, USB, or network connection.

Alternatives

If your app needs to do continuous data transfer to an external device, consider using the companion device manager instead. Use the companion device presence API to help your app stay running while the companion device is in range.

If your app needs to scan for bluetooth devices, consider using the Bluetooth scan API instead.

סנכרון נתונים

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע

android:foregroundServiceType

dataSync

הרשאה להצהרה במניפסט

FOREGROUND_SERVICE_DATA_SYNC

קבוע להעברה אל startForeground()

FOREGROUND_SERVICE_TYPE_DATA_SYNC

דרישות מוקדמות לסביבת זמן ריצה

ללא

תיאור

פעולות העברת נתונים, כגון:

העלאה או הורדה של נתונים
פעולות גיבוי ושחזור
פעולות ייבוא או ייצוא
אחזור נתונים
עיבוד קבצים מקומי
העברת נתונים בין מכשיר לענן דרך רשת

אפשרויות אחרות

למידע מפורט, ראו חלופות לשירותים שפועלים בחזית של סנכרון נתונים.

בריאות

סוג השירות שפועל בחזית שיש להצהיר במניפסט שלו

android:foregroundServiceType

health

הרשאה להצהרה במניפסט

FOREGROUND_SERVICE_HEALTH

קבוע להעברה אל startForeground()

FOREGROUND_SERVICE_TYPE_HEALTH

דרישות מוקדמות לסביבת זמן ריצה

לפחות אחד מהתנאים הבאים חייב להתקיים:

מצהירים על ההרשאה HIGH_SAMPLING_RATE_SENSORS במניפסט.
צריך לבקש לפחות אחת מההרשאות הבאות בסביבת זמן הריצה, ולקבל אותה:
- BODY_SENSORS
- ACTIVITY_RECOGNITION

תיאור

תרחישים לדוגמה לטווח ארוך לתמיכה באפליקציות בקטגוריית הכושר, כמו מכשירי מעקב אחר אימונים.

מיקום

Foreground service type to declare in manifest under

android:foregroundServiceType

location

Permission to declare in your manifest

FOREGROUND_SERVICE_LOCATION

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_LOCATION

Runtime prerequisites

The user must have enabled location services and the app must be granted at least one of the following runtime permissions:

Description

Long-running use cases that require location access, such as navigation and location sharing.

Alternatives

If your app needs to be triggered when the user reaches specific locations, consider using the geofence API instead.

מדיה

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע
android:foregroundServiceType: mediaPlayback
הרשאה להצהרה במניפסט: FOREGROUND_SERVICE_MEDIA_PLAYBACK
קבוע להעברה אל startForeground(): FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
דרישות מוקדמות בסביבת זמן הריצה: ללא
תיאור: להמשיך את ההפעלה של אודיו או וידאו מהרקע. לתמוך בפונקציונליות של הקלטת וידאו דיגיטלית (DVR) ב-Android TV.

הערה: אפליקציות שמטרגטות את Android 15 ואילך לא מורשות להפעיל שירות הפעלת מדיה ממקלט שידורים של BOOT_COMPLETED. למידע נוסף, ראו הגבלות על הפעלת שירותים שפועלים בחזית של BOOT_COMPLETED.
אפשרויות אחרות: אם אתם מציגים סרטון במצב תמונה בתוך תמונה, השתמשו במצב תמונה בתוך תמונה.

המדיה נמצאת בעיבוד

Foreground service type to declare in manifest under

android:foregroundServiceType

mediaProcessing

Permission to declare in your manifest

FOREGROUND_SERVICE_MEDIA_PROCESSING

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING

Runtime prerequisites

None

Description

Service for performing time-consuming operations on media assets, like converting media to different formats. The system allows this service a limited time to run; under normal circumstances, this time limit would be 6 hours out of every 24. (This limit is shared by all of an app's mediaProcessing foreground services.)

Your app should manually stop the media processing service in the following scenario:

When the transcoding operation finishes or reaches a failure state, have the service call Service.stopForeground() and Service.stopSelf() to stop the service completely.

If the timeout period is reached, the system calls the service's Service.onTimeout(int, int) method. At this time, the service has a few seconds to call Service.stopSelf(). If the service does not call Service.stopSelf(), an ANR will occur with this error message: "A foreground service of <fgs_type> did not stop within its timeout: <component_name>".

Note: Service.onTimeout(int, int) is not available on Android 14 or lower. On devices running those versions, if a media processing service reaches the timeout period, the system immediately caches the app. For this reason, your app shouldn't wait to get a timeout notification. Instead, it should terminate the foreground service or change it to a background service as soon as appropriate.

הקרנת מדיה

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע
android:foregroundServiceType: mediaProjection
הרשאה להצהרה במניפסט: FOREGROUND_SERVICE_MEDIA_PROJECTION
קבוע להעברה אל startForeground(): FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
דרישות מוקדמות בסביבת זמן הריצה: קוראים ל-method createScreenCaptureIntent() לפני שמפעילים את השירות שפועל בחזית. הפעולה הזו תציג למשתמש התראה על הרשאה, והמשתמש יצטרך להעניק את ההרשאה כדי שתוכלו ליצור את השירות.; אחרי שיוצרים את שירות החזית, אפשר להפעיל את השיטה MediaProjectionManager.getMediaProjection().
תיאור: הקרנת תוכן למסך לא ראשי או למכשיר חיצוני באמצעות ממשקי ה-API של MediaProjection. התוכן הזה לא חייב להיות תוכן מדיה בלבד.

הערה: אפליקציות שמטרגטות ל-Android בגרסה 15 ואילך לא יכולות להפעיל שירות חזית של הקרנת מדיה ממקלט שידור מסוג BOOT_COMPLETED. מידע נוסף זמין במאמר הגבלות על מקבלי שידור מסוג BOOT_COMPLETED שמפעילים שירותים בחזית.
אפשרויות אחרות: כדי להעביר מדיה בסטרימינג למכשיר אחר, משתמשים ב-Google Cast SDK.

מיקרופון

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע
android:foregroundServiceType: microphone
הרשאה להצהרה במניפסט: FOREGROUND_SERVICE_MICROPHONE
אני רוצה להעביר אל startForeground(): FOREGROUND_SERVICE_TYPE_MICROPHONE
דרישות מוקדמות לסביבת זמן ריצה: מבקשים את ההרשאה RECORD_AUDIO בזמן הריצה ומקבלים אותה.

הערה: ההרשאה RECORD_AUDIO בסביבת זמן הריצה כפופה להגבלות במהלך השימוש. לכן, אי אפשר ליצור שירות microphone שפועל בחזית בזמן שהאפליקציה נמצאת ברקע, ואי אפשר להפעיל שירות microphone שפועל בחזית ממקלט BOOT_COMPLETED, למעט כמה יוצאים מן הכלל. מידע נוסף זמין במאמר הגבלות על הפעלת שירותים שפועלים בחזית שצריכים הרשאות לשימוש.
תיאור: אפשר להמשיך את הקלטת המיקרופון מהרקע, למשל: מקליטים או אפליקציות תקשורת.

שיחת טלפון

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע

android:foregroundServiceType

phoneCall

הרשאה להצהרה במניפסט

FOREGROUND_SERVICE_PHONE_CALL

קבוע להעברה אל startForeground()

FOREGROUND_SERVICE_TYPE_PHONE_CALL

דרישות מוקדמות בסביבת זמן הריצה

לפחות אחד מהתנאים הבאים חייב להתקיים:

האפליקציה הצהירה על ההרשאה MANAGE_OWN_CALLS בקובץ המניפסט שלה.

האפליקציה היא אפליקציית החיוג שמוגדרת כברירת מחדל דרך התפקיד ROLE_DIALER.

תיאור

המשך שיחה פעילה באמצעות ממשקי ה-API של ConnectionService.

אפשרויות אחרות

אם אתם צריכים להתקשר בטלפון, בשיחות וידאו או ב-VoIP, כדאי להשתמש בספרייה android.telecom.

כדאי להשתמש ב-CallScreeningService כדי לסנן שיחות.

העברת הודעות מרחוק

Foreground service type to declare in manifest under
android:foregroundServiceType: remoteMessaging
Permission to declare in your manifest: FOREGROUND_SERVICE_REMOTE_MESSAGING
Constant to pass to startForeground(): FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
Runtime prerequisites: None
Description: Transfer text messages from one device to another. Assists with continuity of a user's messaging tasks when they switch devices.

שירות קצר

Foreground service type to declare in manifest under

android:foregroundServiceType

shortService

Permission to declare in your manifest

None

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_SHORT_SERVICE

Runtime prerequisites

None

Description

Quickly finish critical work that cannot be interrupted or postponed.

This type has some unique characteristics:

Can only run for a short period of time (about 3 minutes).
No support for sticky foreground services.
Cannot start other foreground services.
Doesn't require a type-specific permission, though it still requires the FOREGROUND_SERVICE permission.
A shortService can only change to another service type if the app is currently eligible to start a new foreground service.
A foreground service can change its type to shortService at any time, at which point the timeout period begins.

The timeout for shortService begins from the moment that Service.startForeground() is called. The app is expected to call Service.stopSelf() or Service.stopForeground() before the timeout occurs. Otherwise, the new Service.onTimeout() is called, giving apps a brief opportunity to call stopSelf() or stopForeground() to stop their service.

A short time after Service.onTimeout() is called, the app enters a cached state and is no longer considered to be in the foreground, unless the user is actively interacting with the app. A short time after the app is cached and the service has not stopped, the app receives an ANR. The ANR message mentions FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. For these reasons, it's considered best practice to implement the Service.onTimeout() callback.

The Service.onTimeout() callback doesn't exist on Android 13 and lower. If the same service runs on such devices, it doesn't receive a timeout, nor does it ANR. Make sure that your service stops as soon as it finishes the processing task, even if it hasn't received the Service.onTimeout() callback yet.

It's important to note that if the timeout of the shortService is not respected, the app will ANR even if it has other valid foreground services or other app lifecycle processes running.

If an app is visible to the user or satisfies one of the exemptions that allow foreground services to be started from the background, calling Service.StartForeground() again with the FOREGROUND_SERVICE_TYPE_SHORT_SERVICE parameter extends the timeout by another 3 minutes. If the app isn't visible to the user and doesn't satisfy one of the exemptions, any attempt to start another foreground service, regardless of type, causes a ForegroundServiceStartNotAllowedException.

If a user disables battery optimization for your app, it's still affected by the timeout of shortService FGS.

If you start a foreground service that includes the shortService type and another foreground service type, the system ignores the shortService type declaration. However, the service must still adhere to the prerequisites of the other declared types. For more information, see the Foreground services documentation.

שימוש מיוחד

סוג השירות שפועל בחזית שיש להצהיר במניפסט שלו

android:foregroundServiceType

specialUse

הרשאה להצהרה במניפסט

FOREGROUND_SERVICE_SPECIAL_USE

אני רוצה להעביר אל startForeground()

FOREGROUND_SERVICE_TYPE_SPECIAL_USE

דרישות מוקדמות לסביבת זמן ריצה

ללא

תיאור

רלוונטי לכל תרחישי השימוש החוקיים בשירות שפועל בחזית, שלא נכללים על ידי הצד השני סוגי השירותים שפועלים בחזית.

בנוסף להצהרה על FOREGROUND_SERVICE_TYPE_SPECIAL_USE בסוג השירות שפועל בחזית, מפתחים צריכים להצהיר על תרחישים לדוגמה . כדי לעשות זאת, הן מציינות את הרכיב <property> שבתוך רכיב <service>. הערכים האלה והתרחישים לדוגמה התואמים הם נבדקות כששולחים את האפליקציה אל Google Play Console. השימוש הבקשות שאתם מספקים מתבטאות בחופשיות, וצריך להקפיד לספק מספיק מידע שיאפשר לבודק לראות למה צריך להשתמש בspecialUse מהסוג הזה.

<service android:name="fooService" android:foregroundServiceType="specialUse">
  <property android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
      android:value="explanation_for_special_use"/>
</service>

פטור מהמערכת

Foreground service type to declare in manifest under

android:foregroundServiceType

systemExempted

Permission to declare in your manifest

FOREGROUND_SERVICE_SYSTEM_EXEMPTED

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED

Runtime prerequisites

None

Description

Reserved for system applications and specific system integrations, to continue to use foreground services.

To use this type, an app must meet at least one of the following criteria:

Device is in demo mode state
App is a Device Owner
App is a Profiler Owner
Safety Apps that have the ROLE_EMERGENCY role
Device Admin apps
Apps holding SCHEDULE_EXACT_ALARM or USE_EXACT_ALARM permission
VPN apps (configured using Settings > Network & Internet > VPN)

Otherwise, declaring this type causes the system to throw a ForegroundServiceTypeNotAllowedException.

אכיפת המדיניות של Google Play בנושא שימוש בסוגי שירותים שפועלים בחזית

If your app targets Android 14 or higher, you'll need to declare your app's foreground service types in the Play Console's app content page (Policy > App content). For more information on how to declare your foreground service types in Play Console, see Understanding foreground service and full-screen intent requirements.