Device Group Messaging

With device group messaging, app servers can send a single message to multiple instances of an app running on devices belonging to a group. Typically, "group" refers a set of different devices that belong to a single user. However, a group could also represent a set of devices where the app instance functions in a highly correlated manner, such as a phone with a temperature control app installed, a smart thermostat, and an automatic window opener. All devices in a group share a common notification key, which is the token that GCM uses to fan out messages to all devices in the group.

Device group messaging makes it possible for every app instance in a group to reflect the latest messaging state. In addition to sending messages downstream to a notification key, you can enable devices to send upstream messages to a device group. You can use device group messaging with either the XMPP or HTTP connection server. The limit on data payload is 2KB when sending to iOS devices, and 4KB for other platforms.

Managing device groups

Before sending messages to a device group, you must:

1. Obtain registration tokens for each device in the group: see Registering Client Apps for detail.

2. Create the notification_key, which identifies the device group by mapping a particular group (typically a user) to all of the group’s associated registration tokens. You can create notification keys on the app server.

With a notification_key, instead of sending one message to one registration token at a time, the app server can send one message to the notification_key, and GCM then sends the message to all of the group’s registration tokens.

The maximum number of members allowed for a notification_key is 20.

Creating a device group

To create a device group, send a POST request that provides a name for the group, and a list of registration tokens for the devices. GCM returns a new notification_key that represents the device group.

Send a request like the following to https://android.googleapis.com/gcm/notification:

HTTP POST request

Send a request like the following to https://android.googleapis.com/gcm/notification:

https://android.googleapis.com/gcm/notification
Content-Type:application/json
Authorization:key=SERVER_KEY
project_id:SENDER_ID

{
   "operation": "create",
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["4", "8", "15", "16", "23", "42"]
}

The notification_key_name is a name or identifier (e.g., it can be a username) that is unique to a given group. The notification_key_name and notification_key are unique to a group of registration tokens. It is important that notification_key_name is unique per client app if you have multiple client apps for the same sender ID. This ensures that messages only go to the intended target app.

Response format

A successful request returns a notification_key like the following:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Save the notification_key and the corresponding notification_key_name to use in subsequent operations.

Adding and removing devices from a device group

To add or remove devices from an existing group, send a POST request with the operation parameter set to add or remove, and provide the registration tokens for addition or removal.

HTTP POST request

For example, to add a device with the registration ID 51 to appUser-Chris, you would send this request:

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["51"]
}

Response format

A successful request to either add or remove a device returns a notification_key like the following:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Sending downstream messages to device groups

Sending messages to a device group is very similar to sending messages to an individual device. Set the to parameter to the unique notification key for the device group. See Notifications and data in the message payload for details on payload support. Examples in this page show how to send data messages to device groups in HTTP and XMPP protocols.

HTTP POST Request

https://gcm-http.googleapis.com/gcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to": "aUniqueKey",
  "data": {
    "hello": "This is a GCM Device Group Message!",
   }
}

HTTP Response

Here is an example of "success"— the notification_key has 2 registration tokens 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 registration tokens associated with it. The message was successfully sent to 1 of the registration tokens only. The response message lists the registration tokens 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 body. When a message fails to be delivered to one or more of the registration tokens associated with a notification_key, the app server should retry.

XMPP Message

  <message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to": "aUniqueKey",
      "message_id": "m-1366082849205" ,
      "data": {
          "hello":"This is a GCM Device Group Message!"
      }
  }
  </gcm>
</message>

XMPP Response

When the message is sent to any one of the devices in the group successfully, the XMPP connection server responds with an ACK. If all messages sent to all devices in the group fail, XMPP connection server responds with a NACK.

Here is an example of "success" — the notification_key has 3 registration tokens associated with it, and the message was successfully sent to all of them:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

Here is an example of "partial success" — the notification_key has 3 registration tokens associated with it. The message was successfully sent to 1 of the registration tokens only. The response message lists the registration tokens that failed to receive the message:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

When the GCM connection server fails to deliver to all devices in the group, the app server will receive a NACK response.

For the full list of message options, see the reference information for your chosen connection server protocol, HTTP or XMPP.

Sending upstream messages to device groups

Client apps can send messages upstream to device groups by targeting messages to the appropriate notification key in the to field. The rest of this section provides platform-specific guidance for sending upstream messages to device groups.

Sending upstream messages to device groups on Android

The following call to GCM sends an upstream message to a notification key. The Bundle data consists of a key-value pair.

GoogleCloudMessaging gcm = GoogleCloudMessaging.get(context);
String to = aUniqueKey; // the 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);

Sending upstream messages to device groups on iOS

To send upstream messages to device groups on iOS, the iOS client app needs to implement both GGLInstanceID and GoogleCloudMessaging APIs. Specifically, it needs to set up and connect to GCM service so that upstream messages can be sent when client app is active.

// a unique global identifier for each message sent
int nextMessageID = self.messagesSent++;
NSDictionary *message = @{
  @"user" : [NSString stringWithFormat:"%lld", userID],
  @"hello" : @"world"
};
NSString *to = @"aUniqueKey"; // The notification key
[[GCMService sharedInstance] sendTo:to
                               withMessageID:nextMessageID
                               data:message];