1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
page.title=User Notifications
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>Learn how to send a single message to multiple devices owned by a single user.</li>
</ul>
<h2>In this document</h2>
<ol class="toc">
<li><a href="#what">What are User Notifications?</a> </li>
<li><a href="#examples">Examples</a>
<ol>
<li><a href="#create">Generate a notification key</a></li>
<li><a href="#add">Add registration IDs</a></li>
<li><a href="#remove">Remove registration IDs</a></li>
<li><a href="#upstream">Send upstream messages</a></li>
<li><a href="#response">Response formats</a></li>
</ol>
</li>
</ol>
<h2>See Also</h2>
<ol class="toc">
<li><a href="{@docRoot}google/play-services/gcm/gs.html">Getting Started</a></li>
<li><a href="https://services.google.com/fb/forms/gcm/" class="external-link" target="_android">CCS and User Notifications Signup Form</a></li>
</ol>
</div>
</div>
<p class="note"><strong>Note:</strong> To try out this feature, sign up using <a href="https://services.google.com/fb/forms/gcm/">this form</a>.</p>
<p>The upstream messaging (device-to-cloud) feature described in this document is part of the Google Play services platform. Upstream messaging is available through the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">GoogleCloudMessaging</a> APIs. To use upstream messaging and the new streamlined registration process, you must <a href="{@docRoot}google/play-services/setup.html">set up</a> the Google Play services SDK.</p>
<h2 id="what">What are User Notifications?</h2>
<p>Third party servers can send a single message to multiple instance of an app running on devices owned by a single user. This feature is called <em>user notifications</em>. User notifications make it possible for every app instance that a user owns to reflect the latest messaging state. For example:</p>
<ul>
<li>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.</li>
<li>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.</li>
<li>Likewise, a device can send messages to the {@code notification_key}, which is the token that GCM uses to fan out notifications to all devices whose registration IDs are associated with the key.</li>
</ul>
<p>The way this works is that during registration, the 3rd-party server requests a {@code notification_key}. The {@code 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 {@code notification_key}, which then sends the message to all of the user's regIDs.</p>
<p class="note"><strong>Note:</strong> 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 {@code 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.
</p>
<p>You can use this feature with either the new <a href="ccs.html">GCM Cloud Connection Server</a> (CCS), or the older <a href="gcm.html">GCM HTTP server</a>.</p>
<h3 id="examples">Examples</h3>
<p>The examples in this section 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.</p>
<h4 id="request">Request format</h4>
<p>To send a message, the application server issues a POST request to <code>https://android.googleapis.com/gcm/notification</code>.</p>
<p>Here is the HTTP request header you should use for all create/add/remove operations:</p>
<pre>content-type: "application/json"
Header : "project_id": <projectID>
Header: "Authorization", "key=API_KEY"
</pre>
<h4 id="create">Generate a notification key</h4>
<p>This example shows how to create a new <code>notification_key</code> for a <code>notification_key_name</code> called <code>appUser-Chris</code>. The {@code 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 <code>notification_key_name</code> and <code>notification_key</code> are unique to a group of registration IDs. It is also important that <code>notification_key_name</code> 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.</p>
<p>A create operation returns a token (<code>notification_key</code>). Third parties must save this token (as well as its mapping to the <code>notification_key_name</code>) to use in subsequent operations:</p>
<pre>request:
{
"operation": "create",
"notification_key_name": "appUser-Chris",
"registration_ids": ["4", "8", "15", "16", "23", "42"]
}</pre>
<h4 id="add">Add registration IDs</h4>
<p>This example shows how to add registration IDs for a given notification key. The maximum number of members allowed for a {@code notification_key} is 10.</p>
<p>Note that the <code>notification_key_name</code> is not strictly required for adding/removing regIDs. But including it protects you against accidentally using the incorrect <code>notification_key</code>.</p>
<pre>request:
{
"operation": "add",
"notification_key_name": "appUser-Chris",
"notification_key": "aUniqueKey"
"registration_ids": ["4", "8", "15", "16", "23", "42"]
}</pre>
<h4 id="remove">Remove registration IDs</h4>
<p>This example shows how to remove registration IDs for a given notification key:</p>
<pre>request:
{
"operation": "remove",
"notification_key_name": "appUser-Chris",
"notification_key": "aUniqueKey"
"registration_ids": ["4", "8", "15", "16", "23", "42"]
}</pre>
<h4 id="upstream">Send upstream messages</h4>
<p>To send an upstream (device-to-cloud) message, you must use the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">GoogleCloudMessaging</a> API. Specifying a {@code 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 {@code notification_key}:</p>
<pre>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);
</pre>
<p>This call generates the necessary XMPP stanza for sending the message. The Bundle data consists of a key-value pair.</p>
<p>For a complete example, see <a href="gs.html#gs_example">Getting Started</a>.
<h4 id="response">Response formats</h4>
<p>This section shows examples of the responses that can be returned for notification key operations.</p>
<h5>Response for create/add/remove operations</h5>
<p>When you make a request to create a {@code notification_key} or to add/remove its the wayregIDs, a successful response always returns the <code>notification_key</code>. This is the {@code notification_key} you will use for sending messages:</p>
<pre>HTTP status: 200
{
"notification_key": "aUniqueKey", // to be used for sending
}</pre>
<h5>Response for send operations</h5>
<p>For a send operation that has a {@code notification_key} as its target, the possible responses are success, partial success, and failure.</p>
<p>Here is an example of "success"—the {@code notification_key} has 2 regIDs associated with it, and the message was successfully sent to both of them:</p>
<pre>{
"success": 2,
"failure": 0
}</pre>
<p>Here is an example of "partial success"—the {@code 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:</p>
<pre>{
"success":1,
"failure":2,
"failed_registration_ids":[
"regId1",
"regId2"
]
}</pre>
<p>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 {@code notification_key}, the 3rd-party server should retry.</p>
|
