diff options
Diffstat (limited to 'docs/html/guide/google/gcm/gcm.jd')
| -rw-r--r-- | docs/html/guide/google/gcm/gcm.jd | 20 |
1 files changed, 14 insertions, 6 deletions
diff --git a/docs/html/guide/google/gcm/gcm.jd b/docs/html/guide/google/gcm/gcm.jd index f471560..5515f31 100644 --- a/docs/html/guide/google/gcm/gcm.jd +++ b/docs/html/guide/google/gcm/gcm.jd @@ -203,7 +203,7 @@ ID in a database. </li> <p>The registration ID lasts until the Android application explicitly unregisters itself, or until Google refreshes the registration ID for your Android application.</p> -<p class="note"><strong>Note:</strong> When users uninstall an application, it is not automatically unregistered on GCM. It is only unregistered when the GCM server tries to send a message to the device and the device answers that the application is uninstalled. At that point, you server should mark the device as unregistered (the server will receive a <code><a href="#unreg_device">NotRegistered</a></code> error). +<p class="note"><strong>Note:</strong> When users uninstall an application, it is not automatically unregistered on GCM. It is only unregistered when the GCM server tries to send a message to the device and the device answers that the application is uninstalled or it does not have a broadcast receiver configured to receive <code>com.google.android.c2dm.intent.RECEIVE</code> intents. At that point, you server should mark the device as unregistered (the server will receive a <code><a href="#unreg_device">NotRegistered</a></code> error). <p> Note that it might take a few minutes for the registration ID to be completed removed from the GCM server. So if the 3rd party server sends a message during this time, it will get a valid message ID, even though the message will not be delivered to the device.</p> </p> @@ -546,7 +546,7 @@ private void handleRegistration(Intent intent) { deliver the messages sent by the 3rd-party server to the application running in the device. If the server included key-pair values in the <code>data</code> parameter, they are available as extras in this intent, with the keys being the extra names. GCM also includes an extra called -<code>from</code> which contains the sender ID as an string. +<code>from</code> which contains the sender ID as an string, and another called <code>collapse_key</code> containing the collapse key (when in use). <p>Here is an example, again using the <code>MyIntentReceiver</code> class:</p> @@ -653,7 +653,7 @@ message sent by the application server. See <a href="adv.html#collapsible">Advan <td><code>data</code></td> <td>A JSON object whose fields represents the key-value pairs of the message's payload data. If present, the payload data it will be included in the Intent as application data, with the key being the extra's name. For instance, <code>"data":{"score":"3x1"}</code> would result in an intent extra named <code>score</code> whose value is the string <code>3x1</code>. -There is no limit on the number of key/value pairs, though there is a limit on the total size of the message (4kb). Note that the values <em>must be enclosed by strings</em>. If you want to include objects or other non-string data types (such as integers or booleans), you have to do the conversion to string yourself. Also note that the key cannot be a reserved word (<code>from</code> or any word starting with <code>google.</code>). Optional.</td> +There is no limit on the number of key/value pairs, though there is a limit on the total size of the message (4kb). The values could be any JSON object, but we recommend using strings, since the values will be converted to strings in the GCM server anyway. If you want to include objects or other non-string data types (such as integers or booleans), you have to do the conversion to string yourself. Also note that the key cannot be a reserved word (<code>from</code> or any word starting with <code>google.</code>). To complicate things slightly, there are some reserved words (such as <code>collapse_key</code>) that are technically allowed in payload data. However, if the request also contains the word, the value in the request will overwrite the value in the payload data. Hence using words that are defined as field names in this table is not recommended, even in cases where they are technically allowed. Optional.</td> </tr> <tr> @@ -685,7 +685,8 @@ sent. Optional. The default value is <code>false</code>, and must be a JSON bool </tr> <tr> <td><code>data.<key></code></td> - <td>Payload data, expressed as parameters prefixed with <code>data.</code> and suffixed as the key. For instance, a parameter of <code>data.score=3x1</code> would result in an intent extra named <code>score</code> whose value is the string <code>3x1</code>. There is no limit on the number of key/value parameters, though there is a limit on the total size of the message. Note that the key cannot be a reserved word (<code>from</code> or any word starting with <code>google.</code>). Optional.</td> + <td>Payload data, expressed as parameters prefixed with <code>data.</code> and suffixed as the key. For instance, a parameter of <code>data.score=3x1</code> would result in an intent extra named <code>score</code> whose value is the string <code>3x1</code>. There is no limit on the number of key/value parameters, though there is a limit on the total size of the message. Also note that the key cannot be a reserved word (<code>from</code> or any word starting with +<code>google.</code>). To complicate things slightly, there are some reserved words (such as <code>collapse_key</code>) that are technically allowed in payload data. However, if the request also contains the word, the value in the request will overwrite the value in the payload data. Hence using words that are defined as field names in this table is not recommended, even in cases where they are technically allowed. Optional.</td> </tr> <tr> <td><code>delay_while_idle</code></td> @@ -816,7 +817,7 @@ the HTTP response contains a non-200 status code (such as 400, 401, or 503).</p> <li>Otherwise, get the value of <code>error</code>: <ul> <li>If it is <code>Unavailable</code>, you could retry to send it in another request.</li> - <li>If it is <code>NotRegistered</code>, you should remove the registration ID from your server database because the application was uninstalled from the device.</li> + <li>If it is <code>NotRegistered</code>, you should remove the registration ID from your server database because the application was uninstalled from the device or it does not have a broadcast receiver configured to receive <code>com.google.android.c2dm.intent.RECEIVE</code> intents.</li> <li>Otherwise, there is something wrong in the registration ID passed in the request; it is probably a non-recoverable error that will also require removing the registration from the server database. See <a href="#error_codes">Interpreting an error response</a> for all possible error values.</li> </ul> </li> @@ -850,6 +851,7 @@ has the format of <code>registration_id=<em>canonical ID</em></code>. The second <dt id="invalid_reg"><strong>Invalid Registration ID</strong></dt> <dd>Check the formatting of the registration ID that you pass to the server. Make sure it matches the registration ID the phone receives in the <code>com.google.android.c2dm.intent.REGISTRATION</code> intent and that you're not truncating it or adding additional characters. <br/>Happens when error code is <code>InvalidRegistration</code>.</dd> + <dt id="mismatched_sender"><strong>Mismatched Sender</strong></dt> <dd>A registration ID is tied to a certain group of senders. When an application registers for GCM usage, it must specify which senders are allowed to send messages. Make sure you're using one of those when trying to send messages to the device. If you switch to a different sender, the existing registration IDs won't work. Happens when error code is <code>MismatchSenderId</code>.</dd> @@ -860,15 +862,21 @@ Happens when error code is <code>MismatchSenderId</code>.</dd> <li>If the application manually unregisters by issuing a <span class="prettyprint pretty-java"><code>com.google.android.c2dm.intent.UNREGISTER</code></span><code> </code>intent.</li> <li>If the application is automatically unregistered, which can happen (but is not guaranteed) if the user uninstalls the application.</li> <li>If the registration ID expires. Google might decide to refresh registration IDs. </li> + <li>If the application is updated but the new version does not have a broadcast receiver configured to receive <code>com.google.android.c2dm.intent.RECEIVE</code> intents.</li> </ul> For all these cases, you should remove this registration ID from the 3rd-party server and stop using it to send messages. <br/>Happens when error code is <code>NotRegistered</code>.</dd> - <dt id="big_msg"><strong>Message Too Big</strong></dt> +<dt id="big_msg"><strong>Message Too Big</strong></dt> <dd>The total size of the payload data that is included in a message can't exceed 4096 bytes. Note that this includes both the size of the keys as well as the values. <br/>Happens when error code is <code>MessageTooBig</code>.</dd> +<dt id="invalid_datakey"><strong>Invalid Data Key</strong></dt> +<dd>The payload data contains a key (such as <code>from</code> or any value prefixed by <code>google.</code>) that is used internally by GCM in the <code>com.google.android.c2dm.intent.RECEIVE</code> Intent and cannot be used. Note that some words (such as <code>collapse_key</code>) are also used by GCM but are allowed in the payload, in which case the payload value will be overridden by the GCM value. +<br /> +Happens when the error code is <code>InvalidDataKey</code>.</dd> + <dt id="ttl_error"><strong>Invalid Time To Live</strong></dt> <dd>The value for the Time to Live field must be an integer representing a duration in seconds between 0 and 2,419,200 (4 weeks). Happens when error code is <code>InvalidTtl</code>. </dd> |