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

כדי לעזור למפתחים להגדיר בצורה מכוונת יותר שירותים שפועלים בחזית שגלויים למשתמשים, ב-Android 10 הוספנו את המאפיין android:foregroundServiceType לרכיב <service>.

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

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

הסוגים health, remoteMessaging, shortService, specialUse ו-systemExempted הם חדשים ב-Android 14.

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

<manifest ...>
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
    <application ...>
      <service
          android:name=".MyMediaPlaybackService"
          android:foregroundServiceType="mediaPlayback"
          android:exported="false">
      </service>
    </application>
</manifest>

אם אפליקציה שמטרגטת את Android 14 לא מגדירה סוגי שירות מסוימים במניפסט, המערכת תרים את השגיאה MissingForegroundServiceTypeException בקריאה ל-startForeground() לשירות הזה.

הצהרת הרשאה חדשה לשימוש בסוגי שירותים שפועלים בחזית

אם אפליקציות שמטרגטות את Android 14 נעזרות בשירות שפועל בחזית, הן צריכות להצהיר על הרשאה ספציפית, בהתאם לסוג השירות שפועל בחזית, שהוצגה ב-Android 14. ההרשאות האלה מופיעות בקטעים שמסומנים בתווית 'הרשאה שצריך להצהיר עליה בקובץ המניפסט' בקטע תרחישים לדוגמה ותהליך האכיפה לכל סוג של שירות שפועל בחזית בדף הזה.

כל ההרשאות מוגדרות כהרשאות רגילות ומוקצות כברירת מחדל. המשתמשים לא יכולים לבטל את ההרשאות האלה.

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

对于启动前台服务的应用，最佳实践是使用 startForeground() 的 ServiceCompat 版本（在 androidx-core 1.12 及更高版本中提供），并在其中传入前台服务类型的按位整数。您可以选择传递一个或多个类型值。

通常，您应仅声明特定用例所需的类型。这样可以更轻松地满足系统对每种前台服务类型的预期。如果某项前台服务以多种类型启动，则该前台服务必须遵守所有类型的平台强制执行要求。

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

如果在调用中未指定前台服务类型，则类型默认为清单中定义的值。如果您未在清单中指定服务类型，系统会抛出 MissingForegroundServiceTypeException。

如果前台服务在启动后需要新权限，您应再次调用 startForeground() 并添加新的服务类型。例如，假设一款健身应用运行一项始终需要 location 信息但可能不需要 media 权限的跑步跟踪器服务。您需要在清单中同时声明 location 和 mediaPlayback。如果用户开始跑步，只希望跟踪其位置信息，您的应用应调用 startForeground()，并仅传递 location 服务类型。然后，如果用户想开始播放音频，请再次调用 startForeground() 并传递 location|mediaPlayback。

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

系统会检查前台服务类型的使用是否恰当，并确认应用是否已请求适当的运行时权限或使用所需的 API。例如，系统希望使用前台服务类型 FOREGROUND_SERVICE_TYPE_LOCATION 的应用请求 ACCESS_COARSE_LOCATION 或 ACCESS_FINE_LOCATION。

这意味着，在向用户请求权限和启动前台服务时，应用必须遵循非常具体的操作顺序。应用在尝试调用 startForeground() 之前，必须先请求并获得所需的权限。在启动前台服务后请求相应权限的应用必须更改此顺序，并在启动前台服务之前请求该权限。

本页面的每种前台服务类型的预期用例和强制执行部分中标记为“运行时要求”的部分列出了平台强制执行的具体内容。

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

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

מצלמה

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

מבקשים את הרשאת זמן הריצה CAMERA ומקבלים אותה

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

תיאור

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

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

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
connectedDevice
在清单中声明的权限
FOREGROUND_SERVICE_CONNECTED_DEVICE
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
运行时前提条件

必须至少满足以下其中一个条件：

说明

与需要蓝牙、NFC、IR、USB 或网络连接的外部设备进行互动。

替代方案

如果您的应用需要向外部设备持续传输数据，请考虑改用配套设备管理器。使用配套设备感知 API，可帮助您的应用在配套设备在范围内时保持运行。

如果您的应用需要扫描蓝牙设备，请考虑改用 Bluetooth Scan API。

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

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע
android:foregroundServiceType
dataSync
הרשאה להצהרה במניפסט
FOREGROUND_SERVICE_DATA_SYNC
קבוע להעברה אל startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
דרישות מוקדמות בסביבת זמן הריצה
ללא
תיאור

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

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

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

בריאות

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע
android:foregroundServiceType
health
הרשאה להצהרה במניפסט
FOREGROUND_SERVICE_HEALTH
קבוע להעברה אל startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
דרישות מוקדמות בסביבת זמן הריצה

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

הערה: הרשאות זמן הריצה לקריאה (READ) של BODY_SENSORS ושל חיישנים כפופות להגבלות במהלך השימוש. לכן, אי אפשר ליצור שירות health בחזית שמשתמש בחיישנים גופניים בזמן שהאפליקציה נמצאת ברקע, אלא אם קיבלתם את ההרשאות BODY_SENSORS_BACKGROUND (רמת API 33 עד 35) או READ_HEALTH_DATA_IN_BACKGROUND (רמת API 36 ואילך). מידע נוסף זמין במאמר הגבלות על הפעלת שירותים שפועלים בחזית שצריכים הרשאות לשימוש.

תיאור

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

מיקום

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע
android:foregroundServiceType
location
הרשאה להצהרה במניפסט
FOREGROUND_SERVICE_LOCATION
קבוע להעברה אל startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
דרישות מוקדמות בסביבת זמן הריצה

המשתמש צריך להפעיל את שירותי המיקום, והאפליקציה צריכה לקבל לפחות אחת מההרשאות הבאות בסביבת זמן הריצה:

הערה: כדי לבדוק שהמשתמש הפעיל את שירותי המיקום וגם העניק גישה להרשאות בסביבת זמן הריצה, משתמשים ב-PermissionChecker#checkSelfPermission()

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

תיאור

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

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

אם אתם רוצים שהאפליקציה תופעל כשהמשתמש מגיע למיקומים ספציפיים, מומלץ להשתמש ב-Geofence API במקום ב-Location API.

מדיה

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
mediaPlayback
在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PLAYBACK
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
运行时前提条件
无
说明
在后台继续播放音频或视频。在 Android TV 上支持数字视频录制 (DVR) 功能。
替代方案
如果您要显示画中画视频，请使用画中画模式。

הקרנת מדיה

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע
android:foregroundServiceType
mediaProjection
הרשאה להצהרה במניפסט
FOREGROUND_SERVICE_MEDIA_PROJECTION
קבוע להעברה אל startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
דרישות מוקדמות בסביבת זמן הריצה

צריך לקרוא ל-method‏ createScreenCaptureIntent() לפני שמפעילים את השירות שפועל בחזית. הפעולה הזו תציג למשתמש התראה על הרשאה, והמשתמש יצטרך להעניק את ההרשאה כדי שתוכלו ליצור את השירות.

אחרי שיוצרים את שירות החזית, אפשר להפעיל את השיטה MediaProjectionManager.getMediaProjection().

תיאור

הקרנת תוכן למסך לא ראשי או למכשיר חיצוני באמצעות ממשקי ה-API של MediaProjection. התוכן הזה לא חייב להיות תוכן מדיה בלבד.

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

כדי להעביר מדיה בסטרימינג למכשיר אחר, משתמשים ב-Google Cast SDK.

מיקרופון

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

מבקשים את ההרשאה RECORD_AUDIO בזמן הריצה ומקבלים אותה.

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

תיאור

המשך הקלטה מהמיקרופון ברקע, כמו מכשירי הקלטה קולית או אפליקציות תקשורת.

שיחת טלפון

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע
android:foregroundServiceType
phoneCall
הרשאה להצהרה במניפסט
FOREGROUND_SERVICE_PHONE_CALL
קבוע להעברה אל startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
דרישות מוקדמות בסביבת זמן הריצה

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

  • האפליקציה הצהירה על ההרשאה MANAGE_OWN_CALLS בקובץ המניפסט שלה.
  • האפליקציה היא אפליקציית החיוג שמוגדרת כברירת מחדל דרך התפקיד ROLE_DIALER.
תיאור

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

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

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

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

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

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע
android:foregroundServiceType
remoteMessaging
הרשאה להצהרה במניפסט
FOREGROUND_SERVICE_REMOTE_MESSAGING
קבוע להעברה אל startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
דרישות מוקדמות בסביבת זמן הריצה
ללא
תיאור
העברת הודעות טקסט ממכשיר אחד למכשיר אחר. מאפשרת למשתמשים להמשיך את משימות ההודעות שלהם כשהם עוברים בין מכשירים.

שירות מקוצר

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

לסיים במהירות עבודה קריטית שלא ניתן להפריע לה או לדחות אותה.

לסוג הזה יש כמה מאפיינים ייחודיים:

  • אפשר להריץ אותו רק לפרק זמן קצר (כ-3 דקות).
  • אין תמיכה בשירותי חזית דביקים.
  • אי אפשר להפעיל שירותים אחרים שפועלים בחזית.
  • לא נדרשת הרשאה ספציפית לסוג, אבל עדיין נדרשת ההרשאה FOREGROUND_SERVICE.
  • אפשר לשנות את shortService לסוג שירות אחר רק אם האפליקציה עומדת כרגע בדרישות להפעלת שירות חדש בחזית.
  • שירות שפועל בחזית יכול לשנות את הסוג שלו ל-shortService בכל שלב, ובאותו רגע מתחילה תקופת הזמן הקצובה.

הזמן הקצוב לתפוגה של shortService מתחיל מהרגע שבו מתבצעת הקריאה ל-Service.startForeground(). האפליקציה אמורה לבצע קריאה ל-Service.stopSelf() או ל-Service.stopForeground() לפני שהזמן יפוג. אחרת, Service.onTimeout() החדש ייוצר, ויינתן לאפליקציות הזדמנות קצרה להתקשר ל-stopSelf() או ל-stopForeground() כדי להפסיק את השירות שלהן.

זמן קצר אחרי הקריאה ל-Service.onTimeout(), האפליקציה נכנסת למצב שמאוחסן במטמון והיא כבר לא נחשבת לפעילה בחזית, אלא אם המשתמש מבצע אינטראקציה פעילה עם האפליקציה. זמן קצר אחרי שהאפליקציה מאוחסנת במטמון והשירות לא הופסק, האפליקציה מקבלת אירוע ANR. בהודעת ה-ANR מוזכר FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. לכן, מומלץ להטמיע את פונקציית ה-callback‏ Service.onTimeout().

קריאת החזרה (call back) Service.onTimeout() לא קיימת ב-Android מגרסה 13 ומטה. אם אותו שירות פועל במכשירים כאלה, הוא לא מקבל זמן קצוב לתפוגה ולא מתרחשת בו בעיה מסוג ANR. חשוב לוודא שהשירות יפסיק לפעול ברגע שהוא יסיים את משימת העיבוד, גם אם הוא עדיין לא קיבל את הקריאה החוזרת (callback) של Service.onTimeout().

חשוב לציין שאם לא יתקיים הזמן הקצוב לתפוגה של shortService, תופיע באפליקציה שגיאת ANR גם אם פועלות בה שירותים חוקיים אחרים בחזית או תהליכים אחרים במחזור החיים של האפליקציה.

אם אפליקציה גלויה למשתמש או עומדת באחד מההחרגות שמאפשרות להפעיל שירותים שפועלים בחזית מהרקע, קריאה חוזרת ל-Service.StartForeground() עם הפרמטר FOREGROUND_SERVICE_TYPE_SHORT_SERVICE מאריכה את הזמן הקצוב לתפוגה ב-3 דקות נוספות. אם האפליקציה לא גלויה למשתמש ולא עומדת באחד מההחרגות, כל ניסיון להפעיל שירות נוסף שפועל בחזית, ללא קשר לסוג שלו, יגרום לForegroundServiceStartNotAllowedException.

אם משתמש משבית את אופטימיזציית הסוללה באפליקציה, היא עדיין מושפעת מזמן הקצאת הזמן הקצוב לתפוגה של shortService FGS.

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

שימוש מיוחד

סוג השירות שפועל בחזית שצריך להצהיר עליו במניפסט בקטע
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>

פטור מהמערכת

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
systemExempted
在清单中声明的权限
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
运行时前提条件
无
说明

为系统应用和特定系统集成预留，使其能继续使用前台服务。

如需使用此类型，应用必须至少满足以下条件之一：

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

אם האפליקציה שלכם מטרגטת את Android מגרסה 14 ואילך, תצטרכו להצהיר על סוגי השירותים של האפליקציה בחזית בדף 'תוכן האפליקציה' ב-Play Console (Policy (מדיניות) > App content (תוכן האפליקציה)). מידע נוסף על הצהרת סוגי השירותים שפועלים בחזית ב-Play Console זמין במאמר הסבר על שירותים שפועלים בחזית ועל הדרישות לגבי כוונות במסך מלא.