CPID の設定

GTAF は、DPA との通信時にユーザーキーを使用してサブスクライバーを識別します。ユーザーの MSISDN にアクセスできるアプリは、それを user_key として使用できます。一方、MSISDN にアクセスできないアプリは、ユーザーの MSISDN を検出せずに携帯通信会社のプラン ID（CPID）を確立する必要があります。以降では、CPID を確立するメカニズムについて説明します。

CPID コールフロー

図 2: CPID を確立するためのコールフロー。

  1. UE の Google アプリケーションは、Google 内部 API を使用して GTAF から CPID エンドポイントの URL を取得します。事業者は、クライアントのパブリック IP アドレスとアクティブな SIM カードの MCC+MNC を使用して識別されます。MVNO の場合、Google は SPN と GID1 を使用して MVNO を特定します。
  2. クライアントが CPID エンドポイントに HTTP GET リクエストを発行します。オペレーターは、HTTPS 経由でのリクエストの送信をサポートしても構いません。
  3. 事業者は、ディープ パケット インスペクション機能を使用してリクエストを特定し、ユーザーの電話番号を HTTP ヘッダーとしてリクエストに挿入しても構いません。
  4. CPID エンドポイントはリクエストを受信し、CPID を構築して、UE がこの CPID を使用できる期間を示す有効期間（TTL）とともに CPID を UE に返します。

オペレーターは、必要に応じて、CPID エンドポイント URL でドメイン名の代わりに IP アドレスを使用しても構いません。IP アドレスはプライベート アドレス空間に存在しても構いませんが、オペレーターのネットワーク内の Google クライアントからアクセスできる必要があります。

事業者は、オンボーディング プロセスの一環として、以下の情報を Google に提供しなければなりません。

  1. アプリが CPID を取得するために接続する CPID_URL。CPID_URL は 1 つ必須ですが、可用性を高めるために複数の URL を指定できます。
  2. 事業者が所有する IP 接頭辞のリストと、事業者が指定された CPID_URL にマッピングしたいモバイル カントリー コード（MCC）とモバイル ネットワーク コード（MNC）。事業者がネットワーク内の MVNO を区別するために SPN または GID1 を使用している場合、事業者はこの情報も提供しなければなりません。Google は、この情報を使用して、図 2 のステップ 1 に示すように、クライアントを対応する CPID エンドポイントに照合します。

リクエストの形式は GET CPID_URL です。以前の理由により、CPID エンドポイントは次のようなリクエストをサポートできる必要があります。

GET CPID_URL?app={app_id}

CPID エンドポイントは、CPID の生成時に {app_id} URL パラメータを無視できます。ただし、パラメータを含むリクエストを処理できなければなりません。

CPID エンドポイントへのリクエストには、Accept-Language ヘッダーを含めても構いません。ヘッダーが含まれている場合、DPA がモバイル データプラン共有 API を使用して送信する更新の人間が読める文字列は、CPID リクエストで提供された設定を使用しなければなりません。

クライアントが GET CPID_URL リクエストを発行するたびに、新しい CPID を受け取らなければなりません。CPID の作成が成功した場合、CPID エンドポイントは 200 OK レスポンスを返さなければなりません。レスポンスの本文には、CPIDResponse のインスタンスが含まれていなければなりません。

{
    "cpid": "<CPID_string>",
    "ttlSeconds": 2592000
}

返された CPID は、加入者がその後他の CPID をリクエストした場合でも、ttlSeconds 秒間有効でなければなりません。最適なユーザー エクスペリエンスを実現するには、TTL 値を 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 を URL で使用する場合は、Base64 で使用される特殊文字（/+=）を処理するために URL エンコードしなければなりません。特に、GTAF が DPA を呼び出す場合、または DPA がモバイル データプラン共有 API を呼び出す場合、CPID は URL エンコードされなければなりません。

特定の事業者の状況によっては、CPID エンドポイントの実装が容易でない場合があります。頻繁に発生する課題として、CPID エンドポイントで MSISDN にアクセスすることが挙げられます。オペレーターのオンボーディングで得られた教訓をご紹介します。ご不明な点がございましたら、お気軽にお問い合わせください。

CPID ストレージ

上記のメカニズムを使用して生成された CPID は、データベースに保存する必要はありません。DPA への通話の処理に関連する情報は、CPID から取得できます。

  1. DPA が GTAF からプランのステータスや特典に関する呼び出しを受けた場合、CPID を復号して MSISDN を抽出することで MSISDN を取得できます。
  2. CPID の有効期限は、CPID を復号して有効期限のタイムスタンプを抽出することで取得できます。

可用性と容量の要件

クライアントが CPID を取得できない場合、モバイル データプラン API からの情報を取得することはできません。そのため、オペレーターは CPID エンドポイントの可用性を確保するために必要な措置を講じなければなりません。このような対策には、CPID エンドポイントと DPI 機能の複数のインスタンスを用意し、両方の機能に物理、サイト、ネットワークの冗長性を持たせ、システム リソースと容量が十分であることを確認することが含まれます。また、ヘッダーを挿入する DPI 関数と同様に、CPID エンドポイントには、CPID をリクエストするすべての Google クライアントの負荷を処理するのに十分な容量が必要です。CPID エンドポイントでは、ttlSeconds フィールドでより大きな値を使用して、CPID の生成頻度を減らすことができます。

エラーとなるケース

エラーが発生した場合、CPID エンドポイントは HTTP エラーを返さなければなりません。レスポンス本文には ErrorResponse のインスタンスが含まれていなければなりません。適切なエラー メッセージには、エラーの原因のデバッグに役立つ情報が含まれます。たとえば、CPID の有効期限が切れた場合、CPID の生成と有効期限を含めることで、CPID エンドポイントが設計どおりに機能していることを確認できます。

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

CPID エンドポイントは、シナリオに応じて以下を返さなければなりません。

  1. CPID エンドポイントは、事業者ネットワークに属していないユーザー（別の事業者に属しているが、この CPID エンドポイントが提供するネットワークでローミングしているユーザーなど）や、Google とのデータプラン情報の共有をオプトアウトしているユーザーに対して CPID リクエストを受信した場合、原因として USER_ROAMING、USER_OPT_OUT、INELIGIBLE_FOR_SERVICE を伴う HTTP ステータス コード 403 を返さなければなりません。
  2. 無効な電話番号を含む CPID リクエストを受信した場合、CPID エンドポイントは INVALID_NUMBER エラー原因とともに HTTP 400 を返さなければなりません。
  3. CPID エンドポイントへのリクエストが他の方法で不正な形式になっている場合、CPID エンドポイントは原因として ERROR_CAUSE_UNSPECIFIED を含む HTTP 400 を返さなければなりません。
  4. 他のエラー原因については、互換性のある HTTP エラーコードであればどれでも使用できます。特に、HTTP 500 は CPID エンドポイントでの内部エラーに適したエラー原因です。