GGLInstanceID Class

Overview

Instance ID provides a unique identifier for each app instance and a mechanism to authenticate and authorize actions (for example, sending a GCM message).

Instance ID is long lived but, may be reset if the device is not used for a long time or the Instance ID service detects a problem. If Instance ID is reset, the app will be notified with a callback to [GGLInstanceIDDelegate onTokenRefresh]

If the Instance ID has become invalid, the app can request a new one and send it to the app server. To prove ownership of Instance ID and to allow servers to access data or services associated with the app, call [GGLInstanceID tokenWithAuthorizedEntity:scope:options:handler].

Inherits <NSObject>.

Instance Method Summary

(void) - startWithConfig:
 Start GGLInstanceID with the specified config. More...
 
(void) - stopAllRequests
 Stop any network requests started by the client and release any handlers associated with it. More...
 
(void) - tokenWithAuthorizedEntity:scope:options:handler:
 Returns a token that authorizes an Entity (example: cloud service) to perform an action on behalf of the application identified by Instance ID. More...
 
(void) - deleteTokenWithAuthorizedEntity:scope:handler:
 Revokes access to a scope (action) for an entity previously authorized by [GGLInstanceID tokenWithAuthorizedEntity:scope:options:handler]. More...
 
(void) - getIDWithHandler:
 Asynchronously fetch a stable identifier that uniquely identifies the app instance. More...
 
(void) - deleteIDWithHandler:
 Resets Instance ID and revokes all tokens. More...
 

Class Method Summary

(instancetype) + sharedInstance
 GGLInstanceID. More...
 

Public Attributes

NSString *const kGGLInstanceIDRegisterAPNSOption
 
NSString *const kGGLInstanceIDAPNSServerTypeSandboxOption
 
NSString *const kGGLInstanceIDScopeGCM
 

Related Function Summary

(Note that these are not member functions.)

typedef void(^ GGLInstanceIDTokenHandler )(NSString *token, NSError *error)
 
typedef void(^ GGLInstanceIDDeleteTokenHandler )(NSError *error)
 
typedef void(^ GGLInstanceIDHandler )(NSString *identity, NSError *error)
 
typedef void(^ GGLInstanceIDDeleteHandler )(NSError *error)
 

Method Detail

+ (instancetype) sharedInstance

GGLInstanceID.

Returns
A shared instance of GGLInstanceID.
- (void) startWithConfig: (GGLInstanceIDConfig *)  config

Start GGLInstanceID with the specified config.

See also
GGLInstanceIDConfig
Parameters
configThe GGLInstanceIDConfig used to build the service.
- (void) stopAllRequests

Stop any network requests started by the client and release any handlers associated with it.

- (void) tokenWithAuthorizedEntity: (NSString *)  authorizedEntity
scope: (NSString *)  scope
options: (NSDictionary *)  options
handler: (GGLInstanceIDTokenHandler handler 

Returns a token that authorizes an Entity (example: cloud service) to perform an action on behalf of the application identified by Instance ID.

This is similar to an OAuth2 token except, it applies to the application instance instead of a user.

This is an asynchronous call. If the token fetching fails for some reason we invoke the completion callback with nil token and the appropriate error.

Note, you can only have one token or deleteToken call for a given authorizedEntity and scope at any point of time. Making another such call with the same authorizedEntity and scope before the last one finishes will result in an error with code OperationInProgress.

See also
GGLInstanceID - deleteTokenWithAuthorizedEntity:scope:handler:
Parameters
authorizedEntityEntity authorized by the token.
scopeAction authorized for authorizedEntity.
optionsThe extra options to be sent with your token request. The value for the apns_token should be the NSData object passed to UIApplication's didRegisterForRemoteNotificationsWithDeviceToken method. All other keys and values in the options dict need to be instances of NSString or else they will be discarded. Bundle keys starting with 'GCM.' and 'GOOGLE.' are reserved.
handlerThe callback handler which is invoked when the token is successfully fetched. In case of success a valid token and nil error are returned. In case of any error the token is nil and a valid error is returned. The valid error codes have been documented above.
- (void) deleteTokenWithAuthorizedEntity: (NSString *)  authorizedEntity
scope: (NSString *)  scope
handler: (GGLInstanceIDDeleteTokenHandler handler 

Revokes access to a scope (action) for an entity previously authorized by [GGLInstanceID tokenWithAuthorizedEntity:scope:options:handler].

This is an asynchronous call. Call this on the main thread since InstanceID lib is not thread safe. In case token deletion fails for some reason we invoke the handler callback passed in with the appropriate error code.

Note, you can only have one token or deleteToken call for a given authorizedEntity and scope at a point of time. Making another such call with the same authorizedEntity and scope before the last one finishes will result in an error with code OperationInProgress.

Parameters
authorizedEntityEntity that must no longer have access.
scopeAction that entity is no longer authorized to perform.
handlerThe handler that is invoked once the unsubscribe call ends. In case of error an appropriate error object is returned else error is nil.
- (void) getIDWithHandler: (GGLInstanceIDHandler handler

Asynchronously fetch a stable identifier that uniquely identifies the app instance.

If the identifier has been revoked or has expired, this method will return a new identifier.

Parameters
handlerThe handler to invoke once the identifier has been fetched. In case of error an appropriate error object is returned else a valid identifier is returned and a valid identifier for the application instance.
- (void) deleteIDWithHandler: (GGLInstanceIDDeleteHandler handler

Resets Instance ID and revokes all tokens.

Related Functions Detail

- (typedef void(^ GGLInstanceIDTokenHandler)(NSString *token, NSError *error))
related

The completion handler invoked when the InstanceID token returns. If the call fails we return the appropriate error code as described below.

Parameters
tokenThe valid token as returned by InstanceID backend.
errorThe error describing why generating a new token failed. See the error codes below for a more detailed description.
- (typedef void(^ GGLInstanceIDDeleteTokenHandler)(NSError *error))
related

The completion handler invoked when the InstanceID deleteToken returns. If the call fails we return the appropriate error code as described below

Parameters
errorThe error describing why deleting the token failed. See the error codes below for a more detailed description.
- (typedef void(^ GGLInstanceIDHandler)(NSString *identity, NSError *error))
related

The completion handler invoked when the app identity is created. If the identity wasn't created for some reason we return the appropriate error code.

Parameters
identityA valid identity for the app instance, nil if there was an error while creating an identity.
errorThe error if fetching the identity fails else nil.
- (typedef void(^ GGLInstanceIDDeleteHandler)(NSError *error))
related

The completion handler invoked when the app identity and all the tokens associated with it are deleted. Returns a valid error object in case of failure else nil.

Parameters
errorThe error if deleting the identity and all the tokens associated with it fails else nil.

Member Data Documentation

- (NSString* const) kGGLInstanceIDRegisterAPNSOption

The key for APNS token to be included in the options dictionary when registering for GCM (Google Cloud Messaging). The value should be a NSData object that represents the APNS token for the app. This key is required to get a GCM token.

- (NSString* const) kGGLInstanceIDAPNSServerTypeSandboxOption

The key to specify if the APNS token type is sandbox or production. Set to YES if the app was built with Sandbox certificate else NO for production. At any point of time InstanceID library will support only one type of token.

- (NSString* const) kGGLInstanceIDScopeGCM

The scope to be used when fetching/deleting a token for GCM (Google Cloud Messaging).

Send feedback about...

Instance ID