miniplay.com

Register

IN DEPTH

APPENDIXES

MINIPLAY GENERAL APPENDIXES

This document contains supplementary & unsorted information referenced from multiple pages.

Codename

The codename of our API in all it’s flavours is LeChuck, a tribute to one of our favourite games.

Sitelock

If you use some sort of sitelock to prevent the distribution of your game make sure you whitelist our domains or we won't be able to publish your games.

Please be noticed that according to our internationalization plans more domains could be added.

PLAIN TEXT

*.miniplay.com
*.minijuegos.com
*.minijuegos.es
*.minijuegosgratis.com
*.minigiochi.com
*.minijogos.com.br
*.minijuegos.mx
*.minijuegos.com.mx,
*.minispelletjes.com,
*.grymini.pl

JSON

["*.miniplay.com", "*.minijuegos.com", "*.minijuegos.es", "*.minijuegosgratis.com", "*.minigiochi.com", "*.minijogos.com.br", "*.minijuegos.mx", "*.minijuegos.com.mx", "*.minispelletjes.com", "*.grymini.pl"]

Game player layouts

Our sites provides multiple layouts in order to accommodate to different game dimensions:

  • Small view: For games less than 680px wide, this player type automatically docks our highscores & achievements bar to the right (if available). By calling the API maximize method, games can be scaled up to 980px. The height is calculated automatically to allow the biggest dimensions that fits within the user window.

  • Large view: For games up to 980px wide, with the resize API access games can be scaled up to 980x1400px. If it has achievements or highscores, they’ll float avobe it.

  • 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. This layout is only available to selected developers.

Real time notifications

Our sites features real time notifications for all the registered users, it enables us to push important messages to them, like unlocked achievements or new followers. When the users are playing a game, only notifications related with that game will be dispatched to them, so, they won’t receive notifications from other games. Most of notifications close automatically after a small delay but there are a few notifications that the user must dismiss by clicking on them.

Here’s a list of some of the notifications we’ll send to the users:

  • When a friend beats our score at the main scoreboard we’re both playing the game.
  • When the user beats any of it’s own scores.
  • When the user enters the top 10 on a scoreboard.
  • When the user unlocks an achievement.
  • When the user earns gems.
  • When the user levels up.
  • When the user has new followers (only if not playing a game).
  • When the user receives instant messages.

Game parameters signature

If your game won’t be hosted by us you should validate all the mp_* parameters we sent to your game iframe url in order to avoid someone modifying them that could produce misbehaviour into your game. We’ll always send an additional mini_signature parameter that you can use to check they can be trusted and weren’t modified.

The mini_signature is the md5 signature of your api_key concatenated to the json encoding of all the parameters starting with “mp_”. Here’s a little PHP snippet that shows you how to validate:

/* 1. Decode all get parameters */ foreach ($_GET as $key=>$value) $_GET[$key] = urldecode($value); /* 1. May not be needed in your language */ /* 2. Check signature */ if (!isset($_GET['mini_signature']) || $_GET['mini_signature'] != signParameters("YOUR_API_KEY",$_GET)) { die("The 'mp_*' parameters signature is invalid"); } else { echo "The 'mp_*' parameters signature is valid!"; } /* 3. Helper function definition, yeah, it will look so good inside a class :) */ /** * Signs an array of mp_* parameters, * @param string $apiKey * @param array $parameters * @return string signature */ function signParameters($apiKey, array $parameters) { foreach ($parameters as $key=>$value) { if (substr($key,0,3)!="mp_") unset($parameters[$key]); /* Exclude parameter from validation */ else $parameters[$key] = (string)$value; /* Cast to string not needed in PHP but other languages may need it. */ } return md5($apiKey.json_encode($parameters)); }

Download it here: https://gist.github.com/miniplay/4972221 

Please be noticed that only the parameters starting with “mp_” will be included into the signature. All validations must be performed server-side, do not do client-side validation (javascript), that will expose your api_key, and you shouldn’t ever expose it to clients.

If your game is external (not running inside our sites) you must hardcode all the parameters you expected in your application, therefore, no signature check is needed because there are no parameters to check :)

URL trust tools

We’ve got a few different domains, so, as an additional feature, we provide 2 small trust tools that allows you to validate the urls you’ll receive as parameters, that way, you can be sure they can be trusted, especially when you want to use the mp_api_js_url, mp_api_js_url_bck, mp_api_js_url... that you receive instead of hardcoding them. Be noticed that if you validate the game parameters signature this step is not needed, because all mp_* parameters are validated.

a) Forward if trusted:

Performs a 301 redirection if the provided url is trusted.

  • URL http://beta.miniplay.com/helpers/trust/forward.php?url=[urlencoded_url]
  • Response OK HTTP Redirect to the url
  • Response KO HTTP STATUS CODE: 403 FORBIDDEN + BODY: KO

b) Trust checker:

Checks if an url can be trusted and returns it as a response.

  • URL http://beta.miniplay.com/helpers/trust/trust.php?url=[urlencoded_url]
  • Response OK HTTP STATUS CODE: 200 OK + BODY: OK
  • Response KO HTTP STATUS CODE: 403 FORBIDDEN + Body: KO

Handling guest users

Most of our games allow users to play even without being logged in in our site, but if your game only works for logged users (like most of social games do), the first thing your game should do is check the user status (by using any of our client-side APIs) and in case is guest, you show a "please log in first” screen, tied to the API login method (for javascript, it’s lechuck.user.login() ), and that’s all, we’ll take care automatically of everything (be it either user log in or user registration).

This is the user handling workflow (the play screen is the game itself):