Getting Started with Mobile Data Plan Sharing

Changes

The latest version of the API introduces the following changes:

  • Integrates the Google Mobile Data Plan Sharing API and Data Plan Agent API Specification.
  • Allows operators to share offers with Google using the Google Mobile Data Plan Sharing API.
  • Removes support for querying user account details and purchased plans from Data Plan Agent API specification.

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 udpates 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[^1] 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.
  • Cost, price of the data plan.
  • Status, a data plan can be purchased, but not activated, or it can be active.

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

  • 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_OFFLINE[^1], 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.

  • Plan Module Priority, the traffic that an application generates/consumes can be mapped to multiple data plan modules. For example, consider a user who has purchased a Video Data Plan (VDP) in addition to a general purpose data plan. The intention then is that traffic from the video app should be charged against the VDP, as long as that plan is still valid. Once the VDP expires, YT traffic will be charged against the general purpose data plan. In order to capture this behavior, each data plan module should have a priority. Then, an application can use the traffic categories for each of the data plan modules that a user has purchased and their relative priority to determine how it will be charged.

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 do not have access to MSISDN, need to establish a carrier plan identifier (CPID) without discovering the user's MSISDN. Applications that have access to the user's MSISDN can use MSISDN directly. Here, we explain 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.
  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} URL parameter when generating the CPID. But, it MUST be able to handle a request that contains the parameter.

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": integer
}

The returned CPID string must be URL-encoded, and must be valid for ttlSeconds seconds.

If an error occurs, the response body MUST contain an instance of ErrorResponse.

{
    "error": "<error message>",
    "cause": integer
}

The full list of possible cause values and HTTP status codes for different error conditions is available here. 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 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.