ต้องระบุประเภทบริการที่ทำงานอยู่เบื้องหน้า

Android 10 ได้เปิดตัวแอตทริบิวต์ android:foregroundServiceType ภายในองค์ประกอบ <service> เพื่อช่วยให้นักพัฒนาแอปมีความตั้งใจมากขึ้นในการกำหนดบริการที่ทำงานอยู่เบื้องหน้าที่แสดงต่อผู้ใช้

หากแอปกำหนดเป้าหมายเป็น Android 14 จะต้องระบุประเภทบริการที่ทำงานอยู่เบื้องหน้าที่เหมาะสม คุณสามารถรวมหลายประเภทเข้าด้วยกันได้เช่นเดียวกับใน Android เวอร์ชันก่อนหน้า รายการนี้แสดงประเภทบริการที่ทำงานอยู่เบื้องหน้าที่คุณเลือกได้

หากกรณีการใช้งานในแอปของคุณไม่เกี่ยวข้องกับประเภทใดเลย เราขอแนะนําอย่างยิ่งให้คุณย้ายข้อมูลตรรกะไปใช้ WorkManager หรือการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้

health, remoteMessaging, shortService, specialUse และ systemExempted เป็นประเภทใหม่ใน Android 14

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างการประกาศประเภทบริการที่ทำงานอยู่เบื้องหน้าในไฟล์ Manifest

<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 ไม่ได้กำหนดประเภทสำหรับบริการที่ระบุในไฟล์ Manifest ระบบจะเพิ่ม MissingForegroundServiceTypeException เมื่อเรียกใช้ startForeground() สำหรับบริการนั้น

ประกาศสิทธิ์ใหม่เพื่อใช้ประเภทบริการที่ทำงานอยู่เบื้องหน้า

หากแอปที่กำหนดเป้าหมายเป็น Android 14 ใช้บริการที่ทำงานอยู่เบื้องหน้า แอปจะต้องประกาศสิทธิ์ที่เฉพาะเจาะจงตามประเภทบริการที่ทำงานอยู่เบื้องหน้าซึ่ง Android 14 เปิดตัว สิทธิ์เหล่านี้จะปรากฏในส่วนที่มีป้ายกำกับว่า "สิทธิ์ที่คุณต้องประกาศในไฟล์ Manifest" ในส่วนกรณีการใช้งานที่ต้องการและการบังคับใช้สำหรับบริการที่ทำงานอยู่เบื้องหน้าแต่ละประเภทในหน้านี้

สิทธิ์ทั้งหมดถือเป็นสิทธิ์ทั่วไปและได้รับสิทธิ์โดยค่าเริ่มต้น ผู้ใช้เพิกถอนสิทธิ์เหล่านี้ไม่ได้

รวมประเภทบริการที่ทำงานอยู่เบื้องหน้าไว้ที่รันไทม์

对于启动前台服务的应用，最佳实践是使用 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() แอปที่ขอสิทธิ์ที่เหมาะสมหลังจากที่เริ่มบริการที่ทำงานอยู่เบื้องหน้าแล้วต้องเปลี่ยนลำดับการดำเนินการนี้และขอสิทธิ์ก่อนเริ่มบริการที่ทำงานอยู่เบื้องหน้า

ข้อกำหนดเฉพาะของการบังคับใช้แพลตฟอร์มจะปรากฏในส่วนที่มีป้ายกำกับว่า "ข้อกำหนดรันไทม์" ในส่วนกรณีการใช้งานที่ต้องการและการบังคับใช้สำหรับบริการที่ทำงานอยู่เบื้องหน้าแต่ละประเภทในหน้านี้

กรณีการใช้งานและการบังคับใช้ที่กำหนดไว้สำหรับบริการที่ทำงานอยู่เบื้องหน้าแต่ละประเภท

为了使用给定的前台服务类型，您必须在清单文件中声明特定权限，必须满足特定的运行时要求，并且应用必须满足该类型的其中一组预期用例。以下部分介绍了您必须声明的权限、运行时前提条件以及每种类型的预期用例。

กล้อง

ประเภทบริการที่ทำงานอยู่เบื้องหน้าที่จะประกาศในไฟล์ Manifest ในส่วน android:foregroundServiceType
camera
สิทธิ์ในการประกาศในไฟล์ Manifest
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。

การซิงค์ข้อมูล

ประเภทบริการที่ทำงานอยู่เบื้องหน้าที่จะประกาศในไฟล์ Manifest ในส่วน
android:foregroundServiceType
dataSync
สิทธิ์ในการประกาศในไฟล์ Manifest
FOREGROUND_SERVICE_DATA_SYNC
ค่าคงที่ที่จะส่งไปยัง startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
ข้อกําหนดเบื้องต้นของรันไทม์
ไม่มี
คำอธิบาย

การดำเนินการโอนข้อมูล เช่น การดำเนินการต่อไปนี้

  • การอัปโหลดหรือดาวน์โหลดข้อมูล
  • การดำเนินการสำรองและกู้คืนข้อมูล
  • การดำเนินการนำเข้าหรือส่งออก
  • ดึงข้อมูล
  • การประมวลผลไฟล์ในเครื่อง
  • โอนข้อมูลระหว่างอุปกรณ์กับระบบคลาวด์ผ่านเครือข่าย
ทางเลือก

ดูข้อมูลโดยละเอียดได้ที่ทางเลือกแทนบริการที่ทำงานอยู่เบื้องหน้าสำหรับการซิงค์ข้อมูล

สุขภาพ

ประเภทบริการที่ทำงานอยู่เบื้องหน้าที่จะประกาศในไฟล์ Manifest ในส่วน
android:foregroundServiceType
health
สิทธิ์ในการประกาศในไฟล์ Manifest
FOREGROUND_SERVICE_HEALTH
ค่าคงที่ที่จะส่งไปยัง startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
สิ่งที่ต้องดำเนินการก่อนสำหรับรันไทม์

เงื่อนไขต่อไปนี้อย่างน้อย 1 ข้อจะต้องเป็นจริง

หมายเหตุ: สิทธิ์รันไทม์ 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()

注意：位置信息运行时权限受“使用期间”限制。因此，除非您已获得 ACCESS_BACKGROUND_LOCATION 运行时权限，否则无法在应用在后台运行时创建 location 前台服务。如需了解详情，请参阅与启动需要“使用时”权限的前台服务相关的限制。

说明

需要位置信息使用权的长时间运行的用例，例如导航和位置信息分享。

替代方案

如果您的应用需要在用户到达特定位置时触发，请考虑改用 Geofence API。

สื่อ

ประเภทบริการที่ทำงานอยู่เบื้องหน้าที่จะประกาศในไฟล์ Manifest ในส่วน
android:foregroundServiceType
mediaPlayback
สิทธิ์ในการประกาศในไฟล์ Manifest
FOREGROUND_SERVICE_MEDIA_PLAYBACK
ค่าคงที่ที่จะส่งไปยัง startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
ข้อกําหนดเบื้องต้นของรันไทม์
ไม่มี
คำอธิบาย
เล่นเสียงหรือวิดีโออย่างต่อเนื่องจากเบื้องหลัง รองรับฟังก์ชันการบันทึกวิดีโอดิจิทัล (DVR) ใน Android TV
ทางเลือก
หากกำลังแสดงวิดีโอแบบภาพซ้อนภาพ ให้ใช้โหมดภาพซ้อนภาพ

การฉายภาพสื่อ

ประเภทบริการที่ทำงานอยู่เบื้องหน้าที่จะประกาศในไฟล์ Manifest ในส่วน
android:foregroundServiceType
mediaProjection
สิทธิ์ในการประกาศในไฟล์ Manifest
FOREGROUND_SERVICE_MEDIA_PROJECTION
ค่าคงที่ที่จะส่งไปยัง startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
ข้อกําหนดเบื้องต้นของรันไทม์

เรียกใช้เมธอด createScreenCaptureIntent() ก่อนเริ่มบริการที่ทำงานอยู่เบื้องหน้า ซึ่งจะแสดงการแจ้งเตือนสิทธิ์ให้ผู้ใช้ทราบ ผู้ใช้ต้องให้สิทธิ์ก่อนที่คุณจึงจะสร้างบริการได้

หลังจากสร้างบริการที่ทำงานอยู่เบื้องหน้าแล้ว คุณจะเรียกใช้ MediaProjectionManager.getMediaProjection() ได้

คำอธิบาย

ฉายเนื้อหาไปยังจอแสดงผลที่ไม่ใช่อุปกรณ์หลักหรืออุปกรณ์ภายนอกโดยใช้ MediaProjection API เนื้อหานี้ไม่จำเป็นต้องเป็นเนื้อหาสื่อโดยเฉพาะ

ทางเลือก

หากต้องการสตรีมสื่อไปยังอุปกรณ์อื่น ให้ใช้ Google Cast SDK

ไมโครโฟน

ประเภทบริการที่ทำงานอยู่เบื้องหน้าที่จะประกาศในไฟล์ Manifest ในส่วน
android:foregroundServiceType
microphone
สิทธิ์ในการประกาศในไฟล์ Manifest
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 来过滤来电。

การรับส่งข้อความระยะไกล

ประเภทบริการที่ทำงานอยู่เบื้องหน้าที่จะประกาศในไฟล์ Manifest ในส่วน
android:foregroundServiceType
remoteMessaging
สิทธิ์ในการประกาศในไฟล์ Manifest
FOREGROUND_SERVICE_REMOTE_MESSAGING
ค่าคงที่ที่จะส่งไปยัง startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
ข้อกําหนดเบื้องต้นของรันไทม์
ไม่มี
คำอธิบาย
โอน SMS จากอุปกรณ์เครื่องหนึ่งไปยังอีกเครื่อง ช่วยเหลืองานการรับส่งข้อความของผู้ใช้ให้มีความต่อเนื่องเมื่อเปลี่ยนอุปกรณ์

บริการสั้นๆ

要在清单中的以下位置声明的前台服务类型
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>

ได้รับการยกเว้นจากระบบ

ประเภทบริการที่ทำงานอยู่เบื้องหน้าที่จะประกาศในไฟล์ Manifest ในส่วน
android:foregroundServiceType
systemExempted
สิทธิ์ในการประกาศในไฟล์ Manifest
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
ค่าคงที่ที่จะส่งไปยัง startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
ข้อกําหนดเบื้องต้นของรันไทม์
ไม่มี
คำอธิบาย

สงวนไว้สำหรับแอปพลิเคชันของระบบและการผสานรวมระบบที่เฉพาะเจาะจง เพื่อใช้บริการที่ทำงานอยู่เบื้องหน้าต่อไป

หากต้องการใช้ประเภทนี้ แอปต้องเป็นไปตามเกณฑ์ข้อใดข้อหนึ่งต่อไปนี้เป็นอย่างน้อย

  • อุปกรณ์อยู่ในสถานะโหมดสาธิต
  • แอปเป็นเจ้าของอุปกรณ์
  • แอปเป็นเจ้าของเครื่องมือวิเคราะห์
  • แอปความปลอดภัยที่มีบทบาท ROLE_EMERGENCY
  • แอปผู้ดูแลระบบอุปกรณ์
  • แอปที่มีสิทธิ์ SCHEDULE_EXACT_ALARM หรือ USE_EXACT_ALARM และใช้บริการที่ทำงานอยู่เบื้องหน้าเพื่อส่งเสียงปลุกในเบื้องหลังต่อไป รวมถึงการปลุกด้วยระบบสัมผัสเท่านั้น

  • แอป VPN (กำหนดค่าโดยใช้การตั้งค่า > เครือข่ายและอินเทอร์เน็ต > VPN)

    มิเช่นนั้น การประกาศประเภทนี้จะทำให้ระบบแสดงข้อผิดพลาด 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.