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=""></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.


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 : "" //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.


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 }


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 Also see 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});


- 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 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