MINIPLAY S2S REST API
APIs for casual & social games

Preface:

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 the REST API for server to server communications. Please refer to the MINIPLAY APIs OVERVIEW document first if you haven’t read it yet, knowledge of the concepts explained there is required.

As a convention, we will use red for required parameters and blue for optional parameters. Also be noticed that every timestamp is handled with a precision of milliseconds (POSIX timestamps only have a precision of seconds).

Any api_key or user_token used here are not valid, please use the data we’ve provided you.

1. Introduction

By accepting stateless GET/POST HTTP* requests, this REST API provides full, secure read/write access to our API servers. Use your private api_key to identify your game. Please note this API is intended only for server to server communications, do not make calls that could be intercepted by third parties, specially if they’re originated on clients

* It’s within our plans to support the HTTPS protocol soon. When no method is specified, a HTTP GET is assumed.

1.1 Sandbox template

Our Server 2 Server API is mainly used by games that are self-hosted and running inside an iframe in our sites, in that case you must handle all the GET parameters that we send you, to help you with that task, you can begin by downloading our Sandbox template with the JS API (link to the JS API doc)

The sandbox template will take care of all the initialization & parameters validation (user token, user locale...) and will also initialize our Javascript API that allows your game to interact with your site.

If your game is external and won't run inside our sites you must remove the parameters validation part, no parameters or signature will be provided, only the user_id & user_token when the user connects with Miniplay Connect.

2. Making requests

Our REST service is located at:

https://api.minijuegos.com/lechuck/server/

Use your favourite client or programming language to perform a first GET request:

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "message": "Hello world!, this is the LeChuck S2S REST API :)" } }

And that’s it!, a well formed JSON document is returned for your convenience. In case you need to provide parameters, append them as a standard GET query string: ?foo=bar&baz=qux

3. Handling responses

You can handle the response in any way you may like, a JSON document with the following properties will always be returned:

{ "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": {} }

The status object include all the info related with the processing status of the request, as you can see, a the status.success property indicates whether or not the request was successful, you can easily evaluate it for true or false. The other properties indicates the response type, response HTTP code and status message if there was any.

The data object include the information returned from our servers, from now on, when we talk about the data returned by the API, we will always be referring to the properties included in the data object.

4. Handling error responses

In case there’s something wrong with your request, you’ll receive the corresponding HTTP STATUS code in the HTTP headers, but a JSON document will still be returned (even for 404 errors), including a third object, exception, with the error details, here’s an example:

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/user/1/" { "status": { "success": false, "type": "UNAUTHORIZED", "code": 401, "message": "Log in required or authorization failed. Check the exception object for more information." }, "exception": { "type": "UNAUTHORIZED", "message": "The api_key parameter is mandatory" }, "data": {} }

Most of error responses will come from malformed requests, but very bad things can happen, so, be prepared to receive anyone of the following strings at status.type:

• BAD_REQUEST
• UNAUTHORIZED
• FORBIDDEN
• NOT_FOUND
• SERVICE_UNAVAILABLE
• INTERNAL_SERVER_ERROR

On the contrary, exception.type can be one of the multiple exceptions that our system raises, we recommend you to ignore it, just use the exception.message to get a more detailed explanation of what happened.

5. USER module

Allows you to authenticate users, get their details, followers, subscriptions and friends.

Please remember that the user id is the unique and immutable identifier of our users, on the other side, the alphanumeric user uid is unique as well, but mutable, it can be changed by the user and fetched by a different one. Never treat the user uid as immutable data.

5.1 Get detail

Retrieves the user detail including social totals (followers, subscriptions, friends...)

• Url https://api.minijuegos.com/lechuck/server/user/[user_id]
• Parameters
  • api_key
  • user_token to get the full user detail
• Response data.user Object with the public detail, or full detail if user_token was provided.

Here are some of the most interesting user data returned:

• string data.user.id user id. immutable
• string data.user.uid user uid / nick / alias. mutable
• number data.user.profile url of the user profile mutable
• number data.user.progress_level level of the user mutable
• string data.user.avatar url of public avatar immutable (96x96 jpg)
• string data.user.avatar_mini url of public avatar immutable (32x32 jpg)
• string data.user.avatar_big url of public avatar immutable (256x256 jpg)
• string data.user.avatar_alpha url of public avatar immutable (96x96 png)

If you provide the user_token and its valid, the following properties will be available:

• string data.user.gender gender of the user (if available)

Full dump (basic detail without user_token):

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/user/2/?api_key=XXXX" { "status":{ "success":true, "type":"OK", "code":200, "message":null }, "data":{ "user":{ "id":"2", /* 32 bit number as string (immutable) */ "uid":"demo_user_2", /* 32 character string (mutable) */ "avatar":"http://beta.miniplay.com/....../default/head_96x96.jpg", "avatar_mini":"http://beta.miniplay.com/....../default/head_32x32.jpg", "avatar_big":"http://beta.miniplay.com/....../default/head_256x256.jpg", "avatar_alpha":"http://beta.miniplay.com/....../default/head_96x96.png", "profile":"http://beta.miniplay.com/profile/demo_user_2", "social_total_followers":10, /* 32 bit number */ "social_total_subscriptions":15, /* 32 bit number */ "social_total_friends":10, /* 32 bit number */ "progress_points":2795, /* 32 bit number */ "progress_level":14, /* 32 bit number */ "progress_level_points_max":3061, /* 32 bit number */ "progress_level_points_min":2683 /* 32 bit number */ } } }

Full dump (complete detail with a valid user_token):

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/user/2/?api_key=XXXX&user_token=YYYYYYY” { "status":{ "success":true, "type":"OK", "code":200, "message":null }, "data":{ "user":{ "id":"2", /* 32 bit number as string (immutable) */ "uid":"demo_user_2", /* 32 character string (mutable) */ "gender":"M", /* (M)ale,(F)emale */ "name":"xxxxxx", /* only for selected developers (may be empty) */ "surname":"yyyyyy", /* only for selected developers (may be empty) */ "email":"user@host.com", /* only for selected developers */ "date_birth":"1970-12-30", /* YYYY-mm-dd */ "locale":"en_US", /* user locale string or property not present for null */ "avatar":"http://beta.miniplay.com/....../default/head_96x96.jpg", "avatar_mini":"http://beta.miniplay.com/....../default/head_32x32.jpg", "avatar_big":"http://beta.miniplay.com/....../default/head_256x256.jpg", "avatar_alpha":"http://beta.miniplay.com/....../default/head_96x96.png", "profile":"http://beta.miniplay.com/profile/demo_user_2", "social_total_followers":10, /* 32 bit number */ "social_total_subscriptions":15, /* 32 bit number */ "social_total_friends":10, /* 32 bit number */ "progress_points":2795, /* 32 bit number */ "progress_level":14, /* 32 bit number */ "progress_level_points_max":3061, /* 32 bit number */ "progress_level_points_min":2683 /* 32 bit number */ } } }

Please notice that some fields will only be provided to selected developers prior mutual agreement.

5.2 Authenticate

Authenticates an user.

• Url https://api.minijuegos.com/lechuck/server/user/[user_id]/authenticate/
• Parameters
  • api_key
  • user_token
• Response
  • status.success true if the user_token is valid.
  • data.user object with the user detail if the user_token is valid (Refer to 5.1)

Dump for successful response

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/user/2/authenticate/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066" { "status":{ "success":true, "type":"OK", "code":200, "message":null }, "data":{ "user":{ ... full user data object, see 5.1 ... } } }

5.3 Subscriptions

This is probably the most important list for game developers, this method gets the subscriptions list of an user (the subscriptions are the users that he/she follows), ordered by descending timestamp, can be easily paginated by using the timestamps.

• Url https://api.minijuegos.com/lechuck/server/user/[user_id]/subscriptions/
• Parameters
  • api_key
  • user_token
  • withDetail to include users public detail (true by default)
  • withProgress to include users progress (level, false by default)
  • withInstalled to include installed flag (played the game?, false by def)
  • limit number of items to retrieve (20 by default)
  • fomTimestamp oldest timestamp (in milliseconds), inclusive
  • toTimestamp newest timestamp (in milliseconds), exclusive
• Response
  • status.subscriptions true if the user_token is valid.
  • data.user Array of users (with public detail if requested)

Every user in the list will contain the time property corresponding to the millisecond timestamp (64bit) when the event occurred (in this case, the subscription of the provided user). It will contain as well the is_friend boolean flag and the is_installed boolean flag (if requested).

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/user/2/subscriptions/?api_key=XXXX&user_token=59a82131f40a6f85352437e066&withDetail=1&withProgress=1&withInstalled=1&limit=2" { "status":{ "success":true, "type":"OK", "code":200, "message":null }, "data":{ "subscriptions":[ { "id":"19", /* 32 bit number as string (immutable) */ "uid":"demo_user_19", /* 32 character string (mutable) */ "avatar":"http://beta.miniplay.com/....../default/head_96x96.jpg", "avatar_mini":"http://beta.miniplay.com/....../default/head_32x32.jpg", "avatar_big":"http://beta.miniplay.com/....../default/head_256x256.jpg", "avatar_alpha":"http://beta.miniplay.com/....../default/head_96x96.png", "profile":"http://beta.miniplay.com/profile/demo_user_19", "progress_points":190, /* 32 bit number */ "progress_level":2, /* 32 bit number */ "progress_level_points_max":220, /* 32 bit number */ "progress_level_points_min":100, /* 32 bit number */ "time":1359977519115, /* 64 bit number, when the 'follow' operation occurred */ "is_friend":true, /* boolean, is this user a friend? (follows me as well) */ "is_installed":false /* boolean, has this user played this game? (if requested) */ }, { "id":"14", /* 32 bit number as string (immutable) */ "uid":"demo_user_14", /* 32 character string (mutable) */ "avatar":"http://beta.miniplay.com/....../default/head_96x96.jpg", "avatar_mini":"http://beta.miniplay.com/....../default/head_32x32.jpg", "avatar_big":"http://beta.miniplay.com/....../default/head_256x256.jpg", "avatar_alpha":"http://beta.miniplay.com/....../default/head_96x96.png", "profile":"http://beta.miniplay.com/profile/demo_user_14", "progress_points":1810, /* 32 bit number */ "progress_level":11, /* 32 bit number */ "progress_level_points_max":2024, /* 32 bit number */ "progress_level_points_min":1740, /* 32 bit number */ "time":1358357279751, /* 64 bit number, when the 'follow' operation occurred */ "is_friend":false, /* boolean, is this user a friend? (follows me as well) */ "is_installed":false /* boolean, has this user played this game? (if requested) */ } ] } }

5.4 Friends

Gets the friends list of an user (those who are both being followed by and following the provided user), ordered by descending timestamp, can be easily paginated by using the timestamps. Remember: users can only communicate and share things with their friends.

• Url https://api.minijuegos.com/lechuck/server/user/[user_id]/friends/
• Parameters
  • api_key
  • user_token
  • withDetail to include users public detail (true by default)
  • withProgress to include users progress (level, false by default)
  • withInstalled to include installed flag (played the game?, false by def)
  • limit number of items to retrieve (20 by default)
  • fomTimestamp oldest timestamp (in milliseconds), inclusive
  • toTimestamp newest timestamp (in milliseconds), exclusive
• Response
  • data.friends Array of users (with public detail if requested, Refer to 5.3).

Every user in the list will contain the time property corresponding to the millisecond timestamp (64bit) when the event occurred (in this case, the friendship). It will contain as well the  is_installed boolean flag (if requested).

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/user/2/friends/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&withDetail=1&withProgress=1&withInstalled=1&limit=2" { "status":{ "success":true, "type":"OK", "code":200, "message":null }, "data":{ "friends":[ { "id":"19", /* 32 bit number as string (immutable) */ "uid":"demo_user_19", /* 32 character string (mutable) */ "avatar":"http://beta.miniplay.com/....../default/head_96x96.jpg", "avatar_mini":"http://beta.miniplay.com/....../default/head_32x32.jpg", "avatar_big":"http://beta.miniplay.com/....../default/head_256x256.jpg", "avatar_alpha":"http://beta.miniplay.com/....../default/head_96x96.png", "profile":"http://beta.miniplay.com/profile/demo_user_19", "progress_points":190, /* 32 bit number */ "progress_level":2, /* 32 bit number */ "progress_level_points_max":220, /* 32 bit number */ "progress_level_points_min":100, /* 32 bit number */ "time":1359977519115, /* 64 bit number, when the 'follow' operation occurred */ "is_friend":true, /* boolean, is this user a friend? (always true in this list) */ "is_installed":false /* boolean, has this user played this game? (if requested) */ }, { "id":"14", /* 32 bit number as string (immutable) */ "uid":"demo_user_14", /* 32 character string (mutable) */ "avatar":"http://beta.miniplay.com/....../default/head_96x96.jpg", "avatar_mini":"http://beta.miniplay.com/....../default/head_32x32.jpg", "avatar_big":"http://beta.miniplay.com/....../default/head_256x256.jpg", "avatar_alpha":"http://beta.miniplay.com/....../default/head_96x96.png", "profile":"http://beta.miniplay.com/profile/demo_user_14", "progress_points":1810, /* 32 bit number */ "progress_level":11, /* 32 bit number */ "progress_level_points_max":2024, /* 32 bit number */ "progress_level_points_min":1740, /* 32 bit number */ "time":1358357279751, /* 64 bit number, when the 'follow' operation occurred */ "is_friend":false, /* boolean, is this user a friend? (always true in this list)*/ "is_installed":false /* boolean, has this user played this game? (if requested) */ } ] } }

5.5 Followers

Gets the followers list of an user, ordered by descending timestamp, can be easily paginated by using the timestamps. This list doesn’t provide neither the is_friend and is_installed flags.

• Url https://api.minijuegos.com/lechuck/server/user/[user_id]/friends/
• Parameters
  • api_key
  • user_token
  • withDetail to include users public detail (true by default)
  • withProgress to include users progress (level, false by default)
  • withInstalled to include installed flag (played the game?, false by def)
  • limit number of items to retrieve (20 by default)
  • fomTimestamp oldest timestamp (in milliseconds), inclusive
  • toTimestamp newest timestamp (in milliseconds), exclusive
• Response
  • data.followers Array of users (with public detail if requested).

Every user in the list will contain the time property corresponding to the millisecond timestamp (64bit) when the event occurred (in this case, the following of the provided user).

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/user/2/followers/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&withDetail=1&withProgress=1&limit=2" { "status":{ "success":true, "type":"OK", "code":200, "message":null }, "data":{ "followers":[ { "id":"19", /* 32 bit number as string (immutable) */ "uid":"demo_user_19", /* 32 character string (mutable) */ "avatar":"http://beta.miniplay.com/....../default/head_96x96.jpg", "avatar_mini":"http://beta.miniplay.com/....../default/head_32x32.jpg", "avatar_big":"http://beta.miniplay.com/....../default/head_256x256.jpg", "avatar_alpha":"http://beta.miniplay.com/....../default/head_96x96.png", "profile":"http://beta.miniplay.com/profile/demo_user_19", "progress_points":190, /* 32 bit number */ "progress_level":2, /* 32 bit number */ "progress_level_points_max":220, /* 32 bit number */ "progress_level_points_min":100, /* 32 bit number */ "time":1359977519115 /* 64 bit number, when the 'follow' operation occurred */ }, { "id":"14", /* 32 bit number as string (immutable) */ "uid":"demo_user_14", /* 32 character string (mutable) */ "avatar":"http://beta.miniplay.com/....../default/head_96x96.jpg", "avatar_mini":"http://beta.miniplay.com/....../default/head_32x32.jpg", "avatar_big":"http://beta.miniplay.com/....../default/head_256x256.jpg", "avatar_alpha":"http://beta.miniplay.com/....../default/head_96x96.png", "profile":"http://beta.miniplay.com/profile/demo_user_14", "progress_points":1810, /* 32 bit number */ "progress_level":11, /* 32 bit number */ "progress_level_points_max":2024, /* 32 bit number */ "progress_level_points_min":1740, /* 32 bit number */ "time":1358357279751 /* 64 bit number, when the 'follow' operation occurred */ } ] } }

5.6 Subscription status

Checks if an user is subscribed (follows) another and if the subscription is mutual and they can both communicate wich each other. Additionally, you can get the is_installed flag.

• Url https://api.minijuegos.com/lechuck/server/user/user2_id
• Parameters
  • api_key
  • user_token for the user_id (user_token for user2_id is not required)
  • withInstalled to include installed flag (played the game?, false by def)
• Response
  • (boolean) data.is_subscribed is user_id subscribed to user2_id?.
  • (boolean) data.is_friend Is user_id also friend of user2_id? (a mutual subscription exists).
  • (number) data.time When the operation subscription occurred? (64bit number).
  • (boolean) data.is_installed has user2_id played the game?.

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/user/2/substatus/21/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&withInstalled=1" { "status":{ "success":true, "type":"OK", "code":200, "message":null }, "data":{ "is_subscribed":true, /* boolean */ "is_friend":true, /* boolean */ "is_installed":true, /* boolean (only if requested, it has played the game!) */ "time":1359977519115 /* 64 bit number, when the operation occurred */ } }

6. STAT module

Allows you to send, retrieve and reset game stats for users to track their progress. All configured stats for your game are listed in your development sandbox, give them a look and don’t hesitate to ask us for as many as you want, we love stats!. Please read first the MINIPLAY SOCIAL COMPETITION document for better information and examples.

Please remember that in order to operate with stats, they must be previously configured by us, the stats configured & available for your game are listed in your game development page (IN-GAME STATS tab).

6.1 Retrieve a stat

Gets the game stat for the user. Replace the [stat_uid] with the stat uid that you want to read (must have been created by us or it will return a not found).

• Url https://api.minijuegos.com/lechuck/server/stat/[stat_uid]
• Parameters
  • api_key
  • user_id
  • user_token
• Response
  • data.stat object with the stat detail and configuration (id, uid, type & description).
  • data.value with the integer value saved, null if no value found.
  • data.timestamp with the timestamp when it was sent, null if no time found.

In this example, we get the value of a demo 'points' stat (that must exist).

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/stat/points/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&user_id=2" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "stat": { /* stat configuration */ "id": "10", "uid": "points", "type": "REPLACE", /* stat type [REPLACE, SUM, MAX, MIN] */ "description": "demo stat" }, "value": 9222, /* 32 bit number */ "timestamp": 1360854390469 /* 64 bit number, when the operation occurred */ } }

6.2 Send a stat

Sends a game stat for the user, it will be automatically handled according with the stat type (REPLACE, MIN, MAX or SUM), so it may or not be saved. Please do not spam our API servers with user stats constantly, there’s no problem receiving a few stats each minute, but they perform a lot of complex operations (highscore checking, achievements...), we will be destroyed if we receive stats each time an user shoots a bullet, instead of that, accumulate them and send the total once the user finishes the level. We do track how many stats each API clients sends ;) Replace the [stat_uid] with the stat uid that you want to send (must have been created by us or it will return a not found).

• Url https://api.minijuegos.com/lechuck/server/stat/[stat_uid]/put/
• Parameters
  • api_key
  • user_id
  • user_token
  • value32 bit integer value, if you need floating point, multiply it for. The highest number supported is 2.147.483.647. Negative numbers are not allowed.
• Response
  • data.stat object with the stat detail and configuration (id, uid, type & description).
  • data.result object with the result of the stat sent.
  • data.timestamp with the timestamp when it was sent, null if no time found.

Here are some of the most interesting data returned:

• data.stat.type the type of the stat (REPLACE, MIN, MAX...)
• data.result.statSaved the result of the operation
• data.result.statValue the value saved (if its SUM, the total)
• data.result.highscoresSaved the list of related highscores updated if any

In this example, we send the value of a demo 'points' stat (that must exist).

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/stat/points/put/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&user_id=2&value=12000" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "stat": { /* stat configuration */ "id": "10", "uid": "points", "type": "REPLACE", /* stat type [REPLACE, SUM, MAX, MIN] */ "description": "demo stat" }, "result": { "statProcessed": true, /* successfully processed? */ "statSaved": true, /* the result of the operation */ "statValue": 12000, /* the value saved (if its SUM, the total), 32 bit integer */ "highscoresSaved": [ /* list of related highscores, if value is good enough for them */ { "highscore": { /* scoreboard configuration (see chapter 7) */ "id": "12", "uid": "best_points", "is_main": "1", "is_custom": "0", "is_devel": "0", "type_update": "MAX", "type_sort": "DESC", "display_precision": "0", "display_decorator": "points", "stat_id": "10" }, "score": 12000, /* score, 32 bit integer */ "position": 1 /* position within the scoreboard, if in top 1000 */ }, {...}, /* other scoreboards? */ {...} /* other scoreboards? */ ], "highscoresSharedContentId": "3378196970366566402" /* (see chapter 8) */ } } }

6.2 Send a batch of stats

Allows you to send a batch of multiple stats in just one RPC connection. You can provide as much stat_[stat_uid] parameters as you need with their corresponding values. The response will contain all the results and the errors if there are any.

• Url https://api.minijuegos.com/lechuck/server/stat/batch/
• Parameters
  • api_key
  • user_id
  • user_token
  • stat_[stat_uid] 32 bit integer value for the stat. You can provide as much as you want
• Response
  • data.errors object with the stats errors (if any).
  • data.results object with the results of the stats sent.

Here are some of the most interesting data returned:

• data.results[x].statSaved the result of the operation
• data.results[x].statValue the value saved (if its SUM, the total)
• data.results[x].highscoresSaved the list of related highscores updated if any

In this example, we send the value of a 3 demo stats: 'points', 'time' & 'monsters' (that must exist).

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/stat/batch/?api_key=XXXX&user_token=59a82131fa3e01045352437e066&user_id=2&stat_points=5200&stat_time=12000&stat_monsters=20" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "results": { "points": { "statProcessed": true, /* successfully processed? */ "statSaved": true, /* the result of the operation */ "statValue": 5200, /* the value saved (if its SUM, the total), 32 bit integer */ "highscoresSaved": [{ /* list of related highscores */ "highscore": { "id": "14", "uid": "total_points", "is_main": "0", "is_custom": "0", "is_devel": "0", "type_update": "SUM", "type_sort": "DESC", "display_precision": "0", "display_decorator": "points", "stat_id": "10" }, "score": 32412, /* score, 32 bit integer */ "position": 1 /* position within the scoreboard, if in top 1000 */ }], "highscoresSharedContentId": "3376752096123551746" }, "time": { "statProcessed": true, /* successfully processed? */ "statSaved": true, /* the result of the operation */ "statValue": 18000, /* the value saved (if its SUM, the total), 32 bit integer */ "highscoresSaved": [], /* list of related highscores */ "highscoresSharedContentId": null /* (see chapter 8) */ } }, "errors": { /* list of errors if any */ "monsters": "Stat 'monsters' not found for game '1'" } } }

6.4 Reset a stat

• Url https://api.minijuegos.com/lechuck/server/stat/[stat_uid]/reset/
• Parameters
  • api_key
  • user_id
  • user_token
• Response
  • data.stat object with the stat detail and configuration (id, uid, type & description).

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/stat/points/reset/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&user_id=2" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "stat": { /* stat configuration */ "id": "10", "uid": "points", "type": "REPLACE", /* stat type [REPLACE, SUM, MAX, MIN] */ "description": "demo stat" } } }

7. HIGHSCORE module

Allows you to retrieve scoreboards and positions for users. Remember that all high scores are tied with the stats sent, there are no methods to put scores directly into the scoreboards. You can ask us for as many scoreboards as you like to have, just tell us their sorting method (ASC or DESC), their computation method (SUM, MAX, MIN) and the stat uid that will be sent. The stat type is ignored, we always use the last value sent to calculate its position into the scoreboard. Please be noticed that SUM scoreboards doesn’t have timespans other than TOTAL.

Please remember that if you multiply the stats to handle floating point numbers in your game the highscore will also be stored multiplied, you have to divide them by 10^x in order to get the same precision for displaying it. In our sites we do that automatically, so you don’t have to worry about it, just tell us how many decimal numbers the stat & the highscore have.

In order to operate with highscores, they must be previously configured by us, the highscores configured & available for your game are listed in your game development page (click on the achievements & highscores icon if they're not present by default).

7.1 Get global scoreboards

Gets a global scoreboard, they will be ordered as configured, starting from the best, the items can be easily paginated by using the score and the timestamp of the last item of the batch.

• Url https://api.minijuegos.com/lechuck/server/highscore/[hs_uid]/global/
• Parameters
  • api_key
  • timespan [TOTAL, DAY, WEEK, MONTH] (TOTAL by default)
  • withDetail =1 to include the users public detail
  • withProgress =1 to include the users progress (level)
  • withSharedContent =1 to check if it has shared content and get the id
  • limit number of items to retrieve (20 by default)
  • startScore starting score, inclusive (exclusive if no timestamp sent)
  • startTimestamp starting timestamp (in milliseconds), exclusive.
• Response
  • data.scores Array with a list of scores:
    • data.scores[x].score number score
    • data.scores[x].timestamp number timestamp
    • data.scores[x].user number public user detail (if requested)
    • data.scores[x].sharedcontent_id string shared content id (if requested)
  • data.highscore Object with the scoreboard detail and configuration:
    • data.highscore.id number id
    • data.highscore.uid string uid
    • data.highscore.is_main boolean is the main scoreboard of the game?
    • data.highscore.is_devel number is a scoreboard from a devel game?
    • data.highscore.type_update string update type [SUM, MAX, MIN]
    • data.highscore.type_sort number id
    • data.highscore.display_precision number id
    • data.highscore.display_decorator number id
    • data.highscore.stat_id number id
    • data.highscore.stat_uid number uid

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/highscore/best_points/global/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&withDetail=1&withProgress=1" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "scores": [ { "score": 12000, /* 32 bit number, score */ "timestamp": 1360935872206, /* 64 bit number, when it happened */ "user": { "id": "2", "uid": "user_2", "avatar": "..../head_96x96.jpg", "avatar_mini": "..../head_32x32.jpg", "profile": "http://beta.miniplay.com/profile/user_2", "progress_points": 3510, "progress_level": 16, "progress_level_points_max": 3937, "progress_level_points_min": 3479 } }, { "score": 6562, /* 32 bit number, score */ "timestamp": 1360854616542, /* 64 bit number, when it happened */ "user": { "id": "3", "uid": "user_3", "avatar": "..../head_96x96.jpg", "avatar_mini": "..../head_32x32.jpg", "profile": "http://beta.miniplay.com/profile/user_3", "progress_points": 3510, "progress_level": 16, "progress_level_points_max": 3937, "progress_level_points_min": 3479 } } ], "highscore": { /* scoreboard configuration */ "id": "12", "uid": "best_points", "is_main": "1", /* main highscore for the game? (i.e. user_level or total_points) */ "is_custom": "0", /* custom scoreboard? (created ad_hoc) */ "is_devel": "0", /* development mode? */ "type_update": "MAX", /* scoreboard type [SUM, MAX, MIN] */ "type_sort": "DESC", /* scoreboard sort [ASC, DESC] */ "display_precision": "0", /* decimal precision */ "display_decorator": "points", /* decorator [ null, time, points, wins, kills...] */ "stat_id": "10" /* stat id that is used as base to send scores to this board*/ "stat_uid": "points" /* stat uid that is used as base to send scores to this board*/ } } }

7.2 Get user social scoreboard

Gets a “friends” scoreboard for an user, the friends scoreboard corresponds to a board where only shows the user and the users he/she is following. As soon as the user follows a new one, its score will be sent to the user friends scoreboard, the same happens when the user stops following an user, it will be removed from it. The scores will be ordered as configured, starting from the best, the items can be easily paginated by using the score and the user id of the last item of the batch.

• Url https://api.minijuegos.com/lechuck/server/highscore/[hs_uid]/friends/
• Parameters
  • api_key
  • user_id
  • user_token
  • withDetail=1 to include the users public detail
  • withProgress=1 to include the users progress (level)
  • withSharedContent=1 to check if it has shared content and get the id
  • limitnumber of items to retrieve (20 by default)
  • startScorestarting score, inclusive (exclusive if no starting user sent)
  • startUserstarting user (in milliseconds), exclusive.
• Response
  • data.scores Object with a list of scores {score, timestamp, user_id}
  • data.highscore Object with the scoreboard detail and configuration

The same response as 7.1 is returned.

7.3 Get score

Retrieves an user score from a scoreboard (this value may be different from the one reported by getting the stat value, because the scoreboard can have different sorting or computation methods than the stat.

• Url https://api.minijuegos.com/lechuck/server/highscore/[hs_uid]/score/
• Parameters
  • api_key
  • user_id
  • user_token
  • timespan[TOTAL, DAY, WEEK, MONTH] (TOTAL by default)
  • withSharedContent=1 to check if it has shared content and get the id
• Response
  • data.value number with the score, null if not present
  • data.timestamp number with the timestamp when it was posted, null if not present
  • data.highscore Object with the scoreboard detail and configuration
  • data.sharedcontent_id string with the id of the sharedcontent if any

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/highscore/best_points/score/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&user_id=2&withSharedContent=1" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "score": 6562, /* 32 bit number, score */ "timestamp": 1360854616542, /* 64 bit number, when it happened */ "sharedcontent_id": null, /* string with related sharedcontent_id if any */ "highscore": { /* scoreboard configuration */ "id": "12", "uid": "best_points", "is_main": "1", /* main highscore for the game? (i.e. user_level or total_points) */ "is_custom": "0", /* custom scoreboard? (created ad_hoc) */ "is_devel": "0", /* development mode? */ "type_update": "MAX", /* scoreboard type [SUM, MAX, MIN] */ "type_sort": "DESC", /* scoreboard sort [ASC, DESC] */ "display_precision": "0", /* decimal precision */ "display_decorator": "points", /* decorator [ null, time, points, wins, kills...] */ "stat_id": "10" /* stat id that is used as base to send scores to this board*/ "stat_uid": "points" /* stat uid that is used as base to send scores to this board*/ } } }

7.4 Get position

Retrieves an user position from a scoreboard, only the 1000 top positions are stored, any null value means out of the top 1000.

• Url https://api.minijuegos.com/lechuck/server/highscore/[hs_uid]/position/
• Parameters
  • api_key
  • user_id
  • user_token
• Response
  • data.value number with the position, null if not present (outside of the top 1000)
  • data.timestamp number with the timestamp when it was posted, null if not present
  • data.highscore Object with the scoreboard detail and configuration

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/highscore/best_points/score/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&user_id=2&withSharedContent=1" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "value": 2, /* 32 bit number, position */ "timestamp": 1360854616542, /* 64 bit number, when it happened */ "sharedcontent_id": null, /* string with related sharedcontent_id if any */ "highscore": { /* scoreboard configuration */ "id": "12", "uid": "best_points", "is_main": "1", /* main highscore for the game? (i.e. user_level or total_points) */ "is_custom": "0", /* custom scoreboard? (created ad_hoc) */ "is_devel": "0", /* development mode? */ "type_update": "MAX", /* scoreboard type [SUM, MAX, MIN] */ "type_sort": "DESC", /* scoreboard sort [ASC, DESC] */ "display_precision": "0", /* decimal precision */ "display_decorator": "points", /* decorator [ null, time, points, wins, kills...] */ "stat_id": "10" /* stat id that is used as base to send scores to this board*/ "stat_uid": "points" /* stat uid that is used as base to send scores to this board*/ } } }

8. SHARED CONTENT module

This module allows you to save and retrieve user created shared content (like levels for your games, replays, etc). One of the most interesting features we provide is that they can be associated with highscores: when you post a stat (6.2) and it’s good enough to produce an  update in a scoreboard, a highscoresSharedContentId is returned as well, in case you want to store related data (by issuing a shared content put request afterwards). Here’s one good use-case: You’ve got a racing game, and after each race you have the full lap serialized into a string or bytearray, you can store it, display the best times scoreboard and let your users compete against the best. When loading scoreboards, you can retrieve the associated sharedContentId as well.

There’s no limit in the amount of total data you can store, but each shared content slot can only store 50kb of data. Do not spam our servers with data, we track each game storage usage.

8.1 Get data

Retrieves the shared content data.

• Url https://api.minijuegos.com/lechuck/server/sharedcontent/[id]/
• Parameters
  • api_key
• Response
  • The stored data as a binary application/octet-stream (or 404 if empty)

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/sharedcontent/3377442817059061762/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066"

Returns an octect-stream with the data.

8.2 Put data into a new slot

Saves a shared content binary data into a new slot, the slot id will be returned

• Method HTTP POST
• Url https://api.minijuegos.com/lechuck/server/sharedcontent/put/
• Parameters
  • api_key
  • user_token
  • user_id
• Raw POST binary string to save
• Response
  • data.success boolean was the data saved?
  • data.sharedcontent_id string slot id created
  • data.written_bytes number written bytes

[me@localhost ~]# curl -XPOST "https://api.minijuegos.com/lechuck/server/sharedcontent/put/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&user_id=2" -d "....bytedata...." { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "success": true, /* operation result */ "written_bytes": 102, /* bytes written */ "sharedcontent_id": "3377442817059061762", /* string with slot id */ } }

8.3 Put data into a custom slot

Saves a shared content binary data into a defined slot, if it already exists it will overwrite it.

• Method HTTP POST
• Url https://api.minijuegos.com/lechuck/server/sharedcontent/[id]/put/
• Parameters
  • api_key
  • user_token
  • user_id
• Raw POST binary string to save
• Response
  • data.success boolean was the data saved?
  • data.sharedcontent_id string slot id created
  • data.written_bytes number written bytes

[me@localhost ~]# curl -XPOST "https://api.minijuegos.com/lechuck/server/sharedcontent/3377442817059061762/put/?api_key=XXXX&user_token=59a82fa3e016f85352437e066&user_id=2" -d "....bytedata...." { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "success": true, /* operation result */ "written_bytes": 102, /* bytes written */ "sharedcontent_id": "3377442817059061762", /* string with provided slot id */ } }

9. DATASTORE module

Allows you to store user related content and retrieve it when needed, to keep things simple, the datastore are the “savegames”. There are 3 slots per user, 50kb each, numbered as 0, 1 & 2.

9.1 Get slots status

Retrieves the status of the user slots.

• Method HTTP POST
• Url https://api.minijuegos.com/lechuck/server/datastore/[user_id]/
• Parameters
  • api_key
• Response
  • data.first_free_slot number first available slot [1,2,3]
  • data.slots - Array - list of slots with their status

The slot will be null if empty, otherwise, these are the slot status properties:

• string data.slots[x].label Slot label
• number data.slots[x].size Stored data size in bytes
• number data.slots[x].timestamp When it was saved

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/datastore/2/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "first_free_slot": 1, /* first free slot to save data (0 is the first slot) */ "slots": [ { "label": "My custom label 1", /* slot label */ "size": 675, /* size in bytes */ "timestamp": 1361104327154 /* date stored */ }, null, null ] } }

9.2 Get slot data

Retrieves the datastore user slot data.

• Url https://api.minijuegos.com/lechuck/server/datastore/[user_id]/[slot_num]/get/
• Parameters
  • api_key
  • user_token
• Response
  • The stored data as a a binary application/octet-stream (or 404 if empty)

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/datastore/2/0/get/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066"

Returns an octect-stream with the data.

9.3 Put data into a slot

Saves binary data into an user slot, it overwrites any existing data.

• Method HTTP POST
• Url https://api.minijuegos.com/lechuck/server/datastore/[user_id]/[slot_num]/put/
• Parameters
  • api_key
  • user_token
  • label custom slot label string
• Raw POST binary string to save
• Response
  • data.success boolean was the data saved?
  • data.written_bytes number written bytes

[me@localhost ~]# curl -XPOST "https://api.minijuegos.com/lechuck/server/datastore/2/0/put/?api_key=XXXX&user_token=59a82fa3e016f85352437e066" -d "....bytedata...." { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "success": true, /* operation result */ "written_bytes": 102 /* bytes written */ } }

9.4 Reset a slot

Clears an user slot.

• Url https://api.minijuegos.com/lechuck/server/datastore/[user_id]/[slot_num]/reset/
• Parameters
  • api_key
  • user_token
• Response
  • data.success boolean was the data cleared?

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/datastore/2/0/reset/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "success": true /* operation result */ } }

10. ITEM module

The item module allows you manage the items bought by the users for your game, these items can be purchased with Minicoins through the frontend Javascript API.

Please read first our ITEM PURCHASES in depth document for an overview of our purchase process.

10.1 Get all game items

Retrieves the list of configured items for a game

• Url https://api.minijuegos.com/lechuck/server/item/
• Parameters
  • api_key
  • locale locale of the item names (i.e.: es_ES)
• Response
  • data.items list of configured items

These are the properties of each item:

• number data.items[x].id Item id
• string data.items[x].uid Item uid (alphanumeric)
• string data.items[x].name Name in the locale requested (or default one)
• boolean data.items[x].is_enabled Boolean flag, is the item enabled?
• boolean data.items[x].is_usabe Boolean flag, is the item usable/consumable?
• boolean data.items[x].is_buyable Boolean flag, can the item be purchased?
• number data.items[x].price_minicoins Item price in minicoins
• number data.items[x].max_stock Max stock of the item (for boolean items it will be 1)

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/item/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "items": [ { "id": "6", "uid": "ammo", "name": "Ammo", "is_enabled": "1", /* is the item enabled? */ "is_buyable": "1", /* is the item available for purchase? */ "is_usable": "1", /* is the item consumable / usable? */ "price_minicoins": "1", /* price of each item in minicoins */ "max_stock": "1000" /* max stock of this item for each user */ }, { "id": "7", "uid": "shield", "name": "Permanent shield", "is_enabled": "1", /* is the item enabled? */ "is_buyable": "1", /* is the item available for purchase? */ "is_usable": "0", /* is the item consumable / usable? */ "price_minicoins": "100", /* price of each item in minicoins */ "max_stock": "1" /* max stock of this item for each user */ } ] } }

10.2 Get item detail

Retrieves the item configuration

• Url https://api.minijuegos.com/lechuck/server/item/item_uid/
• Parameters
  • api_key
  • locale locale of the item names (i.e.: es_ES)
• Response
  • data.item Object Item properties (refer to 10.1)

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/item/ammo/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "item": { "id": "6", "uid": "ammo", "name": "Ammo", "is_enabled": "1", /* is the item enabled? */ "is_buyable": "1", /* is the item available for purchase? */ "is_usable": "1", /* is the item consumable / usable? */ "price_minicoins": "1", /* price of each item in minicoins */ "max_stock": "1000" /* max stock of this item for each user */ } } }

10.3 List user items

Retrieves the items owned by an user (the user inventory)

• Url https://api.minijuegos.com/lechuck/server/item/user_id/
• Parameters
  • api_key
  • user_token
  • locale locale of the item names (i.e.: es_ES)
  • withDetail =1 to include the item detail
• Response
  • data.items Array list of items owned by the user

These are the most interesting properties of each item:

• number data.items[x].id Item id
• number data.items[x].stock Stock owned by the user
• number data.items[x].timestamp Timestamp of last increment/operation
• object data.items[x].item Item detail (if requested, null otherwise, refer to 10.1)

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/item/2/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&withDetail=1" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "items": [ { "id": 6, "stock": 15, "timestamp": 1361104327154, /* last operation date */ "item": { .. item data shown at 10.1 .. } }, { "id": 7, "stock": 1, "timestamp": 1361104325237, /* last operation date */ "item": { .. item data shown at 10.1 .. } } ] } }

10.4 Get user item stock

Gets the stock for one item owned by the user.

• Url https://api.minijuegos.com/lechuck/server/item/user_id/item_uid/
• Parameters
  • api_key
  • user_token
  • locale locale of the item names (i.e.: es_ES)
  • withDetail =1 to include the item detail
• Response
  • data.stock number Item stock
  • data.timestamp number Timestamp of last operation
  • data.item Object Item detail (if requested, null otherwise, refer to 10.1)

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/item/2/ammo/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&withDetail=1" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "stock": 1, "timestamp": 1361104325237, /* last operation date */ "item": { .. item data shown at 10.1 .. } } }

10.5 Increment an user item stock

Increments the stock of an user item, or give the item to the user if doesn’t have it already. This is only allowed if the item is non purchasable, items that can be purchased with Minicoins cannot be incremented in any ways. If you need to increment a purchasable item we could suggest to have a separated item (non-buyable) that can be tracked or aggregated with the purchasable one value. If the item stock exceeds

• Url https://api.minijuegos.com/lechuck/server/item/user_id/item_uid>/add/
• Parameters
  • api_key
  • user_token
  • qty Amount to increment, defaults to 1.
  • locale locale of the item names (i.e.: es_ES)
  • withDetail =1 to include the item detail
• Response
  • data.new_stock number Resulting stock after the operation
  • data.item Object Item detail (if requested, null otherwise, refer to 10.1)

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/item/2/ammo/add/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&withDetail=1&qty=10" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "new_stock": 105, "item": { .. item data shown at 10.1 .. } } }

10.6 Decrement an user item stock

Decrements the stock of an user item in any quantity, the item must be configured as usable, otherwise the operation will be forbidden

• Url https://api.minijuegos.com/lechuck/server/item/user_id/item_uid/eat/
• Parameters
  • api_key
  • user_token
  • qty Amount to increment, defaults to 1.
  • locale locale of the item names (i.e.: es_ES)
  • withDetail =1 to include the item detail
• Response
  • data.new_stock number Resulting stock after the operation
  • data.item Object Item detail (if requested, null otherwise, refer to 10.1)

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/item/2/ammo/add/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066&withDetail=1&qty=10" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "new_stock": 105, "item": { .. item data shown at 10.1 .. } } }

10.7 Item purchases & server callbacks

Please read first our ITEM PURCHASES in depth document for an overview of our purchase process.

The purchase workflow must be initiated by our client APIs: Javascript or Actionscript 3. Once the user has purchased some items, we’ll send you a signed HTTP POST request to your callback notify you the operation:

• Timeout: 3 seconds
  The request is synchronous, make sure you can answer within this time frame.
• Origin IP range: 217.13.124.0/24
  Please make sure you allow incoming connections to your 80 port from our whole range.
• Headers:
  • Content-Type: application/json
  • Mini-Signature: [OUR-SIGNATURE]

Raw POST DATA (JSON object containing the following information):

{ "game_id": "1", "game_is_devel": true, "game_is_production": false, "user_id": "2", "user_token": "e62fca9blue255e8aefc8553b6e3f3121", /* For your convenience */ "web_id": 1, /* 1: Minijuegos.com | 10: Miniplay.com | 20: Minigiochi.com | 30: Minijogos.com (These are the main ones but there are a lot more) */ "web_uid": "minijuegos_com", /* minijuegos_com, m_minijuegos_com, miniplay_com, m_miniplay_com, minigiochi_com, m_minigiochi_com, minijogos_com_br, m_minijogos_com_br ... */ "web_locale": "es_ES", /* Web locale, the one that you receive in your game as mp_locale parameter (not user locale) */ "event": "buy-item", /* Event being notified, make sure it's this event, other events will be also be notified to you */ "event_payload": { /* Event payload / parameters */ "items": [{ "uid": "ammo", /* Uid of the item */ "qty": 4, /* Amount purchased */ "current_stock": 9, /* New item stock owned by the user */ "total_minicoins": 0, /* Minicoins spent (0 in devel mode) */ "is_dynamic": false, /* Only for dynamic items (for selected developers) */ "dynamic_payload": "", /* Only for dynamic items (for selected developers) */ "timestamp": "1360266031485" },{ "uid": "shield", "qty": 1, "current_stock": 1, "total_minicoins": 0, "is_dynamic": false, /* Only for dynamic items (for selected developers) */ "dynamic_payload": "", /* Only for dynamic items (for selected developers) */ "timestamp": "1360266031490" }], "transaction": "2-1360266031485-1360266031490" /* String up to 40 chars */ }, "time": "1360266031497" /* Timestamp of the operation */ }

We log the response of your server, any HTTP response code between 200 and 299 will be logged as OK. An error will be logged if the HTTP response code is outside the 200-299 range.

It doesn't matter what do you return as response, you cannot roll back the transaction, once the users buys the item/s, they get charged and the item/s are stored in their inventories.

SIGNATURE

        The signature is the MD5 hash of your api_key + the raw post data (concatenated)

        Here’s some demo code to validate the signature (PHP):

$jsonString = file_get_contents("php://input"); /* Get the RAW POST DATA */ if ( ! ( isset($_SERVER['HTTP_MINI_SIGNATURE']) && $_SERVER['HTTP_MINI_SIGNATURE'] == md5("[YOUR_API_KEY]".$jsonString) )) { throw new Exception("Invalid signature"); } /* the request signature has been validated! */ /* Decode the JSON string received and convert it to an associative array */ $json = json_decode($jsonString, true);

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

HOW TO HANDLE OUR NOTIFICATIONS: EVENT TYPE AND ITEM CONSUMPTION

Do not forget to check that the “event” property is “buy-item”, this same schema could be used to notify other type of events (i.e. when an user likes/shares your game) to allow you tracking them. PHP Example:

$jsonString = file_get_contents("php://input"); /* Get the RAW POST DATA */ if ( ! ( isset($_SERVER['HTTP_MINI_SIGNATURE']) && $_SERVER['HTTP_MINI_SIGNATURE'] == md5("[YOUR_API_KEY]".$jsonString) )) { throw new Exception("Invalid signature"); } /* Decode the JSON string received and convert it to an associative array */ $json = json_decode($jsonString, true); if (isset($json['event']) && $json['event'] === "buy-item")) { /* It's an item purchase event!, 'event_payload' contains the purchased items. What to do now?: */ /* a) If you have your own economy or inventory management, you can ignore the payload and just read the user inventory and consume every items you found to remove them from our system. Please DO NOT EVER add them to your inventory without consuming them from our inventory. */ /* b) If you don't have your own economy you can probably just log this message */ }

If you have your own economy or inventory management, you MUST CONSUME the items from the user inventory in our system. Do not ever add them to your inventory without consuming them from ours, if you don't do that, the user will still have the item and we couldn't know if it has been added to yours.

Download a more detailed version with all the notifications available here: https://gist.github.com/miniplay/5907809

AUTOMATIC USE / CONSUMPTION for games with their own economies

Some games have isolated payment gateways that only receives notifications and cannot be modified to make calls to our API (for consuming/removing the items from the user inventory after registering the transaction), in that case, you can return a plain 'AUTOUSE' (without quotes). If that string is returned in conjunction with an HTTP 200 status code, our system will automatically consume the items from the user inventory without requiring you to do that.
Please make sure your response is a plain UTF-8 string, nothing else.

This operation mode is discouraged. You should stick to make calls to the REST API to consume the items, that way, you can be 100% sure the items are correctly decremented from the user inventory in our system.

10.8 Promotions, discounts & item pre-validations

Please make sure you've read "10.7 Item purchases & server callbacks" first.

In order to provide you more security and/or the ability to decide whether or not an item can be sold to an user (i.e. promotions, discounted or special items), we support S2S item pre-validations (for all or for a few items), in this case, we'll request your authorization (via an S2S callback) for every item purchase. This pre-validation will happen twice, first, prior the user purchase, and lastly, prior the user confirms the purchase. I.e, for items which can be sold only once, you should invalidate the future purchases of the item only when you receive the buy-item event, meaning that the user has purchased the item.

We don't support discounts, but this can be easily overcomed by creating new items which can be sold for less money, letting you to decide when an user can buy them or not. There's no limit in the amount of items you can ask us to configure.

By default, all items don't require pre-validation and can be sold, you must ask us to enable it for some items. Please provide us a list of items that have to be validated and both production & development urls for your validation callbacks. If no custom urls are provided, we'll send the notifications to your standard callback urls, for simplicity, we recommend you to use the same urls for all callbacks.

Download our item pre-validation callback sample: https://gist.github.com/miniplay/11146102

In case your callback doesn't respond "OK", or is unable to respond within the time frame (3sec), the item won't be available for purchase.

Please make sure your response is a plain UTF-8 string (without BOM), nothing else.

10.9 Dynamic items

Please make sure you've read "10.7 Item purchases & server callbacks" & "10.8 Item pre-validations" first. Also, check the Javascript API for more info about how to initiate the workflow.

For selected developers and complex games we support an additional type of items called "dynamic", which allows you to set a custom title and price for an item when you initiate the purchase workflow via any of our client apis. To prevent any modification of the payload, these items purchases must be validated server-side, we will always ask you if the user can purchase the dynamic item with the data that you provided us.

You can initiate the workflow of dynamic items just like standard ones, but, instead of providing the amount to purchase for the item, you have to provide an string with the dynamic item payload like this:

PRICE_IN_MINICOINS|ITEM_NAME|OPT_YOUR_CUSTOM_ICON_URL|OPT_YOUR_CUSTOM_DATA

Please be noticed of this:

• Only one dynamic item can be sold at the same time, only 1 unit of the item can be sold.
• The price in minicoins is not your net share, it's the amount that the user has to pay for it, the amount you specify is the amount that will be charged to the user. It must be an integer.
• You have to provide the name in the user locale language, your game receive the user locale as parameter.
• The icon is optional and provisioned for the future, it's not yet supported, we recommend you to leave it empty or provide a 128x128px transparent png url.
• After the third | you can specify whatever you need, like an internal item id, you can even include more | symbols.
• The payload max length is 700 characters, including icon

VALIDATION OF DYNAMIC ITEMS

You're responsible for the validation of the dynamic item, we'll send you a callback with the purchase request including the payload data you specified. By returning 'OK' you acknowledge that the price & name of the item is correct, and that the user can purchase it. You can (and you should) add as much data as you need to the payload in order to verify it and to prevent users from purchasing items they're not allowed to (like a transaction id or a signature...)

Check our validation callback sample, the payload data provided is included: https://gist.github.com/miniplay/11146102

Please make sure your response is a plain UTF-8 string, nothing else.

PURCHASE NOTIFICATIONS

Dynamic items will be notified just like regular items, but you'll receive the "dynamic_payload" property you provided us inside them so you can process it for your game (Check RAW POST DATA at 10.7 Item purchases & server callbacks).

Important: Given the nature of dynamic items, they doesn't need to be consumed, they will be automatically consumed after they're notified to your S2S callback. We don't store an inventory of dynamic items. If you're manually consuming items from the user inventory you must ignore "dynamic" items.

10.10 User item log

Retrieves the log from an user item (only for that item).

• Url https://api.minijuegos.com/lechuck/server/item/user_id/item_uid/log/
• Parameters
  • api_key
  • user_token
  • limit number of rows (defaults to 20)
  • startTimestamp starting timestamp (in milliseconds), newest, exclusive.
  • stopTimestamp stop timestamp (in milliseconds), oldest, exclusive.
• Response
  • data.log array of row objects

These are the properties of each row:

• data.log[x].item_id Item id
• data.log[x].item_uid Item uid
• data.log[x].user_id User id
• data.log[x].timestamp Timestamp of the operation
• data.log[x].op_amount Amount incremented/decremented
• data.log[x].op_new_stock Resulting stock
• data.log[x].from_api Boolean, was the operation an API request?
• data.log[x].from_ip Ip that originated the operation
• data.log[x].minicoins Amount of minicoins

[me@localhost ~]# curl -XGET "https://api.minijuegos.com/lechuck/server/item/2/ammo/log/?api_key=XXXX&user_token=59a82131fa3e01040a6f85352437e066" { "status": { "success": true, "type": "OK", "code": 200, "message": null }, "data": { "log": [ { "timestamp": "1361113881612", /* Timestamp of the operation */ "item_id": 8, "item_uid": "ammo", "user_id": 2, "op_amount": -1, /* Amount subtracted from the user stock */ "op_new_stock": 0, /* Resulting user stock after operation */ "from_api": true, /* Was an API request? */ "from_ip": "192.168.50.18", /* IP that originated the API request */ "minicoins": 0 /* Minicoins earned */ }, { "timestamp": "1361113876853", /* Timestamp of the operation */ "item_id": 8, "item_uid": "ammo", /* Amount subtracted from the user stock */ "user_id": 2, "op_amount": 1, /* Amount added to the user stock */ "op_new_stock": 1, /* Resulting user stock after operation */ "from_api": false, /* Was an API request? */ "from_ip": "", /* IP that originated the API request */ "minicoins": 100 /* Minicoins earned */ } ], "lastTimestamp": "1361113881612" /* Timestamp of last log line, for pagination */ } }

10.11 User items log

Retrieves the log from every user items.

• Url https://api.minijuegos.com/lechuck/server/item/user_id/log/
• Parameters
  • api_key
  • user_token
  • limit number of rows (defaults to 20)
  • startTimestamp starting timestamp (in milliseconds), newest, exclusive.
  • stopTimestamp stop timestamp (in milliseconds), oldest, exclusive.
• Response
  • data.log array of row objects (refer 10.8)

10.12 Game item log

Retrieves the log for an item of the game (for every users).

• Url https://api.minijuegos.com/lechuck/server/item/item_uid/log/
• Parameters
  • api_key
  • user_token
  • limit number of rows (defaults to 20)
  • startTimestamp starting timestamp (in milliseconds), newest, exclusive.
  • stopTimestamp stop timestamp (in milliseconds), oldest, exclusive.
• Response
  • data.log array of row objects (refer 10.8)

10.13 Full game items log

Retrieves the full log (for every users and every items).

• Url https://api.minijuegos.com/lechuck/server/item/log/
• Parameters
  • api_key
  • user_token
  • limit number of rows (defaults to 20)
  • startTimestamp starting timestamp (in milliseconds), newest, exclusive.
  • stopTimestamp stop timestamp (in milliseconds), oldest, exclusive.
• Response
  • data.log array of row objects (refer 10.8)

Do you have questions or want to report some bugs? please contact us at [email protected]