開始使用行動數據方案分享功能

術語

  • GTAF：Google 流量應用程式功能。實作 Data Plan Sharing API 的 Google 服務，可代表 Google 應用程式與 DPA 互動。Google 應用程式可以查詢 GTAF，取得使用者的資料方案資訊。或者，如果 Google 應用程式向 GTAF 註冊，GTAF 就能傳送使用者資料方案的更新資訊。
  • MSISDN：行動台國際用戶目錄號碼，是行動網路中用來專屬識別訂閱項目的號碼。一般稱為電話號碼。
  • CPID 端點：行動網路業者實作的服務，可產生電信業者方案 ID (CPID)，用於查詢使用者的數據方案資訊。應用程式可透過 CPID 查詢使用者資料方案的詳細資料，不必存取使用者的 MSISDN。我們將在下文說明產生 CPID 的程序。
  • 使用者金鑰：使用者金鑰是可用於識別使用者資料方案的字串。如果應用程式可存取 MSISDN，則可以是 CPID 或 MSISDN。
  • DPA：資料方案代理程式，由行動網路業者實作的服務，可與 GTAF 分享使用者資料方案資訊。DPA 可以透過 Google Mobile Data Plan Sharing API 傳送資料，並實作 Data Plan Agent API，與 GTAF 分享資訊。DPA 也可以視需要做為 CPID 端點。
  • UE：使用者設備，即使用者使用的裝置。

條件用語

本指南中的「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」和「OPTIONAL」等關鍵字，應按照 RFC 2119 的說明解讀。

行動數據方案分享

整體來說，行動數據方案分享功能包含三個部分：

  1. 建立及更新電信業者方案 ID (CPID) 的機制，可用於使用者金鑰。如果應用程式有權存取 MSISDN，即可將其做為使用者金鑰。
  2. Google Mobile Data Plan Sharing API，可讓 DPA 將使用者的資費方案資訊傳送給 Google。舉例來說，如果 DPA 想要通知使用者優惠，可以通知 GTAF，後者會通知使用者。
  3. DPA 實作的資料方案代理程式 API，可讓 GTAF 查詢使用者的資料方案資訊。舉例來說，如果應用程式想向使用者顯示目前的資料方案餘額，可以查詢 GTAF，而 GTAF 會查詢 DPA。

本頁面其餘部分會介紹資料方案術語，並詳細說明如何建立 CPID。Google Mobile Data Plan Sharing API 和 Data Plan Agent API 規格如下。

數據方案術語

API 中定義的 planStatus 結構定義必須能夠代表電信業者提供給使用者的資料方案。API 支援定義資料方案，針對特定網址組合的所有流量，以不同費率向使用者收費 (例如，針對 *.acmefake.com 的所有流量，以不同費率收費)。此外，這項 API 也支援資料方案，針對應用程式中的特定類型動作提供不同費率。我們將這類方案稱為「子應用程式」資料方案。舉例來說，子應用程式資料方案可提供免費 (即零費率) 影片瀏覽服務，但使用者在應用程式中觀看影片時，系統會從訂閱者的資料餘額扣除資料用量。影片應用程式隨後查詢資料方案資訊時，必須能夠瞭解這項資訊。

以下介紹一些與資料方案相關的術語。圖 1 顯示的資料方案範例，代表我們想擷取的概念。

資料方案：訂閱者購買的頂層行動服務套裝組合。可以是簡單的「10 GB 行動數據，效期 30 天」，也可以定義為元件集合，也就是模組。資料方案包含：

  • 資料方案名稱，例如「ACME Red」。
  • 資料方案 ID，用於參照方案，例如在購買期間。
  • 到期時間：數據方案到期時間。
  • 方案類別：方案是預付方案還是後付方案。

方案模組：資料方案的元件。具體來說，計畫模組具有：

  • 模組名稱，例如「免費影片之夜」。
  • 最大速率：這個模組提供給使用者的頻寬。
  • 彈性時間範圍：可為使用者提供折扣的時間範圍。

  • 計畫模組流量類別 (PMTC)：模組套用的資料流量說明。PMTC 可以是廣泛的「所有網際網路流量」，也可以是特定的一或多個應用程式、網站，甚至是單一應用程式內的使用者歷程所產生/消耗的流量。後者例如「無限音樂」、「100 MB 影片資料包 (VDP)」、「無限遊戲資料」和「無限影片瀏覽」。為方便定義 PMTC，我們定義了下列 PMTC：GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE1, MUSIC, GAMING, SOCIAL, MESSAGING 和 PMTC_UNSPECIFIED.

  • 資料用量或時間限制：啟用後，當資料用量或時間限制 (如果是以時間為準的方案，例如 600 分鐘的網路存取時間。在下方的圖 1 中，訂閱者可以購買「ACME Blue」方案模組，取得 1 GB 的一般使用者流量，必須在啟用後一週內使用完畢，否則就會過期。

Data Plan API 範例方案

圖 1. 數據方案範例。

建立 CPID

GTAF 會使用使用者金鑰與 DPA 通訊，藉此識別訂閱者。有權存取使用者 MSISDN 的應用程式可以將其做為 user_key。另一方面，如果應用程式無法存取 MSISDN，則必須建立電信方案 ID (CPID)，而不需探索使用者的 MSISDN。下文將說明建立 CPID 的機制。

CPID Call Flow

圖 2：建立 CPID 的呼叫流程。

  1. UE 中的 Google 應用程式會使用 Google 內部 API，從 GTAF 擷取 CPID 端點的網址。系統會使用用戶端的公開 IP 位址和有效 SIM 卡的 MCC+MNC 識別電信業者。如果是 MVNO，Google 會使用 SPN 和 GID1 判斷 MVNO
  2. 用戶端會向 CPID 端點發出 HTTP GET 要求。營運商「可能」支援透過 HTTPS 傳送要求。
  3. 電信業者「可能」會使用深層封包檢查功能識別要求，並將使用者的電話號碼以 HTTP 標頭的形式插入要求。
  4. CPID 端點會接收要求、建構 CPID，並將 CPID 傳回 UE，同時提供存留時間 (TTL)，指出 UE 可使用這個 CPID 的時間長度。

如果較適合使用 IP 位址，而非網域名稱，則運算子也可以在 CPID 端點網址中使用 IP 位址。IP 位址可能位於私人位址空間，但 Google 用戶端必須能夠在運算子的網路中連上這些位址。

營運商應在啟用程序中向 Google 提供下列資訊： 1. 應用程式會與 CPID_URL 聯絡，以取得 CPID。CPID_URL 為必填欄位，但營運商可提供多個網址，以提高可用性。1. 電信業者擁有的 IP 前置字元清單，以及電信業者要對應至所提供 CPID_URL 的行動裝置國家/地區代碼 (MCC) 和行動網路代碼 (MNC)。如果電信業者使用 SPN 或 GID1 區分網路中的 MVNO，電信業者也應提供這項資訊。Google 會使用這項資訊，將用戶端與對應的 CPID 端點配對，如圖 2 的步驟 1 所示。

要求格式如下： GET CPID_URL 基於舊版原因，CPID 端點應能支援下列要求：

GET CPID_URL?app={app_id}

產生 CPID 時，CPID 端點可以忽略 {app_id} 網址參數。但「必須」能夠處理含有該參數的要求。

對 CPID 端點的要求「可能」包含 Accept-Language 標頭。如果包含標頭，DPA 使用 Mobile Data Plan Sharing API 傳送的更新中，可讀取的字串必須使用 CPID 要求中提供的設定。

用戶端每次發出 GET CPID_URL 要求時，都必須收到新的 CPID。如果 CPID 建立成功，CPID 端點就必須傳回 200 OK 回應。回應主體必須包含 CPIDResponse 的例項。

{
    "cpid": "<CPID_string>",
    "ttlSeconds": 2592000
}

傳回的 CPID 必須在 ttlSeconds 秒內有效。在後續呼叫 DPA 時，GTAF 會根據 RFC2396 編碼 CPID。

如果發生錯誤，CPID 端點必須傳回 HTTP 錯誤，且回應主體必須包含 ErrorResponse 例項。如要查看可能的原因值和 HTTP 錯誤代碼清單，請按這裡。

{
    "errorMessage": "<error message>",
    "cause": "INVALID_NUMBER"
}

具體來說，如果收到不屬於電信業者網路的使用者 (例如屬於其他電信業者，但在這個 CPID 端點服務的網路上漫遊的使用者)，或未選擇與 Google 分享資料方案資訊的使用者，CPID 端點「必須」傳回 HTTP 狀態碼 403。

產生 CPID

CPID 端點建立 CPID 的「建議」方式如下：

CPID_string = Base64(AES(MSISDN + TimeStamp + language, secret))

CPID 端點會串連 MSISDN、用戶端在 Accept-Language 標頭中傳送的語言，以及高解析度時間戳記，並使用 secret金鑰透過 AES 加密。時間戳記應對應 CPID 的到期時間。加密輸出內容會以 Base64 編碼。此外，在網址中使用 CPID 時，必須進行網址編碼，才能處理 Base64 中使用的特殊字元 (/+=)。特別是當 GTAF 呼叫 DPA，或 DPA 呼叫 Mobile Data Plan Sharing API 時，CPID 必須經過網址編碼。使用這種方法產生 CPID 的優點是，DPA 和 CPID 端點不需要有有效的 CPID 和 MSISDN 資料庫。

視特定運算子的情況而定，實作 CPID 端點可能並不容易。我們發現，CPID 端點的 MSISDN 存取權是常見的挑戰。我們很樂意分享在新手上路期間學到的經驗。如有任何問題，歡迎與我們聯絡。

安全性要求

營運商應採取一切必要預防措施，保護訂閱者的私人資訊。具體來說，為盡量減少暴露訂閱者電話號碼的風險，CPID 端點應位於安全防護範圍內。此外，如果電信業者採用 DPI，則在將 MSISDN 插入 HTTP 要求前，電信業者「應」先加密 MSISDN。如果 CPID 端點不是您的安全邊界 (例如，CPID 端點部署在公有雲上)，則營運商不應透過公開網際網路以明碼傳輸 MSISDN。電信業者可以在 DPI 和 CPID 端點之間建立 VPN (請參閱圖 1)，或在將 MSISDN 插入標頭前加密。後者假設 CPID 端點可以解密插入的標頭，以在產生 CPID 前復原 MSISDN。此外，營運商應保護用於產生 CPID 的密鑰，並根據營運商安全政策輪替這組金鑰。

供應情形和容量需求

如果用戶端無法擷取 CPID，就無法存取 Mobile Data Plan API 的任何資訊。因此，營運商應採取必要措施，確保 CPID 端點可用。這類措施包括：擁有 CPID 端點和 DPI 功能的多個執行個體，以及這兩項功能的實體、網站和網路備援，並確保系統資源和容量充足。此外，CPID 端點和插入標頭的 DPI 函式必須有足夠的容量，才能處理所有要求 CPID 的 Google 用戶端負載。CPID 端點可以在 ttlSeconds 欄位中使用較大的值，減少產生 CPID 的頻率。Google 建議使用 30 天的 TTL 值。

附註

  1. VIDEO_OFFLINE PMTC 表示此方案僅適用於離線狀態 (例如串流 QoE 真的很差)。與彈性時間視窗無關。 ↩