iOS Quickstart

Complete the steps described in the rest of this page, and in about five minutes you'll have a simple iOS application that makes requests to the Gmail API.

Prerequisites

To run this quickstart, you'll need:

  • Xcode 8.0 or greater.
  • CocoaPods dependency manager.
  • A Google account with Gmail enabled.

Step 1: Turn on the Gmail API

Click the button below to enable the API and download your credentials file. When prompted, ensure that you:

  • Select the platform iOS.
  • Enter com.example.QuickstartApp as the Bundle ID.
  • Download the client configuration file credentials.plist.

Enable the API

Step 2: Prepare the workspace

  1. Open Xcode and create a new project:
    1. Click File > New > Project, select the iOS > Application > Single View Application template, and click Next.
    2. Set the Product Name to "QuickstartApp", Organization Identifier to "com.example", and Language to Objective-C. Click Next.
    3. Select a destination directory for the project and click Create.
  2. Close the project by clicking File > Close Project.
  3. Open a Terminal window and navigate to the directory that contains the QuickstartApp.xcodeproj file you just created.
  4. Run the following commands to create the Podfile, install the library, and open the resulting XCode project:

    cat << EOF > Podfile &&
    platform :ios, '8.0'
    target 'QuickstartApp' do
        pod 'GoogleAPIClientForREST/Gmail', '~> 1.2.1'
        pod 'GoogleSignIn', '~> 4.1.1'
    end
    EOF
    pod install &&
    open QuickstartApp.xcworkspace
    

  5. In the XCode Project Navigator select the project node "QuickstartApp" and select "QuickstartApp" in the TARGETS section, then select the Info tab, and expand the URL Types section.

  6. Click the + button, and add a URL scheme for your reversed client ID. To find this value, open the credentials.plist configuration file, and look for the REVERSED_CLIENT_ID key. Copy the value of that key, and paste it into the URL Schemes box on the configuration page. Leave the other fields blank.
  7. Rebuild the project by clicking Product > Clean Build Folder (while holding the option key) and Product > Build.

Step 3: Set up the sample

Replace the contents of the following files with the code provided:

AppDelegate.h
#import <UIKit/UIKit.h>
@import GoogleSignIn;

@interface AppDelegate : UIResponder <UIApplicationDelegate>

@property (strong, nonatomic) UIWindow *window;


@end
AppDelegate.m
#import "AppDelegate.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Initialize Google sign-in.
    [GIDSignIn sharedInstance].clientID = @"<YOUR_CLIENT_ID>";

    return YES;
}

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication
         annotation:(id)annotation {
    return [[GIDSignIn sharedInstance] handleURL:url
                               sourceApplication:sourceApplication
                                      annotation:annotation];
}


@end
ViewController.h
#import <UIKit/UIKit.h>
@import GoogleSignIn;
#import <GTLRGmail.h>

@interface ViewController : UIViewController <GIDSignInDelegate, GIDSignInUIDelegate>

@property (nonatomic, strong) IBOutlet GIDSignInButton *signInButton;
@property (nonatomic, strong) UITextView *output;
@property (nonatomic, strong) GTLRGmailService *service;


@end
ViewController.m
#import "ViewController.h"

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    // Configure Google Sign-in.
    GIDSignIn* signIn = [GIDSignIn sharedInstance];
    signIn.delegate = self;
    signIn.uiDelegate = self;
    signIn.scopes = [NSArray arrayWithObjects:kGTLRAuthScopeGmailReadonly, nil];
    [signIn signInSilently];

    // Add the sign-in button.
    self.signInButton = [[GIDSignInButton alloc] init];
    [self.view addSubview:self.signInButton];

    // Create a UITextView to display output.
    self.output = [[UITextView alloc] initWithFrame:self.view.bounds];
    self.output.editable = false;
    self.output.contentInset = UIEdgeInsetsMake(20.0, 0.0, 20.0, 0.0);
    self.output.autoresizingMask = UIViewAutoresizingFlexibleHeight | UIViewAutoresizingFlexibleWidth;
    self.output.hidden = true;
    [self.view addSubview:self.output];

    // Initialize the service object.
    self.service = [[GTLRGmailService alloc] init];
}

- (void)signIn:(GIDSignIn *)signIn
didSignInForUser:(GIDGoogleUser *)user
     withError:(NSError *)error {
    if (error != nil) {
        [self showAlert:@"Authentication Error" message:error.localizedDescription];
        self.service.authorizer = nil;
    } else {
        self.signInButton.hidden = true;
        self.output.hidden = false;
        self.service.authorizer = user.authentication.fetcherAuthorizer;
        [self fetchLabels];
    }
}

// Construct a query and get a list of labels from the user's gmail. Display the
// label name in the UITextView
- (void)fetchLabels {
    self.output.text = @"Getting labels...";
    GTLRGmailQuery_UsersLabelsList *query = [GTLRGmailQuery_UsersLabelsList queryWithUserId:@"me"];
    [self.service executeQuery:query
                      delegate:self
             didFinishSelector:@selector(displayResultWithTicket:finishedWithObject:error:)];
}

- (void)displayResultWithTicket:(GTLRServiceTicket *)ticket
             finishedWithObject:(GTLRGmail_ListLabelsResponse *)labelsResponse
                          error:(NSError *)error {
    if (error == nil) {
        NSMutableString *labelString = [[NSMutableString alloc] init];
        if (labelsResponse.labels.count > 0) {
            [labelString appendString:@"Labels:\n"];
            for (GTLRGmail_Label *label in labelsResponse.labels) {
                [labelString appendFormat:@"%@\n", label.name];
            }
        } else {
            [labelString appendString:@"No labels found."];
        }
        self.output.text = labelString;
    } else {
        [self showAlert:@"Error" message:error.localizedDescription];
    }
}


// Helper for showing an alert
- (void)showAlert:(NSString *)title message:(NSString *)message {
    UIAlertController *alert =
    [UIAlertController alertControllerWithTitle:title
                                        message:message
                                 preferredStyle:UIAlertControllerStyleAlert];
    UIAlertAction *ok =
    [UIAlertAction actionWithTitle:@"OK"
                             style:UIAlertActionStyleDefault
                           handler:^(UIAlertAction * action)
     {
         [alert dismissViewControllerAnimated:YES completion:nil];
     }];
    [alert addAction:ok];
    [self presentViewController:alert animated:YES completion:nil];
}


@end

In the file AppDelegate.m, replace the placeholder <YOUR_CLIENT_ID> in with the client ID listed in credentials.plist.

Step 4: Run the sample

Switch to the scheme QuickstartApp and run the sample (Cmd+R) using the device simulator or a configured device. The first time you run the sample, it will prompt you to log in to your Google account and authorize access.

Notes

  • Authorization information is stored in your Keychain, so subsequent executions will not prompt for authorization.

Further reading

Send feedback about...

Need help? Visit our support page.