Please help us improving it by reporting us any bugs or suggestions to [email protected], we put our best efforts in order to make life easier for you and the other developers, and your help will be greatly appreciated.
In this document we’ll dig into social competition that allow users to gain experience points (XP) and gems, plus your games to be promoted through achievements and highscores. This is vital for us, isolated games which doesn’t allow users to compete against their friends won’t have as much engagement or promotion. Please refer to the MINIPLAY APIs OVERVIEW document first if you haven’t read it yet, knowledge of the concepts explained there is required.
Like we previously stated in the Overview document, all the user competition is based on one simple thing: game statistics. For us to reward the user with experience points (XP) & gems and let him/her compete with their friends we need to know how well is the user doing in your game.
Stats are the multiple scores that the players generates while interacting with your games. It’s very important that you send us meaningful stats, we create them manually so we can assure that you send us the best data available in order to produce great competition and achievements for our players. Don’t worry, it’ll be easy, later we’ll see a few real life examples, and we’ll also provide you with a workflow diagram in order to give you better understanding.
A stat must always be a 32 bit number (absolute and non-decimal), so, no negative numbers or strings are allowed. In case that you need decimal numbers, multiply it for 
to produce an integer number (don’t forget to tell us that you’re doing it so we can adjust the precision!).
The highest number supported is 2 147 483 647.
The stat_uid is the immutable unique alphanumeric string (without spaces or special characters) within your game.
Stats cannot be deleted, if you don’t need one, don’t send it anymore.
We support 4 types of statistics:
We’re most interested in statistics that allows us to track the user progress. Think of the user level, the stars collected in one level, the number of enemies defeated, the total matches won (or lost), the fastest lap...
Always try to send us meaningful stats, a max stat user_level=10 is preferred over a max stat user_progress=3495.
A game_played=1 (or simipar) stat is also recommended to be sent after the game load finishes, so you can be sure that the stat system is working well and wheter the user has already played the game or not, players that don't get their rewards after playing get very angry! :)
Send us a stat whenever the user completes levels and the full game (and if there are difficulties, use different stats for each one of them). A best_level=level_num max stat will allow us to know the best level that your players reached.
If your game have achievements or badges, send us a unlock_[achievement_name] =1 max stat so we can replicate your badges as achievements for our platforms (achievements promotes your games!)
Please do not spam us with statistics constantly, while our servers can handle a lot of connections, the logic behind any stat submission is very complex. I.e., don’t send us a jump=1 every time the user jumps or shoots a bullet, instead, collect it and send us the total bullets shoot for a particular level. API usage is tracked for every game, try to keep it at a reasonable level.
Please use the following Excel as a reference and send us a list of achievements and / or highscores in the same way.
Download the Excel example here: http://bit.ly/AchievementsAndHighscores
Is developer's responsibility to check that the statistics are sent successfully. Use the error messages and try again to send data in case of error.
One option to ensure that the user has the same achievements unlocked both on the game and on the web is to send a batch of in-game unlocked achievements after game loading, as long as the as the data itself is truly relevant for the game (i.e.: do not sync a score of zero points)
Scoreboards are very important not only for us, but for the users as well, we provide both global and friends scoreboards for all users. For global scoreboards they’re available in daily, weekly, monthly and absolute flavours. This allow you to compete and beat the people you follow. When users enters the top 10, 3 or 1, the event gets promoted on their followers newsfeeds.
We use some of the stats you send us for the scoreboards, i.e. if you send us the best_points (or event last_points) stat, we can create a scoreboard for the best points.
Scoreboards have their logic fully detached from the stat type, in other words, it doesn’t care what the stat type is or even if the stat you sent was saved (because it not was higher or lower).
There’s no limit in the amount of scoreboard that we can create, but we’ll try to keep them in a manageable amount (users can select which scoreboard they want to see).
Every game must have one main scoreboard, it should be based on a stat that represent which user is the best, this is a crucial for us, because the main scoreboard will get a lot of social distribution and even real time notifications.
Custom, secondary, time-bound scoreboards may be created by us in order to promote your game in a specific timeframe, i.e. for a halloween or a christmas campaign.
Scoreboards can be hidden but cannot be deleted.
Scoreboards cannot be reset (i.e. to provide weekly based sum counters), it’s within our plans to provide API access to highscore management to allow you create new highscores and deprecate the old ones (feature not available yet).
The scorehs_uid is the immutable unique alphanumeric string (without spaces or special characters) within your game.
We support 3 types of scoreboards:
Scoreboards can be set to sort scores ASCENDING or DESCENDING, this is immutable, once set, it cannot be changed later.
Our team will manually create achievements for your games based on the stats you send us. All the achievements unlocked by the users will promote your game in their followers newsfeeds, they also reward the users with experience points (XP) & gems.
Achievements can be also based on multiple stats, even stats sent with different timestamps to produce complex conditions by combining events!. I.e. if you send us a level_completed=10 REPLACE stat and a remaining_lives=X REPLACE stat 2 seconds later we can group both and unlock an achievement when the user completes the level 10 with more than 3 lives remaining. Anyway, instead of having to do this kind of tricks, we rather prefer you to choose and send us your achievements by using some sort of unlock_[achievement]=1 REPLACE type stat.
Please notice that we do not support OR conditions for multiple stats, only AND.
Achievements can have an easy, medium or hard difficulty. The more difficulty & experience points granted the achievement unlocked has, the more distribution it’ll get.
There’s a limit of 500 experience points (XP) that your game could reward users through achievements (experience points allow users to improve their levels and gain gems), but for larger, longer, or for games that have more achievements the amount could be higher (will be decided ad hoc).
There’s no limit in the amount of achievements we can create, but to keep things simple for casual, short games, we usually recommend no more than 4 achievements (mixing different difficulty levels). For larger games more achievements are recommended, but be warnend that the amount of total experience potints rewarded by your game must be distributed between them, in that case we'll probably grant your game with more XP points to distribute (we'll do that for you).
The achievement_uid is the immutable unique alphanumeric string (without spaces or special characters) within your game.
Send us a list of achievements that your game will unlock through stats (i.e. unlock_tutorial = 1 will unlock the tutorial badge).
For each achievement: include in that list the stat_uid, stat_type, achievement_uid, achievement name, achievement difficulty level & the experience points (XP) rewarded. Don't worry about the XP, we will make corrections to them if they're not very good of if we rise the amount available for your game, just make sure you send us the difficulty, we cannot play each game. Please sort them by ascending difficulty, being the last one the most difficult.
If you already integrated your game for the largest social network :), provide us your achievement configuration files (or urls) and we’ll do the rest.
The following diagram will provide you better understanding of our process and what happens behind the scenes of your game. It all begins when an user starts playing your game...
Here is the configuration of some games.
In this game, users can compete in 3 different tracks with 2 different difficulty leves to try to get the best time.
race_start = 1 (REPLACE)
When a race starts
When a lap is completed:
current_track = 1 (REPLACE)
Track number
current_lap_time = X (REPLACE)
Lap time
When the race ends:
current_difficulty = 1 (REPLACE)
Difficulty level (0:EASY / 1:HARD)
current_track = 1 (REPLACE)
Track number
current_total_time = X (REPLACE)
Track number
current_laps = X (REPLACE)
Number of laps completed
current_laps_leader = X (REPLACE)
Number of laps completed as leader
race_win = 1 (REPLACE)
Did you win the race?
race_lost = 1 (REPLACE)
Did you win the race?
race_wins = X (MAX)
Total race wins
race_wins_easy = X (MAX)
Total race wins with easy difficulty
race_wins_hard = X (MAX)
Total race wins with hard difficulty
driver_points = X (MAX)
Total points won (each race gives users points)
Best lap time for each track:
best_lap_track_1 = (MIN)
Best lap time for track 1 (multiplied by 1000)
best_lap_track_2 = (MIN)
Best lap time for track 2 (multiplied by 1000)
best_lap_track_3 = (MIN)
Best lap time for track 3 (multiplied by 1000)
easy_all_won = 1 (MAX)
Win every race with easy difficulty
hard_all_won = 1 (MAX)
Win every race with hard difficulty
driver_points
best_lap_track_1
best_lap_track_2
best_lap_track_3
race_wins
easy_all_won
hard_all_won
race_wins_hard
driver_points
In this game, users have to beat 10 levels and 3 worlds, on each level they can collect up to 3 stars.
When starts a level:
current_world = X (REPLACE)
World number
current_level = X (REPLACE)
Level number
When the user completes a level:
current_world = X (REPLACE)
World number
current_level = X (REPLACE)
Level number
current_time = X (REPLACE)
Time of the completion
current_stars = X (REPLACE)
Number of laps completed
When the user completes a world:
current_world_completed = X (REPLACE)
World completed
score = X (MAX)
User score (the game produces it)
total_levels_completed = X (MAX)
Total levels completed
total_levels_allstars = X (MAX)
Total levels with all stars
world_1_lvl_completed = X (MAX)
World 1 completed levels
world_2_lvl_completed = X (MAX)
World 2 completed levels
world_3_lvl_completed = X (MAX)
World 3 completed levels
world_1_completed = X (MAX)
World 1 completed
world_2_completed = X (MAX)
World 2 completed
world_3_completed = X (MAX)
World 3 completed
world_1_stars = X (MAX)
Stars collected at world 1
world_2_stars = X (MAX)
Stars collected at world 2
world_3_stars = X (MAX)
Stars collected at world 3
all_completed = X (MAX)
All worlds completed
all_stars = 1 (MAX)
All stars of all worlds collected
total_levels_completed
world_1_stars
world_2_stars
world_3_stars
total_levels_completed
world_1_completed = 1
world_2_completed = 1
all_completed = 1
all_stars= 1
This game uses their own servers and handles everything by itself, so we’re going to replicate all the achievements that the game already has, every time the user unlocks one, they send us an unlock_[achievement_name] = 1 stat (All these stats are MAX type).
Additionally, the game sends us a cummulative total_points stat (MAX type) that allowed us to create a main scoreboard which shows the best players of the game.
The game also handles their own weekly scoreboards, on each weekly reset, they send us a weekly_champion = 1 (MAX type) for the top 3 users, that unlocks the game thropy!!
One of our team members will ask you a few questions in order to create the game stats, scoreboards & achievements, be prepared to answer these questions:
Regarding stats:
Regarding scoreboards:
Regarding achievements:
Do you have questions or want to report some bugs? please contact us at [email protected]