GTAF 使用使用者金鑰與 DPA 通訊時識別訂閱者。有權存取使用者 MSISDN 的應用程式可以使用 user_key。另一方面,無法存取 MSISDN 的應用程式必須建立電信業者方案 ID (CPID),而無需探索使用者的 MSISDN。下文將說明建立 CPID 的機制。
CPID 通話流程
圖 2:建立 CPID 的呼叫流程。
- UE 中的 Google 應用程式使用 Google 內部 API,從 GTAF 擷取 CPID 端點的網址。請使用用戶端的公開 IP 位址和有效 SIM 卡的 MCC+MNC 來識別運算子。以 MVNO 來說,Google 會使用 SPN 和 GID1 來判斷 MVNO
- 用戶端會向 CPID 端點發出 HTTP GET 要求。運算子「可能」支援透過 HTTPS 傳送要求。
- 運算子 MAY 可利用其深度檢查檢查函式來識別要求,並將要求的電話號碼插入 HTTP 標頭。
- CPID 端點會收到要求、建構 CPID,然後將 CPID 傳回 UE 並提供存留時間 (TTL) 來說明 UE 可以使用這個 CPID 的時間長度。
運算子 MAY 也可能會使用 IP 位址,而不是 CPID 端點網址中的網域名稱。IP 位址可能位於私人位址空間,但 Google 用戶端必須可透過電信業者的網路存取。
業者「應該」在新手上路流程中向 Google 提供以下資訊:
- 應用程式要用來取得 CPID 的 CPID_URL。一個 CPID_URL 為必填欄位,但運算子可提供多個網址來提高可用性。
- 業者擁有的 IP 前置字元清單,以及運算子想對應至所提供的 CPID_URLs 的行動裝置國家/地區代碼 (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 Shared API 傳送的更新中使用者可理解的字串「必須」使用 CPID 要求中提供的設定。
每次用戶端發出 GET CPID_URL 要求時,都「必須」收到新的 CPID。如果 CPID 建立成功,則 CPID 端點「必須」傳回 200 OK 回應。回應主體「必須」包含 CPIDResponse 的執行個體。
{
"cpid": "<CPID_string>",
"ttlSeconds": 2592000
}
即使訂閱者隨後已要求其他 CPID,傳回的 CPID 也「必須」在 ttlSeconds 內有效。Google 建議使用 30 天的存留時間值,但不得短於 14 天,以獲得最佳使用者體驗。GTAF 會根據後續的 DPA 呼叫,依照 RFC2396 編碼 CPID。
產生 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 Plan Shared API 時,CPID 「必須」經過網址編碼。
視特定運算子的情況而定,執行 CPID 端點可能並不容易。透過 CPID 端點存取 MSISDN,是經常遇到的一項特定挑戰。我們很樂意分享新手入門課程。如有疑問,歡迎與我們聯絡。
CPID 儲存空間
使用上述機制產生的 CPID 不必儲存在資料庫中。處理 DPA 呼叫的相關資訊時,可以從 CPID 取得。
- 當 DPA 收到來自 GTAF 關於方案狀態或優惠的呼叫時,可以透過解密 CPID 並擷取 MSISDN 來推算 MSISDN。
- 要解密 CPID 的到期時間,可以解密 CPID,然後擷取到期時間。
可用性和容量需求
如果用戶端無法擷取 CPID,就無法透過 Mobile Data Plan API 存取任何資訊。因此,電信業者「必須」採取必要措施,以確保 CPID 端點的可用性。這類措施包括有多個 CPID 端點和 DPI 函式的執行個體,且兩個函式具有實體、網站和網路備援功能,並確保系統資源和容量均充足。此外,CPID 端點和插入標頭的 DPI 函式都必須有足夠的負載量,才能處理所有要求 CPID 的 Google 用戶端負載。CPID 端點可在 ttlSeconds
欄位中使用較大的值,以降低其產生 CPID 的頻率。
錯誤案例
如果發生錯誤,CPID 端點「必須」傳回包含 <錯誤回應> 例項的 HTTP 錯誤,適用的錯誤訊息則可包含有助於偵錯錯誤原因的資訊。舉例來說,如果 CPID 過期,包括 CPID 產生和到期時間,我們可以確認 CPID 端點是否正常運作。
{
"errorMessage": "<error message>",
"cause": "USER_ROAMING"
}
視情境而定,CPID 端點「必須」傳回以下內容:
- 如果 CPID 要求是針對不屬於電信業者網路 (例如屬於其他運算子,但透過這個 CPID 端點提供網路進行漫遊的使用者) 的使用者,或是選擇不與 Google 分享數據方案資訊,則 CPID 端點「必須」傳回 USER_ROAMING、USER_OPT_OUT 或 INELIGIB 的 HTTP 狀態碼 403
- 如果收到 CPID 請求中的電話號碼無效,則 CPID 端點「必須」傳回 HTTP 400,並傳回 INVALID_NUMBER 錯誤。
- 如果對 CPID 端點的要求有任何格式錯誤,CPID 端點「必須」傳回 HTTP 400,且原因為 ERROR_CAUSE_UNSPECIFIED。
- 如果是其他錯誤原因,系統接受任何相容的 HTTP 錯誤代碼。尤其是 HTTP 500 是 CPID 端點發生內部失敗情況的理想錯誤。