Marketing In Code, Part 2: Setting A User’s Status In Facebook From An iPhone App — A Tutorial

In part one of this series we ran the numbers and found that posting a status update to 13 average Facebook users generated as much exposure as spending the entire post-commission revenue for an average priced app in the top-100.

In this tutorial, you’ll learn how post status updates from an iPhone:

Outline

There are, broadly speaking, two big moving pieces to this tutorial:

1. Setting up a Facebook application
2. Adding Facebook capabilities to an iPhone application

Facebook Application

First thing we need to do is create a Facebook Application inside Facebook.

Creating an application will:

1. Give us an API Key and Application Secret, the two elements we need to authenticate for Facebook API access from the iPhone
2. Provide a via/source label for the status updates — e.g., “Dan Grigsby is writing a Facebook iPhone tutorial • 10:12am • via Some iPhone App”

No Server Back-End

Updating a user’s status from an iPhone doesn’t require a server back-end. All of the Facebook API calls will be generated from the phone using Facebook Connect for iPhone, which we’ll set up shortly.

Creating A Facebook Application

To create an application in Facebook you first have to add Facebook’s Developer Application to your Facebook account.

If you have not already added the Developer Application do so now:

1. Login to Facebook
2. Visit the Developer Application page
3. Click the Allow button

Next, add a new application from the Developer Application page:

1. Click the button at the top of the page
2. Enter an Application Name; read the Facebook terms and, if you agree, select the Agree radio button; click Save Changes . The Application Name you provide will be used as the via/source label in the status updates

Your app has now been created. Note the API Key and Secret listed in the Essential Information section of the page. In a later step, you’ll use these to authenticate your application from the iPhone.

Note: this is the minimum Facebook Application setup to support sending updates from your iPhone code. On your own, you’ll want to fancy it up with icons, have your application verified by Facebook, and place it in the Application Directory.

iPhone Code

We’ll create a simple, single view sample app to demonstrate setting status from Facebook from the iPhone.

Source

The sample app uses of Facebook’s own Facebook Connect for iPhone and some helper classes I’ve created.

To download Facebook Connect for iPhone:

1. Visit the Facebook Connect for iPhone page
2. Click the Download the SDK link
3. Unzip the downloaded archive

My helper classes are stored at GitHub. To download my helper classes clone their git repository:

1. Open a terminal window and type: git clone git://github.com/dcgrigsby/MOFBHelper.git

Note: You’ll include Facebook connect and my helper classes app by dragging-and-dropping virtual folders from their respective Xcode projects into yours. Consequently, you’ll want to place your local copies somewhere predictable, semi-permanent, and with an easily referenced path. E.g., placing them on the desktop is probably not a good place for them. I keep all of my work in ~/Projects; I keep the Facebook Connect and helper classes in ~/Projects/fb-connect and ~/Projects/MOFBHelper respectively.

Sample App

We’ll create a simple, single view app that handles Facebook login and status update in four steps:

1. Create the app
2. Add Facebook Connect for iPhone to the project
3. Add my helper classes to the project
4. Add Facebook login and status update code

Create The App

Launch Xcode and create a new View-based iPhone application called StatusUpdater:

1. Create a new project using File > New Project… from Xcode’s menu
2. Select View-Based Application from the iPhone OS > Application section, click Choose…
3. Name the project as StatusUpdater and click Save

Add Facebook Connect For iPhone To The Project

When I sat down to learn Facebook Connect for iPhone this was the step that caused me the most grief. Essentially, we’re going to copy part of another Xcode project into our own project, then we’re going to configure the project to include find the headers it needs to build properly. I’ll walk you through it a step at a time:

1. In Finder, navigate to the folder that contains the Facebook Connect for iPhone source. The folder is usually named fbconnect-iphone
2. While still in Finder, open up the src subdirectory
3. Locate FBConnect.xcodeproj and double-click to open it in Xcode. You should now have two open Xcode projects: StatusUpdater and FBConnect
4. In the Groups & Files panel of the FBConnect Xcode project, expand the blue FBConnect project branch
5. Select the yellow FBConnect folder with your mouse and drag-and-drop it onto the StatusUpdater project icon in the StatusUpdate Xcode project. Important: drag and drop the FBConnect folder, not the FBConnect project itself!
6. Add the items to the StatusUpdater Xcode project by clicking the Add button. Do not copy items into the destinations group’s folder, but do make sure that they will be added to the StatusUpdater target
7. In the Groups & Files panel of the StatusUpdater Xcode project, select the StatusUpdater project icon and bring up the project’s Info window by clicking the big blue-i/info button at the top of the window
8. Select the Build tab
9. Locate and double click the Header Search Paths item in the Search Paths section
10. Click the + button to add a search path
11. Enter the path to the Facebook Connect for iPhone src directory — e.g., ../fbconnect-iphone/src
12. Click OK to add the search path and close the info window

Check your work by building the project. You can safely ignore the setFont warning. If the build fails, confirm that you did the drag-and-drop operation correctly — your Groups and Files panel should look like the image at right — and verify the Header Search Path.

Add My Helper Classes To The Project

Adding my helper classes to the project follows a similar, but slightly simpler approach to the above:

1. In Finder, navigate to the folder that contains the git clone of the helper classes. The folder is usually named MOFBHelper
2. Locate MOFBHelper.xcodeproj and double-click to open it in Xcode. You should now have two open Xcode projects: StatusUpdater and MOFBHelper
3. In the Groups & Files panel of the MOFBHelper Xcode project, expand the blue MOFBHelper project branch
4. Select the yellow MOFBHelper folder with your mouse and drag-and-drop it onto the StatusUpdater project icon in the StatusUpdate Xcode project. Important: drag and drop the MOFBHelper folder, not the MOFBHelper project itself!
5. Add the items to the StatusUpdater Xcode project by clicking the Add button. Do not copy items into the destinations group’s folder, but do make sure that they will be added to the StatusUpdater target

Your your Groups and Files panel should look like the image at right.

Add Facebook Login And Status Update Code

My helper classes make posting a status update as simple as setting a property on an instance of the helper class — e.g., fbHelper.status = @"reading Mobile Orchard";

Before we can do that, however, need to have the user log in to Facebook and give our app permission to update their status. For the former, the sample app contains code to show a login button and post an update after the user has logged in. The latter is handled automatically by my helper classes — if you set the status property and the user hasn’t given your app permission, a dialog will pop up asking them to do so.

There’s very little code, so I’ll paste it in next and walk you through it below:

Use this code for StatusUpdaterViewController.h:

#import <UIKit/UIKit.h>
#import "FBConnect/FBConnect.h"
#import "MOFBHelper.h"

@interface StatusUpdaterViewController : UIViewController <FBSessionDelegate, MOFBHelperDelegate> {
	FBSession *session;
	MOFBHelper *fbHelper;
}

@end

Use this code for StatusUpdaterViewController.m:

#import "StatusUpdaterViewController.h"

@implementation StatusUpdaterViewController

#pragma mark View Methods

- (void)viewDidLoad {
	[super viewDidLoad];

	session = [FBSession sessionForApplication:@"YOUR APP'S API KEY!!!" secret:@"YOUR APP'S SECRET" delegate:self];		

	FBLoginButton* button = [[[FBLoginButton alloc] init] autorelease];
	[self.view addSubview:button];	

	fbHelper = [[MOFBHelper alloc] init];
	fbHelper.delegate = self;
}

- (void)viewDidAppear:(BOOL)animated {
	[super viewDidAppear:animated];
	[session resume];
}

#pragma mark Facebook Session Protocol Methods

- (void)session:(FBSession*)session didLogin:(FBUID)uid {
	fbHelper.status = @"is learning to set Facebook status programatically from an iPhone";
}

#pragma mark Optional MOFBHelper Protocol Methods

- (void)statusDidUpdate:(MOFBHelper*)helper {
	NSLog(@"status updated");
}

-(void)status:(MOFBHelper*)helper DidFailWithError:(NSError*)error {
	NSLog(@"status update failed: %@", [error description]);
}

# pragma mark Housekeeping

- (void)dealloc {
	[session release];
	[fbHelper release];
	[super dealloc];
}

@end

Note: Be sure to change the API Key and Secret in the call to sessionForApplication:secret:delegate:self

In viewDidLoad, the code adds a Facebook login button to the view, and creates/configures an instance of my helper class.

In viewDidAppear:, we resume the session. If the user previously checked the “keep me logged in” box during a Facebook login the session will automatically resume; otherwise a login dialog will be displayed. In either case, after the session is created the session:didLogin: method is called. We send the resume method here, and not in viewDidLoad because the view needs to be on-screen in order to show the login dialog.

The session:DidLogin method updates the status. If the user has not already granted permission for our app to update the status then a dialog asking permission will be displayed.

The MOFBHelper class defines an optional protocol to inform the app whether or not the status update was successful. The statusDidUpdate: and status:DidFailWithError: methods are called as appropriate. The error codes are define in the MOFBErrors.h file. If you don’t care about the success or failure of a status update you can remove these methods and the MOFBHelperDelegate from the protocols section of the .h file.

Next

MOFBHelper aims to be a higher-level interface to Facebook Connect for iPhone. If there’s enough interest — measured by comments to this points, re-tweets, back-links and github project watchers — I’ll expand it to support other Facebook actions. Contributors welcome. Finally, be constructive with your feedback.