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 |
- 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
-
config The 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
-
message The 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
-
handler The 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
-
message Key/Value pairs to be sent. Values must be String, any other type will be ignored. to String identifying the receiver of the message. For GCM project IDs the value is SENDER_ID@gcm.googleapis.com
.msgId A 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
-
message Key/Value pairs to be sent. Values must be String, any other type will be ignored. to A string identifying the receiver of the message. For GCM project IDs the value is SENDER_ID@gcm.googleapis.com
.ttl The 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. msgId The 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.