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

Kể từ Android 14 (API cấp 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. Điều đó có nghĩa là bạn phải khai báo loại dịch vụ trong tệp kê khai ứng dụng và cũng phả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). Hơn nữa, 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 khi bắt đầu chạy trước khi khởi chạy dịch vụ.

Camera

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

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 trong

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:

• Khai báo ít nhất một trong các quyền sau đây trong tệp kê khai:

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

• Yêu cầu và được cấp ít nhất một trong các quyền sau đây khi bắt đầu chạy:

  • BLUETOOTH_CONNECT
  • BLUETOOTH_ADVERTISE
  • BLUETOOTH_SCAN
  • UWB_RANGING

• Gọi UsbManager.requestPermission()

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.

Phương á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 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 nằm 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

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai theo

android:foregroundServiceType

dataSync

Quyền khai báo trong tệp kê khai

FOREGROUND_SERVICE_DATA_SYNC

Hằng số để truyền đến startForeground()

FOREGROUND_SERVICE_TYPE_DATA_SYNC

Điều kiện tiên quyết về thời gian chạy

Không có

Nội dung mô tả

Các hoạt động chuyển dữ liệu, chẳng hạn như:

• Tải dữ liệu lên hoặc tải dữ liệu xuống
• Hoạt động sao lưu và khôi phục
• Hoạt động nhập hoặc xuất dữ liệu
• Tìm nạp dữ liệu
• Xử lý tệp cục bộ
• Chuyển dữ liệu giữa thiết bị và đám mây qua mạng

Lựa chọn thay thế

Hãy xem phần Các giải pháp thay thế cho dịch vụ đồng bộ hoá dữ liệu trên nền trước để biết thông tin chi tiết.

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:

• Khai báo quyền HIGH_SAMPLING_RATE_SENSORS trong tệp kê khai.

• Yêu cầu và được cấp ít nhất một trong các quyền khi bắt đầu chạy sau đây:

  • BODY_SENSORS
  • ACTIVITY_RECOGNITION

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í

Foreground service type to declare in manifest under

android:foregroundServiceType

location

Permission to declare in your manifest

FOREGROUND_SERVICE_LOCATION

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_LOCATION

Runtime prerequisites

The user must have enabled location services and the app must be granted at least one of the following runtime permissions:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

Description

Long-running use cases that require location access, such as navigation and location sharing.

Alternatives

If your app needs to be triggered when the user reaches specific locations, consider using the geofence API instead.

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 hiển thị video 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 trong

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ó

Nội dung mô tả

Dịch vụ thực hiện các thao tác tốn nhiều thời gian đối với 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 các định dạng khác nhau. 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 thông thường, giới hạn thời gian này là 6 giờ trên mỗi 24 giờ. (Giới hạn này dùng chung cho tất cả mediaProcessing dịch vụ trên nền trước của ứng dụng.)

Ứ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 các trường hợp sau:

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

Nếu đạt đến khoảng 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(), một lỗi ANR sẽ xuất hiện với thông báo lỗi sau: "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 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 đa phương tiệ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 nhận thông báo hết thời gian chờ. Thay vào đó, ứng dụng sẽ chấm dứt dịch vụ trên nền trước hoặc thay đổi sang dịch vụ nền ngay khi thích hợp.

Chiếu nội dung nghe nhìn

要在清单中的以下位置声明的前台服务类型

android:foregroundServiceType

mediaProjection

在清单中声明的权限

FOREGROUND_SERVICE_MEDIA_PROJECTION

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION

运行时前提条件

在启动前台服务之前，调用 createScreenCaptureIntent() 方法。这样做会向用户显示权限通知；用户必须先授予权限，您才能创建服务。

创建前台服务后，您可以调用 MediaProjectionManager.getMediaProjection()。

说明

使用 MediaProjection API 将内容投影到非主要显示屏或外部设备。这些内容不必全都为媒体内容。

替代方案

如需将媒体流式传输到其他设备，请使用 Google Cast SDK。

Micrô

要在清单中的以下位置声明的前台服务类型

android:foregroundServiceType

microphone

在清单中声明的权限

FOREGROUND_SERVICE_MICROPHONE

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_MICROPHONE

运行时前提条件

请求并获得 RECORD_AUDIO 运行时权限。

说明

在后台继续捕获麦克风内容，例如录音器或通信应用。

Cuộc gọi điện thoạ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

phoneCall

Quyền khai báo trong tệp kê khai

FOREGROUND_SERVICE_PHONE_CALL

Hằng số để truyền đến startForeground()

FOREGROUND_SERVICE_TYPE_PHONE_CALL

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

• Ứng dụng đã khai báo quyền MANAGE_OWN_CALLS trong tệp kê khai.

• Ứng dụng là ứng dụng quay số mặc định thông qua vai trò ROLE_DIALER.

Mô tả

Tiếp tục cuộc gọi đang diễn ra bằng các API ConnectionService.

Lựa chọn thay thế

Nếu bạn cần thực hiện cuộc gọi điện thoại, video hoặc VoIP, hãy cân nhắc sử dụng thư viện android.telecom.

Cân nhắc sử dụng CallScreeningService để sàng lọc cuộc gọi.

Nhắn tin từ xa

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai trong

android:foregroundServiceType

remoteMessaging

Quyền khai báo trong tệp kê khai

FOREGROUND_SERVICE_REMOTE_MESSAGING

Hằng số để truyền đến startForeground()

FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING

Điều kiện tiên quyết về thời gian chạy

Không có

Nội dung mô tả

Chuyển tin nhắn văn bản từ thiết bị này sang thiết bị khác. Hỗ trợ người dùng nhắn tin liên tục khi họ chuyển đổi thiết bị.

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 trong

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 sang 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ụ mới trên nền trước.
• Dịch vụ trên nền trước có thể thay đổi kiểu của dịch vụ này thành shortService bất cứ lúc nào. Lúc đó, khoảng thời gian chờ sẽ 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ủ đ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

要在清单中声明的前台服务类型

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>

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

要在其清单中声明的前台服务类型

android:foregroundServiceType

systemExempted

在清单中声明的权限

FOREGROUND_SERVICE_SYSTEM_EXEMPTED

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED

运行时前提条件

无

说明

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

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

• 设备处于演示模式状态
• 应用是设备所有者
• 应用是性能分析器所有者
• 属于具有 ROLE_EMERGENCY 角色的安全应用
• 属于设备管理应用
• 具有 SCHEDULE_EXACT_ALARM 或 USE_EXACT_ALARM 权限的应用

• VPN 应用（通过设置 > 网络和互联网 > VPN 进行配置）

  否则，声明此类型会导致系统抛出 ForegroundServiceTypeNotAllowedException。

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

Nếu ứng dụng của bạn nhắm đến Android 14 trở lên, bạn cần khai báo các loại dịch vụ trên nền trước của ứng dụng trên trang nội dung ứng dụng của Play Console (Chính sách > Nội dung ứng dụng). Để biết thêm thông tin về cách khai báo các loại dịch vụ trên nền trước trong Play Console, hãy xem bài viết Tìm hiểu các yêu cầu khi sử dụng ý định truy cập chế độ toàn màn hình và dịch vụ trên nền trước.