GGLContext Class

GGLContext Class Reference

Overview

Main entry point for Google API core configuration.

Google services such as AdMob, Analytics, AppInvite, CloudMessaging, SignIn, etc can be configured via this class and its categories. See GGLContext+ServiceName for details on the individual APIs. Generally, you will import those files directly rather than import the GGLContext.h header itself.

Once the appropriate categories are imported, you can configure all services via the configureWithError: method, for example:

NSError* configureError;
[[GGLContext sharedInstance] configureWithError: &configureError];
if (configureError != nil) {
  NSLog("Error configuring the Google context: %", configureError);
}

The method configureWithError: will read from the file GoogleServices-Info.plist bundled with your app target for the keys to configure each individual API. To generate your GoogleServices-Info.plist, please go to https://developers.google.com/mobile/add

See also
GGLContext (AdMob)
GGLContext (Analytics)
GGLContext (AppInvite)
GGLContext (CloudMessaging)
GGLContext (SignIn)

Inherits NSObject.

Instance Method Summary

(void) - configureWithError:
 Configures all the Google services integrated. More...
 
(void) - fetchInstanceIDTokenWithAPNSToken:handler:
 Gets an InstanceID token scoped for GCM using the gcmSenderID. More...
 
(void) - startGCMService
 Start the Google Cloud Messaging service after setting the appropriate properties. More...
 
(void) - startGCMServiceWithConfig:
 Start the Google Cloud Messaging service with the given config. More...
 
(void) - stopGCMService
 Stop the Google Cloud Messaging service. More...
 
(void) - connectToGCMWithHandler:
 Creates a connection to Google Cloud Messaging, which will be used to receive push and topic notifications when the app is in the foreground, and to send upstream messages. More...
 
(void) - disconnectFromGCM
 Closes an existing connection to GCM, if present. More...
 
(void) - subscribeToTopic:withHandler:
 Subscribe to a GCM pubsub topic. More...
 
(void) - unsubscribeFromTopic:withHandler:
 Unsubscribe the client from a GCM pubsub topic. More...
 

Class Method Summary

(instancetype) + sharedInstance
 Get the shared instance of the GGLContext. More...
 

Properties

GGLConfigurationconfiguration
 The configuration details for various Google APIs. More...
 
NSString * adUnitIDForBannerTest
 Provides an AdUnitID to use the banner view. More...
 
NSString * adUnitIDForInterstitialTest
 Provides an AdUnitID to use the interstitial view. More...
 
GADBannerView * bannerView
 Provides a GADBannerView configured using adUnitIDForBannerTest. More...
 
GADInterstitial * interstitialView
 Provides an GADInterstitial configured using adUnitIDForInterstitialTest. More...
 
id< GAITracker > tracker
 Retrieve a configured GAITracker instance. More...
 
GINInviteTargetApplication * targetApp
 App Invite requires defining the client ID if the invite is received on a different platform than iOS. More...
 
NSString * gcmSenderID
 The Project Number used to configure Google Cloud Messaging. More...
 
NSString * registrationToken
 Provides a token identifying this instance of the app, which can be used by a remote server to push messages to this client. More...
 

Method Detail

+ (instancetype) sharedInstance

Get the shared instance of the GGLContext.

Returns
the shared instance
- (void) configureWithError: (NSError **)  error

Configures all the Google services integrated.

This method should be called after the app is launched and before using other Google services. The services will be available in categories that extend this class, such as GGLContext+AdMob.

Parameters
errorPointer to an NSError that can be used an out param to report the status of this operation. After the call the error object will be nil if the operation is succesful, otherwise contains an appropriate NSError value. Parameter cannot be passed as nil
Warning
error must not be nil.
- (void) fetchInstanceIDTokenWithAPNSToken: (NSData *)  apnsToken
handler: (GGLInstanceIDTokenHandler)  handler 

Gets an InstanceID token scoped for GCM using the gcmSenderID.

This allows the app to receive push notifications using Apple Push Notification Service (APNS).

This method should be called on app launch after -[[GGLContext sharedInstance] configureWithError:] has completed.

Parameters
apnsTokenThe APNS token returned from UIApplication's didRegisterForRemoteNotificationsWithDeviceToken method.
handlerThe handler to be invoked once the InstanceID token has been successfully fetched.

Provided by category GGLContext(CloudMessaging).

- (void) startGCMService

Start the Google Cloud Messaging service after setting the appropriate properties.

Call this only once during the lifetime of the app before you start using Google Cloud Messaging.

Uses the default config to start the service. The log level is set to DEBUG and it does not provide an implementation for GCMReceiverDelegate.

Provided by category GGLContext(CloudMessaging).

- (void) startGCMServiceWithConfig: (GCMConfig *)  config

Start the Google Cloud Messaging service with the given config.

Call this only once during the lifetime of the app before you start using Google Cloud Messaging.

Parameters
configThe GCMConfig used to start the service.

Provided by category GGLContext(CloudMessaging).

- (void) stopGCMService

Stop the Google Cloud Messaging service.

Stop all the operations associated with it and clear any objects or data associated with it. Call this only once during the lifetime of your app when you don't want to use Google Cloud Messaging anymore.

Provided by category GGLContext(CloudMessaging).

- (void) connectToGCMWithHandler: (GCMServiceConnectCompletion)  handler

Creates a connection to Google Cloud Messaging, which will be used to receive push and topic notifications when the app is in the foreground, and to send upstream messages.

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

This method should be called on app launch after -[[GGLContext sharedInstance] configureWithError:], in -[fetchInstanceIDTokenWithAPNSToken:handler:]'s completion handler. As well as each time the app enters the foreground.

Parameters
handlerThe handler to be invoked once the GCM connection has been established. If a connection cannot be established, this will be invoked with an error and the process will retry using an exponential backoff.

Provided by category GGLContext(CloudMessaging).

- (void) disconnectFromGCM

Closes an existing connection to GCM, if present.

Disables connection retries if the connection has not yet been established.

This method should be called each time the app enters the background or terminates.

Provided by category GGLContext(CloudMessaging).

- (void) subscribeToTopic: (NSString *)  topic
withHandler: (GCMPubSubCompletion)  handler 

Subscribe to a GCM pubsub topic.

The topic name should match the regex "/topics/[a-zA-Z0-9-_.~%]{1,900}".

Parameters
topicThe topic to subscribe to.
handlerThe completion handler to invoke when the subscription request finishes.

Provided by category GGLContext(CloudMessaging).

- (void) unsubscribeFromTopic: (NSString *)  topic
withHandler: (GCMPubSubCompletion)  handler 

Unsubscribe the client from a GCM pubsub topic.

The topic name should match the regex "/topics/[a-zA-Z0-9-_.~%]{1,900}".

Parameters
topicThe topic to unsubscribe from.
handlerThe completion handler to invoke when the unsubsribe request finishes.

Provided by category GGLContext(CloudMessaging).

Property Documentation

- (GGLConfiguration*) configuration
readnonatomicstrong

The configuration details for various Google APIs.

- (NSString*) adUnitIDForBannerTest
readnonatomicstrong

Provides an AdUnitID to use the banner view.

This value can be updated by changing the AD_UNIT_ID_FOR_BANNER_TEST in GoogleService-Info.plist.

Provided by category GGLContext(AdMob).

- (NSString*) adUnitIDForInterstitialTest
readnonatomicstrong

Provides an AdUnitID to use the interstitial view.

This value can be updated by changing the AD_UNIT_ID_FOR_INTERSTITIAL_TEST in GoogleService-Info.plist.

Provided by category GGLContext(AdMob).

- (GADBannerView*) bannerView
readwritenonatomicstrong

Provides a GADBannerView configured using adUnitIDForBannerTest.

Provided by category GGLContext(AdMob).

- (GADInterstitial*) interstitialView
readwritenonatomicstrong

Provides an GADInterstitial configured using adUnitIDForInterstitialTest.

Provided by category GGLContext(AdMob).

- (id<GAITracker>) tracker
readnonatomicstrong

Retrieve a configured GAITracker instance.

Note that [[GAI sharedInstance] defaultTracker] is the first initialized tracker. If a developer initializes a tracker before calling -[[GGLContext sharedInstance] configureWithError:], -[[GAI sharedInstance] defaultTracker] is the one initialized first. The one initialized through GGLContext can be accessed by either [[GAI sharedInstance] trackerWithTrackingId:"UA-XXXX-Y"] or [GGLContext sharedInstance].tracker.

Provided by category GGLContext(Analytics).

- (GINInviteTargetApplication*) targetApp
readnonatomicstrong

App Invite requires defining the client ID if the invite is received on a different platform than iOS.

If an Android client ID is defined in the GoogleService-Info.plist it will automatically be configured as a target app for new invites. This property allows retreving a copy of that GINInviteTargetApplication.

Provided by category GGLContext(AppInvite).

- (NSString*) gcmSenderID
readnonatomicstrong

The Project Number used to configure Google Cloud Messaging.

It will be ready to use once -[[GGLContext sharedInstance] configureWithError:] is called.

See also
GGLContext configure

Provided by category GGLContext(CloudMessaging).

- (NSString*) registrationToken
readnonatomicstrong

Provides a token identifying this instance of the app, which can be used by a remote server to push messages to this client.

It will only be ready to use after -[[GGLContext sharedInstance] configureWithError:] has been called and -[fetchInstanceIDTokenWithAPNSToken:handler:]'s completion handler has been invoked.

See also
GGLContext configure

Provided by category GGLContext(CloudMessaging).