IMS service entitlement

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.

Architecture

The following figure describes the architecture and the behavior of the IMS service entitlement feature.

TS.43 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_entitlement TS.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.

  • ImsServiceEntitlement client 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, getIccAuthentication) 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.

Integration

This section describes the process for integrating the service_entitlement library and the ImsServiceEntitlement app.

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

Because the service_entitlement library is statically linked into the ImsServiceEntitlement app, no additional steps are required for integrating the library into the ImsServiceEntitlement app.

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 ServiceEntitlement class
  • Non-TS.43 app using the EAP-AKA protocol implemented in the library: Use the APIs exposed in the EapAkaHelper class

ImsServiceEntitlement app

By default, Android includes the ImsServiceEntitlement app installed in the product partition as a privileged app. To configure the app, use the following CarrierConfig keys:

Key Value
KEY_ENTITLEMENT_SERVER_URL_STRING Carrier's entitlement server URL. The https:// prefix must be included.
KEY_FCM_SENDER_ID_STRING Carrier's FCM sender ID.

Don't set this value if FCM isn't required by the carrier.
KEY_SHOW_VOWIFI_WEBVIEW_BOOL Set to true if the carrier requires a web portal UI for users to sign up for VoWiFi service. For example, consenting to terms and conditions or entering an emergency address.

This is typically required by carriers in North America.
KEY_WFC_EMERGENCY_ADDRESS_CARRIER_APP_STRING
Set to com.android.imsserviceentitlement/.WfcActivationActivity, if KEY_SHOW_VOWIFI_WEBVIEW_BOOL is true.
KEY_IMS_PROVISIONING_BOOL Set to true if the carrier requires network provisioning of IMS (VoLTE/VoWiFi/SMSoIP) services in the background.

This is required by certain European carriers.
KEY_CARRIER_VOLTE_PROVISIONING_REQUIRED_BOOL Set to true if KEY_IMS_PROVISIONING_BOOL is true.

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

The ImsServiceEntitlement app sets the VoWiFi provisioning state into the platform using the ProvisioningManager.setProvisioningIntValue(KEY_VOICE_OVER_WIFI_ENABLED_OVERRIDE, value) system API. This API is also used for VoLTE (with KEY_VOLTE_PROVISIONING_STATUS) and SMSoIP (with KEY_SMS_OVER_IP_ENABLED).

The system UI can then read the provisioning state by using getProvisioningIntValue or by registering a callback to monitor the provisioning state change through registerProvisioningChangedCallback.

Override configurations for testing

Use the following procedures to temporarily alter the ImsServiceEntitlement app behavior for testing purposes. For details on how to override carrier configurations, see Overriding carrier configurations.

Skip VoWiFi sign-up process

To skip the VoWiFi sign-up process, allowing VoWiFi to be turned on directly, override the carrier config KEY_WFC_EMERGENCY_ADDRESS_CARRIER_APP_STRING and sets its value to an empty string.

Skip IMS provisioning

To skip IMS provisioning, making IMS services available and allowing users to turn on such services without network provisioning, override carrier config KEY_CARRIER_VOLTE_PROVISIONING_REQUIRED_BOOL and set its value to false.

Change entitlement server URL

To change the entitlement server URL, override carrier config KEY_ENTITLEMENT_SERVER_URL_STRING and set its value to the expected URL string. You must include the https:// prefix.

Override 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 false. You can run the command multiple times to override multiple configs.

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