Bắt buộc phải có loại dịch vụ trên nền trước

Để giúp nhà phát triển thể hiện rõ ý định khi xác định dịch vụ trên nền trước dành cho người dùng, Android 10 đã cho ra mắt thuộc tính android:foregroundServiceType trong phần tử <service>.

Nếu ứng dụng của bạn nhắm đến Android 14, thì ứng dụng đó phải chỉ định các kiểu dịch vụ thích hợp trên nền trước. Như trong các phiên bản Android trước đây, bạn có thể kết hợp nhiều kiểu. Danh sách này cho thấy các kiểu dịch vụ trên nền trước để bạn lựa chọn:

Nếu một trường hợp sử dụng trong ứng dụng không liên quan đến bất cứ kiểu nào trong số này, bạn nên di chuyển logic để sử dụng WorkManager hoặc công việc chuyển dữ liệu do người dùng khởi tạo.

health, remoteMessaging, shortService, specialUse và systemExempted là các kiểu mới trong Android 14.

Đoạn mã sau đây cho thấy ví dụ về cách khai báo kiểu dịch vụ trên nền trước trong tệp kê khai:

<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>

Nếu một ứng dụng nhắm đến Android 14 không xác định kiểu cho một dịch vụ nhất định trong tệp kê khai, thì hệ thống sẽ tăng MissingForegroundServiceTypeException khi gọi startForeground() cho dịch vụ đó.

Khai báo quyền mới để sử dụng các loại dịch vụ trên nền trước

If apps that target Android 14 use a foreground service, they must declare a specific permission, based on the foreground service type, that Android 14 introduces. These permissions appear in the sections labeled "permission that you must declare in your manifest file" in the intended use cases and enforcement for each foreground service type section on this page.

All of the permissions are defined as normal permissions and are granted by default. Users cannot revoke these permissions.

Cung cấp loại dịch vụ trên nền trước trong thời gian chạy

Phương pháp hay nhất cho các ứng dụng có bắt đầu dịch vụ trên nền trước là sử dụng phiên bản ServiceCompat của startForeground() (có trong androidx-core 1.12 trở lên), trong đó bạn truyền một số nguyên bitwise của các kiểu dịch vụ trên nền trước. Bạn có thể chọn truyền một hoặc nhiều giá trị tương ứng với từng kiểu.

Thường thì bạn chỉ nên khai báo các kiểu cần thiết cho một trường hợp sử dụng cụ thể. Điều này giúp bạn dễ dàng đáp ứng các kỳ vọng của hệ thống đối với từng loại dịch vụ trên nền trước. Trong trường hợp sử dụng nhiều kiểu để bắt đầu dịch vụ trên nền trước, thì dịch vụ trên nền trước đó phải tuân thủ các yêu cầu thực thi trên nền tảng của tất cả kiểu.

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

Nếu kiểu dịch vụ trên nền trước không được chỉ định trong lệnh gọi, thì kiểu này sẽ mặc định là các giá trị được xác định trong tệp kê khai. Nếu bạn không chỉ định loại dịch vụ trong tệp kê khai, hệ thống sẽ gửi MissingForegroundServiceTypeException.

Nếu dịch vụ trên nền trước cần các quyền mới sau khi bạn khởi chạy, bạn nên gọi lại startForeground() và thêm các loại dịch vụ mới. Ví dụ: giả sử một ứng dụng thể dục chạy một dịch vụ theo dõi chạy bộ luôn cần thông tin location, nhưng có thể cần hoặc không cần quyền media. Bạn cần khai báo cả location và mediaPlayback trong tệp kê khai. Nếu người dùng bắt đầu chạy và chỉ muốn theo dõi vị trí của họ, thì ứng dụng của bạn sẽ gọi startForeground() và chỉ truyền loại dịch vụ location. Sau đó, nếu người dùng muốn bắt đầu phát âm thanh, hãy gọi lại startForeground() và truyền location|mediaPlayback.

Kiểm tra thời gian chạy của hệ thống

The system checks for proper use of foreground service types and confirms that the app has requested the proper runtime permissions or uses the required APIs. For instance, the system expects apps that use the foreground service type FOREGROUND_SERVICE_TYPE_LOCATION type to request either ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION.

This implies that apps must follow a very specific order of operations when requesting permissions from the user and starting foreground services. Permissions must be requested and granted before the app attempts to call startForeground(). Apps that request the appropriate permissions after the foreground service has been started must change this order of operations and request the permission before starting the foreground service.

The specifics of platform enforcement appear in the sections labeled "runtime requirements" in the intended use cases and enforcement for each foreground service type section on this page.

Trường hợp sử dụng dự kiến và biện pháp thực thi đối với từng loại dịch vụ trên nền trước

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

Máy ảnh

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai trong android:foregroundServiceType
camera
Quyền khai báo trong tệp kê khai
FOREGROUND_SERVICE_CAMERA
Hằng số để truyền đến startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
Điều kiện tiên quyết về thời gian chạy

Yêu cầu và được cấp quyền khi bắt đầu chạy CAMERA

Lưu ý: Quyền khi bắt đầu chạy CAMERA phải tuân theo các quy định hạn chế khi đang sử dụng. Vì lý do này, bạn không thể tạo dịch vụ trên nền trước camera khi ứng dụng đang chạy ở chế độ nền, ngoại trừ một số trường hợp ngoại lệ. Để biết thêm thông tin, hãy xem phần Hạn chế khi khởi động các dịch vụ trên nền trước cần quyền khi đang sử dụng.

Mô tả

Tiếp tục truy cập vào máy ảnh ở chế độ nền, chẳng hạn như các ứng dụng trò chuyện video cho phép thực thi đa nhiệm.

Thiết bị đã kết nối

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai theo
android:foregroundServiceType
connectedDevice
Quyền khai báo trong tệp kê khai
FOREGROUND_SERVICE_CONNECTED_DEVICE
Hằng số để truyền đến startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
Điều kiện tiên quyết về thời gian chạy

Ít nhất một trong các điều kiện sau phải đúng:

Nội dung mô tả

Các hoạt động tương tác với thiết bị bên ngoài cần có kết nối Bluetooth, NFC, IR, USB hoặc kết nối mạng.

Lựa chọn thay thế

Nếu ứng dụng của bạn cần chuyển dữ liệu liên tục sang một thiết bị bên ngoài, hãy cân nhắc sử dụng trình quản lý thiết bị đồng hành. Sử dụng API hiện diện của thiết bị đồng hành để giúp ứng dụng của bạn luôn chạy trong khi thiết bị đồng hành ở trong phạm vi.

Nếu ứng dụng của bạn cần quét tìm thiết bị Bluetooth, hãy cân nhắc sử dụng API quét Bluetooth.

Đồng bộ hoá dữ liệu

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

数据传输操作，例如：

  • 数据上传或下载
  • 备份和恢复操作
  • 导入或导出操作
  • 获取数据
  • 本地文件处理
  • 通过网络在设备和云端之间传输数据
替代方案

如需了解详情，请参阅数据同步前台服务的替代方案。

Sức khoẻ

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

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

注意：BODY_SENSORS 和基于传感器的读取运行时权限受“在使用时”限制。因此，除非您已获得 BODY_SENSORS_BACKGROUND（API 级别 33 到 35）或 READ_HEALTH_DATA_IN_BACKGROUND（API 级别 36 及更高级别）权限，否则您无法创建在应用处于后台运行时使用身体传感器的 health 前台服务。如需了解详情，请参阅与启动需要使用时权限的前台服务相关的限制。

说明

为健身类别的应用（例如锻炼追踪器）提供支持的所有长时间运行的用例。

Vị trí

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai theo
android:foregroundServiceType
location
Quyền khai báo trong tệp kê khai
FOREGROUND_SERVICE_LOCATION
Hằng số để truyền đến startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
Điều kiện tiên quyết về thời gian chạy

Người dùng phải bật dịch vụ vị trí và ứng dụng phải được cấp ít nhất một trong các quyền khi bắt đầu chạy sau đây:

Lưu ý: Để kiểm tra xem người dùng đã bật dịch vụ vị trí cũng như cấp quyền truy cập vào các quyền khi bắt đầu chạy hay chưa, hãy sử dụng PermissionChecker#checkSelfPermission()

Lưu ý: Quyền khi bắt đầu chạy liên quan đến vị trí phải tuân theo các quy định hạn chế khi đang sử dụng. Vì lý do này, bạn không thể tạo dịch vụ trên nền trước location khi ứng dụng đang chạy ở chế độ nền, trừ phi bạn đã được cấp quyền thời gian chạy ACCESS_BACKGROUND_LOCATION. Để biết thêm thông tin, hãy xem phần Hạn chế khi khởi động các dịch vụ trên nền trước cần quyền khi đang sử dụng.

Mô tả

Các trường hợp sử dụng lâu dài (ví dụ: chỉ đường và chia sẻ vị trí) cần đến quyền truy cập thông tin vị trí.

Lựa chọn thay thế

Nếu ứng dụng của bạn cần được kích hoạt khi người dùng đến một số vị trí cụ thể, hãy cân nhắc sử dụng API khoanh vùng địa lý.

Nội dung nghe nhìn

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

Chiếu nội dung nghe nhìn

Foreground service type to declare in manifest under
android:foregroundServiceType
mediaProjection
Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PROJECTION
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
Runtime prerequisites

Call the createScreenCaptureIntent() method before starting the foreground service. Doing so shows a permission notification to the user; the user must grant the permission before you can create the service.

After you have created the foreground service, you can call MediaProjectionManager.getMediaProjection().

Description

Project content to non-primary display or external device using the MediaProjection APIs. This content doesn't have to be exclusively media content.

Alternatives

To stream media to another device, use the Google Cast SDK.

Micrô

Foreground service type to declare in manifest under
android:foregroundServiceType
microphone
Permission to declare in your manifest
FOREGROUND_SERVICE_MICROPHONE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
Runtime prerequisites

Request and be granted the RECORD_AUDIO runtime permission.

Note: The RECORD_AUDIO runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a microphone foreground service while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Continue microphone capture from the background, such as voice recorders or communication apps.

Cuộc gọi điện thoại

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

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

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

使用 ConnectionService API 继续当前通话。

替代方案

如果您需要拨打电话、视频通话或 VoIP 通话，不妨考虑使用 android.telecom 库。

考虑使用 CallScreeningService 来过滤来电。

Nhắn tin từ xa

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
remoteMessaging
在清单中声明的权限
FOREGROUND_SERVICE_REMOTE_MESSAGING
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
运行时前提条件
无
说明
将短信从一台设备转移到另一台设备。在用户切换设备时，帮助确保用户消息任务的连续性。

Dịch vụ ngắn

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai theo
android:foregroundServiceType
shortService
Quyền khai báo trong tệp kê khai
Không có
Hằng số để truyền đến startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
Điều kiện tiên quyết về thời gian chạy
Không có
Nội dung mô tả

Nhanh chóng hoàn tất công việc quan trọng mà không bị gián đoạn hoặc trì hoãn.

Kiểu này có một số đặc điểm riêng biệt:

  • Chỉ chạy được trong một khoảng thời gian ngắn (khoảng 3 phút).
  • Không hỗ trợ các dịch vụ cố định trên nền trước.
  • Không thể bắt đầu các dịch vụ trên nền trước khác.
  • Không yêu cầu quyền dành riêng cho từng kiểu, tuy vẫn đòi hỏi quyền FOREGROUND_SERVICE.
  • shortService chỉ có thể thay đổi thành một loại dịch vụ khác nếu ứng dụng hiện đủ điều kiện để bắt đầu một dịch vụ trên nền trước mới.
  • Dịch vụ trên nền trước có thể thay đổi loại thành shortService bất cứ lúc nào, tại thời điểm đó, khoảng thời gian chờ bắt đầu.

Thời gian chờ đối với shortService bắt đầu từ thời điểm gọi Service.startForeground(). Ứng dụng dự kiến sẽ gọi Service.stopSelf() hoặc Service.stopForeground() trước khi hết thời gian chờ. Nếu không, Service.onTimeout() mới sẽ được gọi, mang đến cho ứng dụng một khoảng thời gian ngắn để gọi stopSelf() hoặc stopForeground() nhằm dừng dịch vụ.

Một thời gian ngắn sau khi Service.onTimeout() được gọi, ứng dụng sẽ chuyển sang một trạng thái lưu trong bộ nhớ đệm và không còn được xem là chạy ở nền trước, trừ trường hợp người dùng chủ động tương tác với ứng dụng. Một thời gian ngắn sau khi ứng dụng được lưu vào bộ nhớ đệm và dịch vụ vẫn chưa bị dừng, ứng dụng sẽ nhận được một lỗi ANR. Thông báo lỗi ANR đó nhắc đến FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. Vì những lý do này, cách tốt nhất là triển khai lệnh gọi lại Service.onTimeout().

Lệnh gọi lại Service.onTimeout() không tồn tại trên Android 13 trở xuống. Nếu cùng một dịch vụ chạy trên các thiết bị như vậy, thì dịch vụ đó sẽ không bị hết thời gian chờ cũng như không gặp lỗi ANR. Hãy đảm bảo dịch vụ của bạn dừng ngay sau khi hoàn tất tác vụ xử lý, kể cả khi chưa nhận được lệnh gọi lại Service.onTimeout().

Điều quan trọng bạn cần lưu ý là nếu không hết thời gian chờ của shortService, ứng dụng sẽ gặp lỗi ANR ngay cả khi có các dịch vụ trên nền trước hợp lệ khác hoặc các quy trình khác trong vòng đời của ứng dụng.

Nếu người dùng nhìn thấy ứng dụng hoặc ứng dụng đáp ứng một trong các quy tắc miễn trừ cho phép bắt đầu chạy các dịch vụ trên nền trước từ chế độ nền, hãy gọi Service.StartForeground() một lần nữa bằng tham số FOREGROUND_SERVICE_TYPE_SHORT_SERVICE (kéo dài thời gian chờ thêm 3 phút nữa). Nếu người dùng không nhìn thấy ứng dụng và ứng dụng không đáp ứng một trong các quy tắc miễn trừ, thì mọi cố gắng bắt đầu một dịch vụ trên nền trước khác, bất kể kiểu nào, cũng sẽ gây ra ForegroundServiceStartNotAllowedException

Nếu người dùng tắt tính năng tối ưu hoá pin cho ứng dụng, thì ứng dụng vẫn bị ảnh hưởng bởi thời gian chờ của dịch vụ shortService trên nền trước.

Nếu bạn bắt đầu một dịch vụ trên nền trước bao gồm kiểu shortService và một kiểu dịch vụ trên nền trước khác, hệ thống sẽ bỏ qua phần khai báo cho kiểu shortService. Tuy nhiên, dịch vụ vẫn phải tuân thủ các điều kiện tiên quyết của các kiểu khác đã khai báo. Để biết thêm thông tin, hãy xem tài liệu về Dịch vụ trên nền trước.

Cách sử dụng đặc biệt

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai trong
android:foregroundServiceType
specialUse
Quyền khai báo trong tệp kê khai
FOREGROUND_SERVICE_SPECIAL_USE
Hằng số để truyền đến startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
Điều kiện tiên quyết về thời gian chạy
Không có
Nội dung mô tả

Bao gồm mọi trường hợp sử dụng dịch vụ trên nền trước hợp lệ không thuộc các loại dịch vụ trên nền trước khác.

Ngoài việc khai báo loại dịch vụ trên nền trước FOREGROUND_SERVICE_TYPE_SPECIAL_USE, nhà phát triển nên khai báo các trường hợp sử dụng trong tệp kê khai. Để làm vậy, họ cần chỉ định phần tử <property> trong phần tử <service>. Các giá trị này và trường hợp sử dụng tương ứng sẽ được xem xét khi bạn gửi ứng dụng trong Google Play Console. Việc sử dụng yêu cầu của bạn là theo mẫu tuỳ ý và bạn cần đảm bảo cung cấp đủ để cho nhân viên đánh giá biết lý do bạn cần sử dụng specialUse loại.

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

Được miễn trừ hệ thống

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai theo
android:foregroundServiceType
systemExempted
Quyền khai báo trong tệp kê khai
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
Hằng số để truyền đến startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
Điều kiện tiên quyết về thời gian chạy
Không có
Mô tả

Dành riêng cho các ứng dụng hệ thống và chế độ tích hợp hệ thống cụ thể để tiếp tục sử dụng các dịch vụ trên nền trước.

Để sử dụng loại này, ứng dụng phải đáp ứng ít nhất một trong các tiêu chí sau:

Phương thức thực thi chính sách của Google Play đối với việc sử dụng các loại dịch vụ trên nền trước

如果您的应用以 Android 14 或更高版本为目标平台，您需要在 Play 管理中心的“应用内容”页面（政策 > 应用内容）中声明应用的前台服务类型。如需详细了解如何在 Play 管理中心内声明前台服务类型，请参阅了解前台服务和全屏 intent 要求。