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 low balance notification to the user.

Identifying relevant users

The DPA needs a way to determine which users' data to send to GTAF. GTAF expects to receive updates for the following users:

  1. Active CPIDs: users with active CPIDs. Until the CPIDs that have been generated by the CPID endpoint are valid, the DPA SHOULD send updates about a user's data plan. If the Accept-Language header was set at the time of CPID creation, then the human readable strings in data plan status MUST be in that language.
  2. Registered MSISDNs: to serve applications that have access to the MSISDN, GTAF will register the MSISDN with DPA as described in the msisdn registration section of the Data Plan Agent API. Once the MSISDN is registered, DPA SHOULD send updates about the user's data plan until the registration expires.

API Description

Sharing Data Plan Status

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

Applications can receive data plan status information in 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.
    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 UE.
  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.

GTAF-DPA Interaction

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

{
  "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.

Plan Status Push for Default Client

GTAF continues to support 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 the same for the per client use case and the default client use case.

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. 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.