Customize device behavior for out-of-balance users

Android devices with no data balance allow network traffic through, requiring carriers and telcos to implement mitigation protocols. Android implements a generic solution that allows carriers and telcos to indicate when a device has run out of balance.

The Android platform provides a default carrier app with a default behavior for traffic mitigation based on captive-portal detection signal. It also provides carriers and OEMs the opportunity to customize the behaviour with low cost and great flexibility.

Examples and source

The default carrier app is located atplatform/frameworks/base/packages/CarrierDefaultApp/.

Implementation

The default carrier app is configured to provide a better experience for unconfigured carriers out of the box. Carriers can use this default behavior. They can also override the default behavior by adding signal-action mappings to the carrier config XML file. They can decide not to use the default app and instead use UICC privileges with their own standalone carrier app.

Implementation introduction

Signals

Android framework supports configuring actions to the following parameterized signals:

  • TelephonyIntents.ACTION_CARRIER_SIGNAL_REDIRECTED
  • TelephonyIntents.ACTION_CARRIER_SIGNAL_REQUEST_NETWORK_FAILED

These signals are located in frameworks/base/telephony/java/com/android/internal/telephony/TelephonyIntents.java.

Supported actions

The default carrier app defines a set of supported actions that can be mapped to supported signals. These are defined in CarrierActionUtils.java:

    public static final int CARRIER_ACTION_ENABLE_METERED_APNS               = 0;
    public static final int CARRIER_ACTION_DISABLE_METERED_APNS              = 1;
    public static final int CARRIER_ACTION_DISABLE_RADIO                     = 2;
    public static final int CARRIER_ACTION_ENABLE_RADIO                      = 3;
    public static final int CARRIER_ACTION_SHOW_PORTAL_NOTIFICATION          = 4;
    public static final int CARRIER_ACTION_SHOW_NO_DATA_SERVICE_NOTIFICATION = 5;
    public static final int CARRIER_ACTION_CANCEL_ALL_NOTIFICATIONS          = 6;

Note: If a carrier implements their own standalone app, then they can implement support for signals other than those mentioned in this section. They can define and configure their own actions as well.

Default signal-action mappings

Configure default actions by following this process:

  1. Define a key for supported signals.

    The default signal to action mappings are defined in CarrierConfigManager.java. Each of the supported signals has a key:

    public static final String KEY_CARRIER_DEFAULT_ACTIONS_ON_REDIRECTION_STRING_ARRAY = "carrier_default_actions_on_redirection_string_array";
public static final String KEY_CARRIER_DEFAULT_ACTIONS_ON_DCFAILURE_STRING_ARRAY =
"carrier_default_actions_on_dcfailure_string_array";
  2. Associate default actions to signal keys.

    The default action ids are associated to the signal keys:

    sDefaults.putStringArray(KEY_CARRIER_DEFAULT_ACTIONS_ON_REDIRECTION_STRING_ARRAY,                new String[]{
                "1, 4"
                //1: CARRIER_ACTION_SHOW_PORTAL_NOTIFICATION
                // 4: CARRIER_ACTION_DISABLE_METERED_APNS
         });

    The telephony framework maps these actions to the corresponding signals.

Override default actions

You can define custom actions for supported signals in the carrier config XML file by associating action IDs to the signal keys (defined in CarrierConfigManager.java). For example, the following mapping disables metered APNs and shows a portal notification on redirection:

<string-array name="carrier_default_actions_on_redirection_string_array" num="2">
            <item value="1" />
            <item value="4" />
</string-array>

The telephony framework loads these configurations and overrides default actions.

Validation

There are no CTS, CTS Verifier, or GTS tests for this feature.

Use these manual validation tests to validate the feature:

  1. Validate telco's device out-of-balance signal notification.
  2. Verify traffic redirect throttling during out-of-balance state and Wi-Fi off.
  3. Verify network traffic is turned down and notification UI appears during out of balance state.
  4. Validate voice call/VoLTE function during out-of-balance state.
  5. Verify video calling is blocked in out-of-balance state.
  6. With Wi-Fi on, verify user can continue web browsing, and the browsing traffic does not turn on network traffic while in the out-of-balance state.
  7. Validate Wi-Fi, WFC, and Bluetooth functions during out-of-balance state.
  8. Turn Wi-Fi off. Verify the out-of-balance notification UI, and that ordinary browsing traffic is not redirected to the telco registration web site. Verify clicking the link in the notification UI brings the browser to the telco registration web site.
  9. Verify that toggling airplane mode does not reset the traffic throttling state.
  10. Verify that swapping an in-service SIM resets the network traffic state.
  11. Verify that re-inserting the out-of-balance SIM restarts traffic redirection and obtains network traffic throttling again.
  12. Verify that rebooting the phone reactivates redirection and brings back the traffic throttle and notification UI.
  13. Tap on the "captiveportal" notification. Verify a restricted network connection is established to allow the user to add credits.
  14. Verify that SIM balance refill or reactivation causes cellular network traffic to recover, and the Telco link and no balance notification to go away.
  15. Sanity test after data service recovery.

The default app provides a few examples of unit tests and a script to run them (see tests/runtest.sh). When you implement a customized version or behavior, you should mirror those customizations into dedicated unit tests.