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

NOTE: The source code for this tutorial is still linked below, however the FULL Facebook/iPhone Graph API can be found here:  http://github.com/reallylongaddress/iPhone-Facebook-Graph-API

The new Facebook Graph API looks to be the cat’s meow, the bee’s knees, the coolest thing since sliced bread. Ok, that’s a bit much… but it is a whole lot more powerful, easier and cross-platform consistent than the previous plethora of Facebook APIs.  The Graph API was announced at Facebook’s F8 conference just over a month ago.  At the time of release, I was surprised no iPhone SDK was made available. I fully expected that at least an unofficial SDK as well as full blown tutorials would be out en-mass by now, but to no avail.

Not nearly patient enough to wait for an official SDK or iPhone API from Facebook, I asked Google how to “Facebook oAuth 2.0 iPhone” and was disappointed with the results. It turns out, there are very few, woefully incomplete examples of how to authenticate to Facebook via oAuth 2.0, from an Objective-C / native iPhone application. The best implementation I found was a pseudo API, however I don’t care for it since it uses the old Facebook Connect authentication scheme, then implements the graph API on top of that layer.

Adding insult to injury, there was lots of news last week about the Android Graph API but no love for the iPhone:

“Facebook’s mobile development team soft launched a Facebook SDK for Android, bringing functionality that was previously only available on the iPhone to the Android platform. It gets better: Facebook gave the Android platform a de facto exclusive on two of its newest initiatives: Open Graph APIs and OAuth 2.0.”

– Will M, Allfacebook.com

Aside:  My theory on why there’s not iPhone/Objective-C API is:  That functionality is going to be directly (and deeply) integrated in the forthcoming iPhone OS 4.0 (June?).

All of that being said, I slashed, burned and figured it out.  Here’s the result, a very simple end-to-end example of how to connect to Facebook via oAuth 2.0 on the iPhone.

Part 1: Connecting to Facebook with oAuth 2.0 on the iPhone

Part 2 of this series will cover how to interact with the Graph API.

NOTE: You can go to http://graph.facebook.com to play with the Graph API, directly in your browser.

Assumptions and requirements:

• Facebook: You’ve installed the Facebook Developer Application.
• iPhone: You’ve installed the iPhone Xcode SDK installed (I believe most any version will work) and have a some level of knowledge about objective-C, Interface Builder, etc.

Facebook Setup

• Go to the Facebook developer App and install if you haven’t already
• Once you’ve installed Setup a New Application
• Next you need to configure a few app settings:
  • BASIC tab: enter an Application Name
  • AUTHENTICATION tab: un-check and leave everything blank
• Save changes.  Save yourself some frustration and make note of the Application ID now.

Sample Code:

[download id="3" format="1"]

iPhone Setup

Open up the Xcode project. There’s only 2 functions at play here:

viewDidLoad

This function is called as soon as the view has completely loaded.  It then asks the UIWebView to begin the oAuth 2.0 authorization process by sending a request to:

https://graph.facebook.com/oauth/authorize?client_id=your_facebook_app_id&redirect_uri=http://www.facebook.com/connect/login_success.html&type=user_agent&display=touch

(NOTE:  display=touch, we’ll get back to this in a bit)

webViewDidFinishLoad

This function is called several times throughout the login process execution. These multiple web view finished calls have to do with server redirects within the oAuth 2.0 process flow. We’re only interested when the requested URL contains:

access_token=

And the associated obj-c code to identify when this occurs is:

NSRange access_token_range = [url_string rangeOfString:@"access_token="];
if (access_token_range.length > 0) {

Then, this code extracts the oAuth token out of the URL we received back the Facebook oAuth servers:

int from_index = access_token_range.location + access_token_range.length;
NSString *access_token = [url_string substringFromIndex:from_index];

iPhone Configuration

In oAuth2TestViewController.m update the client_id variable with your Facebook Application ID:

/*Facebook Application ID*/
NSString *client_id = @"YOUR_FB_APPLICATION_ID";

Running the App

Once you’ve pasted your Facebook Application ID into the right place, you should be able to run the application straight away.

When you first launch the simulator oAuth2TestViewController it will automagically initialize the oAuth login procedure via the webView object. Barring any errors or configuration issues, you should get a Facebook login screen optimized for an iTouch device (NOTE:  thus the display=touch we made note of above). Finally after you’ve logged in you’ll see your oAuth access token in the Xcode debug console.

Sample Code:

[download id="3" format="1"]

That’s it. No bells & whistles, no buttons, no Interface Builder, no UITableViewControllers; just the bare minimum required to get an oAuth 2.0 token via an itouch device from Facebook.

In part 2, we’ll interact with the Graph GETing from and POSTing data to it, using a pseudo-API.

Find me here: @dominicdimarco

NOTE: (5/27/2010 11:09 AM MST) The original post has been updated incorporating feedback from comments below.