GTAF は、ユーザーキーを使用して DPA と通信するときにサブスクライバーを識別します。ユーザーの MSISDN にアクセスできるアプリは、user_key として使用できます。一方、MSISDN にアクセスできないアプリでは、ユーザーの MSISDN を検出せずにキャリアプラン識別子(CPID)を設定する必要があります。以下では、CPID を確立するメカニズムについて説明します。
CPID 通話フロー
図 2: CPID を確立するための呼び出しフロー。
- UE の Google アプリケーションは、Google 内部 API を使用して GTAF から CPID エンドポイントの URL を取得します。オペレーターは、クライアントのパブリック IP アドレスと、有効な SIM カードの MCC + MNC を使用して識別されます。MVNO の場合、Google は SPN と GID1 を使用して MVNO を決定します。
- クライアントは CPID エンドポイントに HTTP GET リクエストを発行します。オペレータは、HTTPS を介したリクエストの送信をサポートしても構いません。
- オペレーターは、詳細なパケット検査機能を使用してリクエストを識別し、ユーザーの電話番号を HTTP ヘッダーとしてリクエストに挿入しても構いません。
- CPID エンドポイントはリクエストを受信し、CPID を作成して、UE がこの CPID を使用できる期間を示す有効期間(TTL)とともに CPID を返します。
オペレーターは、必要に応じて CPID エンドポイント URL でドメイン名の代わりに IP アドレスを使用しても構いません。IP アドレスはプライベート アドレス空間にあっても構いませんが、オペレーター ネットワーク内の Google クライアントが到達可能である必要があります。
事業者は、オンボーディング プロセスの一環として次の情報を Google に提供する必要があります。
- アプリが CPID を取得するために利用する CPID_URL。1 つの CPID_URL は必須ですが、オペレーターは可用性を高めるために複数の URL を指定できます。
- オペレーターが所有する IP プレフィックスと、オペレーターが指定した CPID_URL にマッピングするモバイル カントリー コード(MCC)とモバイル ネットワーク コード(MNC)のリスト。オペレーターが SPN または GID1 を使用してネットワーク内の MVNO を区別する場合、オペレーターもこの情報を提供する必要があります。図 2 のステップ 1 に示すように、この情報を使用して、クライアントを対応する CPID エンドポイントと照合します。
リクエストの形式は次のとおりです。
GET CPID_URL
従来の理由から、CPID エンドポイントは次のようなリクエストをサポートできる必要があります。
GET CPID_URL?app={app_id}
CPID エンドポイントは、CPID を生成する際、{app_id}
URL パラメータを無視できます。しかし、パラメータを含むリクエストを処理できなければなりません。
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 秒間有効でなければなりません。最適なユーザー エクスペリエンスを実現するには、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 でエンコードされます。さらに、URL で CPID を使用する場合、Base64 で使用される特殊文字(/+=)を処理するために、URL エンコードする必要があります。特に、GTAF が DPA を呼び出す場合、または DPA が Mobile Data Plan Sharing API を呼び出すときは、CPID が URL エンコードされている必要があります。
特定のオペレーターの状況に応じて、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 エンドポイントは、ErrorResponse のインスタンスを含むレスポンス本文を持つ HTTP エラーを返さなければなりません。適切なエラー メッセージには、エラーの原因のデバッグに役立つ情報が含まれます。たとえば、CPID が期限切れになっている場合(CPID の生成と有効期限を含む)は、CPID エンドポイントが設計どおりに機能していることを確認するのに役立ちます。
{
"errorMessage": "<error message>",
"cause": "USER_ROAMING"
}
CPID エンドポイントは、シナリオに応じて次のものを返さなければなりません。
- オペレーター ネットワークに属していないユーザー(別のオペレーターに属するものの、この CPID エンドポイントによって提供されるネットワークをローミングしているユーザーなど)について CPID リクエストを受け取った場合、またはデータプラン情報を Google と共有する設定を選択していないユーザーについて、CPID エンドポイントが HTTP ステータス コード 403 を USER_ROAMING、USER_OPT_OUT、または INESERVICEG として返す必要があります。
- 無効な電話番号で CPID リクエストを受け取った場合、CPID エンドポイントが INVALID_NUMBER エラーの原因を伴って HTTP 400 を返さなければなりません。
- CPID エンドポイントへのリクエストの形式がその他の形式の場合、CPID エンドポイントは ERROR_CAUSE_UNSPECIFIED を原因として HTTP 400 を返さなければなりません。
- その他のエラーには、互換性のある HTTP エラーコードを使用できます。特に、HTTP 500 は CPID エンドポイントでの内部障害に適したエラーの原因になります。