Javascript API

Javascript API provides a GamoogaClient class. You require to have the following files servable by your webserver:

gamooga.js
sock_bridge.swf

gamooga.js needs to be included by you in your HTML files. It uses WebSockets if they are enabled and supported by the browser. If not, it uses Flash sockets for which it requires sock_bridge.swf. Both the files are available in the SDK.

NOTE: Since our WebSocket support is pretty new, we have put it behind a flag until it matures. Hence the current default transport is Flash sockets. Please refer to ENABLE_WEBSOCKET documentation below.

GamoogaClient.init

Usage:

GamoogaClient.init(sockBridgeSwfUrl, onInitHandler);
argument type
sockBridgeSwfUrl string
onInitHandler function

This is a static function and initializes GamoogaClient by adding sock_bridge.swf to DOM if required. The first parameter is the URL to sock_bridge.swf. The second parameter is the function to be called when GamoogaClient is initialised and ready to be instantiated.

Example:

GamoogaClient.init("./sock_bridge.swf", onInit);

ENABLE_WEBSOCKET

Usage:

GamoogaClient.ENABLE_WEBSOCKET = true;

WebSocket support is freshly baked into our API. Hence we have put it behind a flag until it matures. You need to set this flag to true before calling GamoogaClient.init to enable WebSocket support.

Please note that during development, when connected to development server, you should not set this flag to true. (This is because the development server doesnot have a WebSocket component). When connected to production with this flag set to true, the API uses WebSockets by default.

Currently the following versions of WebSocket protocol are supported:

  1. Hixie-76/HyBi-00
  2. HyBi-07
  3. HyBi-08 - HyBi-12 (report version 8)
  4. HyBi-13

GamoogaClient constructor

You require to use the GamoogaClient class to connect and communicate with Gamooga servers (or the local development server). Instantiate the class like below (after onInitHandler above is called).

Usage:

var gc = new GamoogaClient(devServer);
// or
var gc = new GamoogaClient();
argument type
devServer string (optional)

devServer is the ip/domain address of the dev server (provided in the SDK). To connect to production, omit the devServer argument from the constructor.

Example:

var gc = new GamoogaClient("127.0.0.1"); //to connect to development server
var gc = new GamoogaClient(); //to connect to production

connectToRoom

Usage:

gc.connectToRoom(app_id, app_uuid);
argument type
app_id integer
app_uuid string

This method is used to connect to the room of your gamlet with app_id and app_uuid as the application id and the application uuid.

NOTE: Since the dev server in the SDK can only run a single gamlet, you can provide any app_id and app_uuid while connecting to dev server.

Example:

gc.connectToRoom(12, "f824cdbc-46b1-11e1-9008-00266c101cae");

createConnectToSession

Usage:

gc.createConnectToSession(app_id, app_uuid);
argument type
app_id integer
app_uuid string

This method is used to create a new session of the gamlet with app_id and app_uuid as the application id and the application uuid and connect to this newly created session.

NOTE: Since the dev server in the SDK can only run a single gamlet, you can provide any app_id and app_uuid while connecting to dev server.

Example:

gc.createConnectToSession(12, "f824cdbc-46b1-11e1-9008-00266c101cae");

connectToSession

Usage:

gc.connectToSession(sess_id, app_uuid);
argument type
sess_id integer
app_uuid string

This method is used to connect to the session sess_id of the gamlet with app_uuid as the application uuid.

NOTE: Since the dev server in the SDK can only run a single gamlet, you can provide any app_uuid while connecting to dev server.

Example:

gc.connectToSession(12345, "f824cdbc-46b1-11e1-9008-00266c101cae");

onconnect

Usage:

gc.onconnect(onconn_cb);
argument type
onconn_cb function

This method is used to attach a callback onconn_cb to the onconnect event when the client connects to the server. onconn_cb is executed as soon as the connection to server succeeds.

Example:

gc.onconnect(function() {
    alert("now connected to server");
});

onmessage

Usage:

gc.onmessage(msg_type, onmsg_cb);
argument type
msg_type string
onmsg_cb function(msg)

This method is used to attach a callback onmsg_cb to the onmessage event when a server sends a message. Server can send messages of different types. This method can be used to attach a callback to a type of message. onmsg_cb is called as soon as a message of type msg_type is received from the server. onmsg_cb itself is passed one argument: msg (data type: any) which is the message sent from the server.

Example:

gc.onmessage("userjoin", function(msg) {
    alert("received message type: userjoin, with message: "+msg);
});

ondisconnect

Usage:

gc.ondisconnect(ondisconn_cb);
argument type
ondisconn_cb function

This method is used to attach a callback ondisconn_cb to the ondisconnect event when the client disconnects from the server. ondisconn_cb is called as soon as the client disconnects.

Example:

gc.ondisconnect(function() {
    alert("disconnected from server");
});

onerror

Usage:

gc.onerror(onerror_cb);
argument type
onerror_cb function(errno)

This method is used to attach a callback onerror_cb to the onerror event when an error occurs at client or server side. onerror_cb is called as soon as the error occurs. onerror_cb itself is passed one argument: errno (data type: integer) is the error number denoting the error that occured.

errno GamoogaClient constant reason
3 GamoogaClient.CLIENT_SERVER_BUSY Server has too many messages pending to process for this gamlet and hence rejected a message that is sent (we currently queue upto 100 pending messages to be processed by server before we report this error)
4 GamoogaClient.CLIENT_SERVER_ERROR Server is in a state of error, due to error in its gamlet code
6 GamoogaClient.CLIENT_IN_DATA_EXCEED Client sent too much data (> 8KB) to the server in a single send
7 GamoogaClient.CLIENT_OUT_DATA_EXCEED Server sent too much data (> 8KB) to the client in a single send (*)
101 GamoogaClient.IO_ERROR Could not connect to server, probably because server is down
102 GamoogaClient.SECURITY_ERROR Could not get permission to connect, probably the flash policy file is unavailable at server
103 GamoogaClient.WEBSOCKET_ERROR Websocket error occured
201 GamoogaClient.WRONG_APP_ID Could not connect to room, wrong APP_ID
202 GamoogaClient.WRONG_APP_UUID Could not connect to room/session, wrong APP_UUID
203 GamoogaClient.APP_ID_AND_UUID_NOT_PROVIDED APP_ID/APP_UUID not provided in connect* APIs
204 GamoogaClient.LIMITS_REACHED Gamlet usage has reached the currently subscribed plan limits
205 GamoogaClient.GAMLET_UNDEPLOYED Gamlet is currently undeployed
301 GamoogaClient.API_ERROR Other error while connecting to server

(*) - This error is best reported on the server side, but for effeciency of the server, this error is reported on the client side only.

Example:

gc.onerror(function(errno) {
    alert("caught error: "+errno);
});

send

Usage:

gc.send(msg_type, msg);
argument type
msg_type string
msg any

This function is used to send a message msg of type msg_type to the room or session.

Example:

gc.send("userchat", "hi there");

disconnect

Usage:

gc.disconnect();

This method actively closes the connection to the server.

getSessId

Usage:

var sess_id = gc.getSessId();

This method returns the id of the session the client is connected to. If its connected to room or not yet connected to session, then this method returns 0.

disableLogMsg

Usage:

gc.disableLogMsg();

When connected to development server, GamoogaClient logs all events to console.log. You can use this message to disable that logging. (When connected to production, logging is disabled by default, you can enable it using the next method.)

enableLogMsg

Usage:

gc.enableLogMsg();

You can use this function to enable logging events to console.log.