iOS API

Issues with this document? Submit a pull request to the website repository please.

Downloading the API

You can either download the zip or if you're a git user clone the repository.

Initializing the API

Before using the API you must initialize it with your public and private keys. Your keys need to be created in your database.

[Playtomic initWithPublicKey:@"testpublickey"
               andPrivateKey:@"testprivatekey"
                   andAPIURL:@"http://127.0.0.1:3000/"];

Your apiurl will be in the format http://your-application-name.herokuapp.com/ or similar.

Examples

Each API has an extensive test library in the source code that demonstrates how to use every part in a variety of ways.

Newsletter subscription

Please note this requires additional setup you can read about here.

You can subscribe players to your newsletter mailinglist. By default this uses double-opt in so when a player registers for it they are sent an email and then confirm their intention.

You can collect additional data with your subscriptions but you must set it up first at MailChimp.

[[Playtomic Newsletter] subscribe:options andHandler:handler];

Subscription options NSMutableDictionary

Property Type Description
email NSString The player's email address
firstname NSString The player's first name
lastname NSString The player's last name
fields NSMutableDictionary Container for custom MERGE tag name and values defined in your MailChimp list.

Subscribing a player

NSMutableDictionary *fields = [[NSMutableDictionary alloc] init];
[options setObject:@"ipad" forKey:@"version"];

NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
[options setObject:@"[email protected]" forKey:@"email"];
[options setObject:fields forKey:@"fields"];

// note that these example MERGE fields must be created in your MailChimp
// dashboard, they do not exist by default.

[[Playtomic Newsletter] subscribe:options andHandler:^(PResponse* response){

    if(response.success) {
    }
    else {
      // response failed because of response.errormessage
    }
});

Achievements

The Achievements API gives you two powerful ways to add social, cross-platform achievements to your game.

Achievements have to be configured in your database first in the 'achievements' collection with the structure:

{ achievement: "the name", achievementkey: "secret key used when awarding" }

You can include any additional properties you want and have them returned in your game such as image urls, descriptions etc.

PlayerAchievement

Property Type Description
playername NSString The player name. This can be by the player or provided by any 3rd party
playerid NSString Facebook or other userids, used for filtering by friends.
achievement NSString The name of the achievement.
source NSString The website or device the score occurred on
fields NSMutableDictionary Any additional data you want to (or have) attached to an achievement like difficulty - that would mean for each achievement you automatically have 'easy', 'normal', 'hard' and can differentiate between them when retrieving the achievements.
Properties set by the API server
player PlayerAward When listing if a playerid is provided their details are included here when they have the achievement
friends NSArray When listing if a friendslist is provided any friends who have the achievement are included in this collection.
Saving details
achievementkey NSString The secret key used when saving achievements by players
overwrite Boolean If the player already has the achievement save over it
allowduplicates Boolean If the player already has the achievement give it again

Saving achievements

To save an achievement you must know the achievement name and key and they must match what you configure in your database. This means if you want you can provide separate keys for each achievement so players can't easily cheat.

Playtomic.Achievements.save(achievement, callback);

A full example:

NSMutableDictionary *fields = [[NSMutableDictionary alloc] init];
[fields setObject:@"easy" forKey:@"difficulty"];

PlayerAchievement *achievement = [[PlayerAchievement alloc] init];
achievement.achievement = "Punched Tass",
achievement.achievementkey = "abcdefgh",
playerid = "1",
achievement.playername = "ben",
achievement.fields = fields;

[[Playtomic Achievements] save:achievement andHandler:^(PResponse* response) {

  if(response.success) {
    // note that we could still have a failure errorcode here when the player
    // already has an achievement
  }
  else {
    // response failed because of response.errormessage
  }
}];

Listing achievements

Achievement lists can be requested that include just the achievement information or also incorporate the player and friends.

Playtomic.Achievements.list(options, callback);

Listing options

Property Type Description
playerid NSString Facebook or other userids, used for filtering by friends.
friendslist NSArray Friends' playerids
filters NSMutableDictionary Any additional filtering information from the 'fields'

Some examples:

// just the achievements
[[Playtomic Achievements] list:Nil andHandler:^(NSArray* achievements, PResponse* response) {

  if(response.success) {
  for(PlayerAchievement *achievement in achievements)
  {
    NSLog(@"%@", achievement);
  }
  else
  {
    NSLog(@"Request failed because %@", response.errormessage);
  }
  }
}];

NSMutableArray *friends = [[NSMutableArray alloc] init];
[friends addObject:@"2"];
[friends addObject:@"3"];
[friends addObject:@"4"];
[friends addObject:@"5"];

NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
[options setObject:@"1" forKey:@"playerid"];
[options setObject:friends forKey:@"friendslist"];

[[Playtomic Achievements] list:options andHandler:^(NSArray* achievements, PResponse* response) {
  if(response.success) {
    for(PlayerAchievement *achievement in achievements)
    {
      NSLog(@"%@", achievement);
    // something like:
    //{
    //  achievement: "Punched Tass",
    //  player: {
    //    playerid: "1",
    //    playername: "ben",
    //    date: Date(),
    //    rdate: "Just now",
    //    fields: {
    //      difficulty: "easy"
    //    }
    //  },
    //  friends: [
    //    {
    //      // same as player object but for any friends with the achievement
    //    }
    //  ]
    //}
    }
}];

Activity stream

You can also get achievements represented as an activity stream of each award.

Playtomic.Achievements.stream(options, callback);

Streaming options

Property Type Description
group Boolean If 'true' each person is only included once with their most recent award. If false it will include every award.
playerid NSString Facebook or other userids, used for filtering by friends.
friendslist NSArray Friends' playerids
filters NSMutableDictionary Any additional filtering information from the 'fields'
page int Page number to return (default is 1)
perpage int Results per page (default is 20)
mode NSString today, last7days, last30days
source NSString Device or website if you save that information

PlayerAward

When you 'stream' the messages are returned in this format. This is the same format used when you include player or friend information in 'list'.

playername String The player name. This can be by the player or provided by any 3rd party
playerid NSString Facebook or other userids, used for filtering by friends.
date NSDate The date of the the achievement was awarded
rdate NSString The relative date of the achievement was awarded eg "7 minutes ago"
source NSString Device or website if you save that information
fields NSMutableDictionary Any additional data you want to (or have) attached to an achievement like difficulty - that would mean for each achievement you automatically have 'easy', 'normal', 'hard' and can differentiate between them when retrieving the achievements.

Example streams

// show all the hard achievements by my friends and i as a stream
NSMutableArray *friends = [[NSMutableArray alloc] init];
[friends addObject:@"2"];
[friends addObject:@"3"];
[friends addObject:@"4"];
[friends addObject:@"5"];

NSMutableDictionary *filters = [[NSMutableDictionary alloc] init];
[filters setObject:@"hard" forKey:@"difficulty"];

NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
[options setObject:@"1" forKey:@"playerid"];
[options setObject:friends forKey:@"friendslist"];
[options setObject:filters forKey:@"filters"];
[options setObject:[NSNumber numberWithBool:true] forKey:@"group"];

[[Playtomic Achievements] list:options andHandler:^(NSArray* achievements, int numachievements PResponse* response) {
  if(response.success) {
    for(PlayerAchievement *achievement in achievements)
    {
      NSLog(@"%@", achievement);
	  // something like
      // {
      //  playerid: "1",
      //  playername: "ben",
      //  date: Date(),
      //  rdate: "Just now",
      //  fields: {
      //     difficulty: "hard" }
      //  },
      //  awarded: {
      //    achievement: "Punched tass"
      //  }
      // }
    }
}];

Leaderboards

The Leaderboards API gives you very flexible high and low score leaderboards. They can be created in your game dynamically or set up in the edit leaderboards page.

PlayerScore structure

Property Type Description
playername NSString The player name. This can be by the player or provided by any 3rd party
playerid NSString Facebook or other userids, used for filtering by friends.
points int64_t The player's score
source NSString The website or device the score occurred on
fields NSDictionary Any additional data you want to (or have) attached to a score.
Properties set by the API server
date NSDate The date of the score
rdate NSString The relative date of the score eg "7 minutes ago"
rank NSInteger The rank based on your listing parameters.
Table detais
table NSString The name of the score table
highest Boolean The sort ordering by highest or lowest
allowduplicates Boolean Create duplicates, or override or reject scores if they're not the best

Submitting scores

Score submission is handled by:

[[Playtomic Leaderboards] save:score
                     andHander:(void(^)(PResponse *response))handler);
// basic score
PlayerScore *score = [[PlayerScore alloc] init];
score.playername = @"ben";
score.points = 173000;
score.table = @"highscores";
score.allowduplicates = true;

[[Playtomic Leaderboards] save:score andHandler:^(PResponse* response) {
  if(response.success)
  {
  }
  else
  {
    // score failed because of [response errorMessage] with response.errorcode
  }
}];

// another score
NSMutableDictionary *fields = [[NSMutableDictionary] alloc] init];
[fields setObject:@"barbarian" forKey:@"character"];
[fields setObject:[NSNumber numberWithInt:7] forKey:@"level"];
[fields setObject:[NSNumber numberWithInt:18] forKey:@"kills"];

PlayerScore *score2 = [[PlayerScore alloc] init];
score2.playername = @"ben";
score2.points = 173000;
score2.table = @"highscores";
score2.allowduplicates = true;
score2.fields = fields;

[[Playtomic Leaderboards] save:score andHandler:^(PResponse* response)
{
  if(response.success)
  {
  }
  else
  {
    // score failed because of [response errorMessage] with response.errorcode
  }
}];

Showing scores

Scores are loaded via a simple method that returns an array of scores to your function where you can display the data in your leaderboard.

[[Playtomic Leaderboards] list:options
                    andHandler:(void(^)(NSArray *scores, int numscores, PResponse *response))handler;
Property Type Description
table NSString The name of the score table
highest Boolean The sort ordering by highest or lowest
allowduplicates Boolean Reject scores if they're not the player's best (default false) or allow multiple scores per player
filters NSDictionary Additional properties to filter by from the 'save' fields
source NSString The website or device the score occurred on
friendslist NSArray Array of friend's playerids
playerid NSString A specific playerid
mode String Time limits, 'last7days', 'last30days', 'alltime' (default), 'today' and 'newest' which returns latest unsorted scores.
Pagination
page int Page number to return (default is 1)
perpage int Results per page (default is 20)
NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
[options setObject:@"highscores" forKey:@"table"];
[options setObject:[NSNumber numberWithBool:true] forKey:@"highest"];
[options setObject:[NSNumber numberWithInteger:1] forKey:@"page"];
[options setObject:[NSNumber numberWithInteger:10] forKey:@"perpage"];

[[Playtomic Leaderboards] list:options andHandler:^(NSArray *scores, int numscores, PResponse *response) {
    if(response.success)
  {
    for(PlayerScore *score in scores)
    {
      NSLog(@"%@ got %d points", score.name, score.points);
    }
    }
  else
  {
        // score failed because of [response errorMessage] with response.errorcode
    }
}];

Save and list

You can submit scores and at the same time return the leaderboard page that that score is on. This combines the Save and List approaches from above:

[[Playtomic PlayerLevels] saveAndList:(PlayerLevel*)level
                           andOptions:(NSDictionary*)options
                           andHandler:(void(^)(NSArray *scores, int numscores, PResponse *response))handler;

You don't specify a 'page', you specify the 'perpage' (default 20) and it will automatically decide which page to return based on the submitted score's rank. If you submit the 1187th best score at 30 per page then it will show you page 39, scores #1170 - #1200.

Ranks are returned so you are not viewing the top N scores you are viewing the top N scores from rank X onwards.

Level sharing

The level sharing API provides a way to store and retrieve user-generated content for your game. It can operate anonymously or authenticated via any 3rd party service you're already using.

PlayerLevel structure

Saving and listing levels uses this class to represent a level.

Property Type Description
name NSString The level name.
playername NSString The player name.
playerid NSString Facebook or other userids, used for filtering by friends.
data NSstring The created level data as a string
source NSString The website or device the score occurred on
fields NSDictionary Any additional data you want to (or have) attached to a level.

Saving levels

[[Playtomic PlayerLevels] save:(PlayerLevel*)level
                    andHandler:(void(^)(PlayerLevel *level, PResponse *response))handler]

Example saving level:

PlayerLevel *level = [[PlayerLevel alloc] init];
level.name = @"my level";
level.playername = @"ben";
level.data = "obj1=cannon&obj1x=120&obj1y=180",

[[Playtomic PlayerLevels] save:level andHandler:^(PlayerLevel *l, PResponse *response) {
  if(response.success)
  {
    // new levelid is level.levelid;
  }
  else
  {
    // save failed because of [response errorMessage] with response.errorcode
  }
}];

Rating levels

Levels can be rated 1 - 10 by players. Rating can be done anonymously with some protection against repeat voting, or bound to playerids if you specify them.

[[Playtomic PlayerLevels] rate:(NSString*)levelid
                     andRating:(int)rating
                    andHandler:(void(^)(PResponse *response))handler]

Example rating level:

[[Playtomic PlayerLevels] rate:level.levelid andRating:7 andHandler:^(PResponse *response) {
    if(response.success)
  {
        // rating succeeded
    }
  else
  {
        // Rating failed because of [response errorMessage] with response.errorcode
    }
}];

Listing levels

Listing levels can be done by popular or newest, with optional filtering by date ranges and/or custom fields.

[[Playtomic PlayerLevels] list:(NSDictionary*)options
                    andHandler:(void (^)(NSArray *levels, int numlevels, PResponse *response))handler]

Listing options

Property Type Description
mode NSString
  • alltime
    The most popular levels based on all time ratings
  • newest
    The most recently created levels
  • recentaverage
    Average calculated across just the last 100 votes a level received
  • todayaverage | yesterdayaverage | last7daysaverage | last30daysaverage | last90daysaverage
    Aggregated rating averages on / in the specified timeframe
datemin NSString 'mm/dd/yyyy' for the minimum date the level was created.
datemax NSDate The maximum date the level was created.
playerid String Facebook or other userid
friendslist NSArray Array of friend's playerids
data Boolean Return the level data with the request (maybe faster to load individually)
source NSString The website or device the level was created on
filters NSDictionary Any additional data you want to (or have) attached to a level.
Pagination
page int Page number to return (default is 1)
perpage int Results per page (default is 20)

An example listing levels:

NSMutableDictionary *filters = [[NS MutableDictionary alloc] init];
[filters setObject:@"hard" forKey:@"difficulty"];

NSMutableDictionary *list = [[NSMutableDictionary alloc] init];
[list setObject:@"newest" forKey:@"mode"];
[list setObject:[NSNumber numberWithInt30] forKey:@"perpage"];
[list setObject:[NSNumber numberWithBool:NO] forKey:@"data"];
[list setObject:filters forKey:@"filters"];

[[Playtomic PlayerLevels] list:list andHandler:^(NSArray *levels, int numlevels, PResponse *response) {

    if(response.success)
  {
    for(PlayerLevel *level in levels)
    {
      NSLog(@"%@", level.name);
    }
    }
  else
  {
        // score failed because of [response errorMessage] with response.errorcode
    }

}];

Loading levels

If you do not include the data when you load lists of levels then you can request it seperately.

[[Playtomic PlayerLevels] load:(NSString*)levelid
                    andHandler:(void(^)(PlayerLevel *level, PResponse *response))handler];

An example loading a single level:

[[Playtomic PlayerLevels] load:levelid andHandler:^(PlayerLevel *level, PResponse *response) {
    if(response.success)
  {
    // level loaded
    }
  else
  {
        // score failed because of [response errorMessage] with response.errorcode
    }

}];

GameVars

GameVars let you change the value of key variables in your game any time you want.

Setting them up in your database

In your MongoHQ dashboard add a new entry to the "gamevars" collection.

{
  name: "basehitpoints",
  value: 800
}

Loading

They are loaded via:

[[Playtomic GameVars] load:(void (^)(NSDictionary* gamevars, PResponse *response))handler];

You can load variables individually, for instance if you are caching the GameVars you can check a 'version' GameVar to decide whether to reload the full collection.

[[Playtomic GameVars] loadWithName:(NSString*)name
                        andHandler: (void (^)(NSDictionary* gamevars, PResponse *response))handler];

The callback parameter is your function that receives an NSDictionary that has properties matching the variables you have configured in your database. The callback is the same for all or single GameVars.

// our variables with default, original values
int basehitpoints = 100;
int basegold = 50;

[[Playtomic GameVars] load:^(NSDictionary* gamevars, PResponse* response){

  if(response.success)
  {
    basehitpoints = [[gamevars objectForKey:@"basehitpoints"] integerValue];
  }
  else
  {
    // request failed with [response errorMessage] with response.errorcode
  }
}];

Geolocation

The GeoIP service identifies which country the player is from, returning their country code and name.

It is called via:

[[Playtomic GeoIP] lookup:(void (^)(PlayerCountry* country, PResponse *response))handler]

The callback function receives an object that has 'code' and 'name' properties:

[[Playtomic GeoIP] lookup:^(PlayerCountry* country, PResponse* response){
  if(response.success)
  {
    // player is in country.name with the 2 digit code country.code
  }
  else
  {
    // request failed with [response errorMessage] with response.errorcode;
  }
}];