# Set up Pub/Sub notifications

> [!NOTE]
> **Note:** Existing EMM partners with [programmatically created ESAs](https://developers.google.com/android/work/play/emm-api/create-enterprise#create_enterprise_service_accounts_programmatically) need to register their preferred Cloud project with Google before setting up Pub/Sub notifications for Android Management API. For more details, see the [Guide for existing EMM partners](https://developers.google.com/android/management/existing-emms#set_up_pubsub_notifications).

Pub/Sub notifications provide a way for you to receive alerts about newly
enrolled devices, device reports, and recently issued [commands](https://developers.google.com/android/management/introduction#commands).

To set up Pub/Sub notifications, you need to enable the Pub/Sub API and create a
*topic*. To receive messages published to a topic, create a subscription to that
topic. The subscription connects the topic to a subscriber application that
receives and processes messages published to the topic. After you create a
subscription, you need to grant Android Device Policy permission to publish to
your topic.

## 1. Enable the Pub/Sub API for your project

For instructions on how to enable the Pub/Sub API, see the
[console quickstart guide](https://cloud.google.com/pubsub/docs/quickstart-console#before-you-begin). Ensure that you select the **same project** that
the [Android Management API is enabled for](https://developers.google.com/android/management/service-account#enable_the_android_management_api).

## 2. Create a topic

After enabling the API, you need to create a topic that Android Device Policy
can publish notifications to. There are two ways to create a topic:

a. Manually in the [Google Cloud console](https://cloud.google.com/pubsub/docs/quickstart-console#create_a_topic).  

b. Using the Pub/Sub API (see [create topic method](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/create)).

After creating a topic, take note of the topic name.

## 3. Create a subscription

A subscription captures the stream of messages published to a given topic. There
are two ways to create a subscription:

a. Manually in the [Google Cloud console](https://cloud.google.com/pubsub/docs/quickstart-console#add_a_subscription).  

b. Using the Pub/Sub API (see [create subscription method](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/create)).

## 4. Grant Android Device Policy the right to publish to your topic

You need to give android-cloud-policy@system.gserviceaccount.com permission to
publish to your topic. There are two ways to grant publishing rights:

a. Manually in the [Google Cloud console](https://cloud.google.com/pubsub/docs/access_control#console).

- Add android-cloud-policy@system.gserviceaccount.com as a member to your topic.
- Click **Select a role** \> **Pub/Sub** \> **Pub/Sub Publisher**.

b. Using the Pub/Sub API (see [Controlling access through the IAM API](https://cloud.google.com/pubsub/docs/access_control#api))

- Add `serviceAccount:android-cloud-policy@system.gserviceaccount.com` to `members`.
- Set `role` to `roles/pubsub.publisher`.

## 5. Update enterprise to support notifications

Skip this step if the notification you want to support is `ENTERPRISE_UPGRADE`,
which is always supported.

To connect notifications about an enterprise to the topic you created, call
[`enterprises.patch`](https://developers.google.com/android/management/reference/rest/v1/enterprises/patch)
and specify the following parameters:

- `pubsubTopic`: The name of your pub/sub topic in the form `projects/{project}/topics/{topic}`.
- `enabledNotificationTypes`: Include all the notification [types](https://developers.google.com/android/management/reference/rest/v1/enterprises#NotificationType) you want to receive.

## 6. Use the Pub/Sub API to get notifications

A subscription can use either the push or pull mechanism for message delivery.
Guidelines and directions on how to receive notifications through both of these
mechanisms are available in the [Pub/Sub Subscriber Guide](https://cloud.google.com/pubsub/docs/subscriber).

## Message format

Messages take the form of a [PubsubMessage](https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage).
The `attributes` field of the message contains an attribute with key
`notificationType` and value set to the notification type that triggered the
message (e.g. `ENROLLMENT`). The `data` field of the message contains the JSON
representation of the resource that was updated, encoded as a UTF-8 string. The
notifications and their corresponding resource types are as follows:

- `COMMAND` notifications use the resource type [Operation](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices.operations#resource-operation).
- `USAGE_LOGS` notifications use the resource type [UsageLogEvent](https://developers.google.com/android/management/reference/rest/v1/BatchUsageLogEvents#usagelogevent).
- `ENROLLMENT` and `STATUS_REPORT` notifications use the resource type [Device](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#resource-device).
- `ENTERPRISE_UPGRADE` notifications use the resource type [EnterpriseUpgradeEvent](https://developers.google.com/android/management/reference/rest/v1/EnterpriseUpgradeEvent).

When setting the `pubsubTopic` on an Enterprise, an initial message will be
published with `notificationType` set to `test`. This message is sent to verify
Android Device Policy has the publish permission on the topic and should be
ignored.

> [!NOTE]
> **Note:** When using the Pub/Sub REST API, the `data` field is encoded as a base64 string. To get the resource JSON, first perform base64 decoding on the contents of `data`, then interpret the resulting bytes as a UTF-8 string.

## Expected latency

Enterprise upgrade events are expected to be sent immediately.

Local device events that occur in quick succession are batched and reported in a
single Pub/Sub message to EMMs.

| Event type | Expected latency between on-device event and corresponding EMM notification^[1](https://developers.google.com/android/management/notifications#fn1)^ |
|---|---|
| High priority [keyed app states](https://developers.google.com/android/management/app-feedback) | Immediate, at most one report per minute |
| Standard priority [keyed app states](https://developers.google.com/android/management/app-feedback) | Within one minute |
| Application-related events during provisioning, for apps with install states defined by the IT admin^[2](https://developers.google.com/android/management/notifications#fn2)^ | Within one minute on top of other related provisioning events |
| Application-related events after provisioning, for apps with install states defined by the IT admin. | Within 5 minutes |
| Application-related events both during and after provisioning, for apps with install states defined by the employee^[3](https://developers.google.com/android/management/notifications#fn3)^ | Within 60 minutes |
| Other on-device app events | Within 60 minutes |

*** ** * ** ***

1. Best effort targets based on controlled circumstances. Actual latency may
   vary according to a variety of device and environmental factors. [↩](https://developers.google.com/android/management/notifications#fnref1)

2. [`InstallType`](https://developers.google.com/android/management/reference/rest/v1/enterprises.policies#installtype) of apps enforced in the policy: `FORCE_INSTALLED`,
   `BLOCKED`, `REQUIRED_FOR_SETUP`, `PREINSTALLED` and `KIOSK`. [↩](https://developers.google.com/android/management/notifications#fnref2)

3. [`InstallType`](https://developers.google.com/android/management/reference/rest/v1/enterprises.policies#installtype) of available apps: `AVAILABLE`,
   `INSTALL_TYPE_UNSPECIFIED`. [↩](https://developers.google.com/android/management/notifications#fnref3)