CellBroadcast

The CellBroadcast module reduces repetitive efforts for OEMs (which in turn reduces fragmentation across the Android ecosystem and provides consistent behavior to the end users) and helps streamline carrier testing and certification for CellBroadcast-related requirements (because the code can't be modified by OEMs). This module is updatable, meaning it can receive updates to functionality outside of the normal Android release cycle.

Package format

The CellBroadcast module consists of the following service and app.

  • The CellBroadcastService service supports CellBroadcast SMS decoding, geofencing for wireless emergency alert (WEA) 3.0, message duplication checks, and broadcasting messages to apps. It's a one-to-many geotargeted and geofenced messaging service designed to deliver messages to multiple mobile phone users, in a defined area, at the same time. The service is defined by the ETSI GSM committee, 3GPP, and is a part of the telecommunication standards.

  • The CellBroadcastReceiver app is a default system app that handles emergency and nonemergency alerts (such as amber and presidential alerts) and presents the information to end users based on carrier and regional regulations.

CellBroadcast message flow

The following figure shows the CellBroadcast message flow.

CellBroadcastReceiver message flow

Figure 1. CellBroadcastReceiver message flow

  1. The radio interface layer (RIL) notifies InBoundSMSHandler about a CDMA/GSM CellBroadcast SMS.

  2. The framework forwards the CellBroadcast SMS to the CBS module to parse and process the incoming message.

  3. After the message is processed, CellBroadcastService forwards the intent to the system default CellBroadcastReceiver app.

  4. The CellBroadcastReceiver app displays the message to the user.

Module format

The CellBroadcastService and the CellBroadcastReceiver app are included in a single APEX file (com.android.cellbroadcast), which is available for devices running Android 11 or higher. The module includes code in package/app/CellBroadcastReceiver and migrates existing framework classes to packages/modules/CellBroadcastService.

Module dependencies

The CellBroadcast module interacts with the framework using only stable @SystemApi (no @hide APIs) and depends on the following static libraries.

  • Androidx.legacy_legacy-support-v13
  • Androidx.recyclerview_recyclerview
  • Androidx.preference_preference
  • androidx.legacy_legacy-preference-v14
  • androidx.appcompat_appcompat

You can customize the configuration using runtime resource overlays (RROs).

Permission configuration

The CellBroadcast module is signed with a Google signature instead of a platform signature, which means the module loses access to signature permissions. Instead, Android 11 defines the new signature permission com.android.cellbroadcastservice.FULL_ACCESS_CELL_BROADCAST_HISTORY inside the CellBroadcast module; only packages in the module can obtain the permission as they're signed with the same key. This permission allows the CellBroadcastReceiver app to have full access to the database inside CellBroadcastService.

The platform grants the android.permission.READ_CELL_BROADCASTS runtime permission to the default system SMS app for accessing the history of emergency alerts.

Integrate the CellBroadcast module

This section describes how to integrate the CellBroadcast module.

Integrate with Settings

You can decide where to integrate CellBroadcast settings in the Settings app (end users access the CellBroadcast settings page from Settings > Apps & Notifications > Advanced > Emergency alert). To launch the CellBroadcastReceiver app from the Settings app, change the following setting configurations with the package name com.android.cellbroadcastreceiver.

<!-- Cell broacast receiver package name [DO NOT TRANSLATE] -->
<string name="cell_broadcast_receiver_package">
com.android.cellbroadcastreceiver</string>

Integrate with messaging apps

You can integrate an app link into messaging apps to open CellBroadcast message history. In the Android Messaging app, this has been integrated into Settings > Advanced > Emergency alert. To integrate a link in your own messaging app, define the path in the messaging app and configure the component name for the CellBroadcast module as com.android.cellbroadcastreceiver/com.android.cellbroadcastreceiver.CellBroadcastListActivity.

Integrate with SMS inbox

You can enable displaying CellBroadcast messages in the default messaging app by overriding the following configuration using a runtime resource overlay.

<item type="bool" name="enable_write_alerts_to_sms_inbox" />

Because granting permissions is outside the scope of the CellBroadcast module, you must grant the AppOpsManager.OP_WRITE_SMS permission to the CellBroadcast module to provide end-to-end support. For an AOSP reference implementation, refer to this SmsApplication.java patch.

Launch the CellBroadcastReceiver app

The CellBroadcastReceiver app has the following launch points.

  • The Settings app menu.

  • An app (including third-party apps) such as a messages app that links to CellBroadcast message history.

  • (Optional) A launch icon from the Android home screen added by the OEM. For details, see Adding a launch icon.

CellBroadcastReceiver app settings

The following screenshots show the CellBroadcastReceiver app settings menu.

CellBroadcastReceiver app settings menu

Figure 2. CellBroadcastReceiver app settings menu

Emergency alert history

Figure 3. Emergency alert history screen

Add launch icons

You can enable accessing CellBroadcast message history from the app launcher and through your own launch icons.

  • To enable accessing message history from the app launcher, override the following configuration using an RRO.

    <item type="bool" name="show_message_history_in_launcher" />

  • To override the AOSP default icon, override the following configuration using an RRO.

    <!-- Customize launcher icon for cellbroadcast history -->
<item type="mipmap" name="ic_launcher_cell_broadcast" />

Enable the CMAS secret code

To enable the CMAS secret code, *#*#CMAS#*#* (*#*#2627#*#* on the dial pad), a dialer app must listen for the special dialer code in the form of *#*#code#*#* and handle the code using the public method sendDialerSpecialCode.

Area info requirement: Channel 50

Channel 50 is a special channel for carriers to broadcast area-related information (except for MTN in South Africa). For this channel, broadcast messages don't result in a dialog or notification. Instead, broadcast messages appear in the Settings menu's SIM status, or in the status bar (for example, displaying a ZIP code).

The Android CellBroadcastService implementation provides support for the following APIs in the cell broadcast service for the Settings and SysUI apps to get the broadcast Channel 50 information. To implement this, do the following:

  • Register broadcast android.telephony.action.AREA_INFO_UPDATED and override the receiver package name config_area_info_receiver_packages through a RRO.

  • Bind to CellBroadcastService.CELL_BROADCAST_SERVICE_INTERFACE.

Because the Settings and SysUI apps are outside the scope of the CellBroadcast module, you must implement your changes in the SystemUI or the Settings app to provide end-to-end support. For a reference implementation, refer to the CellBroadcastService Settings app.

Customization

You can't directly modify the source code of the CellBroadcast module, but you can use runtime resource overlays (RROs) to enable (or disable) parameters (for example, you can customize the color of notifications and dimensions on dialogs). To override the default values of the parameters used in the CellBroadcast module, change the target package name to com.android.cellbroadcastreceiver. In addition:

If the implementation is missing UI string translation resources or if the translations don't meet your expectation, you can override translation resources using an RRO or work with the Google translation team to upstream string translations to the CellBroadcast module. If you override the translation resources, Google must expose those strings in overlayable.xml to allow overriding. If you need more configurations for UI customization, reach out to the CellBroadcast support group.

Migrate data

Android 11 includes a legacy CellBroadcast app, which is a mechanism to preserve and migrate app data (including user settings and emergency alert histories) for devices upgrading to the CellBroadcast module. Android implementations that use the CellBroadcast module should include the legacy CellBroadcast app in their build for data migration. If your implementation use a custom CellBroadcast solution, you should define a CellBroadcastContentProvider APK to preserve data (you can safely remove the legacy cell broadcast APK in a subsequent release).

On devices upgraded to use the CellBroadcast module, the module fetches data from either the AOSP LegacyCellBroadcastApp or the OEM-defined CellBroadcastContentProvider APK through the well-defined cellbroadcast-legacy authority.

Use an OEM-defined CellBroadcastContentProvider APK

When defining a CellBroadcastContentProvider APK, the APK must follow these specifications.

  • The APK is a headless APK that surfaces only the contents of its database and SharedPreferences through a ContentProvider object with the cellbroadcast-legacy authority, and isn't accessible to third-party apps.

  • The APK is developed and owned by the OEM, where the OEM can continue to host their hidden API schema.

To migrate SharedPreferences to the CellBroadcast module, the CellBroadcastContentProvider APK must support the ContentProvider.call) method with the following parameters:

  • Authority: @SystemAPI CellBroadcast.LEGACY_CONTENT_URI
  • Method: @SystemAPI CellBroadcast.CALL_METHOD_GET_PREFERENCE

  • Arg: @SystemAPI CellBroadcast.Preference

    This is a list of supported shared preference keys for the CellBroadcast module. The data comes from SharedPreferences for the ContentProvider.call method.

To migrate message history to the CellBroadcast module, the CellBroadcastContentProvider APK must support the ContentProvider.query method with following parameters:

  • Authority: @SystemAPI CellBroadcast.LEGACY_CONTENT_URI. Query columns list supported message properties for the CellBroadcast module. Takes in data (from your database) for the ContentProvider.query method.

For a reference implementation for CellBroadcastContentProvider, refer to LegacyCellBroadcastContentProvider.

Testing

The Android Compatibility Test Suite (CTS) verifies the functionality of app-dependent system APIs. You can also run CellBroadcast module unit tests/testappsp.

If the OEM has enabled the CMAS secret code for a device, that device can support debug mode with the following features.

  • Test alerts are grouped under Other Alerts with an on/off toggle.

  • History includes all messages that were received but not displayed, such as duplicate messages or messages in another language.

  • Messages display all available parameters, including serial number, message ID, and expiration date.

To enable the debug mode, dial *#*#CMAS#*#* on the dialer.

Contact

For further details or questions about the CellBroadcast module, contact the CellBroadcast support group.