Getting Started with Mobile Data Plan Sharing

Terminology

  • GTAF: Google Traffic Application Function. A Google service that implements the Data Plan Sharing API and interacts with DPAs on behalf of Google applications. Google applications can query GTAF for the user's data plan information. Alternatively, if the Google applications register with GTAF, GTAF can send updates about the user's data plan.
  • MSISDN: Mobile Station International Subscriber Directory Number, a number uniquely identifying a subscription in a mobile network. More commonly known as phone number.
  • CPID Endpoint: A service implemented by mobile network operators that generates a carrier plan identifier (CPID) that can be used to look up the user's data plan information. CPID allows an application to query for details of a user's data plan without accessing the user's MSISDN. We describe the procedure for generating CPIDs below.
  • User Key: User key is a string that can be used to identify a user's data plan. This can be either the CPID or MSISDN for applications which have access to the MSISDN.
  • DPA: Data Plan Agent, a service implemented by mobile network operators that shares user data plan information with GTAF. The DPA can share information with GTAF by using a combination of sending data using Google Mobile Data Plan Sharing API and implementing the Data Plan Agent API. The DPA can optionally act as the CPID endpoint as well.
  • UE: User Equipment, device used by the user.

Requirements Language

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in these guides are to be interpreted as described in RFC 2119.

Mobile Data Plan Sharing

At a high level, the Mobile Data Plan Sharing comprises three parts:

  1. Mechanism to establish and update a carrier plan identifier (CPID) which can be used as user key. Applications that have access to MSISDN, MSISDN can use it as user key.
  2. A Google Mobile Data Plan Sharing API which allows the DPA to send information about a user's data plan to Google. For example, if the DPA wants to notify the user of an offer, it can notify GTAF which in turn notifies the user.
  3. A Data Plan Agent API implemented by the DPA which allows GTAF to query the DPA for information about the user's data plan. For example, if an application wants to display current data plan balance to the user, it can query GTAF which in turn queries the DPA.

The rest of this page introduces data plan terminology and details how to establish a CPID. Google Mobile Data Plan Sharing API and the Data Plan Agent API Specification follow next.

Data Plan Terminology

The schema of a planStatus defined in the API MUST be able to represent data plans that are offered by operators to the users. The API supports defining data plans which charge users at a different rate for all traffic to a particular set of URLS (e.g., all traffic to *.acmefake.com is charged at a different rate). The API also supports data plans which offer different rates for certain types of actions in an app. We call these sub-app data plans. An example of a sub-app data plan would be to offer free (i.e., zero rate) video browsing, while watching videos within the application deducts data from the subscriber's data balance. The video app MUST then be able to learn this information when querying for data plan information.

Here, we introduce some terms related to data plans. Figure 1 provides examples of data plans that are representative of the concepts that we want to capture.

Data Plan: the top-level mobile service package that a subscriber purchases. It can be as simple as "10 GB mobile data for 30 days" or it can be defined as a collection of components, also known as modules. A data plan has:

  • Data Plan Name, such as "ACME Red".
  • Data Plan Identifier, used to refer to the plan, for example during purchases.
  • Expiration time, when the data plan expires.
  • Plan Category, whether the plan is a prepaid plan or a post paid plan.

Plan Module: a component of a data plan. Specifically a plan module has:

  • Module Name, such as "Free Video Nights".
  • Max Rate, bandwidth that is being offered to the user by this module.
  • Flex Time Windows, time windows during which a discount could be offered to the user.

  • Plan Module Traffic Category (PMTC), a description of the data traffic that a module applies to. The PMTC can be as general as *all Internet traffic *or as specific as traffic generated/consumed by one or more applications, websites, or even user journeys within a single application. Examples of the latter kind are "unlimited music", "100 MB Video Data Pack (VDP)", "unlimited gaming data" and "unlimited video browsing". To facilitate the definition of PMTCs we have defined the following PMTCs : GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE1, MUSIC, GAMING, SOCIAL, MESSAGING and PMTC_UNSPECIFIED.

  • Data volume or time limit, once activated, the plan module expires when either the data volume or time limit (in the case of time-based plans, e.g., 600 minutes of Internet access during the next 7 days) is exceeded. In Figure 1 below, a subscriber can buy a plan module, as part of "ACME Blue", that provides 1 GB of general user traffic that has to be used within a week of activation before they expire.

Data Plan API Sample Plan

Figure 1. Sample data plans.

Establishing CPID

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.

  1. 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
  2. The client issues an HTTP GET request to the CPID endpoint. The operator MAY support sending the request over HTTPS.
  3. 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.
  4. 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: 1. 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. 1. 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. GTAF will encode the CPID per RFC2396 in subsequent calls to the DPA.

If an error occurs, the CPID endpoint MUST return an HTTP error with a response body that MUST contain an instance of ErrorResponse. The list of possible cause values and HTTP error codes is available here.

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

In particular, 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.

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 secretkey. 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. An advantage of generating CPID using this approach is that the DPA and CPID endpoint do not need to have a database of valid CPIDs and MSISDNs.

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.

Security Requirements

The operator SHALL take all necessary precautions to protect the private information of their subscribers. Specifically, to minimize exposure of the subscribers’ phone numbers the CPID endpoint SHOULD be inside your security perimeter. Moreover, for cases where the operator employs DPI, the operator SHOULD encrypt the MSISDN before injecting it to the HTTP request. If the CPID endpoint is not your security perimeter (e.g., when the CPID endpoint is deployed on a public cloud) the operator SHOULD not transmit the MSISDN over the public Internet in the clear. The operator can establish a VPN between the DPI and the CPID endpoint (see Figure 1) or encrypt the MSISDN before injecting it in the header. The latter approach assumes that the CPID endpoint can decrypt the injected header to recover the MSISDN before generating the CPID. Furthermore, the operator SHALL guard the secret key used to generate the CPID and rotate this key according to operator security policies.

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. Google recommends using a TTL value of 30 days.

Notes

  1. The VIDEO_OFFLINE PMTC means this plan is good for offline only (e.g., really bad streaming QoE). It is independent of FlexTime window. ↩