Joyplay Integration API v1.04
We'll send you your operators secret key Base64 encoded.
You'll then be able to embed games within an iframe using following parameters;
<iframe src="http://www.joyplay.com/play/newslots/play?theme=gemcubes&operator=YOUROPERATORNAME&container=apiV1&token=aDx0ExHS2sfdR9N8V7TNgs1GRL48/+rP05T7ehNmmb0y+qmySCk3pDcSvavgbpCLWBc38mgW4YuIMZP+DqtMTg=="></iframe>
theme : is the game name
container : "apiV1"
operator : "your unique operator name"
token : "3pLggT19qs1AOGWZNfYZKLhPuw4Y6Z/zgbyehENdXt86LU6bfSj5liuO2GRwi95XEDCWD/4zomsVCOsFZHCMSQ=="
token must be a json string such as {"session_uuid" : "72ce0fb2-056a-4cab-b434-07e2c3fdb28b"}
-> Encrypt it with the shared secret key using AES. (aes-128-ecb)
-> Then encode it with base64url encoding (as described in RFC4648) and send as a UTF-8 string.
(it is optional to replace the trailing padding =='s with %3D, Joyplay accepts either)
We will then decode and decrypt it and use the session_uuid for the user conversation with your server.
Within the token the session_uuid is a unique identifier that maps to a user on your system.
#NOTE# - as this is encrypted you could just use the users id, but it would give you less control
over the management of user sessions.
Example encrpytion
Encoding string {"session_uuid" : "72ce0fb2-056a-4cab-b434-07e2c3fdb28b"}
Using secret (base64) = aWiUEVloV2IscxI7hTzgNQ==
secret bytes as a UTF-8 string = ih�YhWb,s;�<�5
{"session_uuid" : "72ce0fb2-056a-4cab-b434-07e2c3fdb28b"} encrypted and base 64 encoded is oTbn0I5rT8v2u6Y8/1CZIOdayofcgj8ny9FGiP2JVLPVC9hq2hwJzsYhXku/Bb5zIUfwsHX+gJQbI4WrCcYV8w==
decode-and-decrypt oTbn0I5rT8v2u6Y8/1CZIOdayofcgj8ny9FGiP2JVLPVC9hq2hwJzsYhXku/Bb5zIUfwsHX+gJQbI4WrCcYV8w==
decodes to {"session_uuid" : "72ce0fb2-056a-4cab-b434-07e2c3fdb28b"}
Notes
Make sure the secret key is base64 decoded into bytes and then used as the key. It should be 128 bits when decoded.
Another example encoding;
Encoding string test
Using secret (base64) = aWiUEVloV2IscxI7hTzgNQ==
secret bytes as a UTF-8 string = ih�YhWb,s;�<�5
test encrypted and base 64 encoded is cVCtFgA0mVCuHMcYd/J1dw==
decode-and-decrypt cVCtFgA0mVCuHMcYd/J1dw==
decodes to test
HTTP endpoints on your server
You then need to create an HTTP endpoint on your server so we can query balances with GET and update using POST.
These calls will be made from our server.
HTTP GET
e.g. HTTP GET https://your.domain/accounts?session_uuid=231231231
session_uuid - is the session_id passed into the iframe with the token.
Your http end point must return a JSON that includes;
{
userid : "bob123123", //unique user id, this may just be the same as the session_uuid
displayname : "bob", //the display name of the user
avatar_url : "http://somewhere.com/pic1.png" //the user picture (optional)
balance : 45000, //the balance of the user
valid_balance_duration : 10000 //how long the balance is accurate for in milliseconds. Once expired we'll call this method again before performing a spin.
//with values below a 3000 milliseconds, we'll essentially be checking again before every spin.
experience : "123" //OPTIONAL
}
IMPORTANT - the valid_balance_duration must be respected by you the operator. If you the operator specify a users balance is valid for X milliseconds, you have to respect any subsequent balance updates based on that.
HTTP POST
Which handles the following parameters to update the users balance;
action : "update"
session_uuid : the session_uuid specified within the token, this should map to your user.
balanceDelta : the change in the users balance. A positive number means the users balance increased, negative decreased.
betAmount : the amount that was bet, always a positive number, this can be used to adjust experience points
game : the name of the game they were playing
subgame : the sub game if relevant
transaction_id : a UUID for the api transaction
description : describes whether the delta was from to a spin, gamble etc
and to tell your server we're deleting the session_uuid from memory;
action : "end"
session_uuid : the string specified within the token in session_uuid, this should map to your user.
You must returns a JSON string with the same fields as the GET above.
In the event you no longer want to let the session_uuid play because it's expired you should return
{
error : "EXPIRED_SESION_UUID"
display_message : "optional message to be displayed to the user"
redirect_uri : "http://someurl"
}
Any other JSON message that contain an error field will result in the bet not being placed, the specified message being displayed to the user.
For example;
{
error : "NOT_ENOUGH_FUNDS"
display_message : "NOT ENOUGH FUNDS", optional message to be displayed to the user
redirect_uri : "http://someurl" //optional, if present it will be followed
}
Tournaments
If you want to use the games within tournaments, this can be achieved by allocating a specific "tournament balance"
to the relevant session_uuid.
Client side messages
We send events from the game to the parent web page using postMessage
You can register to receive messages from the game using;
window.addEventListener("message", function(event){
//Handle the event
}, false);
For further information see https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
Also see http://stackoverflow.com/a/8849807/851853
This can be used to perform actions such as managing experience levels.
We send the following events;
On game start;
{ event : "initialised", content : "account initialised"}
Just after each spin;
{ event : "spinStart", game : "gemcubes", subtheme : "xxx", bet : 100});
After each spin has finished and results displayed;
{ event : "spinFinished", game : "gemcubes", subtheme : "xxx", bet : 100, winnings : 200});
FAQ
- We're having problems on Safari on iOS after rotating the screen!
If the frame content is bigger than the outer frame Safari decide not to shrink the frame down. This happens with the width when going from Landscape to Portrait.
See http://stackoverflow.com/questions/16937070/iframe-size-with-css-on-ios
The best option here is probably to set the iframe size with Javascript. With jQuery it would be something like;
$(window).bind('resize', function(){
$("#gameFrame").css("width",$(window).width()+"px");
});
Upcoming featuers
- Add a sig (some values signed with the secret) to the HTTP GET & POST to the third party server so they can verify they are coming from our server.
- To allow a session_duration_time to be included within the token.
- Include our internal game action transaction id in the POST