Knowledgebase

Top :: OpenFeint Developer Support : Guides :

Initializing OpenFeint
OpenFeint is initialized with one function call:
[OpenFeint initializeWithProductKey:andSecret:andDisplayName:andSettings:andDelegates:];

• ProductKey and Secret are strings obtained by registering your application at https://api.openfeint.com
• DisplayName is the string name we will use to refer to your application throughout OpenFeint.
• Settings is dictionary of settings (detailed below) that allow you to customize OpenFeint.
• Delegates is a container object that allows you to provide desired delegate objects pertaining to specific OpenFeint features.

Shutting down OpenFeint
OpenFeint shutdown is accomplished with one function call:
[OpenFeint shutdown];

Additional required functions
Developers are required to notify OpenFeint of device lock / unlock events in order to reduce processing and save battery.

[OpenFeint applicationDidBecomeActive];

This method should be invoked from the UIApplicationDelegate object's applicationDidBecomeActive: method.

[OpenFeint applicationWillResignActive];

This method should be invoked from the UIApplicationDelegate object's applicationWillResignActive: method.

OpenFeint configuration settings
Settings are provided to OpenFeint as an NSDictionary. Here is an example of creating a settings dictionary for use with the initialize method:

NSDictionary* settings = [NSDictionary dictionaryWithObjectsAndKeys:
    [NSNumber numberWithInt:UIInterfaceOrientationLandscapeLeft], OpenFeintSettingDashboardOrientation,
    @"ShortName", OpenFeintSettingShortDisplayName, 
    NSNumber numberWithBool:YES], OpenFeintSettingEnablePushNotifications,
    [NSNumber numberWithBool:NO], OpenFeintSettingDisableChat,
    nil
];

More detail for each of these settings can be found below. These settings are also described in OpenFeintSettings.h.

• OpenFeintSettingRequireAuthorization - deprecated
• OpenFeintSettingDashboardOrientation - Specifies which orientation the OpenFeint dashboard will appear in
• OpenFeintSettingShortDisplayName - In certain areas where the application display name can be too long we will use this more compact version of your application's display name. One example is for the title of the current game tab in the OpenFeint dashboard.
• OpenFeintSettingEnablePushNotifications - This controls whether or not your application will be enabling Push Notifications (for Social Challenges, currently)
• OpenFeintSettingDisableChat - Allows a developer to disable chat for their entire application.

What is OFDelegatesContainer? Where is OpenFeintDelegate?
OFDelegatesContainer is new as of version 2.1 and provides developers a way to specify all of the various delegates that OpenFeint features may require.

If you are only using an OpenFeintDelegate then you may use the simple convenience constructor:
[OFDelegatesContainer containerWithOpenFeintDelegate:];

What is OpenFeintDelegate for?
This is the bread-and-butter OpenFeint delegate.

- (void)dashboardWillAppear;

This method is invoked whenever the dashboard is about to appear. We suggest that application developers use this opportunity to pause any logic / drawing while OpenFeint is displaying.

- (void)dashboardDidAppear;

This method is invoked when the dashboard has finished it's animated transition and is now fully visible.

- (void)dashboardWillDisappear;

This method is invoked when the dashboard is about to animate off the screen. We suggest that applications that do not use OpenGL resume drawing in this method.

- (void)dashboardDidDisappear;

This method is invoked when the dashboard is completed off the screen. We suggest that OpenGL applications resume drawing here, and all applications resume any paused logic / gameplay here.

- (void)userLoggedIn:(NSString*)userId;

This method is invoked whenever an application successfully connects to OpenFeint with a logged in user. The single parameter is the OpenFeint user id of the logged in user.

- (BOOL)showCustomOpenFeintApprovalScreen;

This method is invoked when OpenFeint is about to show the welcome / approval screen that asks a user if they would like to use OpenFeint. You can learn more about customizing the approval screen here.

OFNotificationDelegate
This delegate deals with the in-game notification pop-ups that OpenFeint displays in response to certain events including high score submission, achievement unlocks, and social challenges. You can find more details by referencing the API feature article on notification pop-ups.

OFChallengeDelegate
This delegate deals with the Social Challenges API feature. You can find more details by referencing the Social Challenges feature article.

Launching the OpenFeint dashboard
The most basic launch of the OpenFeint dashboard is accomplished with a single function call:
[OpenFeint launchDashboard];

You can also launch the dashboard with a specific OpenFeintDelegate for use only during this launch using:
[OpenFeint launchDashboardWithDelegate:];

In addition, OpenFeint provides a suite of methods for launching the dashboard to a pre-defined tab or page. These are documented in the header file OpenFeint+Dashboard.h.

+ (void)launchDashboardWithListLeaderboardsPage;

Invoke this method to launch the OpenFeint dashboard to the leaderboard list page for your application.

+ (void)launchDashboardWithHighscorePage:(NSString*)leaderboardId;

Invoke this method to launch the OpenFeint dashboard to a specific leaderboard page. You must pass in a string representing the unique ID of the leaderboard you wish to view which can be obtained from the Developer Dashboard.

+ (void)launchDashboardWithAchievementsPage;

Invoke this method to launch the OpenFeint dashboard to the achievements list page for your application.

+ (void)launchDashboardWithChallengesPage;

Invoke this method to launch the OpenFeint dashboard to the challenge list page for your application.

+ (void)launchDashboardWithFindFriendsPage;

Invoke this method to launch the OpenFeint dashboard to the 'find friends' page, which prompts the user to use twitter, facebook, or a username search to locate friends in OpenFeint.

+ (void)launchDashboardWithWhosPlayingPage;

Invoke this method to launch the OpenFeint dashboard to a page which lists OpenFeint friends who are also playing your application.

Orientation and View Controller information
The OpenFeint dashboard supports being displayed in any orientation you desire. It will not, however, change orientations while it is being displayed.

Developers use the OpenFeintSettingDashboardOrientation to control the initial orientation. If you wish to change the orientation over the course of the application you may invoke:
[OpenFeint setDashboardOrientation:];

Generally this is done by applications which want to support multiple orientations in the UIViewController method didRotateFromInterfaceOrientation:.

If your application is using a view controller with a non-portrait layout then you are required to invoke and return the following method in your UIViewController's shouldAutorotateToInterfaceOrientation method.
[OpenFeint shouldAutorotateToInterfaceOrientation:withSupportedOrientations:andCount:];

Here is an example implementation of shouldAutorotateToInterfaceOrientation:

- (BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)interfaceOrientation
{
    const unsigned int numOrientations = 4;
    UIInterfaceOrientation myOrientations[numOrientations] = 
    { 
        UIInterfaceOrientationPortrait, UIInterfaceOrientationLandscapeLeft, 
        UIInterfaceOrientationLandscapeRight, UIInterfaceOrientationPortraitUpsideDown
    };

    return [OpenFeint 
        shouldAutorotateToInterfaceOrientation:interfaceOrientation 
        withSupportedOrientations:myOrientations 
        andCount:numOrientations];
}