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ụ 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ụ 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 chạy dịch vụ.

Lưu ý: Trong nhiều trường hợp, bạn có thể sử dụng các API được thiết kế riêng thay vì tạo một loại dịch vụ cụ thể trên nền trước. Khi có các API được xây dựng cho mục đích cụ thể, chúng thường là lựa chọn tốt hơn so với việc tạo một dịch vụ nền trước. Các API này được liệt kê trong phần Giải pháp thay thế trong các loại dịch vụ trên nền trước phù hợp.

Máy ảnh

Loại dịch vụ 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ố cần 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ụ nền trước camera khi ứng dụng của bạn đang ở chế độ nền và bạn không thể khởi chạy dịch vụ 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:

  • 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 khi bắt đầu chạy sau đâ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.

Lưu ý: Nếu ứng dụng của bạn thực hiện phép chiếu hoặc hoạt động nhắn tin từ xa, hãy chuyển sang sử dụng lớp Phép chiếu nội dung nghe nhìn tương ứng hoặc nhắn tin từ xa.

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

Note: Apps that target Android 15 or higher are not allowed to launch a data sync foreground service from a BOOT_COMPLETED broadcast receiver. For more information, see Restrictions on BOOT_COMPLETED broadcast receivers launching foreground services.

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

Lưu ý: Quyền khi bắt đầu chạy ĐỌC dựa trên cảm biến và BODY_SENSORS phải tuân theo các 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 health sử dụng cảm biến cơ thể khi ứng dụng đang chạy ở chế độ nền, trừ phi bạn đã được cấp quyền BODY_SENSORS_BACKGROUND (từ API cấp 33 đến API cấp 35) hoặc quyền READ_HEALTH_DATA_IN_BACKGROUND (API cấp 36). Để 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 khi đang sử dụ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í

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:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

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 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 thông tin vị trí phải tuân thủ 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

Foreground service type to declare in manifest under

android:foregroundServiceType

mediaPlayback

Permission to declare in your manifest

FOREGROUND_SERVICE_MEDIA_PLAYBACK

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK

Runtime prerequisites

None

Description

Continue audio or video playback from the background. Support Digital Video Recording (DVR) functionality on Android TV.

Note: Apps that target Android 15 or higher are not allowed to launch a media playback foreground service from a BOOT_COMPLETED broadcast receiver. For more information, see Restrictions on BOOT_COMPLETED broadcast receivers launching foreground services.

Alternatives

If you're showing picture-in-picture video, use Picture-in-Picture mode.

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ụ 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ố cần 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ụ 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ụ 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ưu ý: Các ứng dụng nhắm đến Android 15 trở lên không được phép chạy dịch vụ trên nền trước để truyền 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ế

Để 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ô

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

android:foregroundServiceType

microphone

要在清单中声明的权限

FOREGROUND_SERVICE_MICROPHONE

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_MICROPHONE

运行时前提条件

请求并被授予 RECORD_AUDIO 运行时权限。

注意： RECORD_AUDIO 运行时权限受“使用期间”限制。因此，当应用在后台运行时，您无法创建 microphone 前台服务，也无法从 BOOT_COMPLETED 接收器启动 microphone 前台服务，但有少数例外情况。如需了解详情，请参阅与启动需要“使用时”权限的前台服务相关的限制。

说明

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

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

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

android:foregroundServiceType

phoneCall

要在清单中声明的权限

FOREGROUND_SERVICE_PHONE_CALL

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_PHONE_CALL

运行时前提条件

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

• 应用已在其清单文件中声明 MANAGE_OWN_CALLS 权限。

• 应用通过 ROLE_DIALER 角色成为默认的拨号器应用。

注意： 以 Android 15 或更高版本为目标平台的应用不允许从 BOOT_COMPLETED 广播接收器启动电话呼叫前台服务。如需了解详情，请参阅与 BOOT_COMPLETED 广播接收器启动前台服务相关的限制。

说明

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

Foreground service type to declare in manifest under

android:foregroundServiceType

systemExempted

Permission to declare in your manifest

FOREGROUND_SERVICE_SYSTEM_EXEMPTED

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED

Runtime prerequisites

None

Description

Reserved for system applications and specific system integrations, to continue to use foreground services.

To use this type, an app must meet at least one of the following criteria:

• Device is in demo mode state
• App is a Device Owner
• App is a Profiler Owner
• Safety Apps that have the ROLE_EMERGENCY role
• Device Admin apps
• Apps holding SCHEDULE_EXACT_ALARM or USE_EXACT_ALARM permission

• VPN apps (configured using Settings > Network & Internet > VPN)

  Otherwise, declaring this type causes the system to throw a 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.