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.
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.
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
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
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.
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 and Minicoins doesn’t have any equivalence and they cannot be converted or transferred in any way.
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
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?:
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:
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.
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: https://gist.github.com/miniplay/5317335
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.
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.
If your game is not hosted with us we will append a lot of handful parameters to your sandbox url:
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: https://gist.github.com/miniplay/4996722
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 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.
All the games inside our platform coexist in two isolated versions:
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.
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.
We use so many names it can be confusing for newcomers, here the are for your convenience:
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.
There are 3 APIs available, you may use as many as you need simultaneously:
SERVER TO SERVER (S2S)
Provides full, secure read/write access between your game server/s and our API servers. Use your private api_key to communicate with us.
CLIENT TO SERVER (C2S)
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.
|
|
Module |
S2S API |
C2S JS API |
C2S AS3 API |
|---|---|---|---|---|
|
Interaction between your game sandbox and our site |
environment |
✕ |
✔ |
✔ |
|
Access to user detail and authentication |
user |
✔ |
✔ |
✔ |
|
Get in-game statistics |
stats (read) |
✔ |
✔ |
✔ |
|
Post in-game statistics |
stats (write) |
✔ |
✕ |
✔ |
|
Get scoreboards |
highscore |
✔ |
✔ |
✔ |
|
Read / Write shared content |
shared content |
✔ |
✕ |
✔ |
|
Byte data storage for the users (i.e: savegames) |
datastore |
✔ |
✕ |
✔ |
|
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) |
✔ |
✕ |
✕ |
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:
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.
Send us a support request with the following information (you can ommit how many as you want). If your game is already published on minijuegos.com please provide us the url as well. If there are multiple games to be published, do the same for every one of them.
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...
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).
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).
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.
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.
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.