From Android 12, Android includes support for TS.43 Service Entitlement Configuration, a GSMA specification that defines the entitlement verification step for the activation of services including, Voice-over-Wi-Fi (VoWiFi), Voice-over-LTE (VoLTE), SMS over IP (SMSoIP), On-Device Service Activation (ODSA) of eSIM companion devices (associated with the requesting device) and data plan information.
To support this specification, Android provides an IMS service entitlement feature that allows a service provider to inform mobile devices of the status of IP Multimedia Subsystem (IMS) network services. This entitlement feature allows the device to query the carrier entitlement server as defined by the GSMA TS.43 specification for the IMS entitlement status using EAP-AKA authentication without requiring users to input any credentials manually.
Carriers with IMS entitlement servers can use the IMS service entitlement feature for service provisioning. Adopting the feature provides the following benefits:
- Reduces testing and certification costs for carriers because this entitlement feature can be used across multiple products and OEMs.
- Reduces development overhead for device manufacturers through a standard Android app.
- Allows device manufacturers and carriers to contribute code for the feature as the feature is open source.
- Provides emergency address management for North American carriers.
The following figure describes the architecture and the behavior of the IMS service entitlement feature.
Figure 1. TS.43 entitlement feature architecture
As shown in Figure 1, the IMS service entitlement feature's architecture includes the following components:
service_entitlementTS.43 Service API static library: This library implements the TS.43 specification, interacts with a carrier's entitlement server, and exposes app-facing APIs for each TS.43 use case.
ImsServiceEntitlementclient app: This app uses the TS.43 Service API. The app implements UI elements including webviews for rendering the carrier's service portal for users to activate services and interacts with other Android components to manage the user experience end to end.
For more information on how to configure Android to work with a carrier's TS.43-based entitlement server, see ImsServiceEntitlement app.
The numbered lines in Figure 1 show how the components of the IMS service entitlement feature communicate with each other. The following describes each of the steps as labeled:
(1) The client app invokes the TS.43 service API to initiate a service entitlement request.
(2) The TS.43 service API sends an HTTP request to the carrier's entitlement server to initiate an EAP-AKA challenge.
(3) The TS.43 service API invokes telephony APIs (for example,
to complete the EAP-AKA challenge-response.
(4) The TS.43 service receives service entitlement or configuration data from the carrier's entitlement server after the EAP-AKA response is verified.
(5) The TS.43 service returns the service entitlement or configuration data to the client app.
(6) The client app handles the data and optionally renders the carrier's service portal for the user to finish service activation.
This section describes the process for integrating the
library and the
Because there's no Android 12 API dependency, the
service_entitlement library and
ImsServiceEntitlement app can be backported
to older Android platforms.
service_entitlement library is statically linked into the
ImsServiceEntitlement app, no additional steps are required for integrating
the library into the
service_entitlement library can be integrated with your own apps for TS.43
use cases such as data plan and ODSA. The library can also be integrated into an
app for non-TS.43 entitlement use cases based on the EAP-AKA protocol.
The following describes the APIs to use for such use cases:
- TS.43 app using the TS.43 HTTP protocol implemented in the library:
Use the APIs in the
- Non-TS.43 app using the EAP-AKA protocol implemented in the library: Use
the APIs exposed in the
By default, Android includes the
ImsServiceEntitlement app installed in the
product partition as a privileged app. To configure the app, use the following
||Carrier's entitlement server URL. The
||Carrier's FCM sender ID.
Don't set this value if FCM isn't required by the carrier.
This is typically required by carriers in North America.
This is required by certain European carriers.
The HTTP traffic to a carrier's entitlement server and web portal goes over the default network, for example, default mobile data or Wi-Fi.
GMS partners: The following carriers are supported by the TS.43 entitlement app in Android 12, following the TS.43 v5.0 specification:
- US: CSpire, US Cellular, Cellcom
- France: Orange
Additional system UI for IMS provisioning
This section describes how OEMs can support additional system UI elements related to IMS service provisioning (for example, when showing a notification when VoWiFi is provisioned).
ImsServiceEntitlement app sets the VoWiFi provisioning state into the
platform using the
system API. This API is also used for VoLTE (with
KEY_VOLTE_PROVISIONING_STATUS) and SMSoIP (with
The system UI can then read the provisioning state by using
or by registering a callback to monitor the provisioning state change through
Overriding configurations for testing
Use the following procedures to temporarily alter the
app behavior for testing purposes. For details on how to override carrier
configurations, see Overriding carrier
Skipping VoWiFi sign-up process
To skip the VoWiFi sign-up process, allowing VoWiFi to be turned on directly,
override the carrier config
and sets its value to an empty string.
Skipping IMS provisioning
To skip IMS provisioning, making IMS services available and allowing users to
turn on such services without network provisioning, override carrier config
and set its value to
Changing entitlement server URL
To change the entitlement server URL, override carrier config
and set its value to the expected URL string. You must include the
Overriding carrier configurations
From Android 11, carrier config override commands are built-in and available with root privileges.
The following command is an example of how to override the carrier config key
carrier_volte_provisioning_required_bool and set its value to
can run the command multiple times to override multiple configs.
adb shell cmd phone cc set-value -p carrier_volte_provisioning_required_bool false
To clear all overrides, use the following command:
adb shell cmd phone cc clear-values
To get more information, run the following command:
adb shell cmd phone cc