Jocly OnLine Embedding

From Jocly Wiki
Revision as of 12:19, 22 May 2015 by Mig (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

PRELIMINARY DOCUMENT: This is work in progress and information are subject to changes.

The Jocly JQuery plugin allows to embed games into a third-party site. Those games are defined on Jocly web site or modified/created on the hosting site. This is generally used to permit sites visitors to discover some games by playing against the computer. Using Jocly OnLine Embedding (abbreviated as JOLE), it is also possible to allow users from the third-party site to play against each other. The hosting site can then organize free games and tournaments within its own community.

JOLE provides the abilities:

  • to create and authenticate users on the Jocly live server
  • to create tables between 2 users for existing or host-defined games
  • to display applets so each players can see the board from her own point of view and play moves
  • to get notified of games events, like a move being played and game ending / being created

JOLE does not provide the lobby function: it is the responsibility of the hosting site to put players in relation and setup tables to be played.

You can see a basic demo of JOLE on



  • Hosting site: the third-party Web site using the JOLE API. This may also appear as jole source or simply source. Since the hosting site contains the game applets, it is the hosting site domain that appears in the URL bar of the browser.
  • Embed server: game applets are iframe included in hosting site pages. These iframes are server from the embed server, operated by Jocly. Normally, the embed server is, however during development, other domains may be used.
  • Live server: the live server is in charge of managing the handshake to schedule game moves. It is different from the embed server. Most of the JOLE API functions consist of the hosting making HTTP requests to the live server.

API basics

All API functions are regular HTTP requests issued by the hosting site. This means the API can be used by any language. However for convenience, we provide a PHP library file to make calls easier.

Since the hosting site can perform admin-level functions on Jocly servers, like creating tables and users, Jocly must trust the hosting site and make sure the requests are really coming from it. This is done by specifying a source name unique to the hosting site and digitally signing all the API requests using a key that is only known by Jocly and the hosting site.

So far, there is no automatic way to declare a hosting site. If you want to implement the JOLE API, please contact support at jocly dot com to discuss technical details.

Calls to the live server are HTTP GET requests following the structure:

   <live server base>/jole/<signature>/<json>


  • <live server base> is the beginning of the URL of live server including the protocol, domain and port, for instance: The exact domain and port of the live server can be obtained from a call to the embed server (see below).
  • <signature> is the digital signature for this call obtained by calculating a SHA1 digest of the string resulting from the contatenation of the <json> string (before URL encoding) and the hosting site secret. For instance is the secret is mysecret and the json part is {"foo":12}, the signature is the SHA1 digest of string:

in this case: dde4954f67ffc9503ad14e6add8a5dd9204cf745.

  • <json> is the URL-encoded JSON representation of an object containing the call parameters:
    • source: the unique identifier of the hosting site
    • op: the operation to be performed
    • data: an object containing the parameters specific to the requested operation

If the result of the request is successful (from a network access point of view, i.e returning a 200 HTTP status status code), the response body is a JSON-encoded object with fields:

  • status: a boolean indicating whether the call was successful (from an API point of view)
  • result: present only if status is true. The result of the call, which depends on the actual operation being requested
  • error: present only if status is false. A string indicating the reason of the error

The PHP function for making generic JOLE API calls is implemented as:

   function JOLE_request($joleData,$op,$data=array()) {
       $request = array(	
           'source' => $joleData['source'],
           'op' => $op,
           'data' => $data,
       $json = json_encode($request);
       $sha1 = sha1($json.$joleData['secret']);
       $url = $joleData['server'].'/jole/'.$sha1.'/'.urlencode($json);
       $resp = file_get_contents($url);
           return FALSE;
           return json_decode($resp,true); 

Where $joleData is an associative array variable containing the fields:

  • source: the hosting site identifier
  • secret: the hosting site specific secret
  • server: the live server vase URL

API functions


The createTable operation creates a game table. The associated parameters are:

  • game: the Jocly game machine name, like classic-chess or draughts. It can be a host-defined name as long as the hosting site defines this game name.
  • timing: the string defining the scheduling of the game according to Jocly standards. For instance:
    • 5m+2s: total 5 minutes per player plus 2 seconds per move
    • 30m: total 30 minutes per player
    • 3dpm: 3 days per move
  • players: an object with keys 1 (for player A, the first player) and -1 (for player B, the second player). Each player value is an object with the following fields:
    • joleUserId: a string that identifies the user uniquely on the hosting site
    • joleUserName: a string providing the name/nick of the user. If omitted, joleUserId is used
    • picture: a URL to an image representing the user avatar. If omitted, Jocly default is used

If successful, the operation returns an object containing a single field:

  • gameId: the table id


The getTables operation returns a summary of all the tables currently playing for the calling hosting site.

If successful, the returned object is an array of objects representing the playing tables. TBD


The deleteTable operation deletes a table previously created. Note that if it is useful when developing the hosting site code, it is probably not a good idea to remove a table in normal operations.

The parameters contain a single field:

  • id: the id of the table to be removed


The getUserTag operations returns a temporary key to authenticate a user. This tag is for a unique usage and expires after a minute if not used. The generated is used to be passed to the applet so Jocly knows what user is to be logged in the applet iframe.


  • joleUserId: a string that identifies the user uniquely on the hosting site
  • joleUserName: a string providing the name/nick of the user. If specified, it overrides the name given in a possible previous call to createTable or getUserTag defining that user. If not specified and the user has not been defined, joleUserId is used
  • picture: a URL to an image representing the user avatar. If specified, it overrides the picture given in a possible previous call to createTable or getUserTag defining that user. If not specified and the user has not been defined, Jocly default is used

Live server URL

The API functions above require you know the live server base URL to make the requests to. You can obtain this information from a call to the embed server:


This will return a JSON-encoded structure such as:


From this information you can deduce the live server URL, in this case

You might think you need to make this call prior to every API call to ensure the live server base URL is correct, but in practice, this might not be a good idea as this will slow down the hosting site user interface. The live server URL will only change in case of a major Jocly re-deployment so you may prefer storing the live server URL as a constant in your code/system and use it directly.

Online embedded applet

If you want to run an embedded game against the computer, you execute the following javascript code:

   $(document).ready(function() {


  • GAME is the game you want to play, like classic-chess or draughts

If you want the applet to be playable by the user (or watchable by a user who is not a player of the game), you would get:

   $(document).ready(function() {
       $("#jocly-applet").jocly("onlinePlay",GAME,{ gameId:GAMEID });


  • USERTAG is the user identifier you previously got from a call to getUserTag
  • GAMEID is the game id you got from a previous call to createTable or getTables

Typically, GAME and GAMEID are passed as URL parameters of the hosting site page, for instance, while USERTAG is created within the page. So the page (assuming PHP) could look like:

   $user = mycms_get_current_user();
   $userTag = JOLE_getUserTag('my-hosting-site','getUserTag',array('joleUserId'=>$user->id));
       $(document).ready(function() {
           $("#jocly-applet").jocly({userTag:"<?= $userTag ?>"});
           $("#jocly-applet").jocly("onlinePlay","<?= $_REQUEST['game'] ?>",{ gameId:"<?= $_REQUEST['gameid'] ?>" });
   <div id="jocly-applet"></div>

Hosting site callback

When setting up a hosting site on the Jocly site, one of the parameters, along with the hosting site name and secret, is the callback URL. Whenever an event happens that is related to a table created by the hosting site, this callback is invoked with URL parameters relevant to the event. This can be used for instance to maintain a player rating system on the hosting site by monitoring the endGame event.

The URL is invoked with 2 parameters:

  • json: a JSON and URL-encoded object describing the event
  • sign: the SHA1 digest to validate the json parameter. This signature is generated by concatenating json (not URL-encoded) and the secret shared between the hosting site and Jocly, and applying a SHA1 calculation on it.

It is important for the hosting site to verify the signature in order to prevent malicious attempts to generate fake events (and prevent a player to claim a false win for instance). The verification could look like (in PHP):

   $sign = $_REQUEST['sign'];
   $json = $_REQUEST['json'];
   $sign0 = sha1($json);
   if($sign==$sign0) {
       $data = json_decode($json);
       // handle event described in $data

TBD: define events syntax


A JOLE demo can be seen in action on

The source code of the demo hosting site is available from File:Jole-demo.tar.gz as a PHP web site.

The demo is designed to be as platform-agnostic as possible:

  • the pseudo-authentication system is simply based on a user cookie being set, no password is requested when login as a user.
  • there is no access to any database, API callbacks are simply logged into a file. If you install this demo on your server, make sure jole.log is writable by the system user running the web server.

Even if this demo site is written in PHP, developers should have much problem porting to other languages.