Getting started with iOS

1. Requirements.

  • XCode 4.3.2 or above.
  • iOS version 5.0 or above.

If you need help creating XCode projects check the corresponding documentation at Apple developers site. We also recommend reading Start developing iOS today.

2. Download the Geosophic SDK for iOS.

Download and unzip the latest version of the Geosophic SDK for iOS here.

3. Include Geosophic SDK in your project.

Important notice


Geosophic SDK was built using the Automatic Reference Counting (ARC) setting for iOS SDK 5.0 or higher. If your project uses a previous iOS SDK version you have to setup it to be an ARC project. For more information you can check Transitioning to ARC Release Notes at the Apple developer site.
  1. Open an existing XCode project or create a new one.
  2. Include the SDK inside your project linking the libGeosophicSDK.a as a library. Go to your project target –> Build Phases –> Link Binary With Libraries and add the file. Take into account that to include non iOS SDK libraries you have to press the Other button.
  3. Add these four iOS SDK frameworks (if you haven’t done before):
    1. CoreLocation.framework
    2. SystemConfiguration.framework
    3. CoreTelephony.framework
    4. MediaPlayer.framework
    5. AdSupport.framework
  4. Include the GeosophicSDKResources.bundle in your project. Go to your project target –> Build Phases –> Copy Bundle Resources and add the bundle file.
  5. Include the Geosophic SDK public headers in your project. You can do it using two different ways. One option is to add the header files directly in the project’s workspace. Another more sophisticated option is to add the headers folder path into the the search paths of your project. Go to your project target –> Build Settings –> USER_HEADER_SEARCH_PATHS and include the path where your store the headers folder of the SDK.

4. Connect your game to your Geosophic account.

You need to add the connection parameters to your project.

  1. Create a file to store the connection settings: create a new file in your workspace called GeosophicConfig.plist.How?
  2. Add your connection settings to this file.Edit this file and add these keys:
    • Key: consumerKey, Type: String, Value: Your consumer key .
    • Key: consumerSecret, Type: String, Value: Your consumer secret.
    • Key: clientId, Type: String, Value: Your client id.

5. Using Geosophic features in your game

Build your project to check that everything is ok. Now, you are able to start using the Geosophic services.

Before going on

Here you have the best practices to use the Geosophic SDK but feel free to use it as you consider:

Headers

The headers folder contains a header called GeosophicSDK.h. This header imports all the SDK public headers into your project so it is better to import it instead of using each individual header separately.

Start and stop Geosophic service

To make Geosophic work you have to start the service using the Geosophic_ServiceController object. These functions are in charge of the background processes of the service:

    (void) initService:(NSError**) error;
    (void) stopService;

We recommend you to call the initService in your appDelegate file when the app becomes active and stop it when the app becomes inactive.

...
#import "GeosophicSDK.h"
...
- (void)applicationDidBecomeActive:(UIApplication *)application {
   NSError* error = nil;
   [Geosophic_ServiceController initService:&error];
}
...
- (void)applicationDidEnterBackground:(UIApplication *)application {
   [Geosophic_ServiceController stopService];
}
...

USE CASE: Post player scores and view leaderboards

Check how our location based leaderboards work before you use them.

Post a player score

To post a score you must call the method:

(Geosophic_ScoreResponse*) postScore:(int) score inLeaderboard:(int) leaderboardSchemaId error:(NSError**) error
score: Value of the score.
leaderboardSchemaId: Identifier of the leaderboard you want to submit the score. You can get this id in the “Settings” view of your game.
error: Holds the error message if something went wrong. If not, it returns nil.

This method returns a Geosophic_ScoreResponse object, containing the following information:

highscore: True if the score submitted is a new personal highscore.
leaderboardId: Id of the leaderboard where the score has been submitted.

It is a good practice to make this call asynchronously:

...
#define kBackGroudQueue dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0)
...
dispatch_async(kBackGroudQueue, ^{
            ...
            NSError* error;
            Geosophic_ScoreResponse* scoreResponse = [Geosophic_ServiceController postScore:points inLeaderboard:yourLeaderboardDefinitionId error:&error];
            ...
});
Display a leaderboard

There are two ways to show the leaderboards content in a HTML view:

(UIViewController*)getLeaderboardView:(int) leaderboardId withSchema:(int) leaderboardSchema error:(NSError**) error
(UIViewController*)getLeaderboardViewWithSchema:(int) leaderboardSchema error:(NSError**) error
leaderboardId: Identifier of the leaderboard you want to display. You get this id in the Geosophic_ScoreResponse object after calling “postScore”. The device’s nearest location leaderboard is showed when you use the call without the leaderboardId parameter.
leaderboardSchemaId: Identifier of the leaderboardSchema you are using. You get this id in the “Settings” page of your game.
error: Holds the error message if something went wrong. If not, it returns nil.

This method returns a ViewController which you can associate to your app main window as is shown in the example code:

...
NSError* error = nil;
UIViewController* geosophicView;
geosophicView = [Geosophic_ServiceController getLeaderboardViewWithSchema:bestCompanyLeaderboardId error:&error]; 
[self presentModalViewController:geosophicView animated:TRUE completion:nil];
 ...

Post a player vote

To post a vote you must call the method:

(Geosophic_VoteResponse*) postVote:(NSString*) vote inLeaderboard:(int) leaderboardSchema error:(NSError**) error
vote: Value of the vote.
leaderboardSchema: Identifier of the leaderboard you want to submit the vote. You can get this id in the “Settings” view of your game.
error: Holds the error message if something went wrong. If not, it returns nil. 

This method returns a Geosophic_VoteResponse object, containing the following information:

choice: The last vote posted in the leaderboard by the player. 

firstCast: True if this vote was the first vote of the player, false in other case.leaderboardSchema: Schema of the leaderboard where the score has been submitted.

It is a good practice to make this call asynchronously:

...
#define kBackGroudQueue dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0)
...
dispatch_async(kBackGroudQueue, ^{
            ...
            NSError* error;
            Geosophic_VoteResponse* voteResponse = [Geosophic_ServiceController postVote:@"Candidate 1" inLeaderboard:yourLeaderboardDefinitionId error:&error];
            ...
});
Get a player vote info

To get the player vote info you must call the method:

(Geosophic_VoteResponse*) getPlayerVote: leaderboardSchema error:(NSError**) error
leaderboardSchema: Identifier of the leaderboard which you want to obtain the info. You can get this id in the “Settings” view of your game.
error: Holds the error message if something went wrong. If not, it returns nil.
This method returns a Geosophic_VoteResponse object, containing the following information:
choice: The last vote posted in the leaderboard by the player.firstCastTrue if this vote was the first vote of the player, false in other case.

leaderboardSchema: Schema of the leaderboard where the score has been submitted.

It is a good practice to make this call asynchronously:

...
#define kBackGroudQueue dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0)
...
dispatch_async(kBackGroudQueue, ^{
            ...
            NSError* error;
            Geosophic_VoteResponse* voteResponse = [Geosophic_ServiceController getPlayerVote:yourLeaderboardDefinitionId error:&error];
            ...
});
Display a voting leaderboard

There are two ways to show the voting leaderboards content in a HTML view:

(UIViewController*)getVotingLeaderboardView:(int) leaderboardId withSchema:(int) leaderboardSchema error:(NSError**) error
(UIViewController*)getVotingLeaderboardViewWithSchema:(int) leaderboardSchema error:(NSError**) error
leaderboardId: Identifier of the leaderboard you want to display. You get this id in the Geosophic_ScoreResponse object after calling “postScore”. The device’s nearest location leaderboard is showed when you use the call without the leaderboardId parameter.
leaderboardSchema: Identifier of the leaderboardSchema you are using. You get this id in the “Settings” page of your game.
error: Holds the error message if something went wrong. If not, it returns nil.

This method returns a ViewController which you can associate to your app main window as is shown in the example code:

...
NSError* error = nil;
UIViewController* geosophicView;
geosophicView = [Geosophic_ServiceController getVotingLeaderboardViewWithSchema:bestCompanyLeaderboardId error:&error]; 
[self presentModalViewController:geosophicView animated:TRUE completion:nil];
 ...

USE CASE: Set player’s nickname

Each player has an unique nickname in Geosophic. Geosophic’s service sets a nickname, using the “PLAYER_NUMBER” format, to each player by default. To change or update the player’s nickname you must call the method:

(Geosophic_NicknameResponse*) updateNickname:(NSString*) nickname error:(NSError**) error;
nickname: The new nickname of the player.

This method returns a Geosophic_NicknameResponse object, containing the following information:

isAvailable: Returns if the user nickname is available. If it returns true, the nickname is available and set. If it returns false, the nickname is in use by another player so you have to choose another one.

getSuggestedNickname: If the nickname you requested is taken, a call to this method will give you a suggestion for an available nickname. It is not mandatory to use this one in a new update nickname call.

A sample call:

NSError *error = nil;
Geosophic_NicknameResponse *response = [Geosophic_ServiceController updateNickname:nickname error:&error];
while (![response isAvailable] & !error) {
  response = [Geosophic_ServiceController updateNickname:[response getSuggestedNickname] error:&error];
}

USE CASE: Get player’s nickname

To get the player’s nickname you must call the method:

(NSString*) getPlayerNickname: (NSError**) error;

A sample call:

NSError *error = nil;
NSString* nickname = [Geosophic_ServiceController getPlayerNickname:&error];

USE CASE: Get player’s highscores

To get the player’s global highscores in your game you must call the method:

(NSArray*) getPlayerGlobalHighscore;

This call returns an array of NSDictionary objects which represents the highscores of the player in each leaderboard schema defined in your game. Schemas which don’t have a score associated to the player are not included in the array. So if the player doesn’t have any score in any leaderboard the array is empty.
The fields of the NSDictionary object are:

  • leaderboardSchemaId: Value of the leaderboard schema associated to this highscore.
  • rank: Worldwide ranking of the player.
  • value: Value of the highscore.

An example of array returned by this call:

({leaderboardSchemaId = 567; rank = 2; value = "600.0";},{leaderboardSchemaId = 625; rank = 3; value = "740.0";},{leaderboardSchemaId = 340; rank = 4; value = "720.0";})

The use of the call is as simple as

NSArray* highscores = [Geosophic_ServiceController getPlayerGlobalHighscore];

USE CASE: Get player’s ranking for the nearest leaderboard

To get the player’s ranking for the nearest leaderboard to the current location you must call the method:

(NSArray*) getPlayerRank:(int) leaderboardSchema withNeighbours:(int) neighbours error:(NSError**) error;
leaderboardSchema: Identifier of the leaderboard schema.
neighbours: This value allow you to include data of the players that precede and follow the current player in the ranking. Zero to not include data of other players.

This call returns an array of NSDictionary objects which represents the info of the leaderboards associated to the current location. If the location is disabled the array just contains info of the worldwide leaderboard.
The fields of the NSDictionary object are:

  • latitude: Latitude of the leaderboard.
  • longitude: Longitude of the leaderboard.
  • placeName: Name of the location linked to the leaderboard.
  • playerInfo: NSDictionary with the info of the player. If the player doesn’t have any score uploaded into the leaderboard, this field is not included.
    • scoreDate: Date where the highscore was uploaded.
    • scoreValue: Value of the highscore.
    • userNickname: Nickname of the player.
    • userRank: Player ranking in this leaderboard
  • ranking: NSArray of NSDictionary objects that contains the ranking of the player and the neighbours. The array is ordered by ranking. If the player doesn’t have any score uploaded into the leaderboard, this field is not included. Each NSDictionary contains the same fields as the playerInfo object showed previously.
(
  {
   latitude = 0;
   longitude = 0;
   placeName = World;
   playerInfo =         
   {
     scoreDate = 1360732096087;
     scoreValue = 600;
     userNickname = Player2;
     userRank = 2;
    };
    ranking =         
    (
     {
      scoreDate = 1360732096086;
      scoreValue = 1540;
      userNickname = Player0;
      userRank = 0;
     },
     {
      scoreDate = 1360732096087;
      scoreValue = 1415;
      userNickname = Player1;
      userRank = 1;
     },
     {
      scoreDate = 1360732096087;
      scoreValue = 600;
      userNickname = Player2;
      userRank = 2;
     },
     {
      scoreDate = 1360732096088;
      scoreValue = 400;
      userNickname = Player3;
      userRank = 3;
     },
     {
      scoreDate = 1360732096088;
      scoreValue = 120;
      userNickname = Player4;
      userRank = 4;
     }
   );
  },
  {
   latitude = "52.1082";
   longitude = "5.32986";
   placeName = Netherlands;
  },
  {
   latitude = "52.582619";
   longitude = "4.93554";
   placeName = "North Holland";
  },
  {
   latitude = "52.373119";
   longitude = "4.89319";
   placeName = Amsterdam;
  }
)

A call example

NSArray* rank = [Geosophic_ServiceController getPlayerRank:394 withNeighbours:3 error:&error];
if (!error) {
  NSLog(@"Rank: %@", rank);
}

Use Case: Track custom events

You can track custom in-game events like finishing a level, using a power-up or purchasing an item with this feature.

(BOOL) sendUserEvent:(NSString*) eventName withData:(NSDictionary*) data error:(NSError**) error
eventName: Name that identifies the event.
data: Map of parameters to associate with the event. The objects in this map have to be serializable.
error: Returns the error message if something went wrong, if not returns nil.

This method returns true if the call is sent without problems.

Sample usage:

NSError *error;
NSMutableDictionary *eventData = [[NSMutableDictionary alloc] init];
[eventData setObject:@"30256" forKey:@"Level 1 score"];
[eventData setObject:@"15:25" forKey:@"Level 1 time"];
[Geosophic_ServiceController sendUserEvent:@"Test event" withData:eventData error:&error];

USE CASE: Use custom user account

Now players can access their scores and data from different devices. In order to do that, you need to connect the running instance with your custom User Id.

(boolean) setCustomUserId(String customUserId)
customUserId: Custom User Id. A user id unique to the users space of the developer.

Sample usage:

NSError *error;
NSString* myCustomUserId = [MyUserAccount getUserId];
[Geosophic_ServiceController setCustomUserId:myCustomUserId error:&error];