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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
|
page.title=Server Reference
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol class="toc">
<li><a href="#downstream">Downstream Messages</a></li>
<ol class="toc">
<li><a href="#send-downstream">Sending a downstream message</a></li>
<li><a href="#interpret-downstream">Interpreting a downstream message response</a></li>
</ol>
<li><a href="#upstream">Upstream Messages (XMPP)</a>
<ol class="toc">
<li><a href="#interpret-upstream">Interpreting an upstream XMPP message</a></li>
<li><a href="#upstream-response">Sending an upstream XMPP message response</a></li>
</ol>
</li>
<li><a href="#ccs">Cloud Connection Server Messages (XMPP)</a></li>
<li><a href="#error-codes">Downstream message error response codes (HTTP and XMPP)</a></li>
</ol>
</div>
</div>
<p>This document provides a reference for the syntax used to pass
messages back and forth in GCM. These messages fall into
the following broad categories:</p>
<ul>
<li><a href="#downstream">Downstream messages</a></li>
<li><a href="#upstream">Upstream messages</a></li>
<li><a href="#ccs">Cloud Connection Server messages (XMPP)</a></li>
<li><a href="#error-codes">Downstream message error response codes (HTTP and XMPP)</a></li>
</ul>
<p>The following sections describe the basic requirements for
sending messages.</p>
<h2 id="downstream">Downstream Messages</h2>
<p>This is the message that a 3rd-party app server sends to a client app.
</p>
<p>A downstream message includes the following components:</p>
<ul>
<li>Target: specifies the recipient of the message.</li>
<li>Options: specifies attributes of the message.</li>
<li>Payload: specifies additional content to be included in the message. Optional.</li>
</ul>
<p>The syntax for each of these components is described in the tables below. </p>
<h3 id="send-downstream">Sending a downstream message</h3>
<p>This section gives the syntax for sending a downstream messages. For JSON,
these messages can be either HTTP or XMPP. For plain text, these messages can only be HTTP.</p>
<h4>Downstream HTTP or XMPP messages (JSON)</h4>
<p>The following table lists the targets, options, and payload for HTTP or XMPP JSON messages.</p>
<p class="table-caption" id="table1">
<strong>Table 1.</strong> Targets, options, and payload for downstream HTTP or XMPP message (JSON).</p>
<table border="1">
<tr>
<th>Parameter</th>
<th>Protocol</th>
<th>Usage</th>
<th>Description</th>
</tr>
<tr>
<td colspan="4"><strong>Targets</strong></td>
</tr>
<tr>
<td><code>to</code></td>
<td>XMPP</td>
<td>Required, string</td>
<td><p>This parameter specifies the recipient of a message. </p>
<p>The value must be a registration ID or notification key.</p>
<p>This parameter is used in XMPP in place of {@code registration_ids} or {@code notification_key} in HTTP.</p></td>
</tr>
<tr>
<td><code>registration_ids</code></td>
<td>HTTP</td>
<td>Required if {@code notification_key} not present, string array</td>
<td><p>This parameter specifies the list of devices (registration IDs)
receiving the message. It must contain at least 1 and at most 1000 registration IDs.</p>
<p>Multicast messages (sending to more than 1 registration IDs) are allowed using HTTP JSON format only.</p>
<p>This parameter or {@code notification_key} is used in HTTP in place of {@code to} in XMPP.</p></td>
</tr>
<tr>
<td><code>notification_key</code></td>
<td>HTTP</td>
<td>Required if {@code registration_ids} not present, string</td>
<td><p>This parameter specifies the mapping of a single user to
multiple registration IDs associated with that user.</p>
<p>This allows a 3rd-party app server to send a single message to multiple app instances
(typically on multiple devices) owned by a single user.</p>
<p>A 3rd-party app server can use {@code notification_key} as the target for a
message instead of an individual registration ID (or array of registration IDs).
The maximum number of members allowed for a {@code notification_key} is 20.</p>
<p>This parameter or {@code registration_ids} is used in HTTP in place of {@code to} in XMPP.</p>
<p>See <a href="notifications.html">User Notifications</a> for details.</p></td>
</tr>
<tr>
<td colspan="4"><strong>Options</strong></td>
</tr>
<tr>
<td><code>message_id</code></td>
<td>XMPP</td>
<td>Required, string</td>
<td><p>This parameter uniquely identifies a message in an XMPP connection.</p></td>
</tr>
<tr>
<td><code>collapse_key</code></td>
<td>HTTP, XMPP</td>
<td>Optional, string</td>
<td><p>This parameters identifies a group of messages (e.g., with
{@code collapse_key: "Updates Available"}) that can be collapsed, so that only the
last message gets sent when delivery can be resumed. This is intended to avoid sending too
many of the same messages when the device comes back online or becomes active (see {@code delay_while_idle}).</p>
<p>Note that there is no guarantee of the order in which messages get sent.</p>
<p>Messages with collapse key are also called
<a href="{@docRoot}google/gcm/server.html#s2s">send-to-sync messages</a> messages.
</p>
<p>Note: A maximum of 4 different collapse keys is allowed at any given time. This means a
GCM connection server can simultaneously store 4 different send-to-sync messages per client app. If you
exceed this number, there is no guarantee which 4 collapse keys the GCM connection server will keep. </p></td>
</tr>
<tr>
<td><code>delay_while_idle</code></td>
<td>HTTP, XMPP</td>
<td>Optional, JSON boolean</td>
<td>When this parameter is set to {@code true}, it indicates that the message should not be
sent until the device becomes active.</p>
<p>The default value is {@code false}.</p></td>
</tr>
<tr>
<td><code>time_to_live</code></td>
<td>HTTP, XMPP</td>
<td>Optional, JSON number</td>
<td><p>This parameter specifies how long (in seconds) the message should be kept in GCM storage
if the device is offline. The maximum time to live supported is 4 weeks.</p>
<p>The default value is 4 weeks. </p></td>
</tr>
<tr>
<td><code>delivery_receipt_
<br>requested</code></td>
<td>XMPP</td>
<td>Optional, JSON boolean</td>
<td><p>This parameter lets 3rd-party app server request confirmation of message delivery.</p>
<p>When this parameter is set to {@code true}, CCS sends a delivery receipt
when the device confirms that it received the message.</p>
<p>The default value is {@code false}.</p></td>
</tr>
<tr>
<td><code>restricted_package_
<br>name</code></td>
<td>HTTP</td>
<td>Optional, string</td>
<td>This parameter specifies the package name of the application where the
registration IDs must match in order to receive the message.</td>
</tr>
<tr>
<td><code>dry_run</code></td>
<td>HTTP</td>
<td>Optional, JSON boolean</td>
<td><p>This parameter, when set to {@code true}, allows developers to test a
request without actually sending a message.</p>
<p>The default value is {@code false}.</p></td>
</tr>
<tr>
<td colspan="4"><strong>Payload</strong></td>
</tr>
<tr>
<td><code>data</code></td>
<td>HTTP, XMPP</td>
<td>Optional, JSON object</td>
<td><p>This parameter specifies the key-value pairs of the message's payload. There is
no limit on the number of key-value pairs, but there is a total message size limit of 4kb.</p>
<p>For instance, in Android, <code>data:{"score":"3x1"}</code> would result in an intent extra
named {@code score} with the string value {@code 3x1}.</p>
<p>The key should not be a reserved word ({@code from} or any word starting with
{@code google}). It is also not recommended to use words defined in this table
(such as {@code collapse_key}) because that could yield unpredictable outcomes. </p>
<p>Values in string types are recommended. You have to convert values in objects
or other non-string data types (e.g., integers or booleans) to string.</p></td>
</tr>
</table>
<h3>Downstream HTTP messages (Plain Text)</h3>
<p>The following table lists the syntax for targets, options, and payload in plain
text downstream HTTP messages.</p>
<p class="table-caption" id="table2">
<strong>Table 2.</strong> Targets, options, and payload for downstream plain text HTTP messages.</p>
<table border="1">
<tr>
<th>Parameter</th>
<th>Usage</th>
<th>Description</th>
</tr>
<tr>
<td colspan="3"><strong>Targets</strong></td>
</tr>
<tr>
<td><code>registration _id</code></td>
<td>Required, string</td>
<td><p>This parameter specifies the client apps (registration ID) receiving the message.</p>
<p>Multicast messaging (sending to more than one registration ID) is allowed using HTTP JSON format only.</p></td>
</tr>
<tr>
<td colspan="3"><strong>Options</strong></td>
</tr>
<tr>
<td><code>collapse_key</code></td>
<td>Optional, string</td>
<td>See <a href="#table1">table 1</a> for details.</td>
</tr>
<tr>
<td><code>delay_while_idle</code></td>
<td>Optional, boolean or number</td>
<td>See <a href="#table1">table 1</a> for details.</td>
</tr>
<tr>
<td><code>time_to_live</code></td>
<td>Optional, number</td>
<td>See <a href="#table1">table 1</a> for details.</td>
</tr>
<tr>
<td><code>restricted_package_name</code></td>
<td>Optional, string</td>
<td>See <a href="#table1">table 1</a> for details.</td>
</tr>
<tr>
<td><code>dry_run </code></td>
<td>Optional, boolean</td>
<td>See <a href="#table1">table 1</a> for details.</td>
</tr>
<tr>
<td colspan="3"><strong>Payload</strong></td>
</tr>
<tr>
<td><code>data.<key></code></td>
<td>Optional, string</td>
<td><p>This parameter specifies the key-value pairs of the message's payload.
There is no limit on the number of key-value parameters,
but there is a total message size limit of 4kb.</p>
<p>For instance, in Android, <code>data:{"score":"3x1"}</code> would result in an intent extra
named {@code score} with the string value {@code 3x1}.</p>
<p>The key should not be a reserved word ({@code from} or any word starting with
{@code google}). It is also not recommended to use words defined in this table
(such as {@code collapse_key}) because that could yield unpredictable outcomes.</p></td>
</tr>
</table>
<h3 id="interpret-downstream">Interpreting a Downstream Message Response</h3>
<p>This section describes the syntax of a response to a downstream message. A client
app or the GCM Connection Server sends the response to 3rd-party app server upon processing
the message request. </p>
<h4>Interpreting a downstream HTTP message response </h4>
<p>The 3rd-party app server should look at both the message response header and the body
to interpret the message response sent from the GCM Connection Server. The following table
describes the possible responses.</p>
<p>
<p class="table-caption" id="table3">
<strong>Table 3.</strong> Downstream HTTP message response header.</p>
<table border=1>
<tr>
<th>Response</th>
<th>Description</th>
</tr>
<tr>
<td>200</td>
<td>Message was processed successfully. The response body will contain more
details about the message status, but its format will depend whether the request
was JSON or plain text. See <a href="#table4">table 4</a>
for more details.</td>
</tr>
<tr>
<td>400</td>
<td>Only applies for JSON requests.
Indicates that the request could not be parsed as JSON, or it contained invalid
fields (for instance, passing a string where a number was expected). The exact
failure reason is described in the response and the problem should be addressed
before the request can be retried.</td>
</tr>
<tr>
<td>401</td>
<td>There was an error authenticating the sender account.
<a href="server.html#auth_error">Troubleshoot</a></td>
</tr>
<tr>
<td>5xx</td>
<td>Errors in the 500-599 range (such as 500 or 503) indicate that there was
an internal error in the GCM server while trying to process the request, or that
the server is temporarily unavailable (for example, because of timeouts). Sender
must retry later, honoring any <code>Retry-After</code> header included in the
response. Application servers must implement exponential back-off.
<a href="server.html#internal_error">Troubleshoot</a></td>
</tr>
</table>
<p>The following table lists the fields in a downstream message response body
(JSON).</p>
<p class="table-caption" id="table4">
<strong>Table 4.</strong> Downstream HTTP message response body (JSON).</p>
<table>
<tr>
<th>Parameter</th>
<th>Usage</th>
<th>Description</th>
</tr>
<tr>
<td><code>multicast_id</code></td>
<td>Required, number</td>
<td>Unique ID (number) identifying the multicast message.</td>
</tr>
<tr>
<td><code>success</code></td>
<td>Required, number</td>
<td>Number of messages that were processed without an error.</td>
</tr>
<tr>
<td><code>failure</code></td>
<td>Required, number</td>
<td>Number of messages that could not be processed.</td>
</tr>
<tr>
<td><code>canonical_ids</code></td>
<td>Required, number</td>
<td>Number of results that contain a canonical registration ID. See the
<a href="{@docRoot}google/gcm/gcm.html#canonical">Overview</a> for more discussion of this topic.</td>
</tr>
<tr>
<td><code>results</code></td>
<td>Optional, array object</td>
<td>Array of objects representing the status of the messages processed. The
objects are listed in the same order as the request (i.e., for each registration
ID in the request, its result is listed in the same index in the response).<br>
<ul>
<li><code>message_id</code>: String specifying a unique ID for each successfully processed
message.</li>
<li><code>registration_id</code>: Optional string specifying the canonical registration ID
for the client app that the message was processed and sent to. Sender should use this
value as the Registration ID for future requests. Otherwise, the messages might
be rejected.
</li>
<li><code>error</code>: String specifying the error that occurred when processing the
message for the recipient. The possible values can be found in <a href="#table11">table 11
</a>.</li>
</ul></td>
</tr>
</table>
<p class="table-caption" id="table5">
<strong>Table 5.</strong> Success response for downstream HTTP message response body (Plain Text).</p>
<table border="1">
<tr>
<th>Parameter</th>
<th>Usage</th>
<th>Description</th>
</tr>
<tr>
<td><code>id</code></td>
<td>Required, string</td>
<td>This parameter specifies the unique message ID that GCM server processed successfully.</td>
</tr>
<tr>
<td><code>registration_id</code></td>
<td>Optional, string</td>
<td>This parameter specifies the canonical registration ID for the client app that the message was
processed and sent to. Sender should replace the registration ID with this value on future requests,
otherwise, the messages might be rejected.</td>
</tr>
</table>
<p class="table-caption" id="table6">
<strong>Table 6.</strong> Error response for downstream HTTP message response body (Plain Text).</p>
<table border="1">
<tr>
<th>Parameter</th>
<th>Usage</th>
<th>Description</th>
</tr>
<tr>
<td>{@code Error}</td>
<td>Required, string</td>
<td>This parameter specifies the error value while processing the message for the recipient.
See <a href="#table11">table 11</a> for details. </td>
</tr>
</table>
<h4>Interpreting a downstream XMPP message response</h4>
<p>The following table lists the fields that appear in a downstream XMPP message response.</p>
<p class="table-caption" id="table7">
<strong>Table 7.</strong> Downstream message XMPP message response body.</p>
<table border="1">
<tr>
<th>Parameter</th>
<th>Usage</th>
<th>Description</th>
</tr>
<tr>
<td><code>from</code></td>
<td>Required, string</td>
<td><p>This parameter specifies who sent this response.</p>
<p>The value is the registration ID of the client app.</p></td>
</tr>
<tr>
<td><code>message_id</code></td>
<td>Required, string</td>
<td>This parameter uniquely identifies a message in an XMPP connection.
The value is a string that uniquely identifies the associated message.</td>
</tr>
<tr>
<td><code>message_type</code></td>
<td>Required, string</td>
<td><p>This parameter specifies an 'ack' or 'nack' message from XMPP (CCS)
to the 3rd-party app server.</p>
<p>If the value is set to {@code nack}, the 3rd-party app server should look at
{@code error} and {@code error_description} to get failure information. </p></td>
</tr>
<tr>
<td><code>error</code></td>
<td>Optional, string</td>
<td>This parameter specifies an error related to the downstream message. It is set when the
{@code message_type} is {@code nack}. See <a href="#table11">table 6</a> for details.</td>
</tr>
<tr>
<td><code>error_description</code></td>
<td>Optional, string</td>
<td>This parameter provides descriptive information for the error. It is set
when the {@code message_type} is {@code nack}.</td>
</tr>
</table>
<h2 id="upstream">Upstream Messages (XMPP)</h2>
<p>An upstream message is a message the client app sends to the 3rd-party app server.
Currently only CCS (XMPP) supports upstream messaging.</p>
<h3 id="interpret-upstream">Interpreting an upstream XMPP message </h3>
<p>The following table describes the fields that appear in an upstream XMPP message.
<p class="table-caption" id="table8">
<strong>Table 8.</strong> Upstream XMPP messages.</p>
<table border="1">
<tr>
<th>Parameter</th>
<th>Usage</th>
<th>Description</th>
</tr>
<tr>
<td><code>from</code></td>
<td>Required, string</td>
<td><p>This parameter specifies who sent the message.</p>
<p>The value is the registration ID of the client app.</p></td>
</tr>
<tr>
<td><code>category</code></td>
<td>Required, string</td>
<td>This parameter specifies the application package name of the client app that sent the message. </td>
</tr>
<tr>
<td><code>message_id</code></td>
<td>Required, string</td>
<td>This parameter specifies the unique ID of the message. </td>
</tr>
<tr>
<td><code>data</code></td>
<td>Optional, string</td>
<td>This parameter specifies the key-value pairs of the message's payload.</td>
</tr>
</table>
<h3 id="upstream-response">Sending an upstream XMPP message response</h3>
<p>The following table describes the response that 3rd-party app server is expected to send to
<a href="{@docRoot}google/gcm/ccs.html">XMPP (CCS)</a> in response to an
upstream message it (the app server) received.</p>
<p class="table-caption" id="table9">
<strong>Table 9.</strong> Upstream XMPP message response.</p>
<table border="1">
<tr>
<th>Parameter</th>
<th>Usage</th>
<th>Description</th>
</tr>
<tr>
<td><code>to</code></td>
<td>Required, string</td>
<td><p>This parameter specifies the recipient of a response message. </p>
<p>The value must be a registration ID of the client app that sent the upstream message.</p></td>
</tr>
<tr>
<td><code>message_id</code></td>
<td>Required, string</td>
<td>This parameter specifies which message the response is intended for. The value must be
the {@code message_id} value from the corresponding upstream message.</td>
</tr>
<tr>
<td><code>message_type</code></td>
<td>Required, string</td>
<td>This parameter specifies an {@code ack} message from a 3rd-party app server to CCS.</td>
</tr>
</table>
<h2 id="ccs">Cloud Connection Server Messages (XMPP) </h2>
<p>This is a message sent from XMPP (CCS) to a 3rd-party app server. Here are the primary types
of messages that XMPP (CCS) sends to the 3rd-party app server:</p>
<ul>
<li><strong>Delivery Receipt:</strong> If the 3rd-party app server included {@code delivery_receipt_requested}
in the downstream message, XMPP (CCS) sends a delivery receipt when it receives confirmation
that the device received the message.</li>
<li><strong>Control:</strong> These CCS-generated messages indicate that
action is required from the 3rd-party app server.</li>
</ul>
<p>The following table describes the fields included in the messages CCS
sends to a 3rd-party app server.</p>
<p class="table-caption" id="table10">
<strong>Table 10.</strong> GCM Cloud Connection Server messages (XMPP).</p>
<table border="1">
<tr>
<th>Parameter</th>
<th>Usage</th>
<th>Description</th>
</tr>
<tr>
<td colspan="3"><strong>Common Field</strong></td>
</tr>
<tr>
<td><code>message_type</code></td>
<td>Required, string</td>
<td><p>This parameter specifies the type of the CCS message: either delivery receipt or control.</p>
<p>When it is set to {@code receipt}, the message includes {@code from}, {@code message_id},
{@code category} and {@code data} fields to provide additional information.</p>
<p>When it is set to {@code control}, the message includes {@code control_type} to indicate the
type of control message.</p></td>
</tr>
<tr>
<td colspan="3"><strong>Delivery receipt-specific</strong></td>
</tr>
<tr>
<td><code>from</code></td>
<td>Required, string</td>
<td>This parameter is set to {@code gcm.googleapis.com}, indicating that the
message is sent from CCS.</td>
</tr>
<tr>
<td><code>message_id</code></td>
<td>Required, string</td>
<td>This parameter specifies the original message ID that the receipt is intended for,
prefixed with {@code dr2:} to indicate that the message is a delivery receipt. A 3rd-party app
server must send an {@code ack} message with this message ID to acknowledge that it
received this delivery receipt. See <a href="#table9">table 9</a> for the 'ack' message format.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>Optional, string</td>
<td>This parameter specifies the application package name of the client app that
receives the message that this delivery receipt is reporting. This is available when
{@code message_type} is {@code receipt}.</td>
</tr>
<tr>
<td><code>data</code></td>
<td>Optional, string</td>
<td>This parameter specifies the key-value pairs for the delivery receipt message. This is available
when the {@code message_type} is {@code receipt}.
<ul>
<li>{@code message_status}: This parameter specifies the status of the receipt message.
It is set to {@code MESSAGE_SENT_TO_DEVICE} to indicate the device has confirmed its receipt of
the original message.</li>
<li>{@code original_message_id}: This parameter specifies the ID of the original message
that the 3rd-party app server sent to the client app.</li>
<li>{@code device_registration_id}: This parameter specifies the registration ID of the
client app to which the original message was sent.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="3"><strong>Control-specific</strong></td>
</tr>
<tr>
<td><code>control_type</code></td>
<td>Optional, string</td>
<td><p>This parameter specifies the type of control message sent from CCS.</p>
<p>Currently, only {@code CONNECTION_DRAINING} is supported. XMPP (CCS) sends this control message
before it closes a connection to perform load balancing. As the connection drains, no more messages
are allowed to be sent to the connection, but existing messages in the pipeline will
continue to be processed.</p></td>
</tr>
</table>
<h2 id="error-codes">Downstream message error response codes (HTTP and XMPP)</h2>
<p>The following table lists the error response codes for downstream messages (HTTP and XMPP).</p>
<p class="table-caption" id="table11">
<strong>Table 11.</strong> Downstream message error response codes.</p>
<table border="1">
<tr>
<th>Error</th>
<th>HTTP Code</th>
<th>XMPP Code</th>
<th>Recommended Action</th>
</tr>
<tr>
<td>Missing Registration ID</td>
<td>200 + error:MissingRegistration</td>
<td><code>INVALID_JSON</code></td>
<td>Check that the request contains a registration ID (either in the
{@code registration_id} in a plain text message, or in the {@code registration_ids} in JSON).</td>
</tr>
<tr>
<td>Invalid Registration ID</td>
<td>200 + error:InvalidRegistration</td>
<td><code>BAD_REGISTRATION</code></td>
<td>Check the format of the registration ID you pass to the server. Make sure it
matches the registration ID the client app receives from registering with GCM. Do not
truncate or add additional characters.</td>
</tr>
<tr>
<td>Unregistered Device</td>
<td>200 + error:NotRegistered</td>
<td><code>DEVICE_UNREGISTERED</code></td>
<td>An existing registration ID may cease to be valid in a number of scenarios, including:<br>
<ul>
<li>If the client app unregisters with GCM.</li>
<li>If the client app is automatically unregistered, which can happen if the user uninstalls the application.</li>
<li>If the registration ID expires (for example, Google might decide to refresh registration IDs).</li>
<li>If the client app is updated but the new version is not configured to receive messages.</li>
</ul>
For all these cases, remove this registration ID from the 3rd-party app
server and stop using it to send messages.</td>
</tr>
<tr>
<td>Invalid Package Name</td>
<td>200 + error:InvalidPackageName</td>
<td></td>
<td>Make sure the message was addressed to a registration ID whose package name
matches the value passed in the request.</td>
</tr>
<tr>
<td>Authentication Error</td>
<td>401</td>
<td> </td>
<td>The sender account used to send a message couldn't be authenticated. Possible causes are:<br>
<ul>
<li>Authorization header missing or with invalid syntax in HTTP request.</li>
<li>Invalid project number sent as key.</li>
<li>Key valid but with GCM service disabled.</li>
<li>Request originated from a server not whitelisted in the Server Key IPs.</li>
</ul>
Check that the token you're sending inside the Authentication header is
the correct API key associated with your project. See
<a href="{@docRoot}google/gcm/http.html">GCM HTTP Connection Server</a> for details.</td>
</tr>
<tr>
<td>Mismatched Sender</td>
<td>200 + error:MismatchSenderId</td>
<td><code>BAD_REGISTRATION</code></td>
<td>A registration ID is tied to a certain group of senders. When a client app registers
for GCM, it must specify which senders are allowed to send messages. You should use one
of those sender IDs when sending messages to the client app. If you switch to a different
sender, the existing registration IDs won't work.</td>
</tr>
<tr>
<td>Invalid JSON</td>
<td>400</td>
<td><code>INVALID_JSON</code></td>
<td>Check that the JSON message is properly formatted and contains valid fields
(for instance, making sure the right data type is passed in).</td>
</tr>
<tr>
<td>Message Too Big</td>
<td>200 + error:MessageTooBig</td>
<td><code>INVALID_JSON</code></td>
<td>Check that the total size of the payload data included in a message does
not exceed 4096 bytes. This includes both the the keys and the values.</td>
</tr>
<tr>
<td>Invalid Data Key</td>
<td>200 + error:
<br />
InvalidDataKey</td>
<td><code>INVALID_JSON</code></td>
<td>Check that the payload data does not contain a key (such as {@code from} or any value
prefixed by {@code google}) that is used internally by GCM. Note that some words (such as {@code collapse_key})
are also used by GCM but are allowed in the payload, in which case the payload value
will be overridden by the GCM value.</td>
</tr>
<tr>
<td>Invalid Time to Live</td>
<td>200 + error:InvalidTtl</td>
<td><code>INVALID_JSON</code></td>
<td>Check that the value used in {@code time_to_live} is an integer representing a
duration in seconds between 0 and 2,419,200 (4 weeks).</td>
</tr>
<tr>
<td>Bad ACK message</td>
<td>N/A</td>
<td><code>BAD_ACK</code></td>
<td>Check that the 'ack' message is properly formatted before retrying. See
<a href="#table9">table 9</a> for details.</td>
</tr>
<tr>
<td>Timeout</td>
<td>5xx or 200 + error:Unavailable</td>
<td><code>SERVICE_UNAVAILABLE</code></td>
<td><p>The server couldn't process the request in time. Retry the same request, but you must:<br>
<ul>
<li>For HTTP: Honor the {@code Retry-After} header if it is included in the response from the
GCM Connection Server.</li>
<li>Implement exponential back-off in your retry mechanism. (e.g. if you waited one second
before the first retry, wait at least two second before the next one, then 4 seconds and so on).
If you're sending multiple messages, delay each one independently by an additional random amount
to avoid issuing a new request for all messages at the same time.</li>
<li>For CCS: The initial retry delay should be set to 1 second.</li>
</ul>
<p>Senders that cause problems risk being blacklisted.</p></td>
</tr>
<tr>
<td>Internal Server Error</td>
<td>500 or 200 + error:InternalServerError</td>
<td><code>INTERNAL_SERVER_
<br />
ERROR</code></td>
<td>The server encountered an error while trying to process the request. You could retry
the same request following the requirements listed in "Timeout" (see row above). If the error persists, please
report the problem in the {@code android-gcm group}.</td>
</tr>
<tr>
<td>Device Message Rate Exceeded</td>
<td>200 + error:
<br />DeviceMessageRate
<br />
Exceeded</td>
<td><code>DEVICE_MESSAGE_RATE<br />
_EXCEEDED</code></td>
<td>The rate of messages to a particular device is too high. Reduce the
number of messages sent to this device and do not immediately retry sending to this device.</td>
</tr>
<tr>
<td>Connection Draining</td>
<td>N/A</td>
<td><code>CONNECTION_DRAINING</code></td>
<td>The message couldn't be processed because the connection is draining. This happens because
periodically, XMPP (CCS) needs to close down a connection to perform load balancing. Retry the message over
another XMPP connection.</td>
</tr>
</table>
|