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.
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.
Figure 1. CellBroadcastReceiver message flow
The radio interface layer (RIL) notifies
InBoundSMSHandlerabout a CDMA/GSM CellBroadcast SMS.
The framework forwards the CellBroadcast SMS to the CBS module to parse and process the incoming message.
After the message is processed, CellBroadcastService forwards the intent to the system default CellBroadcastReceiver app.
The CellBroadcastReceiver app displays the message to the user.
The CellBroadcastService and the CellBroadcastReceiver app are included in a
single APEX file
com.google.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
The CellBroadcast module interacts with the framework using only stable
@hide APIs) and depends on the following static libraries.
You can customize the configuration using runtime resource overlays (RROs).
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
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
The platform grants the
permission to the default system SMS app for accessing the history of emergency
Integrating the CellBroadcast module
This section describes how to integrate the CellBroadcast module.
Integrating 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
<!-- Cell broacast receiver package name [DO NOT TRANSLATE] --> <string name="cell_broadcast_receiver_package"> com.google.android.cellbroadcastreceiver</string>
Integrating 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
Integrating with SMS inbox
You can enable displaying CellBroadcast messages in the default messaging app by overridding 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
Launching 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.
Figure 2. CellBroadcastReceiver app settings menu
Figure 3. Emergency alert history screen
Adding 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" />
Enabling 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
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 popup 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:
android.telephony.action.AREA_INFO_UPDATEDand override the receiver package name
config_area_info_receiver_packagesthrough a RRO.
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.
You can't directly modify the source code of the CellBroadcast module, but you
can use runtime resource overlays
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.google.android.cellbroadcastreceiver. In addition:
For a list of overlayable configurations, refer to
For an example implementation, refer to
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.
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
Using 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
ContentProviderobject with the
cellbroadcast-legacyauthority, 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.
SharedPreferences to the CellBroadcast module, the
CellBroadcastContentProvider APK must support the
method with the following parameters:
This is a list of supported shared preference keys for the CellBroadcast module. The data comes from
To migrate message history to the CellBroadcast module, the
CellBroadcastContentProvider APK must support the
method with following parameters:
@SystemAPI CellBroadcast.LEGACY_CONTENT_URI. Query columns list supported message properties for the CellBroadcast module. Takes in data (from your database) for the
For a reference implementation for
CellBroadcastContentProvider, refer to
The Android Compatibility Test Suite (CTS) verifies the functionality of
app-dependent system APIs. You can also run CellBroadcast module
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.
For further details or questions about the CellBroadcast module, contact the CellBroadcast support group.