術語
- 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 的說明解讀。
行動數據方案分享
整體來說,行動數據方案分享功能包含三個部分:
- 建立及更新電信業者方案 ID (CPID) 的機制,可用於使用者金鑰。如果應用程式有權存取 MSISDN,即可將其做為使用者金鑰。
- Google Mobile Data Plan Sharing API,可讓 DPA 將使用者的資費方案資訊傳送給 Google。舉例來說,如果 DPA 想要通知使用者優惠,可以通知 GTAF,後者會通知使用者。
- 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_OFFLINE
1, MUSIC, GAMING, SOCIAL, MESSAGING
和PMTC_UNSPECIFIED.
資料用量或時間限制:啟用後,當資料用量或時間限制 (如果是以時間為準的方案,例如 600 分鐘的網路存取時間。在下方的圖 1 中,訂閱者可以購買「ACME Blue」方案模組,取得 1 GB 的一般使用者流量,必須在啟用後一週內使用完畢,否則就會過期。
圖 1. 數據方案範例。
建立 CPID
GTAF 會使用使用者金鑰與 DPA 通訊,藉此識別訂閱者。有權存取使用者 MSISDN 的應用程式可以將其做為 user_key。另一方面,如果應用程式無法存取 MSISDN,則必須建立電信方案 ID (CPID),而不需探索使用者的 MSISDN。下文將說明建立 CPID 的機制。
CPID Call Flow
圖 2:建立 CPID 的呼叫流程。
- UE 中的 Google 應用程式會使用 Google 內部 API,從 GTAF 擷取 CPID 端點的網址。系統會使用用戶端的公開 IP 位址和有效 SIM 卡的 MCC+MNC 識別電信業者。如果是 MVNO,Google 會使用 SPN 和 GID1 判斷 MVNO
- 用戶端會向 CPID 端點發出 HTTP GET 要求。營運商「可能」支援透過 HTTPS 傳送要求。
- 電信業者「可能」會使用深層封包檢查功能識別要求,並將使用者的電話號碼以 HTTP 標頭的形式插入要求。
- 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 值。
附註
-
VIDEO_OFFLINE PMTC 表示此方案僅適用於離線狀態 (例如串流 QoE 真的很差)。與彈性時間視窗無關。 ↩