Knowledgebase

Top :: OpenFeint Developer Support : API Features :

Overview

OpenFeint Challenges add replay value and depth to your game and are also very viral. The high concept is that a user plays a game session of some sort, game data is recorded and stored on the OpenFeint servers, and a challenge is sent out to one or more of the players friends. Challenges are received as push notifications as well as in-game notifications. When a user receives a challenge he may decide to accept it after which he plays a similar game session trying to beat the challenge. There is much flexibility in the implementation however and a developer may use challenges in many different ways.

All challenges may be split into two categories.

• One Shot Challenges allow the recipient a single try to beat the challenge. This always results in a win, lose or tie. This is a heads on competition in the sense that either player can win, it fits casual gaming and can be used in many different scenarios.
• Multiple Attempt Challenges allow the recipient unlimited attempts at beating the challenge. The challenge is not considered completed until beaten so the only things recorded are the number of attempts and whether or not it's completed. Once a user completes a challenge he may challenge back to the person who sent the challenge with the result of the session he just played. This builds a dynamic where two players may keep sending each other harder and harder challenges.

Challenges are only loosely defined by the API. Depending on the implementation the experience and scope may vary greatly. Here are some possible scenarios but this list is by no means exhaustive.

1. • User selects to create a challenge through in game menus.
   • User plays a short game session.
   • User is presented with a list of friends he may send the challenge to.
2. • User selects a friend to challenge from in game menus.
   • User plays a short game session.
   • The challenge is automatically sent to the recipient the user picked before starting the game session.
3. • User plays a level through regular game play.
   • User is given the option to send the level results as a challenge through in game menu.
   • User is presented with an OpenFeint screen where he may select friends to send the challenge to.

The nature of a challenge is also up to the developer. A challenge may contain any data so it could be used for something as complicated as recording the path of a car in a racing game and then allowing another user to race that car in a challenge as a ghost race. It can also be a simple as trying to beat a specific score in a specific level.

Resources
To get the id of a resource access it's resourceId property. Whenever OpenFeint expects a challengeToUserId parameter that means the resourceId of a OFChallengeToUser etc.

• 
  
• OFChallengeDefinition defines a type of challenge. Title, icon, etc. These are created in the developer dash board and referenced by a unique ID.
• 
  
• OFChallenge is a challenge created by a user. It contains the challenger and all the information about the actual challenge but it does not contain any recipients. Think of it as a free floating challenge that's not aimed at anyone in particular. Each challenge may be the "parent" of many OFChallengeToUsers who contain the recipients.
• 
  
• OFChallengeToUser is a challenge sent to a specific user. On challenge may map to many OFChallengeToUsers. It contains the challenge, the recipient and the status of the challenge (completed, result, etc).
• 
  

Quick Start

It is recommended to set up push notifications to get the most out of challenges. Instructions can be found at http://help.openfeint.com/faqs/api-features/pushnotifications.

This describes the implementation of the first scenario listed above which is likely the most common one. The basic functionality is the same for all scenarios and it should be easy to modify this example to fit your needs.

Create your Challenge Definitions on the OpenFeint developer dashboard. The icon should be of size 44x44.

Creating a challenge

1. To create a challenge the user must have approved OpenFeint. You may find this out by calling [OpenFeint hasUserApprovedFeint]. If the user has not approved OpenFeint , call [OpenFeint presentUserFeintApprovalModal] and only proceed to the next step if the approved delegate gets called.
2. To send out a challenge the user needs to be online. Find this out by calling [OpenFeint isOnline]. If the user is not online you may deny him creating the challenge or still allow him to create it after notifying him that it may not be sent.
3. To send out a challenge the user needs friends to send it to. Find this out by calling [OFFriendsService isLocalUserFollowingAnyone]. If the user is not following anyone it's recommended you let him find friends in the dashboard. You may launch the dashboard with the find friends page by calling [OpenFeint launchDashboardWithFindFriendsPage]. You may also let the user start the challenge after first notifying him that he will not be able to send it to anyone.
4. Have your app delegate (or some other appropriate object) conform to OFChallengeDelegate and pass it in when initializing OpenFeint.
5. In your in-game menu, add an option for the user to create a challenge. Optionally you may use OFChallengeDefinitionService to download challenge titles and icons to use in your menu but this is not a requirement.
6. Allow the user to play a game session while recording the necessary data, The data recorded may be xml, binary data or anything else you'd like. It will be stored on the OpenFeint servers as a binary chunk.
7. Call [OFChallengeService displaySendChallengeModal]. This will allow the user to pick friends and send out the challenge.
8. If you wish to give the user an option to create a stronger challenge for multi attempt challenges instead of sending out the one he just created, implement userRestartedCreateChallenge in your challenge delegate.
9. Implement sendChallengeScreenClosed in your challenge delegate and return the user to your challenge selection menu or some other appropriate screen in it.
   

Playing a challenge

1. Implement userLaunchedChallenge in your challenge delegate. When this gets called you need to launch the appropriate game type based on the challenge definition in the passed in OFChallengeToUser (accessed through the contained challenge) and the challenge data. You must retain the OFChallengeToUser and challenge data somewhere so it may be serialized to disk if the user turns of the game. For multi attempt challenges the user may also decide to retry the challenge in which case you must have this handy.
2. If the user closes the game during the challenge serialize the challenge data along with any other game data. The OFChallengeToUser may be serialized by calling [OFChallengeService writeChallengeToUserToFile].
3. Implement userRestartedChallenge in your challenge delegate. For one shot challenges you may leave it empty. For multi attempt challenges you should start the game session over using the OFChallengeToUser and challenge data you received when the challenge was first started.
4. Once the game session is over call [OFChallengeService submitChallengeResult]. This should always be called, regardless of the result and what kind of challenge it is.
5. Call [OFChallengeService displayChallengeCompletedModal]. This will show the result of the challenge and in the case of multi attempt challenges allow the user to re-challenge (if the challenge was beaten).
6. Implement completedChallengeScreenClosed in your challenge delegate. Either return the user to the main menu or some other appropriate screen.

Header Files

• OpenFeint.h
• 
  
• OpenFeint+Dashboard.h
• 
  
• OFChallengeService.h
• 
  
• OFChallengeDefinitionService.h
• 
  
• OFChallenge.h
• 
  
• OFChallengeDefinition.h
• 
  
• OFChallengeToUser.h
• 
  
• OFChallengeDelegate.h