APIs for casual & social games


Please help us improving this documentation 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.

Sacrifices have been made in exchange for simplicity, we’ve followed our own model, so you won’t probably see many similarities with other APIs you may have used before. Our main goal is to provide you the tools you need to make your games really shine on our social platform, allowing millions of users to compete with their friends. Please remember that our social platform is 100% percent game-centric, you won’t find here tools to viralize your game by spamming users & their friends feeds, your game will be promoted all over the place if it’s good or popular enough, a lot of metrics are constantly captured to track your game success.

Finally, we must state that our APIs will be a living entity, it’s within our plans to keep releasing new features constantly, and supporting even more platforms, like Unity or native Android / iOS.

1. Platform scale

Miniplay, Minijuegos, Minigiochi & Minijogos are all part of our brand new Miniplay network, which will be soon released in English, Spanish, Portuguese & Italian languages respectively (more to come later). Every one of them show its own identity but work as an access point to a common, global-scaled community.

2. Social capabilities

Our social graph follows the publish-subscribe pattern, that means our users don’t need approval in order to compete with each other, you only see scores and updates about the users you follow, and only if they follow you as well, you’re both identified as friends and allowed to private messaging. This model allows fast social interaction & competition between people who don’t even know each other. Playing against the best it’s just only one click away.

For more information, check MINIPLAY SOCIAL FEATURES

3. Competition between users

All the user competition is based on one simple thing: game statistics, just tell us how they’re doing in your game and we’ll take care of the rest: highscores, achievements, trophies and even challenges & time-based competitions, all incoming users will be identified by an unique token  for your game (you can store it and create a new account in your game for the user if you need to handle independent accounts for them), as they progress within your game, just tell us through the API how many gold coins they’re collecting, or how fast did they complete their last lap. We also have the ability to merge multiple user stats to produce achievements with  complex logic. Even if your game has it’s own achievements (or if you want to suggest us achievements), just tell us which they are and send us notifications when they’re unlocked, so we can unlock them within our platform, great isn’t it?.

Game statistics configured for your users can have REPLACE, SUM, MAX or MIN logic being automatically managed by our platform, just send them and we’ll do the rest!!

For more information, check MINIPLAY SOCIAL COMPETITION

4. Experience

All users have a level, starting with 1 and ending with 99, each level is harder than the previous (99 being too hard to be reachable). To improve their level, the users must win experience points: by visiting our site, performing social interactions, and, more importantly, by playing your games!!. Implement our APIs and send us the user game statistics so we can create some achievements and reward users with experience points and gems (we’ll talk about it later). On the contrary, game highscores are just for the fame, no experience points are rewarded.

5. Economy

The economy moves the world, so it does move us as well, there’s two simple, easy to understand economies in here: Gems & Minicoins *

  • Gems: Free. Users earn them by unlocking achievements and increasing their experience points. They’re used to purchase items for their avatars (we’ll talk about it later). Gems are not used in games and doesn’t provide any revenue to developers.
  • Minicoins: Paid. Users do not earn them, they must purchase packages (tied to their payment options), and they’re added to their current balance. They’re used to buy in-game items and developers are paid for the amount of Minicoins spent.

* Gems and Minicoins doesn’t have any equivalence and they cannot be converted or transferred in any way.

6. In-game items

Games can have an infinite number of items, be them free, purchasable or granted by the own game, in the other way, they can be set as limited/unlimited per user, as well as usable/non usable. Our systems manages the inventory of all users and stores every transaction made so you can retrieve logs in case you need them. Even your API transactions are logged, so, no single transaction escapes from our control.

Most social & MMO games use their own infrastructure to handle this, even with their own economies as well. In that case, you can and must use our platform as the payment gateway for all our user base. We define your own economy packages as items according your needs (i.e. gold in your game in 10k, 20k and 100k versions) and let our users buy them as items, once done, the item purchase is signed and notified to a secure url specified by you so you can consume the item through our API and add them to your own game inventory, easy, right?.

For more information, check MINIPLAY IN-GAME ITEM PURCHASES

7. Avatars

Ok, we all have different personalities. There’s a huge young audience in our site, and we do not want them to be able to use their photos, Spongebob, or offensive content as their profile picture. Because of that, we’ve developed a state of the art HTML5 based avatar manager to allow everyone build their own stunning avatars. They’re available to you in various sizes, from 32x32 to 256x256, in both solid and transparent flavours. Here’s a sneak peek, aren’t they cool?:

8. Supported games

There are not any game restrictions, we just require that they run in a browser and they don’t need rare plugins to be installed (Unity is not considered rare). We can host the game files for you, but if you need any server-side language (PHP, ASP, JSP, Ruby...) you must host it by yourself. However, we still can host some of your static files (images, video, flash...) in order to reduce your bandwidth footprint.

All the games integrated in our sites runs inside an sandboxed, isolated iframe, even for hosted games. Three different views are available:

  • Small view: For games less than 680px wide, games can be maximized up to 980px.
  • Large view: For games up to 980px wide, with resize API access games can be scaled up to 980x1400px.
  • Fullscreen view: For fullscreen games, our site is reduced to just header and footer bars (~200px). The rest of the screen real estate (width & height) is yours.

The APIs provides you with enough functionality to know what view is being used and maximize/minimize the game, you will be notified as well when the stage size (iframe) changes. If you need to be able to adjust the player dimensions to your convenience dynamically, we’ve got an API for that as well, just let us know so we can activate it for your game.,

For more information, check APPENDIX. Game player layouts.

9. External games

We’ve put a huge effort to provide a seamless integration between your games and our site, but we do understand you could be also interested into running it in your own site while keeping all the great functionality of our APIs. Don’t worry, we’ve handled that, your visitors can connect into your game by using their Miniplay accounts and they can even purchase items!. It’s easy for them and it doesn’t require additional work from your side, it just works right out from the box!

Download the external demo here:

Please notice that games can be both external & internal, you just need to create separate launchers for each case, check our next chapter (Sandbox), for information regarding the internal implementation.

10. Sandbox

As we has been previously stated, all the games integrated in our sites runs inside a sandboxed, isolated iframe, even for hosted games we put them into another domain, so, your game won’t have direct access to our site’s javascript because of cross-domain restrictions. By that means, only the API calls will be allowed.

10.1 Games hosted by you:

If your game is not hosted with us we will append a lot of handful parameters to your sandbox url:

  • mp_game_idId of the game
  • mp_game_uidUid of the game (up to 30char unique alphanumeric id)
  • mp_game_urlUrl of the game *(current page)
  • mp_site_urlSite url where the game is running *(we’ve got a few ones!)
  • mp_site_nameSite name where the game is running *(we’ve got a few ones!)
  • mp_api_js_urlJavascript API url *
  • mp_api_js_url_bckJavascript backend url *
  • mp_api_as3_urlActionscript 3 API url *
  • mp_api_as3_url_bckActionscript 3 backend url *
  • mp_api_user_iduser id if it’s logged in, use it as the unique, immutable identifier of the user!
  • mp_api_user_tokenunique user token, you can store it, but keep it private and secure.
  • mp_localelocale of the user i.e: es_ES
  • mp_timezonetimezone of the user i.e.: Europe/Madrid
  • mp_game_devel1 if the game it’s in development mode, not present if not.
  • mini_signaturesignature of all the mp_* parameters sent (APPENDIX. PARAMETERS SIGNATURE)

Validating the parameters signature it's a must if you don't want to be hacked badly, but if you still don't want to validate the parameters signature, we provide you an additional, easy to use, wrapper url that you can use to validate the urls you receive, in order to prevent some attackers to send you malicious urls. Never trust the urls you receive through parameters, i.e. when you insert them as javascript, anyone could send you different urls to steal session cookies or worse. Check Appendix 5. URL Trust tools.

For your convenience we've created a sandbox template (in php) that you can just download and put into your server to act as a game launcher. It automatically takes care of all received parameters, validates them, initializes the JS API for you and checks the user status.

Download the sandbox template here:

Additionally, all the parameters that our game page receives will be also sent to your game, allowing you to provide extra functionality to users.

10.2 Games hosted by us:

In case of hosted games, the same variables shown at 10.1 will be provided to them by their corresponding means, like flashvars for flash games. Additionally, all the parameters that our game page receives will be also sent to your game, allowing you to provide extra functionality to users.

In case of external games, you must handle all by yourself, you’ll only receive mp_user_id & mp_user_token parameters when your users use Miniplay connect to authenticate.

11. Development

All the games inside our platform coexist in two isolated versions:

  • Development. The game is not visible for the public, but is really playable in our site!, just only accessible for the game developer, administrators and a few other users that the game developer can grant access to (so they can test the game). You’ve got full access to the APIs to post stats, unlock achievements, buy items (freely)... The only difference is that they don’t get socialized, and no experience or gems are rewarded. The development page features some useful tools to allow you reset scoreboards, clear your items, or see the stats your game is sending in real time!.
  • Production. The game is visible to everyone when they’re released to the public. Users can like the game, share it, unlock achievements, get experience, post scores...  being all this activity socialized and reported to their followers.

Once your game is ready, request us to launch it to production and we’ll schedule a date for it. If in the future you want to perform some changes to your game, you can still work in the development version (while people plays your production game) to add new stats, items or whatever you like, and again, requesting us to release it when its ready, cool isn’t it?. Just note that if your game is hosted with us we will maintain 2 separated copies of your files but if you host your game, you must check for the mp_game_devel parameter presence, or you can provide us 2 different urls, one for development, and one for production.

Local development

We do not provide mock APIs to allow you local debugging, being socially oriented it just doesn’t make sense, instead, we’ve made our best effort to provide you a development environment that allows you to test the game in it’s full glory. You can even host the development game by yourself to make as many changes as you like. In the case of Flash developers, we’ll give you some tips in the actionscript documentation so you can remotely debug your local files.

12. Ids, Uids, Keys, Tokens...

We use so many names it can be confusing for newcomers, here the are for your convenience:

  • game_idNumeric ID of your game
  • game_uidAlphanumeric unique ID of your game
  • api_idNumeric ID of your API access
  • api_key16 char string for secure Server 2 Server communications. Keep it private.
  • api_token16 char string for Client 2 Server communications. Keep it private.
  • user_idNumeric ID of an user, this is the unique, immutable id of the user, it never changes.
  • user_uidAlphanumeric unique ID (alias, nick) of an user, this field is mutable, the user could change the uid and it could be aquired by another user.
  • user_token16 char string to identify the user for your game. Keep it private.

As previously said, all games have development and production versions, please note that all  values are different for them, using the production api_token for the devel game won’t work. It’s your responsibility to keep these data safe and private, any leak will cause your games to be removed from our platform immediately.

The user token gives you access to the user and allows you to use the APIs on behalf of him/her  to get user data, post scores, consume items... It will differ from game to game (and even between dev/prod versions). It doesn’t change, so you can store it but you must keep it always private. Think of it as your password to the user, without the user_token you cannot do anything but getting very basic data about the user.

13. API languages

There are 3 APIs available, you may use as many as you need simultaneously:


Provides full, secure read/write access between your game server/s and our API servers. Use your private api_key to communicate with us.


Provides read only access between your game sandbox and our site & API servers. Write access is forbidden to avoid the user exploiting the API directly by running javascript within their debug consoles (like firebug).

Provides medium security read/write access between your game and our API servers. Use your private api_token to communicate with us. All outgoing communications are automatically encrypted with a random salt. Please take every security measure that are available to you in order to prevent cheaters to gain access to the token, starting with obfuscation. If we detect your game has been compromised in any way, we will deactivate all rewards for users. Please note that the Actionscript 3 API requires the Javascript API to be also implemented simultaneously on your game sandbox.

14. Main API modules








Interaction between your game sandbox and our site
(i.e: opening the friends scoreboard)


Access to user detail and authentication


Get in-game statistics

stats (read)

Post in-game statistics

stats (write)

Get scoreboards


Read / Write shared content

shared content

Byte data storage for the users (i.e: savegames)


Get user inventory

items (read)

Initiates item purchase dialog

items (purchase)

Consume items (remove from user inventory)

items (use)

Add items(any amount) to the user inventory

items (add)

15. Game publishing checklist

Ok, you've read this document and you want to start implementing your game right now in order to be published in our sites. These are the needed steps:

15.1 Register as user at Miniplay

If you're not already a registered user, register now!, we need to grant your user with development permissions for your games. We recommend you to pick a "corporate" uid, i.e. my-game-studio, you can register multiple accounts and you can also ask us to make them friends if you want to test the social features.

15.2 Ask us to register your game (in order to get the keys & tokens)

Send us a support request with the following information (you can ommit how many as you want). If your game is already published on please provide us the url as well. If there are multiple games to be published, do the same for every one of them.

15.2.1 For browser-based / IFRAME games

  1. Your Miniplay user uid (nick / alias). Please sign up in our site to get an account.
  2. Game name (important!)
  3. Already published at / ?: Game URL (important!)
  4. Development URL + Production URL (+ preproduction url if needeed)
  5. APIs interested in: [ S2S | C2S JS]
  6. Game layout you're going to use & game dimensions in pixels [ SMALL | LARGE | FULL ] + [ W x H ]px
  7. Some additional information about your game that could be useful for us.
  8. Users uids that you want to be able to access the development version of the game (by default, only you can see it, but you can request us to grant access to other users in order to test the game). Do you want them to be 'friended'?.
  9. Url for S2S callbacks if you need to process them, we support both development & production urls.
  10. Will your game be available outside from our sites?, you need additional permissions to use our APIs, send us the url where the game will run. We rather prefer games to be running within our site for a better user experience.
  11. Extended user data required if any: full name and/or email. (an agreement is required).

15.2.2 For plugin-based games (FLASH, UNITY, SHOCKWAVE...)

  1. Your Miniplay user uid (nick / alias). Please sign up in our site to get an account.
  2. Game name (important!)
  3. Game technology: [ FLASH | SHOCKWAVE | UNITY ...]
  4. Already published at / ?: Game URL (important!)
  5. Hosted by yourself: [ YES | NO ]
  6. Will you host the game in your own servers? Send us the Development URL + Production URL, make sure it contains the full path, including the extension.
  7. Do you need an FTP account to upload & test your game during development: [ YES | NO ]
  8. APIs interested in: [ S2S | C2S JS | C2S AS3 ]
  9. Game layout you're going to use & game dimensions in pixels [ SMALL | LARGE | FULL ] + [ W x H ]px
  10. Some additional information about your game that could be useful for us.
  11. Users uids that you want to be able to access the development version of the game (by default, only you can see it, but you can request us to grant access to other users in order to test the game). Do you want them to be 'friended'?.
  12. Url for S2S callbacks if you need to process them, we support both development & production urls.
  13. Will your game be available outside from our sites?, you need additional permissions to use our APIs, send us the url where the game will run. We rather prefer games to be running within our site for a better user experience.
  14. Extended user data required if any: full name and/or email. (an agreement is required).

Once we process it, we'll send you the development url of your game, there you can find all tokens and information regarding it (you need to be logged in or you won't be able to see it).

We'll later ask you more information about your game, like screenshots, url to test it, stats that you want us to create, achievements if you have some, highscores, items that can be purchased in your game...

15.3 Integrate our APIs into your game

For games hosted in your own servers you need to set up the sandbox that launches your game.

You can ask us for as many changes into your configuration as needed, we'll be ready to assist you.

This is a good time to discuss about the social competition aspects of your game: stats, highscores, achievements... Read the document and ask us for as many stats & highscores as you need.

If you game already has achievements, please tell us which they are so both our/your achievements are synchronized (a stat will be created for each achievement, you just set it to 1 when the user unlocks it), do not forget to tell us the difficulty level of each achievement (easy, mid, hard).

15.4 Test the game (a lot!) and check that stats, achievements & scoreboards work properly.

Perform as many tests as you can and use a few beta testers. Your development url allows you to reset highscores, achievements, stats and items to see everything is working properly.

In this step we will also ask you for images for the achievements (64x64px png) or other graphic assets you may have available in case we plan to promote / feature your game (i.e. our landing page carousel).

15.5 Ask us to publish your game (VALIDATION PROCESS)

Once you're ready, tell us by sending us a support ticket and allow us to test your game and every API related thing. We'll probably make you one or two suggestions, once they get addressed, we'll schedule a date for your games and you'll have access to the production url of the game, tied to your production ready game so you can test it.

You've worked so hard!. Rest, grab some beers and enjoy life till the day comes.

15.6 Check your production game is working properly

The day has come, lots of users are playing your game, check everything is under control. In case of bugs, you can still go back to your development version of the game to check and fix them.

15.7 Have you made changes to your game?

Ask us to upload the new version configuration (with stats, items, scoreboards... if there are more than previously), including the files if your game is hosted.