建立 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 會使用 SPNGID1 判斷 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 為必填欄位,但營運商可以提供多個網址,提高可用性。
  2. 電信業者擁有的 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 取得。

  1. 當 DPA 收到 GTAF 傳送的方案狀態或優惠呼叫時,可以解密 CPID 並擷取 MSISDN,藉此衍生 MSISDN。
  2. 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 端點「必須」視情況傳回下列內容:

  1. 如果收到 CPID 要求的使用者不屬於電信業者網路 (例如屬於其他電信業者,但漫遊至這個 CPID 端點服務的網路),或未選擇與 Google 分享資料方案資訊,CPID 端點就必須傳回 HTTP 狀態碼 403,並將 USER_ROAMING、USER_OPT_OUT 或 INELIGIBLE_FOR_SERVICE 設為原因。
  2. 如果 CPID 要求收到的電話號碼無效,CPID 端點「必須」傳回 HTTP 400,並指出 INVALID_NUMBER 錯誤原因。
  3. 如果對 CPID 端點的要求有任何其他格式錯誤,CPID 端點必須傳回 HTTP 400,並將 ERROR_CAUSE_UNSPECIFIED 設為原因。
  4. 如果是其他錯誤原因,則可接受任何相容的 HTTP 錯誤代碼。特別是 HTTP 500,適用於 CPID 端點的任何內部失敗。