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 提供下列資訊:
- 應用程式會與 CPID_URL 聯絡,以取得 CPID。CPID_URL 為必填欄位,但營運商可以提供多個網址,提高可用性。
- 電信業者擁有的 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,傳回的 CPID 也必須在 ttlSeconds 秒內有效。為獲得最佳使用者體驗,Google 建議使用 30 天的 TTL 值,但不得少於 14 天。在後續呼叫 DPA 時,GTAF 會根據 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 Sharing 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 錯誤,且回應主體必須包含 ErrorResponse 例項。良好的錯誤訊息應包含有助於偵錯錯誤原因的資訊。舉例來說,如果 CPID 已過期,提供 CPID 生成和到期時間,有助於我們確認 CPID 端點是否正常運作。
{
"errorMessage": "<error message>",
"cause": "USER_ROAMING"
}
CPID 端點「必須」視情況傳回下列內容:
- 如果收到 CPID 要求的使用者不屬於電信業者網路 (例如屬於其他電信業者,但漫遊至這個 CPID 端點服務的網路),或未選擇與 Google 分享資料方案資訊,CPID 端點就必須傳回 HTTP 狀態碼 403,並將 USER_ROAMING、USER_OPT_OUT 或 INELIGIBLE_FOR_SERVICE 設為原因。
- 如果 CPID 要求收到的電話號碼無效,CPID 端點「必須」傳回 HTTP 400,並指出 INVALID_NUMBER 錯誤原因。
- 如果對 CPID 端點的要求有任何其他格式錯誤,CPID 端點必須傳回 HTTP 400,並將 ERROR_CAUSE_UNSPECIFIED 設為原因。
- 如果是其他錯誤原因,則可接受任何相容的 HTTP 錯誤代碼。特別是 HTTP 500,適用於 CPID 端點的任何內部失敗。