Add real-time developer notifications

Overview

Google Play Billing provides server push notifications that let you monitor state changes for Play-managed subscriptions and one-time purchases with pending transactions. By enabling real-time developer notifications, you'll receive a purchase token directly from Cloud Pub/Sub anytime there is an update to a pending transaction or an existing subscription.

Real-time developer notifications do not provide full information about the state of the subscription, such as whether the user is currently entitled to access subscription content. When you receive the token, you should always use the purchase token to query the Google Play Developer API to get the full information and update your backend with the user's current entitlement status.

Notification types might change in the future. You should be able to handle unrecognized notifications types, and you should always rely on the Google Play Developer API for critical business logic.

To enable this capability:

  1. Setup Cloud Pub/Sub using your own Google Cloud Platform (GCP) project.
  2. Enable real-time developer notifications for your Android app.

Setup Cloud Pub/Sub

Cloud Pub/Sub is a fully-managed real-time messaging service allowing you to send and receive messages between independent applications. It delivers low-latency, durable messaging that helps you quickly integrate systems hosted on the Google Cloud Platform and externally.

Google Play Billing uses the Cloud Pub/Sub to publish push notifications on topics to which you subscribe.

Establish prerequisites

To use the Cloud Pub/Sub, you must have a project on the Google Cloud Platform (GCP) with the Cloud Pub/Sub API enabled. If you are not familiar with GCP and Cloud Pub/Sub, read the Quickstart guide.

To receive the push notifications, you must create secure backend server to consume the messages sent to your topic. Your server can use the Cloud Pub/Sub Client Libraries libraries to consume the messages.

Create a topic

To start receiving the notifications, you need to create a topic to which the Google Play Billing should publish the notifications. To create a topic:

  1. Read the instructions in Create the topic.
  2. Use the Google Cloud Platform Console to create the topic.

Create a Pub/Sub subscription

To receive messages published to a topic, you must create a Pub/Sub subscription to that topic. To create a Pub/Sub subscription:

  1. Read the Cloud Pub/Sub Subscriber Guide to determine whether to configure the subscription as either a push subscription or pull subscription. A pull subscription requires your secure backend server to initiate requests to the Cloud Pub/Sub server to retrieve messages. A push subscription requires Cloud Pub/Sub to initiate requests to your secure backend server to deliver messages.
  2. Read the instructions in Add a subscription.
  3. Use the Google Cloud Platform Console to create the subscription.

Grant publish rights on your topic

Cloud Pub/Sub requires that you grant Google Play Billing privileges to publish notifications to your topic using the following steps:

  1. Open the Google Cloud Console.
  2. Select your project and click Pub/Sub in the left-hand navigation.
  3. Find your topic and open the permissions details.
    Figure 1. Accessing topic Permissions configuration.
  4. Add the service account google-play-developer-notifications@system.gserviceaccount.com and grant it the role of Pub/Sub Publisher.
    Figure 2. Adding Google Play service account as Pub/Sub publisher.
  5. Save to complete topic set up.
    Figure 3. Topic configured.

Enable real-time developer notifications for your app

To enable real-time developer notifications for your app:

  1. Open the Google Play Console.
  2. Select your Android app.
  3. Navigate to the Development tools > Services & APIs page.

  4. Scroll to the Real-time developer notifications section at the bottom of the page.

    Figure 4. Real-time developer notifications section.

  5. In the Topic name field, enter the full Cloud Pub/Sub topic name that you configured earlier. The topic name should be in the format of projects/{project_id}/topics/{topic_name} where project_id is the unique identifier for your project and topic_name is the name of the topic created earlier.

  6. Click Send Test Message to send a test message. Performing a test publish helps ensure that everything is setup and configured properly. If the test publish succeeds, a message is displayed stating that the test publish was successful. If you have a subscriber running for this topic, it should receive this test message.

    If the publish fails, an error is shown. Ensure that the topic name is correct and that google-play-developer-notifications@system.gserviceaccount.com service account has Pub/Sub Publisher access to the topic.

  7. Click Update Topic.

Change topic name

To change the topic name without dropping messages, perform the following steps:

  1. Create and configure the new topic and subscription.
  2. Begin reading and processing messages published to the new topic.
  3. Update the topic name for that app in the Play Console.
  4. Using Stackdriver or the Cloud Developer Console, wait for the old topic to stop receiving messages while ensuring the new topic is receiving messages.
  5. Delete the old topic after it has stopped receiving messages.

Delete a topic

To delete a topic:

  1. Remove your app's topic name using the Google Play Console.
  2. Once messages stop arriving, delete the Pub/Sub topic using Google or the Google Cloud Platform Console

Note: Deleting the topic in Pub/Sub before removing the name can result in dropped messages. You must re-setup the topic using Pub/Sub to fix this issue.

Scale notification processing

Due to the variety of notifications that can potentially be sent to the Pub/Sub topic, it may not be practical for you to have a single binary processing of all the notifications. There are variety of options to research when deciding how to scale your notification processing. These options include:

  • Using push and pull style notifications.
  • Setting up multiple subscriptions for a topic.
  • Republishing the notification message to other Pub/Sub projects.

For example, a single subscription can have multiple processes pulling messages from that subscription. The messages from that subscription is divided between the readers automatically. Each of these processes can then process the notification or route the request to a more specialized service.

New notification types may be added over time. Subscribers should be ready to gracefully handle new notifications if they appear, usually by acknowledging the received message.

Note: If you choose to use a push subscription, register your endpoints before adding the push endpoint. For more information, see Registering endpoints

For more information, refer to the Pub/Sub Subscriber Overview.

Monitor notification traffic

To monitor notification traffic, use the Google Stackdriver service. This service allows you to monitor traffic on a topic and set up alerts for certain conditions. For example, you can alert if your unacknowledged message count is too high (likely meaning there is a problem with the subscribers) or if the publish count is too low (likely meaning there is an issue publishing to the topic).

Determine pricing and quotas

For details on pricing and quotas, refer to pricing and quotas.

Estimate data usage

The data portion of the subscription notification is approximately 1KB of data per request. Each publish and pull require a separate request, or approximately 2KB of data per notification. The number of notifications per month depends on your billing cycle and your users' behavior. You should expect at least one notification for each user during a billing cycle.

SLA

The real-time developer notifications service does not offer an official latency SLA. However, most notifications should be published within a few seconds of the event occurring. You should monitor usage metrics on your Stackdriver page, such as number of unacknowledged Messages, to ensure you are processing all messages in a timely manner.

JSON Specification

Each publish made to a Pub/Sub topic contains a single base64-encoded DeveloperNotification with the following fields:

{
  "version": string,
  "packageName": string
  "eventTimeMillis": long
  "oneTimeProductNotification": OneTimeProductNotification
  "subscriptionNotification": SubscriptionNotification
  "testNotification": TestNotification
}
Property name Value Description
version string The version of this notification. Initially, this will be “1.0”. This version is distinct from other version fields.
packageName string The package name of the application that this notification relates to (for example, com.some.thing).
eventTimeMillis long The timestamp of that the event occurred, in milliseconds since the Epoch.
oneTimeProductNotification OneTimeProductNotification If this field is present, then this notification relates to a one-time product. It contains additional information related to the one-time product. This field is mutually exclusive with testNotification and subscriptionNotification.
subscriptionNotification SubscriptionNotification If this field is present, then this notification relates to a subscription. It contains additional information related to the subscription. This field is mutually exclusive with testNotification and oneTimeProductNotification.
testNotification TestNotification If this field is present, then this notification relates to a test publish. These are only sent through the Play Developer Console. This field is mutually exclusive with subscriptionNotification and oneTimeProductNotification.

A OneTimeProductNotification contains the following fields:

{
  "version": string
  "notificationType": int
  "purchaseToken": string
  "sku": string
}
Property name Value Description
version string The version of this notification. Initially, this will be “1.0”. This version is distinct from other version fields.
notificationType int

The type of notification. It can have the following values:

  • (1) ONE_TIME_PRODUCT_PURCHASED - A one time product was successfully purchased by a user.
  • (2) ONE_TIME_PRODUCT_CANCELED - A pending one-time product purchase has been canceled by the user.
purchaseToken string The token provided to the user’s device when purchase was made.
sku string The purchased one-time product ID (for example, ‘sword_001’).

Note: One-time product notifications are only sent for pending transactions. See the Play Billing Library 2.0 Release Notes for more information.

A SubscriptionNotification contains the following fields:

{
  "version": string
  "notificationType": int
  "purchaseToken": string
  "subscriptionId": string
}
Property name Value Description
version string The version of this notification. Initially, this will be “1.0”. This version is distinct from other version fields.
notificationType int

The type of notification. It can have the following values:

  • (1) SUBSCRIPTION_RECOVERED - A subscription was recovered from account hold.
  • (2) SUBSCRIPTION_RENEWED - An active subscription was renewed.
  • (3) SUBSCRIPTION_CANCELED - A subscription was either voluntarily or involuntarily cancelled. For voluntary cancellation, sent when the user cancels.
  • (4) SUBSCRIPTION_PURCHASED - A new subscription was purchased.
  • (5) SUBSCRIPTION_ON_HOLD - A subscription has entered account hold (if enabled).
  • (6) SUBSCRIPTION_IN_GRACE_PERIOD - A subscription has entered grace period (if enabled).
  • (7) SUBSCRIPTION_RESTARTED - User has reactivated their subscription from Play > Account > Subscriptions (requires opt-in for subscription restoration)
  • (8) SUBSCRIPTION_PRICE_CHANGE_CONFIRMED - A subscription price change has successfully been confirmed by the user.
  • (9) SUBSCRIPTION_DEFERRED - A subscription's recurrence time has been extended.
  • (10) SUBSCRIPTION_PAUSED - A subscription has been paused.
  • (11) SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED - A subscription pause schedule has been changed.
  • (12) SUBSCRIPTION_REVOKED - A subscription has been revoked from the user before the expiration time.
  • (13) SUBSCRIPTION_EXPIRED - A subscription has expired.
purchaseToken string The token provided to the user’s device when the subscription was purchased.
subscriptionId string The purchased subscription ID (for example, ‘monthly001’).

Note: Notifications are only sent for events that require changes to the user entitlement. For example, the refund API does not change the user entitlement, so it won't trigger a notification.

A TestNotification contains the following fields:

{
  "version": string
}
Property name Value Description
version string The version of this notification. Initially, this will be “1.0”. This version is distinct from other version fields.

Examples

Here is an example of a notification for a subscription purchase:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "subscriptionNotification":
  {
    "version":"1.0",
    "notificationType":4,
    "purchaseToken":"PURCHASE_TOKEN",
    "subscriptionId":"my.sku"
  }
}

Here is an example of a test notification:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503350156918",
  "testNotification":
  {
    "version":"1.0"
  }
}