בהתאם לרמת ה-API שהאפליקציה מיועדת אליה, יש כמה הגבלות על המקרים שבהם אפליקציה יכולה להפעיל שירות שפועל בחזית.
אפליקציות שמטרגטות ל-Android 12 (רמת API 31) ומעלה לא יכולות להפעיל שירות שפועל בחזית כשהאפליקציה פועלת ברקע, למעט כמה חריגים ספציפיים. מידע נוסף על הכלל הזה ועל החריגים לו זמין במאמר הגבלות על הפעלת שירות חזיתי מהרקע.
אפליקציות שמטרגטות ל-Android 14 (רמת API 34) ואילך צריכות לבקש את ההרשאות המתאימות לסוג השירות שפועל בחזית. כשהאפליקציה מנסה להעביר שירות לחזית, המערכת בודקת אם יש לה את ההרשאות המתאימות. אם חסרה לאפליקציה הרשאה כלשהי, המערכת מחזירה את השגיאה SecurityException. לדוגמה, אם מנסים להפעיל שירות שפועל בחזית מסוג location, המערכת בודקת שלאפליקציה כבר יש הרשאה מסוג ACCESS_COARSE_LOCATION או ACCESS_FINE_LOCATION. במסמכי התיעוד בנושא סוג השירות שפועל בחזית מפורטים התנאים המוקדמים הנדרשים לכל סוג של שירות שפועל בחזית.
הפעלת שירות
כדי להפעיל שירות שפועל בחזית, צריך קודם להפעיל אותו כשירות רגיל (לא שירות שפועל בחזית):
Kotlin
valintent=Intent(...)// Build the intent for the servicecontext.startForegroundService(intent)
Java
Contextcontext=getApplicationContext();Intentintent=newIntent(...);// Build the intent for the servicecontext.startForegroundService(intent);
נקודות עיקריות לגבי הקוד
קטע הקוד מפעיל שירות. אבל השירות עדיין לא פועל בחזית. בתוך השירות עצמו, צריך להתקשר אל ServiceCompat.startForeground() כדי לקדם את השירות לשירות חזיתי.
סוגי השירותים שפועלים בחזית שמועברים אל startForeground()הסוגים שמוצהרים במניפסט, בהתאם לתרחיש הספציפי לדוגמה. אם תצטרכו להוסיף עוד סוגי שירותים, תוכלו להפעיל את השיטה startForeground() שוב.
לדוגמה, נניח שאפליקציית כושר מפעילה שירות למעקב אחרי ריצה שתמיד צריך מידע על location, אבל יכול להיות שיצטרך להפעיל מדיה ויכול להיות שלא. תצטרכו להצהיר על השימוש בנתוני location ובנתוני mediaPlayback בקובץ המניפסט. אם משתמש מתחיל ריצה ורוצה רק לעקוב אחרי המיקום שלו, האפליקציה צריכה לקרוא ל-startForeground() ולהעביר רק את ההרשאה ACCESS_FINE_LOCATION. לאחר מכן, אם המשתמש רוצה להתחיל להפעיל אודיו, הוא צריך להתקשר שוב אל startForeground() ולהעביר את השילוב הביטווי של כל סוגי השירותים שפועלים בחזית (במקרה הזה, ACCESS_FINE_LOCATION|FOREGROUND_SERVICE_MEDIA_PLAYBACK).
בדוגמה הבאה מוצג הקוד ששירות מצלמה ישתמש בו כדי להפוך לשירות שפועל בחזית:
Kotlin
classMyCameraService:Service(){privatefunstartForeground(){// Before starting the service as foreground check that the app has the// appropriate runtime permissions. In this case, verify that the user has// granted the CAMERA permission.valcameraPermission=PermissionChecker.checkSelfPermission(this,Manifest.permission.CAMERA)if(cameraPermission!=PermissionChecker.PERMISSION_GRANTED){// Without camera permissions the service cannot run in the foreground// Consider informing user or updating your app UI if visible.stopSelf()return}try{valnotification=NotificationCompat.Builder(this,"CHANNEL_ID")// Create the notification to display while the service is running.build()ServiceCompat.startForeground(/* service = */this,/* id = */100,// Cannot be 0/* notification = */notification,/* foregroundServiceType = */if(Build.VERSION.SDK_INT>=Build.VERSION_CODES.R){ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA}else{0},)}catch(e:Exception){if(Build.VERSION.SDK_INT>=Build.VERSION_CODES.S&&eisForegroundServiceStartNotAllowedException){// App not in a valid state to start foreground service// (e.g. started from bg)}// ...}}}
Java
publicclassMyCameraServiceextendsService{privatevoidstartForeground(){// Before starting the service as foreground check that the app has the// appropriate runtime permissions. In this case, verify that the user// has granted the CAMERA permission.intcameraPermission=ContextCompat.checkSelfPermission(this,Manifest.permission.CAMERA);if(cameraPermission==PackageManager.PERMISSION_DENIED){// Without camera permissions the service cannot run in the// foreground. Consider informing user or updating your app UI if// visible.stopSelf();return;}try{Notificationnotification=newNotificationCompat.Builder(this,"CHANNEL_ID")// Create the notification to display while the service// is running.build();inttype=0;if(Build.VERSION.SDK_INT>=Build.VERSION_CODES.R){type=ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA;}ServiceCompat.startForeground(/* service = */this,/* id = */100,// Cannot be 0/* notification = */notification,/* foregroundServiceType = */type);}catch(Exceptione){if(Build.VERSION.SDK_INT>=Build.VERSION_CODES.S&&einstanceofForegroundServiceStartNotAllowedException){// App not in a valid state to start foreground service// (e.g started from bg)}// ...}}//...}
נקודות עיקריות לגבי הקוד
האפליקציה כבר הצהירה במניפסט שהיא זקוקה להרשאה CAMERA. עם זאת, האפליקציה צריכה גם לבדוק בזמן הריצה כדי לוודא שהמשתמש העניק את ההרשאה הזו. אם לאפליקציה אין את ההרשאות הנכונות, היא צריכה להודיע למשתמש על הבעיה.
סוגים שונים של שירותים בחזית הוצגו בגרסאות שונות של פלטפורמת Android. הקוד הזה בודק איזו גרסה של Android מופעלת ומבקש את ההרשאות המתאימות.
הקוד בודק אם יש ForegroundServiceStartNotAllowedException למקרה שהוא מנסה להפעיל שירות שפועל בחזית במצב שאסור (לדוגמה, אם הוא מנסה להעביר את השירות לחזית כשהאפליקציה פועלת ברקע).
דוגמאות התוכן והקוד שבדף הזה כפופות לרישיונות המפורטים בקטע רישיון לתוכן. Java ו-OpenJDK הם סימנים מסחריים או סימנים מסחריים רשומים של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-08-27 (שעון UTC).
[[["התוכן קל להבנה","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-08-27 (שעון UTC)."],[],[],null,["There are two steps to launching a foreground service from your app. First, you\nmust start the service by calling\n[`context.startForegroundService()`](/reference/android/content/Context#startForegroundService(android.content.Intent)). Then, have the\nservice call [`ServiceCompat.startForeground()`](/reference/androidx/core/app/ServiceCompat#startForeground(android.app.Service,int,android.app.Notification,int)) to promote\nitself into a foreground service.\n\nPrerequisites\n\nDepending on which API level your app targets, there are some restrictions on\nwhen an app can launch a foreground service.\n\n- Apps that target Android 12 (API level 31) or higher are not allowed to\n start a foreground service while the app is in the background, with a few\n specific exceptions. For more information, and information about the\n exceptions to this rule, see [Restrictions on starting a foreground service\n from the background](/develop/background-work/services/fgs/restrictions-bg-start).\n\n- Apps that target Android 14 (API level 34) or higher must request the\n appropriate\n permissions for the foreground service type. When the app attempts to\n promote a service to the foreground, the system checks for the appropriate\n permissions and throws throws [`SecurityException`](/reference/java/lang/SecurityException) if\n the app is missing any. For example, if you try to launch a foreground\n service of type `location`, the system checks to make sure your app already\n has either the `ACCESS_COARSE_LOCATION` or `ACCESS_FINE_LOCATION`\n permission. The [foreground service type](/develop/background-work/services/fgs/service-types) documentation lists the\n required prerequisites for each foreground service type.\n\nLaunch a service\n\nIn order to launch a foreground service, you must first launch it as an\nordinary (non-foreground) service: \n\nKotlin \n\n```kotlin\nval intent = Intent(...) // Build the intent for the service\ncontext.startForegroundService(intent)\n```\n\nJava \n\n```java\nContext context = getApplicationContext();\nIntent intent = new Intent(...); // Build the intent for the service\ncontext.startForegroundService(intent);\n```\n\nKey points about the code\n\n- The code snippet launches a service. However, the service is not yet running in the foreground. Inside the service itself, you need to call `ServiceCompat.startForeground()` to promote the service to a foreground service.\n\nPromote a service to the foreground\n\nOnce a service is running, you need to call\n[`ServiceCompat.startForeground()`](/reference/androidx/core/app/ServiceCompat#startForeground(android.app.Service,int,android.app.Notification,int)) to request that the service\nrun in the foreground. Ordinarily you would call this method in the service's\n[`onStartCommand()`](/reference/android/app/Service#onStartCommand(android.content.Intent,%20int,%20int)) method.\n\n`ServiceCompat.startForeground()` takes the following parameters:\n\n- The service.\n- A positive integer that uniquely identifies the service's notification in the status bar.\n- The [`Notification`](/reference/android/app/Notification) object itself.\n- The [foreground service type or types](/develop/background-work/services/fgs/service-types) identifying the work done by the service\n\n| **Note:** If you pass a foreground service type to `startForeground` that you did not declare in the manifest, the system throws `IllegalArgumentException`.\n\nThe foreground service types you pass to `startForeground()`\n[types declared in the manifest](/develop/background-work/services/fgs/service-types#declare-fgs), depending on the specific\nuse case. Then, if you need to add more service types, you can call\n`startForeground()` again.\n\nFor example, suppose a fitness app runs a running-tracker service that always\nneeds `location` information, but might or might not need to play media. You\nwould need to declare both `location` and `mediaPlayback` in the manifest. If a\nuser starts a run and just wants their location tracked, your app should call\n`startForeground()` and pass just the `ACCESS_FINE_LOCATION` permission. Then,\nif the user wants to start playing audio, call `startForeground()` again and\npass the bitwise combination of all the foreground service types (in this case,\n`ACCESS_FINE_LOCATION|FOREGROUND_SERVICE_MEDIA_PLAYBACK`).\n| **Note:** The status bar notification must use a priority of [`PRIORITY_LOW`](/reference/androidx/core/app/NotificationCompat#PRIORITY_LOW) or higher. If your app attempts to use a notification that has a lower priority than `PRIORITY_LOW`, the system adds a message to the notification drawer, alerting the user to the app's use of a foreground service.\n\nThe following example shows the code a camera service would use to promote\nitself to a foreground service: \n\nKotlin \n\n```kotlin\nclass MyCameraService: Service() {\n\n private fun startForeground() {\n // Before starting the service as foreground check that the app has the\n // appropriate runtime permissions. In this case, verify that the user has\n // granted the CAMERA permission.\n val cameraPermission =\n PermissionChecker.checkSelfPermission(this, Manifest.permission.CAMERA)\n if (cameraPermission != PermissionChecker.PERMISSION_GRANTED) {\n // Without camera permissions the service cannot run in the foreground\n // Consider informing user or updating your app UI if visible.\n stopSelf()\n return\n }\n\n try {\n val notification = NotificationCompat.Builder(this, \"CHANNEL_ID\")\n // Create the notification to display while the service is running\n .build()\n ServiceCompat.startForeground(\n /* service = */ this,\n /* id = */ 100, // Cannot be 0\n /* notification = */ notification,\n /* foregroundServiceType = */\n if (Build.VERSION.SDK_INT \u003e= Build.VERSION_CODES.R) {\n ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA\n } else {\n 0\n },\n )\n } catch (e: Exception) {\n if (Build.VERSION.SDK_INT \u003e= Build.VERSION_CODES.S\n && e is ForegroundServiceStartNotAllowedException) {\n // App not in a valid state to start foreground service\n // (e.g. started from bg)\n }\n // ...\n }\n }\n}\n```\n\nJava \n\n```java\npublic class MyCameraService extends Service {\n\n private void startForeground() {\n // Before starting the service as foreground check that the app has the\n // appropriate runtime permissions. In this case, verify that the user\n // has granted the CAMERA permission.\n int cameraPermission =\n ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA);\n if (cameraPermission == PackageManager.PERMISSION_DENIED) {\n // Without camera permissions the service cannot run in the\n // foreground. Consider informing user or updating your app UI if\n // visible.\n stopSelf();\n return;\n }\n\n try {\n Notification notification =\n new NotificationCompat.Builder(this, \"CHANNEL_ID\")\n // Create the notification to display while the service\n // is running\n .build();\n int type = 0;\n if (Build.VERSION.SDK_INT \u003e= Build.VERSION_CODES.R) {\n type = ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA;\n }\n ServiceCompat.startForeground(\n /* service = */ this,\n /* id = */ 100, // Cannot be 0\n /* notification = */ notification,\n /* foregroundServiceType = */ type\n );\n } catch (Exception e) {\n if (Build.VERSION.SDK_INT \u003e= Build.VERSION_CODES.S &&\n e instanceof ForegroundServiceStartNotAllowedException\n ) {\n // App not in a valid state to start foreground service\n // (e.g started from bg)\n }\n // ...\n }\n }\n\n //...\n}\n```\n\nKey points about the code\n\n- The app has already declared in the manifest that it needs the `CAMERA` permission. However, the app also has to check at runtime to make sure the user granted that permission. If the app does not actually have the correct permissions, it should let the user know about the problem.\n- Different foreground service types were introduced with different versions of the Android platform. This code checks what version of Android it's running on and requests the appropriate permissions.\n- The code checks for `ForegroundServiceStartNotAllowedException` in case it's trying to start a foreground service in a situation that's not allowed (for example, if it's trying to promote the service to the foreground [while\n the app is in the background](/develop/background-work/services/fgs/restrictions-bg-start))."]]