html5-client-apis

*We assure you that we do not spam. You may receive occasional emails from us.
 You can always unsubscribe.
AppWarp SDKs
AppWarp Concept
Tutorials
ebook
WarpClient APIs WarpClient Events WarpClient Listeners WarpClient Event Result Codes
Html5

HTML5 Client APIs

Initialize
Top
 
	AppWarp.WarpClient.initialize(apiKey, secretKey);
Initializes the singleton instance of WarpClient with the developer credentials. This has to be called only once during the lifetime of the application. It is required before you can call any other API.

Parameters

 
	apiKey - The Application key given when the application was created.
	secretKey - The secret key corresponding to the application key given when the application was created.

Returns

void

getInstance
Top
 
	AppWarp.WarpClient.getInstance();
Gets the Singleton instance of WarpClient

Returns

WarpClient

getSessionID
Top
 
	getSessionID();
It gives sessionId of the current established connection,otherwise returns zero.

Returns

SessionID - int sessionID

Connect
Top
 
	connect(username);
Sets up your connection with the AppWarp cloud server. The username passed in this method must be unique across all other concurrently connected users. If two users with the same name try to connect at the same time, then the first one will win and the second one will get an auth error in onConnectDone. The username string parameter length must be more than 0 and less than 25. Also it shouldn’t contain the following characters “, ; / \”. The result of the operation is provided in the onConnectDone callback.

Parameters

username - Username of the player

Returns

void

Disconnect
Top
 
	disconnect();
Disconnects the connection with the AppWarp server. The result for this request will be provided in the onDisConnectDone callback.

Parameters

Returns

void

recoverConnection
Top
 
	recoverConnection();
Attempts to recover from an intermittent connection error. If successful, the client will be placed in the same room as before the loss and all its subscriptions will be maintained. The other subscribed users of the room, will receive onUserResumed notification. This can only be called if an established session was lost due to a connectivity error and the client got onConnectDone with a recoverable connection error code. The connection must be restored within the recovery allowance period, after which the server considers the session to be over (non-recoverable).

Returns

void

recoverConnectionWithSessionID
Top
 
	recoverConnectionWithSessionID(sessionID, userName);
Attempts to recover from an intermittent connection error.Since this API requires sessionId so it has to be saved by the game on the last successful connection.The other subscribed users of the room, will receive onUserResumed notification.The connection must be restored within the recovery allowance period, after which the server considers the session to be over (non-recoverable).

Parameters

 
	sessionID- sessionId of the last successful session.
	userName- name of the player.

Returns

void

setRecoveryAllowance
Top
 
	setRecoveryAllowance(time);
Sets the time allowed for the client to recover from an intermittent connection loss. This must be set before the initial connect API is called as that associates the value on the server for the given connection.

Parameters

 
	time - the time (in seconds) allowed to the client to recover from intermittent connection loss.

Returns

void

Join Lobby
Top
 
	joinLobby();
Sends a join lobby request to the server. Result of the request is provided in the onJoinLobbyDone callback.

Parameters

Returns

void

leave Lobby
Top
 
	leaveLobby();
Sends a leave lobby request to the server. Result of the request is provided in the onLeaveLobbyDone callback.

Parameters

Returns

void

Subscribe Lobby
Top
 
	subscribeLobby();
Sends a subscribe lobby request to the server. Result of the request is provided in the onSubscribeLobbyDone callback. Users which have subscribed to the lobby receive chat events from other users in the lobby as well as join/leave notifications about all players to and fro the lobby and all the rooms. In addition, lobby subscribers get notifications when a new room is created or deleted.

Parameters

Returns

void

Unsubscribe Lobby
Top
 
	unsubscribeLobby();
Sends a unsubscribe lobby request to the server. Result of the request is provided in the onUnsubscribeLobbyDone callback.

Parameters

Returns

void

Join Room
Top
 
	joinRoom(roomId);
Sends a join room request to the server. Result of the request is provided in the onJoinRoomDone callback. A user can only be joined in one location (room or lobby) at a time. If a user joins a room, it will automatically be removed from its current location.

Parameters

roomId - Id of the room to be joined

Returns

void

Join Room In Range
Top
 
	joinRoomInRange(minJoinedUsers, maxJoinedUsers, maxPreferred);
sends a join room request to the server for any room that currently has joined users in the range given. maxPreferred indicates the preference in the case that multiple rooms with the desired params are found. The result of the request is provided in the onJoinRoomDone callback. This is useful in supporting quick play modes.

Parameters

minJoinedUsers - minimum number of users joined in room

maxJoinedUsers - maximum number of users joined in room

maxPreferred - Prefer room with maximum joined users

Returns

void

Join Room With Properties
Top
 
	joinRoomWithProperties(tableProperties);
Sends a join room request to the server with the condition that the room must have a matching set of property value pairs associated with it. This is useful in match making. Result of the request is provided in the onJoinRoomDone callback.

Parameters

tableProperties- properties of the room to be joined

Returns

void

Leave Room
Top
 
	leaveRoom(roomId);
Sends a leave room request to the server. Result of the request is provided in the onLeaveRoomDone callback.

Parameters

roomId - Id of the room to be left

Returns

void

Create Room
Top
 
	createRoom(name, owner, maxUsers, tableProperties);
Sends a create room request to the server with the given meta data. Result of the request is provided in the onCreateRoomDone callback. If successful, this will create a dynamic room at the server. These rooms lifetime is limited till the time users are inside it. Read more about Rooms here.

Parameters

    name - name of the room
	owner - administrator of the room
	maxUsers - number of maximum users allowed in the room
	tableProperties - properties of room for matchmaking (pass null if not required)

Returns

void

Delete Room
Top
 
	deleteRoom(roomId);
Sends a delete room request to the server. Result of the request is provided in the onDeleteRoomDone callback. Only dynamic rooms can be deleted through this API. Static rooms (created from AppHQ) can not be deleted through this. Read more about Rooms here.

Parameters

roomId - Id of the room to be deleted

Returns

void

Subscribe Room
Top
 
	subscribeRoom(roomId);
Sends a subscribe room request to the server. Result of the request is provided in the onSubscribeRoomDone callback. Once subscribed, the client will receive all notifications from the room such as chat, update and property change events. In addition the client will also receive notifications when a user joins or leaves the subscribed room.

Parameters

roomId - Id of the room to be subscribed

Returns

‘void’

Unsubscribe Room
Top
 
	unsubscribeRoom(roomId);
Sends a unsubscribe room request to the server. Result of the request is provided in the onUnSubscribeRoomDone callback.

Parameters

roomId - Id of the room to be subscribed

Returns

void

Send Chat
Top
 
	sendChat(message);
Sends a chat message to the room (or lobby) in which the user is currently joined. Result of the request is provided in the onSendChatDone callback. All users who are subscribed to the location in which the message is sent will get a onChatReceived event on their registered callback.

Parameters

message - message to be send

Returns

void

Send Private Chat
Top
 
	sendPrivateChat(toUser, message)

Sends a private message to the given user if its online. Result of the request is provided in the onSendPrivateChatDone callback. The sender and receiver don’t need to be in the same room or lobby for the private message to be delivered. This is useful in building invite/challenge friend like scenarios. If successful, the receiver will get a onPrivateChatReceived event on its registered callback.

Parameters

toUser - the recipient of the private chat

message - message to be send

Returns

void

Send Update Peers
Top
 
	sendUpdatePeers(update);
Sends a byte array update message to room in which the user is currently joined. Result of the request is provided in the onSendUpdateDone callback. All users who are subscribed to the room in which the update is sent will get a onUpdatePeersReceived event. This is useful if developers want to send their own binary encoded data across and is useful in minimizing the payload exchanged between the clients and AppWarp cloud server.

Parameters

update - binary data to be send

Returns

void

Get Live Room Info
Top
 
	getLiveRoomInfo(roomId);
Retrieves the live information of the given room from the server. Result is provided in the onGetLiveRoomInfoDone callback. The information includes the names of the currently joined users, the rooms properties and any associated customData. This is useful in getting a snapshot of a rooms state.

Parameters

roomId - Id of the room

Returns

void

Get Live User Info
Top
 
	getLiveUserInfo(username);
Retrieves the live information of the user from the server. Result is provided in the onGetLiveUserInfo callback. The information (if user is online) includes the current location of the user and any associated custom data. It is useful in building scenarios where you want to find if a users friends are online or not and then join their room if found online.

Parameters

username - user who's information is requested

Returns

void

Get Live Lobby Info
Top
 
	getLiveLobbyInfo();
Retrieves live information of the lobby from the server. Result is provided in the onGetLiveLobbyInfo callback. The information returned includes the names of the users who are currently joined in the lobby.

Parameters

Returns

void

Set Custom User Data
Top
 
	WarpClient.setCustomUserData(userName, customData);
Updates the custom data associated with the given user on the server (if the given user is online). Result is provided in the onSetCustomUserDataDone callback. It can be useful in setting status messages or avatar url’s etc for online users.

Parameters

userName - user for whom custom data has to be update
customData - custom data that will be set for the user

Returns

void

Set Custom Room Data
Top

Updates the custom data associated with the given room on the server. The result is provided in the onSetCustomRoomDataDone callback. It is recommended you use the room’s properties where ever possible. Use this when you need to associate data with a room which can not be represented as key value pairs.

 
	SetCustomRoomData(roomId, customRoomData)

Parameters

roomId - Id of the room
customRoomData - custom data that will be set for the room

Returns

void

Update Room Properties
Top
 
	updateRoomProperties(roomID, tableProperties, removeArray);
Updates the properties associated with the given room on the server. Result is provided in the onUpdatePropertyDone callback. Properties which are not found on the server, will be added while properties which are already present will simply be updated with the new values. You can also specify the list of properties that you want to remove from the remove. This request (if successful) will also result in an onUserChangeRoomProperty notification to be triggered for all subscribed users of the room.

Parameters

roomId - Id of the room
tableProperties - properties that will be set for the room
removeArray - properties that will be removed for the room

Returns

void

Lock Properties
Top
 
	lockProperties(properties);

Lock the properties associated with the joined room on the server for requested user. Result is provided in the onLockPropertyDone callback. Lock properties will fail if any other user has lock on same property, otherwise property will be added in lockTable with owner name. This request (if successful) will also result in an onUserChangeRoomProperty notification to be triggered for all subscribed users of the room.

Parameters

properties - properties and their values to be locked

Returns

void

Unlock Properties
Top
 
	unlockProperties(properties);

Unlock the properties associated with the joined room on the server for requested user. Result is provided in the onUnlockPropertyDone callback. Unlock properties will fail if any other user has lock on same property, otherwise property will be removed from lock table. This request (if successful) will also result in an onUserChangeRoomProperty notification to be triggered for all subscribed users of the room.

Parameters

properties - vector of properties to be unlocked

Returns

void

Get Online Users
Top
 
	getOnlineUsers();
Retrieves usernames of all the users connected (online) to the server. Result is provided in the onGetOnlineUsers callback.

Parameters

Returns

void

Get All Rooms
Top
 
	getAllRooms();
Retrieves the room ids of all the rooms on the server. Result is provided in the onGetAllRoomsDone callback. To get a filtered list of rooms, use the GetRoomWithNUser or GetRoomWithProperties APIs.

Parameters

Returns

void

Get Rooms In Range
Top
 
	getRoomsInRange(minJoinedUsers, maxJoinedUsers);
Retrieves information of the rooms that contain currently have joined users in the range given. Result is provided in the onGetMatchedRoomsDone callback. This is useful in building a filtered list of rooms.

Parameters

minJoinedUsers- minimum number of users in room to be joined

maxJoinedUsers- maximum number of users in room to be joined

Returns

void

Get Room With Properties
Top
 
	getRoomWithProperties(properties);
Retrieves information of the room that contain properties which match with the given properties. Result is provided in the onGetMatchedRoomsDone callback. This is useful in building a filtered list of rooms.

Parameters

properties- properties of the room to be joined

Returns

void

Set the Response Listener
Top
 
	setResponseListener(event, callback);
This function Registers the given callback function to a response event. Callback will be invoked when a response corresponding to that event is received from the server. All response events are present inside `AppWarp.Events` namespace. Click here to know more about listeners

Parameters

event - Event to be registered

callback - Callback Function

Returns

void

Set the Notify Listener
Top
 
	setNotifyListener(event, callback);
This function Registers the given callback function to a notification event. Callback will be invoked when a notification corresponding to that event is received from the server. All notification events are present inside `AppWarp.Events` namespace. Click here to know more about listeners.

Parameters

event - Event to be registered

callback - Callback Function

Returns

void

Reset the Notify Listener
Top
 
	resetNotifyListener(event);
This function resets the callback function for the given notification event. Hence you will no longer get events for that notification.

Parameters

event - Event to be registered

callback - Callback Function

Returns

void

Reset the Response Listener
Top
 
	resetResponseListener(event);
This function resets the callback function for the given response event. Hence you will no longer get events for that response.

Parameters

event - Event to be registered

callback - Callback Function

Returns

void

Create Turn Room
Top

Sends a create turn based room request to the server with the given meta data. Result of the request is provided in the onCreateRoomDone callback. If successful, this will create a dynamic turn based room at the server. These rooms lifetime is limited till the time users are inside it. Read more about Rooms here.

createTurnRoom (name ,owner , maxUsers , tableProperties , turnTime )

Parameters

name -  name  of  the  room 
owner -  owner  of  the  room  ( behavior  and  usage  of  this  meta  property  is  up  to  the  developer ) 
maxUsers -  number  of  maximum  users  allowed  in  the  room 
tableProperties -  properties  of  room  ( can  be  null ) 
turnTime -  the  time  ( in  seconds )  allowed for  a  user  to  complete  its  turn  and  send  a  move .

Returns

void

Send Move
Top

Sends a move to the server for the joined turn based room. Result of the request is provided in the onSendMoveDone callback. If the joined user is not a turn based room or if its not the users turn, this request will fail. If successful, this will result in onMoveCompleted notification event.

sendMove (moveData )

Parameters

moveData -  any  meta  data  associated  with  the  move

Returns

void

Start Game
Top

Sends a start game request to the server. Result of the request is provided in the onGameStarted callback of the TurnBasedRoomListener.

startGame ( )

Returns

void

Stop Game
Top

Sends a stop game request to the server. Result of the request is provided in the onGameStopped callback of the TurnBasedRoomListener.

stopGame ( )

Returns

void

Get Move History
Top

Sends a get move history request to the server. Result of the request is provided in the onGetMoveHistoryDone callback of the TurnBasedRoomListener. 

getMoveHistory ( )

Returns

void

setGeo
Top

setGeo allows you to connect to our cloud servers in locations other than the default location. This offers developers the choice to connect to the closest server depending on the client’s device location.

 setGeoLocation(location)

Parameters

location - server location. For e.g. US, EU, JAPAN

Returns

void

setNextTurn
Top

When the onNextTurnRequest is sent by the server, it sends the next turn to the server for the joined turn based room.Result of the request is provided in the onSetNextTurnDone callback of the registered Turn Based Room Listener objects. If the joined user is not in turn based room or if it’s not the user’s turn, this request will fail. If successful, this will result in onMoveCompleted notification for all the subscribed users on the registered NotifyListener objects.

 setNextTurn(nextTurn)

Parameters

nextTurn - the string value for the next turn

Returns

void

sendPrivateUpdatePeers
Top
 
	sendPrivateUpdatePeers(to,bytes);
Sends a byte array update message to the recipient user. Result of the request is provided in the onSendPrivateUpdateDone callback of the registered UpdateRequestListener objects. Remote user will get an onPrivateUpdateReceived event on their registered NotifyListener objects. This is useful if developers want to send private data between the users.

Parameters

to - to username

bytes - update message

Returns

void

Get Online Users Count
Top
 
	getOnlineUsersCount();
Retrieves total number of users connected (online) to the server. Result is provided in the onGetOnlineUsersCountDone callback of the ZoneRequestListener objects.

Parameters

Returns

void

Get All Rooms Count
Top
 
	getAllRoomsCount();
Retrieves total number of rooms on the server. Result is provided in the onGetAllRoomsCountDone callback of the ZoneRequestListener objects.

Parameters

Returns

void

Join And Subscribe Room
Top
 
	joinAndSubscribeRoom(roomId);
Sends a join and subscribe room request to the server. Result of the request is provided in the onJoinAndSubscribeRoomDone callback of the registered RoomRequestListener objects. A user can only be joined in one location (room or lobby) at a time. If a user joins a room, it will automatically be removed from its current location. Once subscribed, the client will receive all notifications from the room such as chat, update and property change events. In addition the client will also receive notifications when a user joins or leaves the subscribed room. These notifications are given in the registered NotifyListener objects.

Parameters

roomId - Id of the room to be join and subscribed

Returns

void

Leave And Unsubscribe Room
Top
 
	leaveAndUnsubscribeRoom(roomId);
Sends a leave and unsubscribe room request to the server. Result of the request is provided in the onLeaveAndUnsubscribeRoomDone callback of the registered RoomRequestListener objects.

Parameters

roomId - Id of the room to be subscribed

Returns

void

Get Rooms In Range With Properties
Top
 
	getRoomInRangeWithProp(minJoinedUsers,maxJoinedUsers,properties);
Retrieves information of the rooms that contain at least minUsers , at most maxUsers and set of property value pairs in them. Result is provided in the onGetMatchedRoomsDone callback of the registered ZoneRequestListener objects. This is useful in building a filtered list of rooms.

Parameters

minJoinedUsers- minimum number of users in room to be joined

maxJoinedUsers- maximum number of users in room to be joined

properties- properties of the room to be joined

Returns

void

Get User Status
Top
 
	getUserStatus(username);
Retrieves status of user via username on the server. Result is provided in the onGetUserStatusDone callback of the registered ZoneRequestListener objects. This is useful to find either user is connected or not.

Parameters

username - Username of the player

Returns

Send chat (overloaded method for chat history)
Top
 
	sendChat(message,saveHistory,roomId);
Sends a chat message with two more parameters specially used if chat history is enabled. Here user need to provide boolean variable(i.e true/false) for either save this chat or not and roomID of joined room.Result of the request is provided in the onSendChatDone callback. All users who are subscribed to the location in which the message is sent will get a onChatReceived event on their registered callback.

Parameters

message - message to be sent

saveHistory - Boolean variable indicating sent message needs to be saved or not.

roomId - Id of the room

Returns

Set Database name
Top
 
	setDbName(dbName);
Set a db name where chat history need to be saved. To create a db if not created already, please follow the steps given below:

1.Login to AppHQ Management Console.

2.Select App42 Cloud API from the product drop down.

3.Select Storage from left most menu.

4.Select JSON from the sub menu and click on Add DB button.

5.Provide the DBName and click on Submit button

Parameters

dbName - Database name that will be set for the chat history.

Returns

Enable chat history
Top
 
	enableChatHistory(saveHistory);
Enables client to save the chat sent using sendChat API.

Parameters

saveHistory - If true, the client can save chat using sendChat API

Returns

Get chat history
Top
 
	getChatHistory(roomId,max,offset);
Retrieves chat history of a room of specified roomId from the server. Result is provided in the onGetChatHistoryDone callback.

Parameters

roomId- Id of the room whose history is requested

max- Number of messages to be fetched from the server

offset- index from where the messages need to be fetched

Returns