Skip to content

Most visited

Recently visited

navigation

Real-time Developer Notifications

Overview

The In-app Billing API provides server push notifications that give developers the capability to monitor state changes for Play-managed subscriptions. To enable this capability, you will need to integrate your backend with Cloud Pub/Sub using your own Google Cloud Platform (GCP) project, and indicate in Google Play Console the Pub/Sub topic to which Play should publish notifications.

Initial Cloud Pub/Sub Setup

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

The In-app Billing API uses the Cloud Pub/Sub to publish push notifications on topics to which the developer subscribes.

Prerequisites

To use the Cloud Pub/Sub, you need to have project on the GCP with the Cloud Pub/Sub API enabled. If you are not familiar with GCP and Cloud Pub/Sub, check out this Quickstart guide that shows you how to get started.

To receive the push notifications, you will need to create an application in your backend to consume the messages sent to your topic. Currently, there are available client libraries for C#, Go, Java, Node.Js, PHP, Python and Ruby. Check the page Cloud Pub/Sub Client Libraries for full details about how to use these libraries.

Create a topic

To start receiving the notifications, you need to create a topic to which the In-app Billing API should publish the notifications. You can use the Google Cloud command-line tool to create the topic or the Google Cloud Platform Console to create the topic.

Create a subscription

Follow the Cloud Pub/Sub Subscriber Guide to set up a subscription to the topic that you created. You also can use the console to add a subscription. You can configure the subscription type to be either a webhook push (i.e. HTTP POST callback) or pull (i.e. initiated by your app). This is how your application will consume the messages with the notifications for updates.

Grant publish rights on your topic

Cloud Pub/Sub requires that you grant Google In-app Billing privileges to publish notifications to your topic using the steps below:

  1. Open the Google Cloud Console .
  2. Select your project and go to the Cloud Pub/Sub interface.
  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.

Updating the Google Play Console

Open the Google Play Console, and select the app for which you want to enable developer notifications. Navigate to the Development tools > Services & APIs page. Scroll to the bottom of the page to find the section Real-Time Developer Notifications.

Figure 4. Real-time Developer Notifications section.

Enter the full Cloud Pub/Sub topic name that you configured earlier. It should be in the format 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. This is the same topic name as the one seen earlier when creating the Pub/Sub topic.

Next, it is recommended to send a test message before saving the topic name. This can be done by clicking Send Test Message after entering the topic name. Performing a test publish helps ensure that everything is setup and configured properly before receiving real notifications. If the test publish succeeds, a message will be 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 will be 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.

When everything looks good, save the topic information by clicking Update Topic. If successful, you will begin receiving developer notifications.

Migrating or Deleting Topics

You may wish to change the topic name for receiving notifications for a particular app. In order to do this without dropping messages, you should perform the following steps:

  1. Create and configure the new topic and subscription. Begin reading and processing messages published to the new topic.
  2. Update the topic name for that app in the Play Console.
  3. Using Stackdriver or the Cloud Developer Console, wait for the old topic to stop receiving messages in lieu of the new topic.
  4. Delete the old topic once it is inactive.

To stop receiving messages, you must remove the topic name entry in the Play Console. Once messages stop arriving, you can delete the Pub/Sub topic.

Note: Deleting the topic in Pub/Sub beforehand may result in dropping messages until it is set up again.

Pulling from Pub/Sub

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 all of the notifications. Since the developer owns the Pub/Sub topic, they have a variety of options for scaling their notification processing. This includes deciding between push and pull style notifications, setting up multiple subscriptions for a topic, or 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 will be 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 acking the received message.

See Pub/Sub Subscriber Overview for more information.

Developer-side Monitoring and Alerting

To keep up with topic maintenance, you can take advantage of Google Stackdriver service. Stackdriver will allow developers to monitor traffic on their topic and set up alerts for certain conditions. For example, they can alert if their unack’d 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).

Pricing and Quota

Please see the Cloud Pub/Sub for details on pricing and quotas.

Data usage estimation

The data portion of the subscription notification is 1KB of data per request. Each publish and pull take a request, so that's 2KB per notification.

Assuming you handle 2 notifications per subscriber per month (this is an over-estimate for monthly subscribers since for active users you would receive 1 notification per month), each subscriber results in an estimated 4KB/month. That comes out to:

GB/Month = (# of subscribers) / 262144

For weekly subscriptions, divide this by ~4.4.

Note: This assumes 1 Pub/Sub subscription for the topic. Each pull from each Pub/Sub subscription counts towards the limit, so if you have 2 Pub/Sub subscriptions, you will use twice as much data.

SLA

This service does not offer an official latency SLA. Every notification type will be eventually published. Most notifications should be published within a few seconds of the event occurring. You should monitor the usage metrics on your Stackdriver page (such as number of Unacknowledged Messages) to ensure you are processing all messages in a timely manner.

Notification Types

Type Notes
SUBSCRIPTION_PURCHASED
SUBSCRIPTION_RENEWED
SUBSCRIPTION_RECOVERED Only if the user was on hold
SUBSCRIPTION_CANCELED Sent for both voluntary and involuntary cancellation. For voluntary cancellation, sent when the user cancels
SUBSCRIPTION_ON_HOLD Sent when the user enters account hold (if enabled)
SUBSCRIPTION_IN_GRACE_PERIOD Sent when the user enters grace period (if enabled)
SUBSCRIPTION_RESTARTED User has reactivated their subscription from the Play Store (requires subscription restoration opt-in from Play Console)

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.

JSON Specification

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

{
  "version": string,
  "packageName": string
  "eventTimeMillis": long
  "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.
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.
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.

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. A subscription was recovered from account hold.
  • 2. An active subscription was renewed.
  • 3. Sent for both voluntary and involuntary cancellation. For voluntary cancellation, sent when the user cancels.
  • 4. A new subscription was purchased.
  • 5. A subscription has entered account hold (if enabled).
  • 6. A subscription has entered grace period (if enabled).
  • 7. User has reactivated their subscription from Play - Account - Subscriptions (requires opt-in for subscription restoration)
purchaseToken string The token provided to the user’s device when the subscription was purchased.
subscriptionId string The purchased subscription ID (for example, ‘monthly001’).

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"
  }
}
This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)