GTAF uses user key to identify a subscriber when communicating with the DPA. Applications that have access to the user's MSISDN can use it as a user_key. On the other hand, applications that do not have access to MSISDN, need to establish a carrier plan identifier (CPID) without discovering the user's MSISDN. In what follows, we describe the mechanism that establishes a CPID.
CPID Call Flow
Figure 2: Call flow to establish CPID.
- A Google application in the UE uses a Google-internal API to retrieve the URL of the CPID endpoint from GTAF. The operator is identified using the client's public IP address and the MCC+MNC of the active SIM card. In the case of MVNOs, Google will use the SPN and GID1 to determine the MVNO
- The client issues an HTTP GET request to the CPID endpoint. The operator MAY support sending the request over HTTPS.
- The operator MAY employ their Deep Packet Inspection function to identify the request and inject the user's phone number to the request as an HTTP header.
- CPID endpoint receives the request, constructs the CPID, and returns CPID to the UE with a time to live (TTL) indicating how long the UE can use this CPID for.
The operator MAY also use IP addresses instead of domain names in the CPID endpoint URL if that is preferable. The IP addresses MAY be in private address space but they have to be reachable by Google clients inside the operators's network.
The operator SHALL provide the following information to Google as part of the onboarding process:
- The CPID_URL that applications will contact to acquire CPIDs. One CPID_URL is mandatory but the operator can provide multiple URLs to increase availability.
- The list of IP prefixes that the operator owns and the Mobile Country Code (MCC) and Mobile Network Code(s) (MNC) that the operator wants to be mapped to the provided CPID_URLs. If the operator uses SPN or GID1 to distinguish MVNOs in their network, the operator SHALL provide this information as well. Google will use this information to match clients to the corresponding CPID endpoints, as shown in Step 1 of Figure 2.
The format of the request is:
GET CPID_URL
For legacy reasons, CPID endpoint should be able to support a request like the
following:
GET CPID_URL?app={app_id}
The CPID endpoint can ignore the {app_id}
URL parameter when generating the
CPID. But, it MUST be able to handle a request that contains the parameter.
The request to the CPID endpoint MAY include Accept-Language
header. If the
header is included then human readable strings in updates that the DPA sends
using the Mobile Data Plan Sharing API MUST use the settings provided in the
CPID request.
Each time the client issues a GET CPID_URL request, it MUST receive a new CPID. If the creation of CPID is successful, then the CPID endpoint MUST return a 200 OK response. The response body MUST contain an instance of CPIDResponse.
{
"cpid": "<CPID_string>",
"ttlSeconds": 2592000
}
The returned CPID MUST be valid for ttlSeconds seconds even if a subscriber has requested other CPIDs afterwards. Google recommends using a TTL value of 30 days but not less than 14 days for best user experience. GTAF will encode the CPID per RFC2396 in subsequent calls to the DPA.
CPID generation
The RECOMMENDED way for the CPID endpoint to create a CPID is:
CPID_string = Base64(AES(MSISDN + TimeStamp + language, secret))
The CPID endpoint concatenates MSISDN, language sent by the client in
Accept-Language header, and a high resolution timestamp and encrypts it via AES
using secret
key. The timestamp SHOULD correspond to the time that the CPID
expires. The encrypted output is Base64 encoded. Furthermore, when the CPID is
used in a URL, it MUST be URL-encoded to handle special characters (/+=) used in
Base64. In particular when GTAF calls the DPA or when the DPA calls Mobile Data
Plan Sharing API, the CPID MUST be URL-encoded.
Depending on a particular operators's situation, it may be non-trivial to implement the CPID endpoint. A particular challenge that has been frequently encountered is getting access to MSISDN at the CPID endpoint. We are happy to share the lessons learned onboarding operators. Please reach out to us if you face any challenges.
CPID Storage
A CPID generated using the mechanism described above does not have to be stored into a database. Relevant information for handling calls to the DPA can be derived from the CPID.
- When the DPA receives a call from GTAF for a plan status or offers, the MSISDN can be derived by decrypting the CPID and extracting the MSISDN.
- Expiration time of the CPID can be derived by decrypting the CPID and then extracing the expiration timestamp.
Availability and Capacity Requirements
If clients cannot retrieve a CPID they cannot access any information from the
Mobile Data Plan API. For this reason, the operator SHALL take the necessary
measures to ensure the availability of the CPID endpoint. Such measures include
having multiple instances of the CPID endpoint and DPI functions and having
physical, site, and network redundancy for both functions, and ensure that
system resources and capacity are adequate. Moreover, the CPID endpoint as well
as the DPI function that injects the header must have adequate capacity to
handle the load of all the Google clients requesting CPIDs. The CPID endpoint
can use larger values in the ttlSeconds
field to reduce the frequency it
generates CPIDs.
Error Cases
If an error occurs, the CPID endpoint MUST return an HTTP error with a response body that MUST contain an instance of ErrorResponse. A good error message would include information that can help with debugging the cause of the error. For example, in case of an expired CPID, including CPID generation and expiration time would help us confirm that the CPID endpoint is working as designed.
{
"errorMessage": "<error message>",
"cause": "USER_ROAMING"
}
The CPID endpoint MUST return the following depending on the scenario:
- If a CPID request is received for a user who does not belong to the operator network (e.g., a user belonging to another operator but roaming on network served by this CPID endpoint) or who has not opted to sharing data plan information with Google, the CPID endpoint MUST return HTTP status code 403 with USER_ROAMING, USER_OPT_OUT or INELIGIBLE_FOR_SERVICE as the cause.
- If a CPID request is received with an invalid phone number, then the CPID endpoint MUST return HTTP 400 with INVALID_NUMBER error cause.
- If the request to the CPID endpoint is malformed in any other way, the CPID endpoint MUST return HTTP 400 with ERROR_CAUSE_UNSPECIFIED as the cause.
- For other error causes, any compatible HTTP error code is acceptable. In particular, HTTP 500 is a suitable error cause for any internal failure at the CPID endpoint.