自 2025 年 3 月 27 日起,我们建议您使用 android-latest-release
而非 aosp-main
构建 AOSP 并为其做出贡献。如需了解详情,请参阅 AOSP 的变更。
为流量已用完的用户自定义设备行为
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
流量已用完的 Android 设备允许网络流量通过,但需要运营商和电信服务商来实现缓解协议。Android 实现了一个通用解决方案,使运营商和电信服务商能够在设备用完流量时发出提示。
Android 平台提供了一个默认的运营商应用,该应用会基于强制门户检测信号采取默认行为来实现流量缓解。此外,它还使运营商和原始设备制造商 (OEM) 能够以较低的成本和极大的灵活性对该行为进行自定义。
示例和源代码
默认的运营商应用位于以下位置:platform/frameworks/base/packages/CarrierDefaultApp/.
实现
默认的运营商应用已经过预先配置,以便直接为未配置的运营商提供更好的体验。运营商可以使用该默认行为,也可以通过向运营商配置 XML 文件添加“信号-操作”映射来覆盖该默认行为。他们可以不使用默认应用,而是使用 UICC 权限和自己的独立运营商应用。
实现简介
信号
Android 框架支持对以下参数化信号进行配置操作:
TelephonyIntents.ACTION_CARRIER_SIGNAL_REDIRECTED
TelephonyIntents.ACTION_CARRIER_SIGNAL_REQUEST_NETWORK_FAILED
这些信号位于以下位置:frameworks/base/telephony/java/com/android/internal/telephony/TelephonyIntents.java
。
支持的操作
默认运营商应用定义了一组支持的操作,这些操作可映射到支持的信号。这些操作是在 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;
注意:如果运营商实现了自己的独立应用,他们也可以为其他信号实现支持,不仅限于本部分中所介绍的。他们还可以定义和配置自己的操作。
默认“信号-操作”映射
可以按照以下流程配置默认操作:
- 为支持的信号定义键。
CarrierConfigManager.java
中定义了默认的“信号-操作”映射。每个支持的信号都有一个键:
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";
- 将默认操作与信号键相关联。
默认操作 ID 会与信号键相关联:
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
});
电话框架会将这些操作映射到相应的信号。
覆盖默认操作
通过将操作 ID 与信号键(在 CarrierConfigManager.java
中定义)相关联,您可以在运营商配置 XML 文件中为支持的信号指定操作。例如,以下映射会停用按流量计费的 APN,并会在重定向时显示门户网站通知:
<string-array name="carrier_default_actions_on_redirection_string_array" num="2">
<item value="1" />
<item value="4" />
</string-array>
电话框架会加载这些配置并覆盖默认操作。
验证
没有针对该功能的 CTS、CTS 验证程序或 GTS 测试。
您可以按照以下手动验证测试来验证该功能:
- 验证电信服务商在设备流量用完时的信号通知。
- 验证在流量用完状态和 Wi-Fi 关闭期间的流量重定向限制。
- 验证在流量用完状态期间网络流量是否会被关闭,以及系统是否会显示通知界面。
- 验证在流量用完状态期间的语音通话/VoLTE 功能。
- 验证在流量用完状态下视频通话是否会被屏蔽。
- 在启用 Wi-Fi 的情况下,验证在流量用完状态下用户是否可以继续浏览网页,以及浏览流量是否不会开启网络流量。
- 验证在流量用完状态下的 WLAN、WFC 和蓝牙功能。
- 关闭 Wi-Fi。验证流量用完通知界面,并验证普通浏览流量是否不会被重定向到电信服务商的注册网站。验证点击通知界面中的链接后浏览器是否会转到电信服务商的注册网站。
- 验证开关飞行模式是否不会重置流量限制状态。
- 验证换用可正常使用的 SIM 卡是否会重置网络流量状态。
- 验证重新插入流量用完的 SIM 卡是否会重新启动流量重定向并再次开启网络流量限制。
- 验证重新启动手机是否会重新启用重定向并恢复流量限制和通知界面。
- 点按“captiveportal”通知。验证是否建立了受限网络连接以允许用户充值。
- 验证 SIM 卡重新充值或重新启用是否会使移动网络流量恢复,以及电信服务商链接和流量用完通知是否会消失。
- 移动网络服务恢复后的健康测试。
默认应用提供了一些单元测试示例和一个用于运行它们的脚本(请参阅 tests/runtest.sh
)。实现自定义版本或行为时,您应将这些自定义镜像到专用的单元测试。
本页面上的内容和代码示例受内容许可部分所述许可的限制。Java 和 OpenJDK 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-03-26。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["没有我需要的信息","missingTheInformationINeed","thumb-down"],["太复杂/步骤太多","tooComplicatedTooManySteps","thumb-down"],["内容需要更新","outOfDate","thumb-down"],["翻译问题","translationIssue","thumb-down"],["示例/代码问题","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC):2025-03-26。"],[],[],null,["# Customize device behavior for out-of-balance users\n\nAndroid devices with no data balance allow network traffic through, requiring\ncarriers and telcos to implement mitigation protocols. Android implements a\ngeneric solution that allows carriers and telcos to indicate when a device has\nrun out of balance.\n\nThe Android platform provides a default carrier app with a default behavior for\ntraffic mitigation based on captive-portal detection signal. It also provides\ncarriers and OEMs the opportunity to customize the behaviour with low cost and\ngreat flexibility.\n\nExamples and source\n-------------------\n\nThe default carrier app is located at[platform/frameworks/base/packages/CarrierDefaultApp/](https://android.googlesource.com/platform/frameworks/base/+/refs/heads/android16-release/packages/CarrierDefaultApp/)`.`\n\nImplementation\n--------------\n\nThe default carrier app is configured to provide a better experience for\nunconfigured carriers out of the box. Carriers can use this default behavior.\nThey can also override the default behavior by adding signal-action mappings to\nthe carrier config XML file. They can decide not to use the default app and\ninstead use UICC privileges with their own standalone carrier app.\n\n### Implementation introduction\n\n#### Signals\n\nAndroid framework supports configuring actions to the following parameterized\nsignals:\n\n- `TelephonyIntents.ACTION_CARRIER_SIGNAL_REDIRECTED`\n- `TelephonyIntents.ACTION_CARRIER_SIGNAL_REQUEST_NETWORK_FAILED`\n\nThese signals are located in\n`frameworks/base/telephony/java/com/android/internal/telephony/TelephonyIntents.java`.\n\n#### Supported actions\n\nThe default carrier app defines a set of supported actions that can be mapped to\nsupported signals. These are defined in `CarrierActionUtils.java`: \n\n```scdoc\n public static final int CARRIER_ACTION_ENABLE_METERED_APNS = 0;\n public static final int CARRIER_ACTION_DISABLE_METERED_APNS = 1;\n public static final int CARRIER_ACTION_DISABLE_RADIO = 2;\n public static final int CARRIER_ACTION_ENABLE_RADIO = 3;\n public static final int CARRIER_ACTION_SHOW_PORTAL_NOTIFICATION = 4;\n public static final int CARRIER_ACTION_SHOW_NO_DATA_SERVICE_NOTIFICATION = 5;\n public static final int CARRIER_ACTION_CANCEL_ALL_NOTIFICATIONS = 6;\n```\n\n**Note:** If a carrier implements their own standalone app, then\nthey can implement support for signals other than those mentioned in this\nsection. They can define and configure their own actions as well.\n\n### Default signal-action mappings\n\nConfigure default actions by following this process:\n\n1. Define a key for supported signals. The default signal to action mappings are defined in `CarrierConfigManager.java`.\n Each of the supported signals has a key:\n\n ```scdoc\n public static final String KEY_CARRIER_DEFAULT_ACTIONS_ON_REDIRECTION_STRING_ARRAY = \"carrier_default_actions_on_redirection_string_array\";\n public static final String KEY_CARRIER_DEFAULT_ACTIONS_ON_DCFAILURE_STRING_ARRAY =\n \"carrier_default_actions_on_dcfailure_string_array\";\n ```\n2. Associate default actions to signal keys. The default action ids are associated to the signal keys:\n\n ```\n sDefaults.putStringArray(KEY_CARRIER_DEFAULT_ACTIONS_ON_REDIRECTION_STRING_ARRAY, new String[]{\n \"1, 4\"\n //1: CARRIER_ACTION_SHOW_PORTAL_NOTIFICATION\n // 4: CARRIER_ACTION_DISABLE_METERED_APNS\n });\n ```\n\n The telephony framework maps these actions to the corresponding signals.\n\n### Override default actions\n\nYou can define custom actions for supported signals in the carrier config XML\nfile by associating action IDs to the signal keys (defined in\n`CarrierConfigManager.java`). For example, the following mapping\ndisables metered APNs and shows a portal notification on redirection: \n\n```scdoc\n\u003cstring-array name=\"carrier_default_actions_on_redirection_string_array\" num=\"2\"\u003e\n \u003citem value=\"1\" /\u003e\n \u003citem value=\"4\" /\u003e\n\u003c/string-array\u003e\n```\n\nThe telephony framework loads these configurations and overrides default\nactions.\n\nValidation\n----------\n\nThere are no CTS, CTS Verifier, or GTS tests for this feature.\n\nUse these manual validation tests to validate the feature:\n\n1. Validate telco's device out-of-balance signal notification.\n2. Verify traffic redirect throttling during out-of-balance state and Wi-Fi off.\n3. Verify network traffic is turned down and notification UI appears during out of balance state.\n4. Validate voice call/VoLTE function during out-of-balance state.\n5. Verify video calling is blocked in out-of-balance state.\n6. 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.\n7. Validate Wi-Fi, WFC, and Bluetooth functions during out-of-balance state.\n8. 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.\n9. Verify that toggling airplane mode does not reset the traffic throttling state.\n10. Verify that swapping an in-service SIM resets the network traffic state.\n11. Verify that re-inserting the out-of-balance SIM restarts traffic redirection and obtains network traffic throttling again.\n12. Verify that rebooting the phone reactivates redirection and brings back the traffic throttle and notification UI.\n13. Tap on the \"captiveportal\" notification. Verify a restricted network connection is established to allow the user to add credits.\n14. Verify that SIM balance refill or reactivation causes cellular network traffic to recover, and the Telco link and no balance notification to go away.\n15. Sanity test after data service recovery.\n\nThe default app provides a few examples of unit tests and a script to run them\n(see `tests/runtest.sh`). When you implement a customized version or\nbehavior, you should mirror those customizations into dedicated unit tests."]]