Important: We are no longer accepting new registrations for the Play EMM API. Learn more.

Enable EMM push notifications

This guide assumes that you already have a manually created ESA and shows you how to configure it for use with EMM push notifications. The tasks are completed by the ESA owner (you, as EMM solution provider, or your customer) using the Google API Console:

1. Enable Google Cloud Pub/Sub API access in the Google API Console for a cloud project.

2. Grant Editor permissions to the ESA.

3. Set up a project to receive EMM notifications.

4. Send a test EMM notification.

5. Subscribe to the topic.

These steps are outlined more completely in the sections below.

1. Enable Cloud Pub/Sub API access for a project

To activate the Cloud Pub/Sub API for your project:

  1. In the API Console, open the API Library. Select the project (or create a new one, if necessary). The API Library lists all available APIs, grouped by product family and popularity.
  2. Under Google Cloud APIs, find the Cloud Pub/Sub API. (If it's not visible in the list, use search to find it.)
  3. Select Cloud Pub/Sub API and then click Enable.

After you enable an API, from the APIs & Services menu, click Dashboard to see a list of all your enabled APIs. Before the Cloud Pub/Sub API can be used for messages to your customer, you must grant Editor permissions to that customer’s service account (its ESA).

2. Grant Editor permissions to the ESA

From the API Console, grant the necessary permissions:

  1. From the APIs & Services menu, click Credentials. You should see your customer’s ESA listed under Service account keys.
  2. Click Manage service accounts to open all the service accounts associated with the project.
  3. From the list, select the appropriate ESA account, and then click Permissions.
  4. In the Add members field:
    • Enter the email address associated with the ESA.
    • From the drop-down selector, choose Editor (next to the entry field).
  5. Click Add to save the Permissions.

3. Set up a project to receive EMM notifications

With the Cloud Pub/Sub API enabled and an ESA configured with Editor permissions, you can configure a project to receive EMM notifications as detailed in Set up EMM push notifications. Briefly, the setup process involves configuring an HTTP server endpoint to push notifications to subscribers.

EMM notifications are delivered as protobufs (protocol buffers, a simple format for serializing structured data) packed as byte64-encoded byte-array messages inside JSON packets. In your code, you must parse this JSON and decode the protocol buffer content. Here’s an example of a base64 URL-safe encoded protobuf for a NewPermissionsEvent notification:


CglDMTIzNDU2NzgQgM-C6sMqOooBChdhcHA6Y29tLmZha2VhcHAuZXhhbXBsZRIpYW5kcm9pZ
C5wZXJtaXNzaW9uLldSSVRFX0VYVEVSTkFMX1NUT1JBR0UaKGFuZHJvaWQucGVybWlzc2lvbi5SRUF
EX0VYVEVSTkFMX1NUT1JBR0UaGmFuZHJvaWQucGVybWlzc2lvbi5WSUJSQVRF

It decodes to:


{
 enterprise_id: "C12345678"
 event_notification_sent_timestamp_millis: 1461316528000 # 1.33Ti;
    [as milliseconds]: 2016-04-22 10:15:28 +0100
 new_permissions_event: {
   product_id: "app:com.fakeapp.example"
   requested_permissions: [ "android.permission.WRITE_EXTERNAL_STORAGE" ]
   approved_permissions : [ "android.permission.READ_EXTERNAL_STORAGE",
    "android.permission.VIBRATE" ]
  }
}

To decode the protobuf-formatted EMM notifications, you can use the emm_pubsub.proto file located in the google/play-work repository on GitHub. When new notification types are added, that file is extended with the new type and the sample code is updated. These changes should be backward-compatible, but make sure your code can cope gracefully with receiving notifications of unknown types in addition to those listed in the .proto file.

4. Send a test EMM notification

Sending a test notification allows you to confirm that you have successfully set up your system to receive EMM notifications from Google Play, and also allows you to learn the topic name (the same topic name is used to deliver all Google Play EMM notifications).

Using the Play EMM API, call the sendTestPushNotification method on the Enterprises resource.

Invoking this operation causes a test EMM notification to be sent. If EMM notifications are properly configured, the API returns the following:

    {
        topic_name: "/projects/project-name/topics/play-work-012345",
        message_id: "128976912439"
    }

5. Subscribe to the topic

Using the sample code provided in Run the publisher test code (in the Set up EMM push notifications guide), subscribe to the specified topic. You should receive the test EMM notification, along with any real notifications that were generated since you began the configuration process.