# Push Notifications

## Overview

The Google Mobile Data Plan Sharing API also allows an operator to send
notifications to a user by pushing a
[PlanStatus](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.planStatuses#PlanStatus).

The API currently supports the following notifications:

1. **Low Balance** : when [PlanModule](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.PlanModule).coarseBalanceLevel is set to [LOW_QUOTA](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#balancelevel)
2. **Out of Data** : when [PlanModule](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.PlanModule).coarseBalanceLevel is set to [OUT_OF_DATA](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#balancelevel). If in addition to this, the [PlanModule](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.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](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.PlanModule).planModuleState is set to [EXPIRING_SOON](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#planstate)
4. **Plan Activation** : when [PlanModule](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.PlanModule).planModuleState is set to [NEWLY_ACTIVE](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#planstate)
5. **Pay as you go** : when [AccountInfo](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.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](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.planStatuses#AccountInfo).accountTopUp and [AccountInfo](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.planStatuses#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](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.planStatuses#AccountInfo).accountTopUp, are set to zero then the top up amount is not included in the notification.
7. **Data Expiration** : when [PlanModule](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.PlanModule).planModuleState is set to [EXPIRED](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#planstate). 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](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.UiCompatibility)
to `UI_INCOMPATIBLE`.

## Requirements

A notification
[PlanStatus](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.planStatuses#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 |