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 uses a Google-internal API to retrieve the URL of the CPID endpoint. The operator is identified using the client's public IP address and the MCC+MNC of the active data 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.
  3. CPID endpoint returns CPID for the user (or an error code).

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 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 string MUST be URL-encoded, and must be valid for ttlSeconds seconds.

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, secret))

The CPID endpoint concatenates MSISDN, 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.

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.

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.