Quickview
- Learn how to send a single message to multiple devices owned by a single user.
In this document
- Request Format
- Generate a Notification Key
- Add Registration IDs
- Remove Registration IDs
- Send Upstream Messages
- Response Formats
See Also
Note: To try out this feature, sign up using this form.
With user notifications, 3rd-party app servers can send a single message to multiple instance of an app running on devices owned by a single user. This feature is called user notifications. User notifications make it possible for every app instance that a user owns to reflect the latest messaging state. For example:
- If a message has been handled on one device, the GCM message on the other devices are dismissed. For example, if a user has handled a calendar notification on one device, the notification will go away on the user's other devices.
- If a message has not been delivered yet to a device and but it has been handled, the GCM server removes it from the unsent queue for the other devices.
- Likewise, a device can send messages to the
notification_key
, which is the token that GCM uses to fan out notifications to all devices whose registration IDs are associated with the key.
The way this works is that during registration, the 3rd-party server requests
a notification_key
. The notification_key
maps a particular user
to all of the user's associated registration IDs (a regID represents a particular
Android application running on a particular device). Then instead of sending one
message to one regID at a time, the 3rd-party server can send a message to to the
notification_key
, which then sends the message to all of the user's regIDs.
Note: A notification dismissal message is like any
other upstream message, meaning that it will be delivered to the other devices that
belong to the specified notification_key
. You should design your app to
handle cases where the app receives a dismissal message, but has not yet displayed
the notification that is being dismissed. You can solve this by caching the dismissal
and then reconciling it with the corresponding notification.
You can use this feature with either the XMPP (CCS) or HTTP connection server.
The examples below show you how to perform generate/add/remove operations, and how to send upstream messages. For generate/add/remove operations, the message body is JSON.
Request Format
To send a message, the application server issues a POST request to
https://android.googleapis.com/gcm/notification
.
Here is the HTTP request header you should use for all create/add/remove operations:
content-type: "application/json" Header : "project_id": <projectID> Header: "Authorization", "key=API_KEY"
Generate a Notification Key
This example shows how to create a new notification_key
for a
notification_key_name
called appUser-Chris
.
The notification_key_name
is a name or identifier (can be a username for
a 3rd-party app) that is unique to a given user. It is used by third parties to
group together registration IDs for a single user. Note that notification_key_name
and notification_key
are unique to a group of registration IDs. It is also
important that notification_key_name
be uniquely named per app in case
you have multiple apps for the same project ID. This ensures that notifications
only go to the intended target app.
A create operation returns a token (notification_key
). Third parties
must save this token (as well as its mapping to the notification_key_name
)
to use in subsequent operations:
request: { "operation": "create", "notification_key_name": "appUser-Chris", "registration_ids": ["4", "8", "15", "16", "23", "42"] }
Add Registration IDs
This example shows how to add registration IDs for a given notification key.
The maximum number of members allowed for a notification_key
is 10.
Note that the notification_key_name
is not strictly required for
adding/removing regIDs. But including it protects you against accidentally using
the incorrect notification_key
.
request: { "operation": "add", "notification_key_name": "appUser-Chris", "notification_key": "aUniqueKey" "registration_ids": ["4", "8", "15", "16", "23", "42"] }
Remove Registration IDs
This example shows how to remove registration IDs for a given notification key:
request: { "operation": "remove", "notification_key_name": "appUser-Chris", "notification_key": "aUniqueKey" "registration_ids": ["4", "8", "15", "16", "23", "42"] }
Send Upstream Messages
To send an upstream (device-to-cloud) message, you must use the
GoogleCloudMessaging
API. Specifying a notification_key
as the target
for an upstream message allows a user on one device to send a message to other
devices in the notification group—for example, to dismiss a notification.
Here is an example that shows targeting a notification_key
:
GoogleCloudMessaging gcm = GoogleCloudMessaging.get(context); String to = NOTIFICATION_KEY; AtomicInteger msgId = new AtomicInteger(); String id = Integer.toString(msgId.incrementAndGet()); Bundle data = new Bundle(); data.putString("hello", "world"); gcm.send(to, id, data);
This call generates the necessary XMPP stanza for sending the message. The Bundle data consists of a key-value pair.
For a complete example, see Implementing GCM Client.
Response Formats
This section shows examples of the responses that can be returned for notification key operations.
Create/add/remove operations
When you make a request to create a notification_key
or to add/remove its
regIDs, a successful response always returns the notification_key
.
his is the notification_key
you will use for sending messages:
HTTP status: 200 { "notification_key": "aUniqueKey", // to be used for sending }
Send operations
For a send operation that has a notification_key
as its target, the
possible responses are success, partial success, and failure.
Here is an example of "success"—the notification_key
has 2 regIDs
associated with it, and the message was successfully sent to both of them:
{ "success": 2, "failure": 0 }
Here is an example of "partial success"—the notification_key
has
3 regIDs associated with it. The message was successfully send to 1 of the regIDs,
but not to the other 2. The response message lists the regIDs that failed to
receive the message:
{ "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
In the case of failure, the response has HTTP code 503 and no JSON. When a message
fails to be delivered to one or more of the regIDs associated with a notification_key
,
the 3rd-party server should retry.