GCMService Class

Instance Methods | Class Methods

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

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 [e-mail].
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 [e-mail].
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.