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

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 hạn chế khi 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 của bạn đang chạy ở chế độ nền và bạn không thể khởi chạy dịch vụ trên nền trước camera từ một bộ nhận BOOT_COMPLETED, ngoại trừ một số trường hợp. Để biết thêm thông tin, hãy xem phần Các hạn chế khi khởi động dịch vụ trên nền trước cần có quyền truy cập khi đang sử dụng.
Mô tả: Tiếp tục truy cập vào camera ở chế độ nền, chẳng hạn như các ứng dụng trò chuyện video cho phép thực hiện đ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:

Khai báo ít nhất một trong các quyền sau đây 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:
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.

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

Foreground service type to declare in manifest under

android:foregroundServiceType

dataSync

Permission to declare in your manifest

FOREGROUND_SERVICE_DATA_SYNC

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_DATA_SYNC

Runtime prerequisites

None

Description

Data transfer operations, such as the following:

Data upload or download
Backup-and-restore operations
Import or export operations
Fetch data
Local file processing
Transfer data between a device and the cloud over a network

Alternatives

See Alternatives to data sync foreground services for detailed information.

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 trên API 35 trở xuống
- READ_HEART_RATE
- READ_SKIN_TEMPERATURE
- READ_OXYGEN_SATURATION
- 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í

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:

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

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ưu ý: Các ứng dụng nhắm đến Android 15 trở lên không được phép chạy một dịch vụ trên nền trước phát nội dung nghe nhìn từ một bộ nhận tín hiệu truyền tin BOOT_COMPLETED. Để biết thêm thông tin, hãy xem phần Các hạn chế đối với BOOT_COMPLETED broadcast receiver khi khởi chạy các dịch vụ trên nền trước.
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

Foreground service type to declare in manifest under

android:foregroundServiceType

mediaProcessing

Permission to declare in your manifest

FOREGROUND_SERVICE_MEDIA_PROCESSING

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING

Runtime prerequisites

None

Description

Service for performing time-consuming operations on media assets, like converting media to different formats. The system allows this service a limited time to run; under normal circumstances, this time limit would be 6 hours out of every 24. (This limit is shared by all of an app's mediaProcessing foreground services.)

Your app should manually stop the media processing service in the following scenario:

When the transcoding operation finishes or reaches a failure state, have the service call Service.stopForeground() and Service.stopSelf() to stop the service completely.

If the timeout period is reached, the system calls the service's Service.onTimeout(int, int) method. At this time, the service has a few seconds to call Service.stopSelf(). If the service does not call Service.stopSelf(), an ANR will occur with this error message: "A foreground service of <fgs_type> did not stop within its timeout: <component_name>".

Note: Service.onTimeout(int, int) is not available on Android 14 or lower. On devices running those versions, if a media processing service reaches the timeout period, the system immediately caches the app. For this reason, your app shouldn't wait to get a timeout notification. Instead, it should terminate the foreground service or change it to a background service as soon as appropriate.

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.

Note: Apps that target Android 15 or higher are not allowed to launch a media projection foreground service from a BOOT_COMPLETED broadcast receiver. For more information, see Restrictions on BOOT_COMPLETED broadcast receivers launching foreground services.
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 and you cannot launch a microphone foreground service from a BOOT_COMPLETED receiver, 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

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 gọi điện 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 cần gọi điện thoại, gọi video hoặc gọi 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 theo
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

Foreground service type to declare in manifest under

android:foregroundServiceType

shortService

Permission to declare in your manifest

None

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_SHORT_SERVICE

Runtime prerequisites

None

Description

Quickly finish critical work that cannot be interrupted or postponed.

This type has some unique characteristics:

Can only run for a short period of time (about 3 minutes).
No support for sticky foreground services.
Cannot start other foreground services.
Doesn't require a type-specific permission, though it still requires the FOREGROUND_SERVICE permission.
A shortService can only change to another service type if the app is currently eligible to start a new foreground service.
A foreground service can change its type to shortService at any time, at which point the timeout period begins.

The timeout for shortService begins from the moment that Service.startForeground() is called. The app is expected to call Service.stopSelf() or Service.stopForeground() before the timeout occurs. Otherwise, the new Service.onTimeout() is called, giving apps a brief opportunity to call stopSelf() or stopForeground() to stop their service.

A short time after Service.onTimeout() is called, the app enters a cached state and is no longer considered to be in the foreground, unless the user is actively interacting with the app. A short time after the app is cached and the service has not stopped, the app receives an ANR. The ANR message mentions FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. For these reasons, it's considered best practice to implement the Service.onTimeout() callback.

The Service.onTimeout() callback doesn't exist on Android 13 and lower. If the same service runs on such devices, it doesn't receive a timeout, nor does it ANR. Make sure that your service stops as soon as it finishes the processing task, even if it hasn't received the Service.onTimeout() callback yet.

It's important to note that if the timeout of the shortService is not respected, the app will ANR even if it has other valid foreground services or other app lifecycle processes running.

If an app is visible to the user or satisfies one of the exemptions that allow foreground services to be started from the background, calling Service.StartForeground() again with the FOREGROUND_SERVICE_TYPE_SHORT_SERVICE parameter extends the timeout by another 3 minutes. If the app isn't visible to the user and doesn't satisfy one of the exemptions, any attempt to start another foreground service, regardless of type, causes a ForegroundServiceStartNotAllowedException.

If a user disables battery optimization for your app, it's still affected by the timeout of shortService FGS.

If you start a foreground service that includes the shortService type and another foreground service type, the system ignores the shortService type declaration. However, the service must still adhere to the prerequisites of the other declared types. For more information, see the Foreground services documentation.

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

Foreground service type to declare in manifest under

android:foregroundServiceType

specialUse

Permission to declare in your manifest

FOREGROUND_SERVICE_SPECIAL_USE

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_SPECIAL_USE

Runtime prerequisites

None

Description

Covers any valid foreground service use cases that aren't covered by the other foreground service types.

In addition to declaring the FOREGROUND_SERVICE_TYPE_SPECIAL_USE foreground service type, developers should declare use cases in the manifest. To do so, they specify the <property> element within the <service> element. These values and corresponding use cases are reviewed when you submit your app in the Google Play Console. The use cases you provide are free-form, and you should make sure to provide enough information to let the reviewer see why you need to use the specialUse type.

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

Thiết bị đang ở trạng thái chế độ minh hoạ
Ứng dụng là Chủ sở hữu thiết bị
Ứng dụng là Chủ sở hữu trình phân tích tài nguyên
Ứng dụng An toàn có vai trò ROLE_EMERGENCY
Ứng dụng Quản trị thiết bị
Ứng dụng có quyền SCHEDULE_EXACT_ALARM hoặc USE_EXACT_ALARM
Ứng dụng VPN (được định cấu hình bằng cách sử dụng Cài đặt > Mạng và Internet > VPN)

Nếu không, việc khai báo loại này sẽ khiến hệ thống gửi ra một 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

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.

Loại dịch vụ trên nền trước Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Máy ảnh

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

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

Sức khoẻ

Vị trí

Nội dung nghe nhìn

Xử lý phương tiện

Chiếu nội dung nghe nhìn

Micrô

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

Nhắn tin từ xa

Dịch vụ ngắn

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

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

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

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