# 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](https://www.ietf.org/rfc/rfc2119.txt).

## 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_OFFLINE`^[1](https://developers.google.com/mobile-data-plan/v6_1/overview#fn1)^`, 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](https://developers.google.com/mobile-data-plan/v6_1/images/Data_Plan_API_Sample_Plan.png "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

![](https://developers.google.com/mobile-data-plan/v6_1/images/Data_Plan_API_CPID.png)

**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](https://developer.android.com/reference/android/telephony/TelephonyManager.html#getSimOperatorName()) and [GID1](https://developer.android.com/reference/android/service/carrier/CarrierIdentifier#getGid1()) 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](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/CPIDResponse).

    {
        "cpid": "<CPID_string>",
        "ttlSeconds": 2592000
    }

The returned CPID MUST be valid for *ttlSeconds* seconds. GTAF will encode the
CPID per [RFC2396](https://www.ietf.org/rfc/rfc2396.txt) 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](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/ErrorResponse). The list of possible *cause*
values and HTTP error codes is available
[here](https://developers.google.com/mobile-data-plan/v6_1/agent_api_specification#error-cases).

    {
        "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 `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. 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. [↩](https://developers.google.com/mobile-data-plan/v6_1/overview#fnref1)