建立 CPID

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

CPID 通話流程

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

  1. UE 中的 Google 應用程式使用 Google 內部 API，從 GTAF 擷取 CPID 端點的網址。請使用用戶端的公開 IP 位址和有效 SIM 卡的 MCC+MNC 來識別運算子。以 MVNO 來說，Google 會使用 SPN 和 GID1 來判斷 MVNO
  2. 用戶端會向 CPID 端點發出 HTTP GET 要求。運算子「可能」支援透過 HTTPS 傳送要求。
  3. 運算子 MAY 可利用其深度檢查檢查函式來識別要求，並將要求的電話號碼插入 HTTP 標頭。
  4. CPID 端點會收到要求、建構 CPID，然後將 CPID 傳回 UE 並提供存留時間 (TTL) 來說明 UE 可以使用這個 CPID 的時間長度。

運算子 MAY 也可能會使用 IP 位址，而不是 CPID 端點網址中的網域名稱。IP 位址可能位於私人位址空間，但 Google 用戶端必須可透過電信業者的網路存取。

業者「應該」在新手上路流程中向 Google 提供以下資訊：

  1. 應用程式要用來取得 CPID 的 CPID_URL。一個 CPID_URL 為必填欄位，但運算子可提供多個網址來提高可用性。
  2. 業者擁有的 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 取得。

  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 錯誤，適用的錯誤訊息則可包含有助於偵錯錯誤原因的資訊。舉例來說，如果 CPID 過期，包括 CPID 產生和到期時間，我們可以確認 CPID 端點是否正常運作。

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

視情境而定，CPID 端點「必須」傳回以下內容：

  1. 如果 CPID 要求是針對不屬於電信業者網路 (例如屬於其他運算子，但透過這個 CPID 端點提供網路進行漫遊的使用者) 的使用者，或是選擇不與 Google 分享數據方案資訊，則 CPID 端點「必須」傳回 USER_ROAMING、USER_OPT_OUT 或 INELIGIB 的 HTTP 狀態碼 403
  2. 如果收到 CPID 請求中的電話號碼無效，則 CPID 端點「必須」傳回 HTTP 400，並傳回 INVALID_NUMBER 錯誤。
  3. 如果對 CPID 端點的要求有任何格式錯誤，CPID 端點「必須」傳回 HTTP 400，且原因為 ERROR_CAUSE_UNSPECIFIED。
  4. 如果是其他錯誤原因，系統接受任何相容的 HTTP 錯誤代碼。尤其是 HTTP 500 是 CPID 端點發生內部失敗情況的理想錯誤。