Loại dịch vụ trên nền trước

Kể từ Android 14 (cấp độ API 34), bạn phải khai báo một loại dịch vụ phù hợp cho mỗi dịch vụ trên nền trước. Tức là bạn phải khai báo loại dịch vụ trong tệp kê khai ứng dụng, đồng thời yêu cầu quyền sử dụng dịch vụ trên nền trước phù hợp cho loại dịch vụ đó (ngoài việc yêu cầu quyền FOREGROUND_SERVICE). Ngoài ra, tuỳ thuộc vào loại dịch vụ trên nền trước, bạn có thể phải yêu cầu quyền trong thời gian chạy trước khi chạy dịch vụ.

Máy ảnh

要在清单中的 android:foregroundServiceType 下声明的前台服务类型
camera
要在清单中声明的权限
FOREGROUND_SERVICE_CAMERA
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_CAMERA
运行时前提条件

请求并获得 CAMERA 运行时权限

说明

继续在后台访问相机，例如支持多任务的视频聊天应用。

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

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

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

说明

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

替代方案

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

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

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

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

数据传输操作，例如：

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

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

Sức khoẻ

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai theo
android:foregroundServiceType
health
Quyền khai báo trong tệp kê khai
FOREGROUND_SERVICE_HEALTH
Hằng số để truyền đến startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
Đ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:

Mô tả

Trường hợp sử dụng lâu dài bất kỳ để hỗ trợ các ứng dụng trong danh mục thể dục (ví dụ: trình theo dõi bài tập thể dục).

Vị trí

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

用户必须已启用位置信息服务，并且应用必须至少获得以下一项运行时权限：

说明

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

替代方案

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

Nội dung nghe nhì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
mediaPlayback
Quyền khai báo trong tệp kê khai
FOREGROUND_SERVICE_MEDIA_PLAYBACK
Hằng số để truyền đến startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
Điều kiện tiên quyết về thời gian chạy
Không có
Nội dung mô tả

Tiếp tục phát âm thanh hoặc video ở chế độ nền. Hỗ trợ chức năng Quay video kỹ thuật số (DVR) trên Android TV.

Lựa chọn thay thế

Nếu bạn đang chiếu video ở chế độ hình trong hình, hãy sử dụng chế độ Hình trong hình.

Xử lý phương tiệ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
mediaProcessing
Quyền khai báo trong tệp kê khai
FOREGROUND_SERVICE_MEDIA_PROCESSING
Hằng số để truyền đến startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
Điều kiện tiên quyết về thời gian chạy
Không có
Mô tả

Dịch vụ để thực hiện các thao tác tốn thời gian trên các thành phần nội dung nghe nhìn, chẳng hạn như chuyển đổi nội dung nghe nhìn sang nhiều định dạng. Hệ thống cho phép dịch vụ này chạy trong một khoảng thời gian giới hạn; trong trường hợp bình thường, giới hạn thời gian này sẽ là 6 giờ trong mỗi 24 giờ. (Tất cả dịch vụ mediaProcessing trên nền trước của ứng dụng đều dùng chung giới hạn này.)

Ứng dụng của bạn nên dừng dịch vụ xử lý nội dung nghe nhìn theo cách thủ công trong trường hợp sau:

  • Khi quá trình chuyển mã hoàn tất hoặc đạt đến trạng thái không thành công, hãy yêu cầu dịch vụ gọi Service.stopForeground() và Service.stopSelf() để dừng hoàn toàn dịch vụ.

Nếu hết thời gian chờ, hệ thống sẽ gọi phương thức Service.onTimeout(int, int) của dịch vụ. Tại thời điểm này, dịch vụ có vài giây để gọi Service.stopSelf(). Nếu dịch vụ không gọi Service.stopSelf(), thì lỗi ANR sẽ xảy ra kèm theo thông báo lỗi này: "Dịch vụ trên nền trước của <fgs_type> không dừng trong thời gian chờ: <component_name>".

Lưu ý: Service.onTimeout(int, int) không dùng được trên Android 14 trở xuống. Trên các thiết bị chạy các phiên bản đó, nếu một dịch vụ xử lý nội dung nghe nhìn đạt đến khoảng thời gian chờ, thì hệ thống sẽ ngay lập tức lưu ứng dụng vào bộ nhớ đệm. Vì lý do này, ứng dụng của bạn không nên đợi nhận thông báo hết thời gian chờ. Thay vào đó, ứng dụng phải chấm dứt dịch vụ trên nền trước hoặc thay đổi dịch vụ đó thành dịch vụ trên nền ngay khi thích hợp.

Chiếu nội dung nghe nhì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
mediaProjection
Quyền khai báo trong tệp kê khai
FOREGROUND_SERVICE_MEDIA_PROJECTION
Hằng số để truyền đến startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
Điều kiện tiên quyết về thời gian chạy

Gọi phương thức createScreenCaptureIntent() trước khi bắt đầu dịch vụ trên nền trước. Thao tác này sẽ cho người dùng thấy một thông báo về quyền; người dùng phải cấp quyền trước khi bạn có thể tạo dịch vụ.

Sau khi tạo dịch vụ trên nền trước, bạn có thể gọi MediaProjectionManager.getMediaProjection().

Mô tả

Chiếu nội dung lên màn hình phụ hoặc thiết bị bên ngoài bằng các API MediaProjection. Nội dung này không nhất thiết chỉ là nội dung nghe nhìn.

Lựa chọn thay thế

Để truyền trực tuyến nội dung nghe nhìn đến một thiết bị khác, hãy sử dụng Google Cast SDK.

Micrô

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai theo
android:foregroundServiceType
microphone
Quyền khai báo trong tệp kê khai
FOREGROUND_SERVICE_MICROPHONE
Hằng số để truyền đến startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
Đ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 RECORD_AUDIO.

Mô tả

Tiếp tục ghi âm qua micrô ở chế độ nền, chẳng hạn như trình ghi âm giọng nói hoặc ứng dụng giao tiếp.

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 trong
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ó
Nội dung mô tả

Dành riêng cho các ứng dụng hệ thống, cũng như 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 要求。