iPhone, Facebook, oAuth 2.0 and the Graph API. A Tutorial, Part 2.

NOTE: I’ve moved the source code for this project to Git Hub, please get it here:  http://github.com/reallylongaddress/iPhone-Facebook-Graph-API

Preface

In part 1 of this tutorial we walked through obtaining an oAuth 2.0 access token from Facebook via an iPhone (or any iTouch device).  If you wish to go back and review the oAuth 2.0 process in some detail HERE.

Facebook Login and Extended Permission Dialogs

In the second part of this tutorial I’ll show you how to leverage my pseudo-API to:

• Login to Facebook using oAuth 2.0
• Request extended permissions for your mobile application (photos, videos, publish stream and offline access)
• Get your profile data
• Get your friend list
• Get your feed
• Post to your feed
• Post a photo (via a local image (UIImage) not a url)
• Get metadata
• Delete a feed post (via a Post)
• Get search results
• Get (and display) the author’s avatar

Convention

There are 2 APIs being talked about in this tutorial. To avoid confusion, I’m going to refer to them consistently as Facebook’s  ‘Graph API’ and my ‘pseudo-API’*.  Facebook’s Graph API is the stuff we’re interacting with via HTTP Get and Post calls.  The pseudo-API is the Objective-C/iPhone code that’s facilitating the interaction.

* I call it a pseudo-API if for no other reason I haven’t proven to myself it supports 100% of the Facebook Graph API functions.

An aside about my API design philosophy:  I could have written the pseudo-API to be much more robust and feature rich, with exceptions, logging, auto-magical json parsing, full featured functions like ‘getMyWallFeed’, etc.  However with robustness and features comes complexity and dependencies.  I kept everything aside from the absolute core functionality required to read/write data from/to the Facebook Graph API out of this implementation.  In short, I’ve left it primitive enough that anybody should be able to extend/wrap it easily, if they see fit.

The pseudo-API has only 3 classes.  The core functionality lies in the FbGraph.m file.  The other two classes support this core class.  FbGraphFile is used when uploading a file to Facebook.  FbGraphResponse is, I would hope, self-explanatory.

We’re going to skip over the steps required to create a Facebook application.  I covered that in Part 1:  iPhone, Facebook, oAuth 2.0 and the Graph API.  A Tutorial.  If you completed part 1 of the tutorial, you can use the same Facebook application without modification here.

Sample Code:

http://github.com/reallylongaddress/iPhone-Facebook-Graph-API

Creating the FbGraph Object

Before we can interact with the Graph API, we need to make a connection to it. And before we make a connection to it, we need a FbGraph object instance.  We do so like:

self.fbGraph = [[FbGraph alloc]initWithFbClientID:client_id];

Where:

FbGraph *fbGraph;

And

NSString *client_id = @"123145257717248";

The client_id should be YOUR Facebook application id.  I’ve left my application ID in here for no other reason than the tutorial code will work ‘out of the box’.

The login process

Now we have our fbGraph object instance, we’ll want to ask Facebook for a login screen.  Additionally we’ll need to let Facebook know the extended permissions we’re requesting for our app.  Here’s the code to do that:

[fbGraph authenticateUserWithCallbackObject:self andSelector:@selector(fbGraphCallback:) andExtendedPermissions:@"user_photos,user_videos,publish_stream,offline_access"];

There are 3 major things to note in this line (found in oAuth2TestViewController).

1)  We’re asking the fbGraph object to initialize the authentication process by calling the function: authenticateUserWithCallbackObject

2)  We’re setting a callback object (self) and a callback function (fbGraphCallback).   This object and function will be called upon completion of the oAuth authentication process.

3)  We’re requesting extended permissions:@”user_photos,user_videos,publish_stream,offline_access”

When this function is called, the pseudo-API will find the root application window**, stick in a UIWebView, and ask Facebook for a login screen (passing along your client_id and requested extended permissions):

NSString *url_string = [NSString stringWithFormat:@"https://graph.facebook.com/oauth/authorize?client_id=%@&redirect_uri=%@&scope=%@&type=user_agent&display=touch", facebookClientID, redirectUri, extended_permissions];

**-There’s a second authenticateUserWithCallbackObject function that allows you to specify a specific view you wish the login screen to be anchored/rendered in, if you don’t want it to render within the root view of your application.  Look at the FbGraph class for further details.

Note the ‘display=touch’ parameter.  It tells Facebook we’d like a login screen optimized for an iPhone/iPod touch screen.

Now that the process is started the UIWebView will render the login window that Facebook has returned to us.

After you’ve successfully authenticated to Facebook, you will be presented with a second screen with an extended permissions request dialog.  2 things to note here:  First, all permissions are unified into a single step.  Second, after you’ve approved the permissions, you won’t have to complete this step or see this screen again (so long as you don’t revoke the permissions).

Under the Hood of the Authentication Process

There’s some http redirects involved with the oAuth 2.0 (User-Agent flow) login process.  The FbGraph object is a UIWebViewDelegate, one of the functions associated with this delegate class is: webViewDidFinishLoad.  This function is called several times during the authentication process.  When the URL contains “access_token=” we’re golden.  We’ve successfully logged into Facebook.  When the pseudo-API sees this string, it parses out our oAuth access token, stores it to a class level variable, removes the UIWebView we inserted and finally calls the callback function we defined, returning control to your application.

The Rest of the Pseudo-API

The core of the pseudo-API is about 250 lines of code (including whitespace and comments), which is very little indeed.  This is possible because the Facebook Graph API does everything via simple HTTP Gets and Posts.  In fact, once you’ve figured out how to do Get and Post with the Graph API, you’ve pretty much figured out everything.

If you’re familiar with the current Facebook Connect implementation, you’ll immediately notice Graph API is immeasurably less complex and more consistent.

So, I could go through and explain how everything works in painful (and highly repetitive) detail…but I’m going to peace out, let you read over the code, dissect it, add some breakpoints and get your hands dirty.

FYI:  There is very intentionally very little UI in the app. Rather than having you, the reader, have to figure out my UI conventions as well as Interface Builder, I’ve kept it simple and dumped most all output to the debugger console.  The code is simple, the pseudo-API is simple, the Graph API is simple……

I hope you take a look at my pseudo-API and agree, it’ simple…that’s the idea.

If you find this post useful, if you include this code or the concepts you learned here in an app, if you extend this into a more full featured API….I’d love to know!

Happy hacking.

Dominic

ddimarco@room214.com

@dominicdimarco

Sample Code:

http://github.com/reallylongaddress/iPhone-Facebook-Graph-API