Để giúp nhà phát triển thể hiện rõ ý định khi xác định dịch vụ trên nền trước dành cho người dùng, Android 10 đã cho ra mắt thuộc tính android:foregroundServiceType
trong phần tử <service>
.
Nếu ứng dụng của bạn nhắm đến Android 14, thì ứng dụng đó phải chỉ định các kiểu dịch vụ thích hợp trên nền trước. Như trong các phiên bản Android trước đây, bạn có thể kết hợp nhiều kiểu. Danh sách này cho thấy các kiểu dịch vụ trên nền trước để bạn lựa chọn:
camera
connectedDevice
dataSync
health
location
mediaPlayback
mediaProjection
microphone
phoneCall
remoteMessaging
shortService
specialUse
systemExempted
Nếu một trường hợp sử dụng trong ứng dụng không liên quan đến bất cứ kiểu nào trong số này, bạn nên di chuyển logic để sử dụng WorkManager hoặc công việc chuyển dữ liệu do người dùng khởi tạo.
health, remoteMessaging, shortService, specialUse
và systemExempted
là các kiểu mới trong Android 14.
Đoạn mã sau đây cho thấy ví dụ về cách khai báo kiểu dịch vụ trên nền trước trong tệp kê khai:
<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>
Nếu một ứng dụng nhắm đến Android 14 không xác định kiểu cho một dịch vụ nhất định trong tệp kê khai, thì hệ thống sẽ tăng MissingForegroundServiceTypeException
khi gọi startForeground()
cho dịch vụ đó.
Khai báo quyền mới để sử dụng các loại dịch vụ trên nền trước
Nếu ứng dụng nhắm đến Android 14 và có sử dụng dịch vụ trên nền trước, thì ứng dụng đó phải khai báo một quyền cụ thể, dựa trên loại dịch vụ trên nền trước mà Android 14 ra mắt. Các quyền này xuất hiện trong những phần có nhãn "quyền mà bạn phải khai báo trong tệp kê khai" trong phần các trường hợp sử dụng dự kiến và biện pháp thực thi cho từng loại dịch vụ trên nền trước trên trang này.
Tất cả quyền đó được xác định là quyền thông thường và được cấp theo mặc định. Người dùng không thể thu hồi các quyền này.
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
- Foreground service type to declare in manifest under
android:foregroundServiceType
camera
- Permission to declare in your manifest
FOREGROUND_SERVICE_CAMERA
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
- Runtime prerequisites
Request and be granted the
CAMERA
runtime permissionNote: The
CAMERA
runtime permission is subject to while-in-use restrictions. For this reason, you cannot create acamera
foreground service 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
Continue to access the camera from the background, such as video chat apps that allow for multitasking.
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:
Declare at least one of the following permissions in your manifest:
Request and be granted at least one of the following runtime permissions:
- 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:
Declare the
HIGH_SAMPLING_RATE_SENSORS
permission in your manifest.Request and be granted at least one of the following runtime permissions:
Note: The
BODY_SENSORS
runtime permission is subject to while-in-use restrictions. For this reason, you cannot create ahealth
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 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:
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 các 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 liên quan đến vị trí phải tuân theo 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ạyACCESS_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
- 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.
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ô
- 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 amicrophone
foreground service 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
Continue microphone capture from the background, such as voice recorders or communication apps.
Cuộc gọi điện thoại
- Foreground service type to declare in manifest under
android:foregroundServiceType
phoneCall
- Permission to declare in your manifest
FOREGROUND_SERVICE_PHONE_CALL
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
- Runtime prerequisites
At least one of these conditions must be true:
- App has declared the
MANAGE_OWN_CALLS
permission in its manifest file.
- App has declared the
- App is the default dialer app through the
ROLE_DIALER
role.
- App is the default dialer app through the
- Description
Continue an ongoing call using the
ConnectionService
APIs.- Alternatives
If you need to make phone, video, or VoIP calls, consider using the
android.telecom
library.Consider using
CallScreeningService
to screen calls.
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 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ọiService.stopSelf()
hoặcService.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ọistopSelf()
hoặcstopForeground()
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 đếnFOREGROUND_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ạiService.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ạiService.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 raForegroundServiceStartNotAllowedException
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ểushortService
. 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
- 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 thespecialUse
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:
- 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
orUSE_EXACT_ALARM
permission and are using Foreground Service to continue alarms in the background, including haptics-only alarms. 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.