How To: Use leaderboards on iOS (iPhone/iPad) with XPG
This is a continuation of the How To series. This first post is here.
This article will cover:
- Leaderboard types and setup
- Accessing leaderboards in game
- Posting a score to a leaderboard
- Retrieving scores from a leaderboard
Prerequisites
- XCode 4 and the iOS SDK
- MonoFramework, and MonoDevelop with MonoTouch
- XPG Live API for iOS or MonoTouch
- An existing project or XPG Demo Source for iOS or MonoTouch
Leaderboard types and setup
In order to setup a leaderboard you’ll need to have a free developer account with XPG and have registered a game in the management app. Assuming you’ve done these things, you can click on the leaderboards tab in the management app and begin defining your leaderboards.
In the above image you can see the leaderboard dialog. As with most display values in the XPG system, the leaderboard name is globalized to help you provide a local experience for the end user. A display image can be defined by clicking the icon in the top right corner. The XPG system allows you to define a game-unique identifier for your leaderboard which is particularly helpful when migrating from another system to XPG, or implementing XPG along side another system. The available score types are Float, Integer, Money, and Time and each can be used with a score order of Ascending or Descending. The score order indicates if the high scores take high ranks (Descending) or if the lower scores take high ranks (Ascending). You can also limit this leaderboard’s availability by game version. Game versions are defined on the Access Keys tab in the Games area of the management app. Each version gets a new access key (or secret key) which positively identifies your game and game version.
Accessing leaderboards in game
As with many things in XPG, accessing leaderboards within your game is very simple. When your game was initialized (discussed in this post) the leaderboards defined in the XPG Management App were loaded in-game. Once these leaderboards were loaded the first page of scores for each of them was also retrieved and loaded. All the objects provided in the XPG API for MonoTouch implement the INotifyPropertyChanged interface to provide UI binding assistance and to help simplify your coding effort.
Objective-C Code
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath { static NSString *CellIdentifier = @"Cell"; UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier]; if (cell == nil) { cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault reuseIdentifier:CellIdentifier] autorelease]; } XPGLeaderboardScoreInfo* score = [((XPGLeaderboardInfo*)[[XPGAPI getCurrentGame].Leaderboards objectAtIndex:boardIndex]).Scores objectAtIndex:indexPath.row]; NSNumberFormatter* formatter = [[NSNumberFormatter new] autorelease]; formatter.numberStyle = NSNumberFormatterDecimalStyle; UILabel* scoreValLabel = [[UILabel alloc] initWithFrame:CGRectMake(350, 7, 150, 36)]; scoreValLabel.text = [formatter stringFromNumber:[NSNumber numberWithDouble:score.UserScore]]; scoreValLabel.textAlignment = UITextAlignmentRight; cell.textLabel.text = [NSString stringWithFormat:@"%d. %@", score.UserRank, score.UserNameDisplay, nil]; cell.accessoryView = scoreValLabel; return cell; } |
C# Code
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
public override UITableViewCell GetCell(UITableView tableView, MonoTouch.Foundation.NSIndexPath indexPath) { string cellIdentifier = string.Format("CellForSection{0}", indexPath.Section); var cell = tableView.DequeueReusableCell(cellIdentifier); if(cell == null) { cell = new UITableViewCell(UITableViewCellStyle.Default, cellIdentifier); } if(indexPath.Section == 0) { XPGLeaderboardScoreInfo score = XPGAPI.Instance.CurrentGame.Leaderboards[controller.BoardIndex].Scores[indexPath.Row]; UILabel scoreValLabel = new UILabel(new RectangleF(350f, 7f, 150f, 36f)); scoreValLabel.Text = score.UserScore.ToString(); scoreValLabel.TextAlignment = UITextAlignment.Right; cell.TextLabel.Text = string.Format("{0}. {1}", score.UserRank, score.UserNameDisplay); cell.AccessoryView = scoreValLabel; } else if(indexPath.Section == 1) { switch(indexPath.Row) { case 0: cell.TextLabel.Text = "Post High Score"; break; case 1: cell.TextLabel.Text = "Post Medium Score"; break; case 2: cell.TextLabel.Text = "Post Low Score"; break; case 3: cell.TextLabel.Text = "Refresh Scores"; break; default: break; } } return cell; } |
Posting a score to a leaderboard
There are overloads in C# and additional methods in Objective-C provided to work with each of the score types mentioned above. The API will perform local updates of the leaderboard data after posting a score to the server when it detects that no user data from other players has affected the ranking other than the local user. Alternatively, the API will also initiate a full update of the leaderboard local data if it detects that one or more users have affected the leaderboard ranking other than the local user. This is all handled auto-magically in order to conserve bandwidth, processor time, and device battery.
Here is an example of score posting simplicity.
Objective-C Code
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath { if (indexPath.section == 1) { XPGLeaderboardInfo* leaderboard = [[XPGAPI getCurrentGame].Leaderboards objectAtIndex:boardIndex]; if (leaderboard != nil) { NSArray* sortedArray; NSArray* sortDescriptors; NSSortDescriptor* sortDescriptor; double scoreLow, scoreHigh; sortDescriptor = [[[NSSortDescriptor alloc] initWithKey:@"UserScore" ascending:NO] autorelease]; sortDescriptors = [NSArray arrayWithObject:sortDescriptor]; sortedArray = [leaderboard.Scores sortedArrayUsingDescriptors:sortDescriptors]; scoreHigh = ((XPGLeaderboardScoreInfo*)[sortedArray objectAtIndex:0]).UserScore; sortDescriptor = [[[NSSortDescriptor alloc] initWithKey:@"UserScore" ascending:YES] autorelease]; sortDescriptors = [NSArray arrayWithObject:sortDescriptor]; sortedArray = [leaderboard.Scores sortedArrayUsingDescriptors:sortDescriptors]; scoreLow = ((XPGLeaderboardScoreInfo*)[sortedArray objectAtIndex:0]).UserScore; switch (indexPath.row) { case 0: [XPGAPI submitScoreFor:leaderboard.LeaderboardTag withLong:(scoreHigh + 10) andCallback:self]; break; case 1: [XPGAPI submitScoreFor:leaderboard.LeaderboardTag withLong:(scoreLow + (scoreHigh - scoreLow)) andCallback:self]; break; case 2: [XPGAPI submitScoreFor:leaderboard.LeaderboardTag withLong:(scoreHigh - 10) andCallback:self]; break; default: break; } } } [tableView deselectRowAtIndexPath:indexPath animated:true]; } |
C# Code
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
public override void RowSelected(UITableView tableView, NSIndexPath indexPath) { if(indexPath.Section == 1) { double lowScore, highScore; XPGLeaderboardInfo leaderboard = XPGAPI.Instance.CurrentGame.Leaderboards[controller.BoardIndex]; if(leaderboard != null) { lowScore = leaderboard.Scores.Min(x => x.UserScore); highScore = leaderboard.Scores.Max(x => x.UserScore); switch(indexPath.Row) { case 0: XPGAPI.Instance.SubmitScore(leaderboard.LeaderboardTag, (highScore + 10), HandleScoreSubmitted); break; case 1: XPGAPI.Instance.SubmitScore(leaderboard.LeaderboardTag, (lowScore + (highScore - lowScore)), HandleScoreSubmitted); break; case 2: XPGAPI.Instance.SubmitScore(leaderboard.LeaderboardTag, (highScore - 10), HandleScoreSubmitted); break; default: break; } } } tableView.DeselectRow(indexPath, true); } |
Retrieving scores from a leaderboard
Retrieving scores from XPG is equally simple. The scores are stored locally on the leaderboard instance of the initialized game instance, so there are no collections for you to keep up with and manage on your own. Also, leaderboards support paging, so you are not required to have all the ranked user scores in memory at once.
Objective-C Code
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath { if (indexPath.section == 1) { XPGLeaderboardInfo* leaderboard = [[XPGAPI getCurrentGame].Leaderboards objectAtIndex:boardIndex]; if (leaderboard != nil) { switch (indexPath.row) { case 3: [XPGAPI getScoresFor:leaderboard.LeaderboardTag atOffset:0 withCallback:self]; break; default: break; } } } [tableView deselectRowAtIndexPath:indexPath animated:true]; } |
C# Code
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
public override void RowSelected(UITableView tableView, NSIndexPath indexPath) { if(indexPath.Section == 1) { XPGLeaderboardInfo leaderboard = XPGAPI.Instance.CurrentGame.Leaderboards[controller.BoardIndex]; if(leaderboard != null) { switch(indexPath.Row) { case 3: XPGAPI.Instance.GetScores(leaderboard.LeaderboardTag, 0, HandleScoresObtained); break; default: break; } } } tableView.DeselectRow(indexPath, true); } |
The full code
Objective-C Code
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
#import <UIKit/UIKit.h> #import <XPGLive/XPGLive.h> @interface LeaderboardViewController : UITableViewController <XPGAPIReceiver> { int boardIndex; } @property (nonatomic) int boardIndex; -(void)reset; @end |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 |
#import "LeaderboardViewController.h" @implementation LeaderboardViewController @synthesize boardIndex; - (id)initWithStyle:(UITableViewStyle)style { self = [super initWithStyle:style]; if (self) { // Custom initialization } return self; } #pragma mark - View lifecycle - (void)viewWillAppear:(BOOL)animated { [super viewWillAppear:animated]; XPGLeaderboardInfo* leaderboard = (XPGLeaderboardInfo*)[[XPGAPI getCurrentGame].Leaderboards objectAtIndex:boardIndex]; self.title = leaderboard.DisplayName; } - (BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)interfaceOrientation { // Return YES for supported orientations return (interfaceOrientation == UIInterfaceOrientationPortrait); } #pragma mark - Table view data source - (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView { return 2; } - (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section { NSInteger retVal = 0; if (section == 0) { XPGLeaderboardInfo* leaderboard = (XPGLeaderboardInfo*)[[XPGAPI getCurrentGame].Leaderboards objectAtIndex:boardIndex]; retVal = [leaderboard.Scores count]; } else if (section == 1) { retVal = 4; } return retVal; } - (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath { static NSString *CellIdentifier = @"Cell"; UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier]; if (cell == nil) { cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault reuseIdentifier:CellIdentifier] autorelease]; } if (indexPath.section == 0) { XPGLeaderboardScoreInfo* score = [((XPGLeaderboardInfo*)[[XPGAPI getCurrentGame].Leaderboards objectAtIndex:boardIndex]).Scores objectAtIndex:indexPath.row]; NSNumberFormatter* formatter = [[NSNumberFormatter new] autorelease]; formatter.numberStyle = NSNumberFormatterDecimalStyle; UILabel* scoreValLabel = [[UILabel alloc] initWithFrame:CGRectMake(350, 7, 150, 36)]; scoreValLabel.text = [formatter stringFromNumber:[NSNumber numberWithDouble:score.UserScore]]; scoreValLabel.textAlignment = UITextAlignmentRight; cell.textLabel.text = [NSString stringWithFormat:@"%d. %@", score.UserRank, score.UserNameDisplay, nil]; cell.accessoryView = scoreValLabel; } else if (indexPath.section == 1) { switch (indexPath.row) { case 0: cell.textLabel.text = @"Post High Score"; break; case 1: cell.textLabel.text = @"Post Medium Score"; break; case 2: cell.textLabel.text = @"Post Low Score"; break; case 3: cell.textLabel.text = @"Refresh Scores"; break; default: break; } } return cell; } #pragma mark - XPG API delegate -(void)getScoresCompletedWith:(XPGAPIResponse *)response { [self.tableView reloadData]; } -(void)submitScoreCompletedWith:(XPGAPIResponse *)response { [self.tableView reloadData]; } -(void)reset { } #pragma mark - Table view delegate - (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath { if (indexPath.section == 1) { XPGLeaderboardInfo* leaderboard = [[XPGAPI getCurrentGame].Leaderboards objectAtIndex:boardIndex]; if (leaderboard != nil) { NSArray* sortedArray; NSArray* sortDescriptors; NSSortDescriptor* sortDescriptor; double scoreLow, scoreHigh; sortDescriptor = [[[NSSortDescriptor alloc] initWithKey:@"UserScore" ascending:NO] autorelease]; sortDescriptors = [NSArray arrayWithObject:sortDescriptor]; sortedArray = [leaderboard.Scores sortedArrayUsingDescriptors:sortDescriptors]; scoreHigh = ((XPGLeaderboardScoreInfo*)[sortedArray objectAtIndex:0]).UserScore; sortDescriptor = [[[NSSortDescriptor alloc] initWithKey:@"UserScore" ascending:YES] autorelease]; sortDescriptors = [NSArray arrayWithObject:sortDescriptor]; sortedArray = [leaderboard.Scores sortedArrayUsingDescriptors:sortDescriptors]; scoreLow = ((XPGLeaderboardScoreInfo*)[sortedArray objectAtIndex:0]).UserScore; switch (indexPath.row) { case 0: [XPGAPI submitScoreFor:leaderboard.LeaderboardTag withLong:(scoreHigh + 10) andCallback:self]; break; case 1: [XPGAPI submitScoreFor:leaderboard.LeaderboardTag withLong:(scoreLow + (scoreHigh - scoreLow)) andCallback:self]; break; case 2: [XPGAPI submitScoreFor:leaderboard.LeaderboardTag withLong:(scoreHigh - 10) andCallback:self]; break; case 3: [XPGAPI getScoresFor:leaderboard.LeaderboardTag atOffset:0 withCallback:self]; break; default: break; } } } [tableView deselectRowAtIndexPath:indexPath animated:true]; } @end |
C# Code
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 |
using System; using System.Collections.Generic; using System.Drawing; using System.Linq; using MonoTouch.Foundation; using MonoTouch.UIKit; using XPG; namespace XPG.Demo.MT { public partial class LeaderboardViewController : UITableViewController { public int BoardIndex { get; set; } //loads the LeaderboardViewController.xib file and connects it to this object public LeaderboardViewController() : base ("LeaderboardViewController", null) { } public override void ViewDidLoad() { base.ViewDidLoad(); this.Title = XPGAPI.Instance.CurrentGame.Leaderboards[BoardIndex].DisplayName; this.TableView.Source = new DataSource(this); } public override bool ShouldAutorotateToInterfaceOrientation(UIInterfaceOrientation toInterfaceOrientation) { return toInterfaceOrientation.Equals(UIInterfaceOrientation.Portrait); } public override void DidReceiveMemoryWarning() { base.DidReceiveMemoryWarning(); } public override void ViewDidUnload() { base.ViewDidUnload(); } class DataSource : UITableViewSource { LeaderboardViewController controller; public DataSource(LeaderboardViewController controller) { this.controller = controller; } // Customize the number of sections in the table view. public override int NumberOfSections(UITableView tableView) { return 2; } public override int RowsInSection(UITableView tableview, int section) { return (section == 1 ? 4 : XPGAPI.Instance.CurrentGame.Leaderboards[controller.BoardIndex].Scores.Count); } // Customize the appearance of table view cells. public override UITableViewCell GetCell(UITableView tableView, MonoTouch.Foundation.NSIndexPath indexPath) { string cellIdentifier = string.Format("CellForSection{0}", indexPath.Section); var cell = tableView.DequeueReusableCell(cellIdentifier); if(cell == null) { cell = new UITableViewCell(UITableViewCellStyle.Default, cellIdentifier); } if(indexPath.Section == 0) { XPGLeaderboardScoreInfo score = XPGAPI.Instance.CurrentGame.Leaderboards[controller.BoardIndex].Scores[indexPath.Row]; UILabel scoreValLabel = new UILabel(new RectangleF(350f, 7f, 150f, 36f)); scoreValLabel.Text = score.UserScore.ToString(); scoreValLabel.TextAlignment = UITextAlignment.Right; cell.TextLabel.Text = string.Format("{0}. {1}", score.UserRank, score.UserNameDisplay); cell.AccessoryView = scoreValLabel; } else if(indexPath.Section == 1) { switch(indexPath.Row) { case 0: cell.TextLabel.Text = "Post High Score"; break; case 1: cell.TextLabel.Text = "Post Medium Score"; break; case 2: cell.TextLabel.Text = "Post Low Score"; break; case 3: cell.TextLabel.Text = "Refresh Scores"; break; default: break; } } return cell; } public override void RowSelected(UITableView tableView, NSIndexPath indexPath) { if(indexPath.Section == 1) { double lowScore, highScore; XPGLeaderboardInfo leaderboard = XPGAPI.Instance.CurrentGame.Leaderboards[controller.BoardIndex]; if(leaderboard != null) { lowScore = leaderboard.Scores.Min(x => x.UserScore); highScore = leaderboard.Scores.Max(x => x.UserScore); switch(indexPath.Row) { case 0: XPGAPI.Instance.SubmitScore(leaderboard.LeaderboardTag, (highScore + 10), HandleScoreSubmitted); break; case 1: XPGAPI.Instance.SubmitScore(leaderboard.LeaderboardTag, (lowScore + (highScore - lowScore)), HandleScoreSubmitted); break; case 2: XPGAPI.Instance.SubmitScore(leaderboard.LeaderboardTag, (highScore - 10), HandleScoreSubmitted); break; case 3: XPGAPI.Instance.GetScores(leaderboard.LeaderboardTag, 0, HandleScoresObtained); break; default: break; } } } tableView.DeselectRow(indexPath, true); } private void HandleScoreSubmitted(XPGAPIResponse<XPGScoreResultInfo> response) { controller.TableView.ReloadData(); } private void HandleScoresObtained(XPGAPIResponse<XPGScoresResultInfo> response) { controller.TableView.ReloadData(); } } } } |
Leave a Reply
You must be logged in to post a comment.
-
Recent Posts
Recent Comments
- How To: Use Leaderboards on BlackBerry with XPG | XPG Live | ThrowSMS News on How To: Use Leaderboards on BlackBerry with XPG
- How To: Use Leaderboards on BlackBerry with XPG | XPG Live on How To: Initialize a game on Android with XPG
- How To Use leaderboards on Windows Phone with XPG on How To: Get started with XPG
- How To: Use Leaderboards on Android with XPG | XPG Live on How To: Initialize a game on Android with XPG
- How To: Use leaderboards on iOS (iPhone/iPad) with XPG | XPG Live on How To: Get started with XPG
Archives
Tags
.NET access Account Achievement Android Announcement api BlackBerry C# callback Code Create cross-platform demo Dev Development Edit Framework Game Generics GUI IDE initialization Intermediate iOS JAR Java Leaderboard Manage Mobile Mono MonoDroid MonoTouch Obj-C Posting Profile Publisher reference response Retrieving Score thread UI WP7 XPGCategories
