向用户提供广告网络切片追加销售

注意 ：网络切片追加销售功能仅在 Android 14 及更高版本中可用。

借助 5G 网络切片，运营商能够针对特定使用场景提供网络性能提升。本指南将介绍应用如何触发网络切片追加销售用户体验流程，并在用户决定购买付费连接时请求高级连接。

图 1. 追加销售用户体验流程示例。

声明高级功能 intent

为了让您的应用对网络功能的请求能够被遵循，应用必须在应用清单中声明请求该功能的意图。否则，网络请求会失败，并抛出 SecurityException。

为此，您的应用必须在 AndroidManifest.xml 文件中声明 PackageManager.PROPERTY_SELF_CERTIFIED_NETWORK_CAPABILITIES 属性，并包含相应的 XML 资源文件。

清单文件中的功能声明如下所示：

<property android:name="android.net.PROPERTY_SELF_CERTIFIED_NETWORK_CAPABILITIES"
          android:resource="@xml/network_capabilities" />

相应的 network_capabilities.xml 资源文件如下所示：

<network-capabilities-declaration> xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-network-capability android:name="NET_CAPABILITY_PRIORITIZE_LATENCY"/>
</network-capabilities-declaration>

触发广告网络切片追加销售流程

注意 ：Android 14 支持的唯一功能是 PREMIUM_CAPABILITY_PRIORITIZE_LATENCY。

此代码示例演示了如何触发追加销售流程并请求购买的高级功能。

Context mContext;
Network mNetwork;

public void purchasePremiumCapability() {
    TelephonyManager tm = mContext.getSystemService(TelephonyManager.class);
    int capability = TelephonyManager.PREMIUM_CAPABILITY_PRIORITIZE_LATENCY;
    if (tm.isPremiumCapabilityAvailableForPurchase(capability)) {
        tm.purchasePremiumCapability(capability, Runnable::run, new Consumer<Integer>() {
            @Override
            public void accept(Integer result) {
                Log.d("Purchase premium capability result: "
                        + TelephonyManager.convertPurchaseResultToString(result));
                switch (result) {
                    case /* success or already purchased */:
                        requestPremiumCapabilityNetwork();
                        break;
                    case /* temporary failure */:
                        // TODO: wait and retry
                        break;
                    case /* hard failure */:
                        // TODO: handle failure
                        break;
                    default:
                        Log.e("Unknown purchase result: " + result);
                }
            }
        });
    } else {
        Log.e("Premium capability is not available for purchase.");
    }
}

public void requestPremiumCapabilityNetwork() {
    ConnectvityManager cm = mContext.getSystemService(ConnectivityManager.class);
    NetworkRequest request = NetworkRequest.Builder()
            .addCapability(NetworkCapabilities.NET_CAPABILITY_PRIORITIZE_LATENCY)
            .build();
    cm.requestNetwork(request, new NetworkCallback() {
        @Override
        public void onAvailable(Network network) {
            Log.d("Application can now use the network with the premium capability.");
            mNetwork = network;
        }

        @Override
        public void onLost(Network network) {
            Log.d("Premium capability network is no longer available.");
            mNetwork = null;
            // TODO: clean up anything relying on the premium capability network
        }
    });
}

以下部分更详细地介绍了此过程中所涉及的步骤。

注意 ：此过程涉及的 API 需要 READ_BASIC_PHONE_STATE 权限。

第 1 步：验证高级功能是否可用

调用 isPremiumCapabilityAvailableForPurchase() API 方法以确定所选高级功能是否可用。如果可以通过追加销售通知工作流从运营商处购买该功能，则此方法会返回 true。

第 2 步：启动追加销售通知流程

确认高级功能可用后，您的应用应调用 purchasePremiumCapability() 以启动追加销售通知流程。如果用户尚未购买指定的功能且满足所有前提条件，则平台会向用户显示通知，告知用户其运营商可能提供性能提升选项。如果用户点按该通知，平台会打开运营商的 WebView，以便购买流程可以继续。

传递给 purchasePremiumCapability() 的 parameter 回调会返回购买请求的结果代码。

结果代码 PURCHASE_PREMIUM_CAPABILITY_RESULT_SUCCESS 和 PURCHASE_PREMIUM_CAPABILITY_RESULT_ALREADY_PURCHASED 表示成功结果，您的应用可以继续请求所选高级功能。

以下列表中的结果代码表示失败的购买请求。如需了解详情，请参阅 API 参考文档。

• PURCHASE_PREMIUM_CAPABILITY_RESULT_ALREADY_IN_PROGRESS
• PURCHASE_PREMIUM_CAPABILITY_RESULT_CARRIER_DISABLED
• PURCHASE_PREMIUM_CAPABILITY_RESULT_CARRIER_ERROR
• PURCHASE_PREMIUM_CAPABILITY_RESULT_ENTITLEMENT_CHECK_FAILED
• PURCHASE_PREMIUM_CAPABILITY_RESULT_FEATURE_NOT_SUPPORTED
• PURCHASE_PREMIUM_CAPABILITY_RESULT_NETWORK_NOT_AVAILABLE
• PURCHASE_PREMIUM_CAPABILITY_RESULT_NOT_DEFAULT_DATA_SUBSCRIPTION
• PURCHASE_PREMIUM_CAPABILITY_RESULT_NOT_FOREGROUND
• PURCHASE_PREMIUM_CAPABILITY_RESULT_PENDING_NETWORK_SETUP
• PURCHASE_PREMIUM_CAPABILITY_RESULT_REQUEST_FAILED
• PURCHASE_PREMIUM_CAPABILITY_RESULT_THROTTLED
• PURCHASE_PREMIUM_CAPABILITY_RESULT_TIMEOUT
• PURCHASE_PREMIUM_CAPABILITY_RESULT_USER_CANCELED

第 3 步：请求购买的高级连接

如果追加销售通知流程返回成功的代码（PURCHASE_PREMIUM_CAPABILITY_RESULT_SUCCESS 或 PURCHASE_PREMIUM_CAPABILITY_RESULT_ALREADY_PURCHASED），您的应用应使用 requestNetwork() 请求满足所请求功能的网络。请注意，当您构建 NetworkRequest 对象时，您添加的功能与您在前面步骤中传递给 TelephonyManager API 的功能不同。下表列出了 TelephonyManager 类中的常量映射到 NetworkCapabilities 中的相应常量。

TelephonyManager 常量	NetworkCapabilities 常量
PREMIUM_CAPABILITY_PRIORITIZE_LATENCY	NET_CAPABILITY_PRIORITIZE_LATENCY

如果购买请求失败，您的应用应改为请求并使用默认网络。如果无法实现高级切片请求，则没有自动回退行为。

注意 ：除非您在应用清单中声明请求特定功能的 intent，否则针对给定功能的网络请求会失败。