5G 網路切割可讓電信業者針對特定用途提供網路效能提升效果。本指南說明應用程式如何觸發網路壓縮向上銷售使用者體驗流程,並在使用者決定購買時要求付費連線。
![使用者體驗流程會顯示通知,要求使用者開啟電信業者網頁工作表,以便完成購買交易。](https://developer.android.google.cn/static/images/develop/connectivity/5g/upsell-ux-flow.png?authuser=3&hl=zh-tw)
宣告付費功能意圖
為了讓應用程式遵循網路功能的要求,應用程式必須在應用程式資訊清單中宣告其意圖,以要求該項功能。否則網路要求會擲回 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>
觸發網路區隔向上銷售流程
這個程式碼範例示範如何觸發向上銷售流程及要求已購買的付費功能。
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
}
});
}
以下各節將詳細說明這項程序的步驟。
步驟 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 |
如果購買要求失敗,應用程式應要求並改用預設網路。如果無法完成付費配量要求,不會有自動備用行為。