為使用者提供網路區隔向上銷售

注意： 網路切片向上銷售功能僅適用於 Android 14 以上版本。

5G 網路切割可讓電信業者針對特定用途提供網路效能提升效果。本指南說明應用程式如何觸發網路壓縮向上銷售使用者體驗流程，並在使用者決定購買時要求付費連線。

圖 1. 向上銷售使用者體驗流程示例。

宣告付費功能意圖

為了讓應用程式遵循網路功能的要求，應用程式必須在應用程式資訊清單中宣告其意圖，以要求該項功能。否則網路要求會擲回 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

如果購買要求失敗，應用程式應要求並改用預設網路。如果無法完成付費配量要求，不會有自動備用行為。

注意： 除非您在應用程式資訊清單中宣告某項功能，否則針對特定功能的網路要求會失敗。