Push Notifications

  • The Google Mobile Data Plan Sharing API enables operators to send various plan-related notifications to users, such as low balance, out-of-data, and plan expiration warnings.

  • Notifications are triggered by specific plan status updates and include relevant information about the user's plan, improving the user experience.

  • Operators must include certain required fields for each notification type to ensure the notification text can be generated properly.

  • The API supports sending multiple notifications simultaneously if multiple status fields are updated within a single PlanStatus.

  • Carriers should set UiCompatibility to UI_INCOMPATIBLE if the notification's plan status is incomplete and shouldn't be displayed to the user directly.

Overview

The Google Mobile Data Plan Sharing API also allows an operator to send notifications to a user by pushing a PlanStatus.

The API currently supports the following notifications:

  1. Low Balance: when PlanModule.coarseBalanceLevel is set to LOW_QUOTA
  2. Out of Data: when PlanModule.coarseBalanceLevel is set to OUT_OF_DATA. If in addition to this, the PlanModule.overUsagePolicy is set to PAY_AS_YOU_GO, then the user will be notified that they are about to enter pay as you go mode.
  3. Data Expiration Warning: when PlanModule.planModuleState is set to EXPIRING_SOON
  4. Plan Activation: when PlanModule.planModuleState is set to NEWLY_ACTIVE
  5. Pay as you go: when AccountInfo.payAsYouGoCharge is populated with the amount that the user has spent. If the accountBalance is populated, then the notification shows the remaining balance on the account.
  6. Account top up: when AccountInfo.accountTopUp and AccountInfo.accountBalance are populated. Both these fields are required to send the account top up notification to the user. If units and nanos in AccountInfo.accountTopUp, are set to zero then the top up amount is not included in the notification.
  7. Data Expiration: when PlanModule.planModuleState is set to EXPIRED. This is for plans that are already expired.

One notification is sent to the user for each field set. If multiple coarseBalanceLevel or planModuleState fields are set in a single PlanStatus, then an equal number of notifications will be sent to the user.

The plan status which triggers the notification is sent to user device to update the on device cache. This improves user experience by showing a recent plan status when the user clicks on the notification. If the plan status used for sending a notification is not complete and should not be shown to the user, then the carrier MUST set UiCompatibility to UI_INCOMPATIBLE.

Requirements

A notification PlanStatus SHOULD contain as much information as possible about the user's mobile plan. For each type of notification, the Data Plan Sharing API also defines a minimum set of fields which are required to build the notification text. The operator MUST include these fields in a notification PlanStatus.

Notification Required Fields
Low Balance PlanModule.moduleName, PlanModule.byteBalance.remainingBytes
Out of Data PlanModule.moduleName
Data Expiration Warning PlanModule.moduleName, PlanModule.expirationTime
Plan Activation PlanModule.moduleName
Pay as you go AccountInfo.payAsYouGoCharge
Account top up AccountInfo.accountTopUp
Data Expiration PlanModule.moduleName