Matt Tuttle

Adding OpenFeint to your iPhone app is much easier than you might imagine. There are several steps you should take before reading this document. The first is to sign up for a developer account at http://api.openfeint.com. The second is to download the OpenFeint SDK on the developer website and unzip the files. Take note of the product key and product secret key as we will be using this later.

This tutorial is geared around developing apps with Cocos2D but most of this will apply to other frameworks as well. After you have downloaded the SDK you'll want to drop the OpenFeint folder into your XCode project window, I put it under frameworks. Make sure you also include additional frameworks that OpenFeint requires (libsqlite, CFNetwork, SystemConfiguration, MapKit, CoreLocation, and Security). There is a readme included with the OpenFeint SDK that would be good to read since newer versions may have different requirements. After you've got everything setup make sure it builds before we start adding any code to the project. One thing I commonly miss is adding OpenFeintPrefix.pch to my prefix header file.

Basic Setup of OpenFeint

If everything builds correctly then we can begin to integrate OpenFeint! To begin add the following lines of code to your main AppDelegate.m file. Note that you'll want to add your product and secret keys as well as the proper orientation for your app.

#include "OpenFeint.h"
- (void)initializeOpenFeint {
    NSDictionary* settings = [NSDictionary dictionaryWithObjectsAndKeys:
        [NSNumber numberWithInt:UIInterfaceOrientationPortrait], OpenFeintSettingDashboardOrientation,
        [NSNumber numberWithBool:YES], OpenFeintSettingEnablePushNotifications,
        nil
    ];
    ofDelegate = [OFDelegate new];
    OFDelegatesContainer *delegates = [OFDelegatesContainer containerWithOpenFeintDelegate:ofDelegate];
    [OpenFeint initializeWithProductKey:@"YourProductKey"
                              andSecret:@"YourSecretProductKey"
                         andDisplayName:@"YourDisplayName"
                            andSettings:settings    // see OpenFeintSettings.h
                           andDelegates:delegates];    // see OFDelegatesContainer.h
}

Also, make sure you call the function inside applicationDidFinishLaunching right before calling Cocos2D runWithScene. Now create a new class file named OFDelegate.mm and put the following code in it.

#import "cocos2d.h"
#import "TritoneOFDelegate.h"
#import "OpenFeint+UserOptions.h"
@implementation OFDelegate
- (void)dashboardWillAppear {
    [[CCDirector sharedDirector] pause];
}
- (void)dashboardDidAppear {
    [[CCDirector sharedDirector] stopAnimation];
}
- (void)dashboardWillDisappear {
}
- (void)dashboardDidDisappear {
    [[CCDirector sharedDirector] resume];
    [[CCDirector sharedDirector] startAnimation];
}
- (void)userLoggedIn:(NSString*)userId {
    OFLog(@"New user logged in! Hello %@", [OpenFeint lastLoggedInUserName]);
}
- (BOOL)showCustomOpenFeintApprovalScreen {
   return NO;
}

What this does is pause and resume the game before and after the OpenFeint window is shown. This code is specific to Cocos2D so if you are using a different framework then you can drop the pause and resume functions into the Appear and Disappear functions respectively.

Highscores and Leaderboards

Now onto the fun part! Let's create leaderboards and start sending highscores to OpenFeint. The first thing is to log into the OpenFeint website again and create a new leaderboard which is found under the Basic Features tab. Create a leaderboard and give it an appropriate name. Take note of the leaderboard ID as it will be important for your code.

Now open up your XCode project and add a new import line to the top of your main scene/layer code file.

#import "OFHighScoreService.h"

Now add the following line of code to submit a highscore to OpenFeint. It's really that easy!

[OFHighScoreService setHighScore:YourHighscore
                  forLeaderboard:@"YourLeaderBoardID"
                       onSuccess:OFDelegate()
                      onFailure:OFDelegate()];

Another thing you many want to consider is adding multiple leaderboards for different modes of gameplay. The only part you would have to change is the leaderboard ID section.

Setting up Achievements

Achievements work very similar to leaderboards except that you must assign a point value to each achievement. OpenFeint suggests creating approximately 20-30 achievements that are worth 800-1000 points in total. Of course, you are free to create as many achievements as you want within OpenFeint's limits.

Start by creating a new achievement and giving it a name. It's a good idea to add an icon that will be shown on the achievements page. OpenFeint will assign an achievement ID that you will use in your code. Drop the following code into your project to unlock achievements.

#import "OFAchievementService.h"

[OFAchievementService unlockAchievement:@"YourAchievementCode"];

Launching the OpenFeint Dashboard

Finally, it's important to add a snippet to your app to launch the OpenFeint dashboard so people can view their achievements and highscores. The easiest way to do so is adding a button that will execute the following code.

[OpenFeint launchDashboard];

Final Word of Advice

That's all it takes to integrate the most basic features of OpenFeint into your iPhone app. Make sure you test all of your achievements with test users before submitting your application to Apple. Good luck!