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

כדי לעזור למפתחים להגדיר בצורה מכוונת יותר שירותים שפועלים בחזית שגלויים למשתמשים, ב-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 中引入的特定权限。这些权限显示在本页每种前台服务类型的预期用例和强制执行部分中标记为“您必须在清单文件中声明的权限”的部分。

所有这些权限都定义为一般权限，并默认授予。用户无法撤消这些权限。

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

השיטה המומלצת לאפליקציות שמפעילות שירותים שפועלים בחזית היא להשתמש בגרסה ServiceCompat של startForeground() (זמינה ב-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
דרישות מוקדמות בסביבת זמן הריצה

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

תיאור

אינטראקציות עם מכשירים חיצוניים שדורשים חיבור Bluetooth,‏ NFC,‏ IR,‏ USB או חיבור לרשת.

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

אם באפליקציה שלכם יש צורך לבצע העברה רציפה של נתונים למכשיר חיצוני, כדאי להשתמש במקום זאת במנהל המכשיר הנלווה. אתם יכולים להשתמש ב-companion device presence API כדי לעזור לאפליקציה להמשיך לפעול בזמן שהמכשיר הנלווה נמצא בטווח.

אם האפליקציה שלכם צריכה לסרוק מכשירי Bluetooth, כדאי להשתמש ב-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
דרישות מוקדמות בסביבת זמן הריצה
ללא
תיאור
המשך ההפעלה של האודיו או הווידאו מהרקע. תמיכה בפונקציונליות של הקלטת וידאו דיגיטלית (DVR) ב-Android TV.
אפשרויות אחרות
אם אתם מציגים סרטון ב'תמונה בתוך תמונה', תוכלו להשתמש במצב 'תמונה בתוך תמונה'.

הקרנת מדיה

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

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

  • 应用是通过 ROLE_DIALER 角色的默认拨号器应用。
说明

使用 ConnectionService API 继续当前通话。

替代方案

如果您需要拨打电话、视频通话或 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。出于这些原因，实现 Service.onTimeout() 回调被视为一种最佳实践。

Android 13 及更低版本中不存在 Service.onTimeout() 回调。如果同一服务在此类设备上运行，则不会出现超时，也不会发生 ANR。确保您的服务在完成处理任务后立即停止，即使它尚未收到 Service.onTimeout() 回调也是如此。

请务必注意，如果未遵循 shortService 的超时设置，即使应用还有其他有效的前台服务或其他应用生命周期进程，应用也会遇到 ANR。

如果应用对用户可见，或满足允许从后台启动前台服务的某一豁免条件，则使用 FOREGROUND_SERVICE_TYPE_SHORT_SERVICE 参数再次调用 Service.StartForeground() 会将超时时间再延长 3 分钟。如果应用对用户不可见且不满足其中一个豁免条件，则尝试启动其他前台服务（无论其类型如何）都会导致 ForegroundServiceStartNotAllowedException。

即使用户为您的应用停用电池优化功能，仍然会受到 shortService FGS 的影响。

如果您启动包含 shortService 类型和另一个前台服务类型的前台服务，系统会忽略 shortService 类型声明。不过，该服务仍必须遵守其他声明类型的先决条件。如需了解详情，请参阅前台服务文档。

שימוש מיוחד

要在清单中声明的前台服务类型
android:foregroundServiceType
specialUse
在清单中声明的权限
FOREGROUND_SERVICE_SPECIAL_USE
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
运行时前提条件
无
说明

涵盖其他前台服务类型未涵盖的所有有效前台服务用例。

除了声明 FOREGROUND_SERVICE_TYPE_SPECIAL_USE 前台服务类型之外，开发者还应在清单中声明用例。为此，他们会在 <service> 元素内指定 <property> 元素。这些值和相应的应用场景 。用途 您提供的案例均为自由形式，因此，您应确保提供足够的 相关信息，让审核人员了解您为何需要使用 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
דרישות מוקדמות בסביבת זמן הריצה
ללא
תיאור

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

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

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

  • אפליקציות VPN (שמוגדרות באמצעות הגדרות > רשת ואינטרנט > VPN)

    אחרת, ההצהרה על הסוג הזה תגרום למערכת להפעיל ForegroundServiceTypeNotAllowedException.

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

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