Firebase Cloud Messaging (FCM) is the new version of GCM. It inherits the reliable and scalable GCM infrastructure, plus new features! See the FAQ to learn more. If you are integrating messaging in a new app, start with FCM. GCM users are strongly recommended to upgrade to FCM, in order to benefit from new FCM features today and in the future. Before you go, please visit our GCM and FCM developer survey to give us feedback!

GCMService Class

GCMService Class Reference

Overview

GoogleCloudMessaging (GCM) enables apps to communicate with their app servers using simple messages.

To send or receive messages, the app must get a registration token from GGLInstanceID, which authorizes an app server to send messages to an app instance. Pass your sender ID and kGGLInstanceIDScopeGCM as parameters to the method.

A sender ID is a project number created when you configure your API project. It is labeled "Project Number" in the Google Developers Console.

In order to receive GCM messages, declare application:didReceiveRemoteNotification:

Client apps can send upstream messages back to the app server using the XMPP-based Cloud Connection Server,

Inherits NSObject.

Instance Method Summary

(void) - startWithConfig:
 Start the GCMService with config. More...
 
(void) - teardown
 Teardown the GCM connection and free all the resources owned by GCM. More...
 
(BOOL) - appDidReceiveMessage:
 Call this to let GCM know that the app received a downstream message. More...
 
(void) - connectWithHandler:
 Create a GCM data connection which will be used to send the data notifications send by your server. More...
 
(void) - disconnect
 Disconnect the current GCM data connection. More...
 
(void) - sendMessage:to:withId:
 Send an upstream ("device to cloud") message. More...
 
(void) - sendMessage:to:timeToLive:withId:
 Send an upstream ("device to cloud") message. More...
 

Class Method Summary

(instancetype) + sharedInstance
 GCMService. More...
 

Method Detail

+ (instancetype) sharedInstance

GCMService.

Returns
A shared instance of GCMService.
- (void) startWithConfig: (GCMConfig *)  config

Start the GCMService with config.

This starts the GCMService and allocates the required resources.

See also
GCMConfig
Parameters
configThe GCMConfig used to build the service.
- (void) teardown

Teardown the GCM connection and free all the resources owned by GCM.

Call this when you don't need the GCM connection or to cancel all subscribe/unsubscribe requests. If GCM connection is alive before calling this, it would implicitly disconnect the connection.

Calling disconect before invoking this method is useful but not required. Once you call this you won't be able to use GCMService for this session of your app. Therefore call this only when the app is going to exit. In case of background you should rather use disconnect and then if the app comes to the foreground again you can call connect again to establish a new connection.

- (BOOL) appDidReceiveMessage: (NSDictionary *)  message

Call this to let GCM know that the app received a downstream message.

Used to detect duplicate messages and to track message delivery for messages with different routes.

Parameters
messageThe downstream message received by the app.
Returns
For APNs messages this always returns FALSE. For other messages, this returns FALSE for new, non-duplicated messages.
- (void) connectWithHandler: (GCMServiceConnectCompletion)  handler

Create a GCM data connection which will be used to send the data notifications send by your server.

It will also be used to send ACKS and other messages based on the GCM ACKS and other messages based on the GCM protocol.

Use the disconnect method to disconnect the connection.

See also
GCMService - disconnect
Parameters
handlerThe handler to be invoked once the connection is established. If the connection fails we invoke the handler with an appropriate error code letting you know why it failed. At the same time, GCM performs exponential backoff to retry establishing a connection and invoke the handler when successful.
- (void) disconnect

Disconnect the current GCM data connection.

This stops any attempts to connect to GCM. Calling this on an already disconnected client is a no-op.

Call this before teardown when your app is going to the background. Since the GCM connection won't be allowed to live when in background it is prudent to close the connection.

See also
GCMService - teardown
- (void) sendMessage: (NSDictionary *)  message
to: (NSString *)  to
withId: (NSString *)  msgId 

Send an upstream ("device to cloud") message.

The message will be queued if we don't have an active connection for the max interval.

Parameters
messageKey/Value pairs to be sent. Values must be String, any other type will be ignored.
toString identifying the receiver of the message. For GCM project IDs the value is SENDER_ID@gcm.googleapis.com.
msgIdA unique ID of the message. This is generated by the application. It must be unique for each message. This allows error callbacks and debugging.
- (void) sendMessage: (NSDictionary *)  message
to: (NSString *)  to
timeToLive: (int64_t)  ttl
withId: (NSString *)  msgId 

Send an upstream ("device to cloud") message.

The message will be queued if we don't have an active connection for the max interval. You can only use the upstream feature if your GCM implementation uses the XMPP-based Cloud Connection Server.

Parameters
messageKey/Value pairs to be sent. Values must be String, any other type will be ignored.
toA string identifying the receiver of the message. For GCM project IDs the value is SENDER_ID@gcm.googleapis.com.
ttlThe Time to live for the message. In case we aren't able to send the message before the ttl expires we will send you a callback. If 0, we'll attempt to send immediately and return an error if we're not connected. Otherwise, the message will be queued.As for server-side messages, we don't return an error if the message has been dropped because of TTL; this can happen on the server side, and it would require extra communication.
msgIdThe ID of the message. This is generated by the application. It must be unique for each message. It allows error callbacks and debugging, to uniquely identify each message.

Send feedback about...

Cloud Messaging
Cloud Messaging