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