Google Mobile Data Plan Sharing API

Motivation

The Google Mobile Data Plan Sharing API allows an operator to send information about a user's (identified by user key) data plan to GTAF. On this page, we outline the mechanism through which these updates can be pushed to GTAF and thereby Google applications. The API currently allows the DPA to send data plan status to GTAF to be consumed by a Google client.

Authentication

All Data Plan Sharing API requests to GTAF must be authenticated using the Google Cloud OAuth2 server. The requests must be authenticated as a service account that has been whitelisted in the ISP Portal for the ASN the DPA represents. See Google Cloud OAuth 2.0 for Service Accounts for documentation on how to use OAuth with Google Cloud service accounts.

Data Plan Updates

Currently the Google Mobile Data Plan Sharing API allows an operator to share updates about a user's data plan:

  • Data Plan Status: Captures current status of a user's data plan. For example, if a user is running out of data, an operator can push a data plan status update to GTAF which could then be used by GTAF to send a plan status notification to the user.

API Description

Figure 3. GTAF-DPA interaction when DPA shares data plan status with GTAF.

Applications can receive data plan status information shared with GTAF in one of two ways:

  1. UE calls GTAF for data plan status information:
    1. The operator's DPA uses the Data Plan Sharing API to push a user's data plan status to GTAF. GTAF stores the plan status and its associated user key until the expiration time specified by the operator.
    2. Google application running on UE requests the data plan status information using a Google-internal API. The application includes the user key in its request.
    3. If the application can use cached data plan status then GTAF uses the user key to look up the user's data plan status. GTAF then returns this status to the application.
  2. GTAF pushes data plan status information to the UE:
    1. When relevant, data plan status received from the operator is directly pushed to the UE. In particular, the pushed plan status is used to update the on device cache of Mobile Data Plan module in Google Play Services.

Sharing Data Plan Status

The DPA uses an HTTPS POST to create and update an existing plan status entry for a user to be used by a client. Currently GTAF supports mobiledataplan and youtube as valid client identifiers. Here is an example request for an operator with asn 12345 and user key abcdef sharing plan information with GTAF for youtube client:

POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/planStatus

The request body is an instance of PlanStatus.

{
  "plans": [{
    "planName": "ACME1",
    "planId": "1",
    "planCategory": "PREPAID",
    "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
    "planModules": [{
      "moduleName": "Giga Plan", // req.
      "trafficCategories": ["GENERIC"],
      "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
      "overUsagePolicy": "BLOCKED",
      "maxRateKbps": "1500",
      "description": "1GB for a month", // req.
      "coarseBalanceLevel": "HIGH_QUOTA"
    }]
  }],
  "planInfoPerClient": {
    "youtube": {
      "rateLimitedStreaming": {
        "maxMediaRateKbps": 569
      }
    }
  },
  "languageCode": "en-US", // req.
  "expireTime": "2018-06-14T08:41:27-07:00", // req.
  "updateTime": "2018-06-07T07:41:22-07:00", // req.
  "title": "Prepaid Plan"
}

If the request is successful, GTAF will return HTTP response code 200 and the pushed planStatus entry with a notifications entry if any notification was sent to the user. If GTAF identifies a problem with the request, it will return an HTTP status code in the range 400-499. If GTAF is unable to complete a request due to a GTAF fault, GTAF will return an HTTP code in the range 500-599. Requests that receive a response in the 500-599 range are considered retryable and requests that receive a response in the 400-499 range are generally not retryable. Error Cases explains the error responses from GTAF in detail.

Plan Status Push for Default Client

GTAF supports the following call where the plan status is pushed by the operator without specifying the client for which it can be used. In this case, we assume that the plan status is intended for mobiledataplan client and the operator intends to send a notification to the user. The request body is an instance of PlanStatus

POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef

Internationalization

In order to support internationalization, the DPA must know the user’s preferred language even without a direct request from GTAF. To solve this issue the request to the CPID endpoint MAY include an Accept-Language header depending on the clients access to user language preferences. If the header is included then human readable strings in updates that the DPA sends using the MDP API must use the settings provided in the CPID request.

The DPA MAY update user language preferences when it gets a request from GTAF with an Accept-Language header and use the updated user preferences to determine the language code in future requests to GTAF.

The DPA MUST specify the language used for user visible strings using languageCode. GTAF uses this to construct the title and the body of notifications shown to the user.