To verify that they can send and receive messages, client apps must register with GCM. In this process, the client obtains a unique registration token and passes it to the app server, which stores the token and sends an acknowledgement back to the client app. The registration token exchanged in this process is the same client app instance identifier that the app server uses to send messages to the particular client.
To register with GCM:
- The client app obtains a registration token using the Instance ID API. The call to this API must have the authorized entity set to your app server's sender ID, and the scope set to the appropriate value for GCM (depending on your platform). Refer to the API reference for full detail on this API.
- The client app passes the registration token to the app server.
- The app server saves the registration token and acknowledges to the client app that the process completed successfully.
If the app server fails to complete its part of the registration handshake, the client app should retry sending registration token to the server or delete the registration token.
For detailed platform-specific examples of how to register client apps, see the client guide for your platform.
Automatic Retry Using Exponential Back-Off
If registration fails, the client app is recommended to retry. In cases where GCM is not essential to the client app's functioning, the app could ignore the registration error and try to register again the next time it starts. Otherwise, it should retry the registration operation using exponential back-off (the client app should wait twice the previous amount of time before retrying).
Client apps should handle unregistration failure in the same way.
If a bug in the client app triggers multiple registrations for the same device, it can be hard to reconcile state and the client app might end up with duplicate messages.
Implementing canonical IDs can help you more easily recover from these situations. A canonical registration ID is the registration token of the last registration requested by the client app . This is the ID that the server should use when sending messages to the device.
If you try to send a message using an old registration token, GCM will process
the request as usual, but it will include the canonical ID in the
registration_id field of the response. Make sure to
replace the registration token stored in your server with this canonical ID,
as eventually the old registration token will stop working.
Unregistration and Unsubscription
There are three methods a client app can use to stop receiving messages and/or topic subscriptions from the app server:
deleteToken()with audience set to the app server's sender ID and scope set to
GCM. This stops messages (including topic messages) from a specific app server
deleteID(). This stops messages from all previous registrations and topic subscriptions for all app servers
unsubscribe(). This stops topic messages from the specific topic of the app server
A client app should call these unregistration and unsubscription functions only if it needs to stop receiving messages. Developers should never unregister the client app as a mechanism for logout or for switching between users, for the following reasons:
- A registration token isn't associated with a particular logged in user. If the client app unregisters and then re-registers, the app can receive the same registration token or a different registration token.
- Unregistration and re-registration may each take up to five minutes to propagate. During this time messages may be rejected due to the unregistered state, and messages may go to the wrong user.
To make sure that messages go to the intended user:
- The app server can maintain a mapping between the current user and the registration token.
- The client app can then check to ensure that messages it receives match the logged in user.
How uninstalled client app unregistration works
A client app can be automatically unregistered after it is uninstalled. However, this process does not happen immediately. What happens in this scenario is:
- The end user uninstalls the client app.
- The app server sends a message to GCM connection server.
- The GCM connection server sends the message to the GCM client on the device.
- The GCM client on the device receives the message and detects that the client app has been uninstalled; the detection details depend on the platform on which the client app is running.
- The GCM client on the device informs the GCM connection server that the client app was uninstalled.
- The GCM connection server marks the registration token for deletion.
- The app server sends a message to GCM.
- The GCM returns a NotRegistered error message to the app server.
- The app server should delete the registration token.
Note that it might take a while for the registration token to be completely removed from GCM. Thus it is possible that messages sent during step 7 above get a valid message ID as a response, even though the message will not be delivered to the client app. Eventually, the registration token will be removed and the server will get a NotRegistered error, without any further action being required from the app server.