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

To help developers be more intentional with defining user-facing foreground services, Android 10 introduced the android:foregroundServiceType attribute within the <service> element.

If your app targets Android 14, it must specify appropriate foreground service types. As in previous versions of Android, multiple types can be combined. This list shows the foreground service types to choose from:

If a use case in your app isn't associated with any of these types, we strongly recommend that you migrate your logic to use WorkManager or user-initiated data transfer jobs.

The health, remoteMessaging, shortService, specialUse, and systemExempted types are new in Android 14.

The following code snippet provides an example of a foreground service type declaration in the manifest:

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

If an app that targets Android 14 doesn't define types for a given service in the manifest, then the system will raise MissingForegroundServiceTypeException upon calling startForeground() for that service.

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

The best practice for applications starting foreground services is to use the ServiceCompat version of startForeground() (available in androidx-core 1.12 and higher) where you pass in a bitwise integer of foreground service types. You can choose to pass one or more type values.

Usually, you should declare only the types required for a particular use case. This makes it easier to meet the system's expectations for each foreground service type. In cases where a foreground service is started with multiple types, then the foreground service must adhere to the platform enforcement requirements of all types.

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

If the foreground service type is not specified in the call, the type defaults to the values defined in the manifest. If you didn't specify the service type in the manifest, the system throws MissingForegroundServiceTypeException.

If the foreground service needs new permissions after you launch it, you should call startForeground() again and add the new service types. For example, suppose a fitness app runs a running-tracker service that always needs location information, but might or might not need media permissions. You would need to declare both location and mediaPlayback in the manifest. If a user starts a run and just wants their location tracked, your app should call startForeground() and pass just the location service type. Then, if the user wants to start playing audio, call startForeground() again and pass 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

Để sử dụng một kiểu dịch vụ trên nền trước nhất định, bạn phải khai báo một quyền cụ thể trong tệp kê khai, bạn phải đáp ứng các yêu cầu cụ thể về thời gian chạy, cũng như ứng dụng của bạn phải đáp ứng một trong các nhóm trường hợp sử dụng dự kiến cho kiểu đó. Các phần sau giải thích quyền bạn phải khai báo, các điều kiện tiên quyết về thời gian chạy và các trường hợp sử dụng dự kiến của từng kiểu.

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à nhận 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ụ camera trên nền trước trong khi ứng dụng chạy ở chế độ nền, với một số trường hợp ngoại lệ. Để biết thêm thông tin, hãy xem phần Các quy định hạn chế khi bắt đầu các dịch vụ trên nền trước cần quyền trong khi sử dụng.

Nội dung mô tả

Tiếp tục truy cập vào máy ảnh từ 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

Foreground service type to declare in manifest under
android:foregroundServiceType
connectedDevice
Permission to declare in your manifest
FOREGROUND_SERVICE_CONNECTED_DEVICE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
Runtime prerequisites

At least one of the following conditions must be true:

Description

Interactions with external devices that require a Bluetooth, NFC, IR, USB, or network connection.

Alternatives

If your app needs to do continuous data transfer to an external device, consider using the companion device manager instead. Use the companion device presence API to help your app stay running while the companion device is in range.

If your app needs to scan for bluetooth devices, consider using the Bluetooth scan API instead.

Đồ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ẻ

Foreground service type to declare in manifest under
android:foregroundServiceType
health
Permission to declare in your manifest
FOREGROUND_SERVICE_HEALTH
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
Runtime prerequisites

At least one of the following conditions must be true:

Note: The BODY_SENSORS runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a health foreground service that uses body sensors 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

Any long-running use cases to support apps in the fitness category such as exercise trackers.

Vị trí

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai trong
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 khi bắt đầu chạy hay chưa, hãy sử dụng PermissionChecker#checkSelfPermission()

Lưu ý: Các quyền truy cập thông tin vị trí khi bắt đầu chạy phải tuân theo các quy định hạn chế trong 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 location khi ứng dụng đang chạy ở chế độ nền, trừ phi bạn đã được cấp quyền khi bắt đầu chạy ACCESS_BACKGROUND_LOCATION. Để biết thêm thông tin, hãy xem Quy định hạn chế khi bắt đầu các dịch vụ trên nền trước mà cần có quyền trong khi sử dụng.

Nội dung 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í.

Phương á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 các 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 trong
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.
Phương á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.

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ô

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai trong
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à nhận quyền khi bắt đầu chạy RECORD_AUDIO.

Lưu ý: Quyền khi bắt đầu chạy RECORD_AUDIO 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ụ microphone trên nền trước trong khi ứng dụng chạy ở chế độ nền, với một số trường hợp ngoại lệ. Để biết thêm thông tin, hãy xem phần Các quy định hạn chế khi bắt đầu các dịch vụ trên nền trước cần quyền trong khi sử dụng.

Nội dung 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

Loại dịch vụ trên nền trước cần khai báo trong tệp kê khai trong
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 là ứng dụng quay số mặc định thông qua vai trò ROLE_DIALER.
Nội dung mô tả

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

Phương án thay thế

Nếu bạn 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.

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

Nhắn tin từ xa

Foreground service type to declare in manifest under
android:foregroundServiceType
remoteMessaging
Permission to declare in your manifest
FOREGROUND_SERVICE_REMOTE_MESSAGING
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
Runtime prerequisites
None
Description
Transfer text messages from one device to another. Assists with continuity of a user's messaging tasks when they switch devices.

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

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

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:

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.