動機
如總覽中所述，視運算子想要支援的用途而定，DPA 必須實作 Google Mobile Data Plan Shared API 與 Data Plan Agent API 的組合。本文件說明 Google 將用於識別使用者的行動數據方案、Data Plan Agent API，以及購買方案的相關資訊。
驗證
DPA 必須先驗證 GTAF，才能呼叫 GTAF。在運算子新手上路流程中，我們會檢查 DPA SSL 憑證的有效性。目前「必須」使用 OAuth2 進行共同驗證。如要進一步瞭解 GTAF 使用 DPA 進行驗證的方式，請參閱「企劃書代理程式驗證」一文。
國際化
向 DPA 提出的 GTAF 要求包含 Accept-Language 標頭，指出人類可讀字串 (例如方案說明) 應使用的語言。此外，DPA 回應 (PlanStatus、PlanOffers) 含有必要的 languageCode 欄位，其值是 BCP-47 語言代碼 (例如「en-US」)。
如果 DPA 不支援使用者要求的語言，則可以使用預設語言，並使用 languageCode 欄位表示選擇語言。
API 說明
GTAF 使用使用者金鑰來識別運算子和訂閱者的 DPA。當 GTAF 代表可存取 MSISDN 的應用程式查詢 DPA 時，GTAF MAY 可能會使用 MSISDN。大致上，提議的 Data Plan Agent API 包含下列元件：
- 查詢使用者資料方案狀態的機制。
- 向使用者查詢數據方案優惠的 DPA 機制。
- 變更使用者數據方案的機制 (例如購買新方案)。
- 分享 CPID 的機制，可用來傳送通知給使用者。
- 告知使用者是否要訂閱我們的服務機制。
本文件的其餘部分會逐一介紹這些 API 元件。除非另有說明，否則所有通訊都「必須」透過 HTTPS (使用有效的 DPA SSL 憑證) 進行。視實際支援的功能而定，運算子可能會選擇實作所有或部分 API 元件。
GTAF-DPA 互動
圖 4. 用於要求及接收使用者資料方案資訊的呼叫流程。
圖 4 說明與查詢使用者數據狀態和其他數據方案資訊的用戶端相關的呼叫流程。這個呼叫流程由用戶端在 UE 上觸發的 API 呼叫共用。
- 用戶端會呼叫私人 Google API，要求數據方案狀態和/或其他資訊。用戶端會在向 GTAF 發出的要求中納入使用者金鑰。
- GTAF 會使用使用者金鑰和用戶端 ID 查詢運算子的 DPA。支援的用戶端 ID 為 mobiledataplan 和 youtube。當 DPA 收到包含其中一個用戶端 ID 的呼叫時，「必須」回應用戶端可使用的方案資訊。
- GTAF 將要求的資訊傳回用戶端，而 GTAF 會擷取方案資訊，直到 DPA 指定的到期時間為止。
圖 4 中的步驟 1 和 3 是私人 Google API，因此不會詳細說明。步驟 2 是下文所述的公用 API。從 GTAF 提供這些 API 呼叫時，DPA 「必須」遵循 Cache-Control: no-cache HTTP 標頭。
查詢數據方案狀態
GTAF 會發出下列 HTTP 要求來取得方案狀態：
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
使用 CLIENT_ID 來識別 GTAF 代表與 DPA 聯絡的用戶端。視 Google 用戶端和業者之間的協議而定，DPA 可以自訂 GTAF 的回應。如果成功，DPA 「必須」傳回 HTTP 200 OK，且回應主體代表 PlanStatus。請參閱錯誤案例，瞭解發生錯誤時可預期的回應。
{
"plans": [{
"planName": "ACME1",
"planId": "1",
"planCategory": "PREPAID",
"expirationTime": "2017-01-29T01:00:03.14159Z", // req.
"planModules": [{
"moduleName": "Giga Plan", // req.
"trafficCategories": ["GENERIC"],
"expirationTime": "2017-01-29T01:00:03.14159Z", // req.
"overUsagePolicy": "BLOCKED",
"maxRateKbps": "1500",
"description": "1GB for a month", // req.
"coarseBalanceLevel": "HIGH_QUOTA"
}]
}],
"languageCode": "en-US", // req.
"expireTime": "2018-06-14T08:41:27-07:00", // req.
"updateTime": "2018-06-07T07:41:22-07:00", // req.
"title": "Prepaid Plan"
"planInfoPerClient": {
"youtube": {
"rateLimitedStreaming": {
"maxMediaRateKbps": 256
}
}
}
}
如果是後付方案，expirationTime 必須是方案的重複日期 (也就是在資料重新整理/重新載入時)。
每個方案模組都包含多個企劃書模組流量類別 (PMTCs) 用於建立在多個應用程式之間共用方案模組的案例，例如遊戲和音樂的大小上限為 500 MB)。以下 PMTC 預先定義：GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING.
查詢計畫優惠
GTAF 會發出下列 HTTP 要求，取得業者提供的方案優惠：
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
使用 CLIENT_ID 來識別 GTAF 代表與 DPA 聯絡的用戶端。視 Google 用戶端和業者之間的協議而定，DPA 可以自訂 GTAF 的回應。選用結構定義參數可提供發出要求的應用程式結構定義。通常是應用程式透過 GTAF 傳遞給運算子的字串。
如果成功，DPA 「必須」傳回 HTTP 200 OK，且回應主體代表 PlanOffer。如果發生錯誤，請參閱錯誤案例。
{
"offers": [
{
"planName": "ACME Red", // req.
"planId": "turbulent1", // req.
"planDescription": "Unlimited Videos for 30 days.", // req.
"promoMessage": "Binge watch videos.",
"languageCode": "en_US", // req.
"overusagePolicy": "BLOCKED",
"cost": { // req.
"currencyCode": "INR",
"units": "300",
"nanos": 0
},
"duration": "2592000s",
"offerContext": "YouTube",
"trafficCategories": ["VIDEO"],
"quotaBytes": "9223372036850",
"filterTags": ["repurchase", "all"]
}
],
"filters" : [
{
"tag": "repurchase",
"displayText": "REPURCHASE PLANS"
},
{
"tag": "all",
"displayText": "ALL PLANS"
}
]
"expireTime": "2019-03-04T00:06:07Z" // req.
}
offers 陣列中資料方案的順序可決定使用者能看見資料方案的順序。此外，如果應用程式因 UI 或其他限製而僅能顯示 x 方案，且回應包含 y > x 方案，則「只能」顯示第一個 x 方案。如果查詢優惠的應用程式是 Google Play 服務隨附的行動數據方案模組，GTAF 最多僅能分享 50 個方案。這是為了確保 Google Play 服務為使用者提供優質的體驗。
向上銷售優惠含有 filterTags 做為選用參數，該參數是附加至各個方案的標記陣列。這些 filterTag 應與在篩選條件中的物件相符標記。Filter 是第一層物件，包含 tutu<tag、displaytextquoquot;">。Filter 是合併的篩選器清單，會在使用者介面中顯示。使用者只要按一下 DisplayText 即可進行篩選。與 displayText 相對應的標記會用來篩選優惠。
請注意，運算子「必須」提供機制，為使用者的任何優惠購買購買要求。您可以在回應中使用 formOfPayment 選項，向使用者收取任何購買交易的機制。
資料購買
購買方案 API 定義 GTAF 如何透過 DPA 購買方案。GTAF 會啟動交易，向 DPA 購買一項數據方案。要求應內含專屬交易 ID (transactionId)，用於追蹤要求並避免重複執行交易。DPA 「必須」傳回成功/失敗回應。
交易要求
收到客戶提出的要求後，GTAF 會向 DPA 發出 POST 要求。 要求的網址如下：
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
其中 userKey 為 CPID 或 MSISDN。要求主體是 TransactionRequest 的執行個體，其中包含下列欄位：
{
"planId": string, // Id of plan to be purchased. Copied from
// offers.planId field returned from a
// Upsell Offer request,
// if available. (req.).
"transactionId": string, // Unique request identifier (req.)
"offerContext": string, // Copied from from the
// offers.offerContext, if available.
// (opt.)
"callbackUrl": string // URL that the DPA can call back with response once
// it has handled the request.
}
交易回應
DPA SHALL 只會為成功執行的交易或排入佇列的交易產生 200-OK 回應。如要在發生錯誤時取得預期的回應，請參閱錯誤案例。如果是已排入佇列的交易，DPA 只會填入交易狀態，並將回應中的其他欄位留空。排入佇列的交易後，DPA 「必須」傳回 GTAF 回應。回應主體是 TransactionResponse 的例項，其中包含下列詳細資料：
{
"transactionStatus": "SUCCESS",
"purchase": {
"planId": string, // copied from request. (req.)
"transactionId": string, // copied from request. (req.)
"transactionMessage": string, // status message. (opt.)
"confirmationCode": string, // DPA-generated confirmation code
// for successful transaction. (opt.)
"planActivationTime" : string, // Time when plan will be activated,
// in timestamp format. (opt.)
},
// walletInfo is populated with the balance left in the user's account.
"walletBalance": {
"currencyCode": string, // 3-letter currency code defined in ISO 4217.
"units": string, // Whole units of the currency amount.
"nanos": number // Number of nano units of the amount.
}
}
如果缺少 planActivationTime，GTAF SHALL 會假設方案已啟用。
註冊 CPID
當支援通知的用戶端從 CPID 端點取得新的 CPID 時，如果用戶端條款允許 GTAF，系統就會向 GTAF 註冊 CPID。如果用戶端成功向 GTAF 註冊 CPID，GTAF 會使用下列 API 呼叫，向 DPA 註冊 CPID：
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
其中 userKey 是 CPID，唯一支援的 CLIENT_ID 是 mobiledataplan。要求的主體是 RegisterCpidRequest 的執行個體，且包含無法使用 CPID 傳送通知的時間點，如下所示：
{"staleTime": "2017-01-29T01:00:03.14159Z"}
這個 API 僅適用於想要在 Google Play 服務中支援行動數據方案模組的運算子。為了可靠地向使用者傳送通知，DPA 可以儲存每位使用者的最新註冊 CPID。如要瞭解如何使用已註冊的 CPID 傳送通知，請參閱「選擇 CPID」。
如果 DPA 成功將 CPID 與使用者建立關聯並持續儲存，DPA 就會產生 200-OK 回應。如果發生錯誤，請參閱錯誤案例。
同意聲明
GTAF 可以提出下列要求，將使用者的同意聲明偏好設定傳遞至電信業者。
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
其中 userKey 為 CPID 或 MSISDN。要求的主體是 SetConsentStatusRequest 的執行個體。如果成功，回應主體應留空。
每次從 GTAF 到 DPA 時，都會遵循發出呼叫的 Google 用戶端服務條款。視 DPA 支援的應用程式而定，電信業者必須判斷 DPA 是否實作這個 API。如果 DPA 選擇導入同意聲明 API，DPA 「必須」為每位使用者儲存最新的同意聲明狀態。如要瞭解如何使用同意聲明狀態資訊，請參閱選擇 CPID。
如果成功，DPA 「必須」傳回空白回應內容 HTTP 200 OK。若發生錯誤，請參閱錯誤案例以獲得預期回應。