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, loss, 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 its completed. Once a user completes a challenge he may challenge back 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 theimplementation the experience and scope may vary greatly. Here are some possible scenarios but this list is by no means exhaustive:
User chooses to create a challenge through in-game menus. User plays a short game session. User is presented with a list of friends to whom he may send the challenge.
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.
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 as simple as trying to beat a specificscore in a specific level.
Resources
To get the id of a resource, access its 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 thats not aimed at anyone in particular. Each challenge may be the parent of many OFChallengeToUsers that contain the recipients.
OFChallengeToUser is a challenge sent to a specific user. One 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 that you set up push notifications in order to get the most out of challenges. 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 4444.
Creating a challenge
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 inOFChallengeToUser (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. 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 [OFChallengeServicewriteChallengeToUserToFile]. Implement userRestartedChallenge in your challenge delegate.For one shot challenges you may leave it empty. For multi attemptchallenges you should start the game session over using theOFChallengeToUser and challenge data you received when thechallenge was first started. Once the game session is over, call OFChallengeServicesubmitChallengeResult]. This should always be called regardless of the result and what kind of challenge it is. Call [OFChallengeService displayChallengeCompletedModal]. This displays the result of the challenge and in the case of multiattempt challenges allows the user to re-challenge (if the challenge was beaten). 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