iOS Implementation

The following examples will help you implement Instance ID in an iOS client. Note that these examples use the GCM scope, which you would use to manage tokens for an iOS client for Google Cloud Messaging.

Set up your CocoaPods dependencies

Instance ID uses CocoaPods to install and manage dependencies. Open a terminal window and navigate to the location of the Xcode project for your application. If you have not already created a Podfile for your application, create one now:

pod init

Open the Podfile created for your application and add the following:

pod 'Google/GGLInstanceID'

Save the file and run:

pod install

This creates an .xcworkspace file for your application. Use this file for all future development on your application.

Get an Instance ID

The following code returns an Instance ID:

__block NSString *iid;
GGLInstanceIDHandler handler = ^void(NSString *identity, NSError *error) {
  if (error) {
    // failed to get the identity for the app
    // handle error
  } else {
    iid = identity;
    // handle InstanceID for the app
  }
};
[[GGLInstanceID sharedInstance] getIDWithHandler:handler];

Generate a token

Generating tokens requires a Project ID generated by the Google Developers Console.

// Project ID from Google Developer Console
NSString *authorizedEntity = PROJECT_ID;
String *scope = kGGLInstanceIDScopeGCM; // Scope “GCM” in GGLInstanceID.h
NSDictionary *options = @{
  kGGLInstanceIDRegisterAPNSOption : <APNS Token data>,
  // 1 if APNS sandbox token else 0
  kGGLInstanceIDAPNSServerTypeSandboxOption : @(1),
};
GGLInstanceIDTokenHandler handler = ^void(NSString *token, NSError *error) {
  if (error) {
    // check the error and try again after an exponential backoff
  } else {
    // got the token successfully
  }
};

// Start GGLInstanceID (do it once only)
GGLInstanceID *config = [GGLInstanceIDConfig defaultConfig];
[[GGLInstanceID sharedInstance] startWithConfig:config];
GGLInstanceID *iidInstance = [GGLInstanceID sharedInstance];

NSString *token = [iidInstance tokenWithAuthorizedEntity:authorizedEntity
                                                   scope:scope
                                                 options:options
                                                 handler:handler];

Manage tokens and Instance IDs

Instance ID lets you delete and refresh tokens.

Delete tokens and Instance IDs

NSString *authorizedEntity = PROJECT_ID; // Project ID from Google Developer Console
String *scope = kGGLInstanceIDScopeGCM; // Scope “GCM” in GMPInstanceID.h
GGLInstanceIDDeleteTokenHandler handler = ^void(NSError *error) {
  if (error) {
    // Failed to delete the token. Check error and do an exponential
    // backoff to retry again.
  } else {
    // Successfully deleted the token.
  }
};
[[GGLInstanceID sharedInstance]
    deleteTokenWithAuthorizedEntity:authorizedEntity
                              scope:scope
                            handler:handler];

You can also delete the Instance ID itself, in which case next time you call getInstance() you will get a new Instance ID:

GGLInstanceID *iid = [GGLInstanceID sharedInstance];

GGLInstanceIDDeleteHandler deleteHandler = ^void(NSError *error) {
  if (error) {
    // failed to delete the identity for the app
    // do an exponential backoff and retry again.
  } else {
    // try to get a new ID
    dispatch_async(dispatch_get_main_queue(), ^{
       GGLInstanceIDHandler handler =
           ^void(NSString *identity, NSError *error) {
              if (error) {
                // failed to get the identity for the app
                // handle error
              } else {
                NSString *instanceID = identity;
                // handle InstanceID for the app
              }
           }
       [iid getIDWithHandler:handler];
    });
  }
}

[iid deleteIDWithHandler:deleteHandler];

Refresh tokens

The Instance ID service initiates callbacks periodically (for example, every 6 months), requesting that your app refreshes its tokens. It may also initiate callbacks when:

• There are security issues; for example, SSL or platform issues.
• Device information is no longer valid; for example, backup and restore.
• The Instance ID service is otherwise affected.

To listen for these Instance ID service callbacks in your iOS app, implement the InstanceID delegate protocol:

@interface MyAppInstanceIDDelegate : NSObject <GGLInstanceIDDelegate>
@end

@implementation MyAppInstanceIDDelegate
  -(void)onTokenRefresh {
    // assuming you have defined TokenList as
    // some generalized store for your tokens
    NSArray *tokenList = [MyAppTokensList allTokens];
    GGLInstanceID iid = [GGLInstanceID sharedInstance];
    for(MyAppTokenItem *tokenItem in tokenList) {
      tokenItem.token =
        [iid tokenWithAuthorizedEntity:tokenItem.authEntity
                                 scope:tokenItem.scope
                               options:tokenItem.options
                               handler:tokenItem.handler];
      // send this tokenItem.token to your server
    }
  }

@end