SandBoxd API - Version 1.0

Introduction

The SandBoxd API (SPI) is the method by which games can communicate with the backend of the SandBoxd.com site. The protocol uses xml-rpc to communicate.

All procedure calls require the API version number (in the format "[Major Version].[Minor Version]") as the first parameter, followed by the gameid followed by the API key hash for this game. The API key hash is a 20-byte hex encoded SHA1 digest of your API key with a randomly generated nonce. The next value is the nonce you generated. What follows is subject to the procedure being called. The response value of the rpc is always an array unless an error occurs in which case the standard fault format applies. A detailed breakdown follows.

General Header Format

API version (string) - IE "1.0"
game id (int) - The game's unique identifier (0 for development mode)
api key hash (string) - A hex encoded SHA1 hash of your api key and a random nonce
nonce (string) - The generated nonce value.

General Error Codes

7 - Game id does not exist.
8 - API key not valid.
10 - Invalid function call.
11 - Unknown error.
12 - Unknown version.
16 - Malformed input.

Examples

The following is a typical header.

<?xml version="1.0"?><methodCall>
<methodName>spi.getuser</methodName>
<params>
	<!-- Header -->
	<param>
		<!-- The SPI version number we are targetting -->
		<value><string>1.0</string></value>
	</param>
	<param>
		<!-- Our game id -->
		<value><int>2</int></value>
	</param>
	<param>
		<!-- A hex encoded SHA1 hash digest of our secret api key and a randomly generated nonce -->
		<value><string>40e48c6faf6df5b58683d770f60539371bbf7138</string></value>
	</param>
	<param>
		<!-- The nonce we generated -->
		<value><string>kyrtqwhuvr</string></value>
	</param>
	<!-- Payload -->
</params>
</methodCall>

spi.getuser

Description

Returns a list of detailed information about a given user. This procedure has two uses. In the first case only the user id of the user is provided and a list of information is returned. In the second case a session id (and ip address if further security is needed) is also provided and SandBoxd will verify the user is valid.

Call Structure

uid (int) - The user's id. A user id of 0 means the guest account.
sid (string, optional) - The session id of the requested user.
ip (string, optional) - The ip address of the requested user.

Response Structure

name (string) - The user's name.
avatar (string) - A full url to the user's avatar.
gid (int) - The user's display group for this game. 0 if user does not have group for this game.
friends (array) - A list of the user's friends. Entries are the user id of the friend.
achievements (struct) - A list of the user's achievements. Entries are the name of the achievement and the progress on that achievement.
stats (struct) - A list of the user's statistics. Entries are the name of the stat and the number for that stat.
microids (array) - A list of microtransaction ids that this user has purchased for this game. This is only provided if the sid is provided for security reasons.

Error Codes

1 - User does not exist.
2 - Session is not valid.
9 - IP is not valid.

Examples

A request for guest account information.

<?xml version="1.0"?><methodCall>
<methodName>spi.getuser</methodName>
<params>
	<!-- Header (Excluded for brevity) -->
	
	<!-- Payload -->
	<param>
		<!-- We want the guest account information so we use uid = 0 -->
		<value><int>0</int></value>
	</param>
</params>
</methodCall>

A typical login scenario. User id is 1 and we are given the session id via the url which loaded the game.

<?xml version="1.0"?><methodCall>
<methodName>spi.getuser</methodName>
<params>
	<!-- Header (Excluded for brevity) -->
	
	<!-- Payload -->
	<param>
		<!-- We want to login user with uid = 1 -->
		<value><int>1</int></value>
	</param>
	<param>
		<!-- The given session id -->
		<value><string>gau2pxfczg9um6mb1mof3zd98td2ak99</string></value>
	</param>
</params>
</methodCall>

For further security measures we can verify the user's ip address has not changed (Session hijacking, etc). This is usually only used in multiplayer games when the server is making the request to SPI.

<?xml version="1.0"?><methodCall>
<methodName>spi.getuser</methodName>
<params>
	<!-- Header (Excluded for brevity) -->
	
	<!-- Payload -->
	<param>
		<!-- We want to login user with uid = 1 -->
		<value><int>1</int></value>
	</param>
	<param>
		<!-- The given session id -->
		<value><string>gau2pxfczg9um6mb1mof3zd98td2ak99</string></value>
	</param>
	<param>
		<!-- The user's ip address -->
		<value><string>123.45.67.89</string></value>
	</param>
</params>
</methodCall>

spi.getgroup

Description

Returns a list of detailed information about a given group.

Call Structure

gid (int) - The group's id.

Response Structure

name (string) - The group's name.
members (array) - A list of the group's members. Entries are the user id of the member.

Error Codes

3 - Group does not exist.

Examples

A request for the group with the group id of 5.

<?xml version="1.0"?><methodCall>
<methodName>spi.getgroup</methodName>
<params>
	<!-- Header (Excluded for brevity) -->
	
	<!-- Payload -->
	<param>
		<value><int>5</int></value>
	</param>
</params>
</methodCall>

spi.achievement

Description

Updates a user's achievement.

Call Structure

uid (int) - The user's id.
sid (string) - The session id of the requested user.
key (string) - The name of the achievement.
value (int) - The value to set the achievement to. Must be a value between 0 and the maximum value defined.

Response Structure

<Empty>

Error Codes

1 - User does not exist.
2 - Session is not valid.
4 - Achievement does not exist.
5 - User is not registered with this game.
15 - Guest users are not valid for this request.

Examples

Update user with uid of 5 to set achievement "someAchievement" to a value of 9.

<?xml version="1.0"?><methodCall>
<methodName>spi.achievement</methodName>
<params>
	<!-- Header (Excluded for brevity) -->
	
	<!-- Payload -->
	<param>
		<value><int>5</int></value>
	</param>
	<param>
		<value><string>gau2pxfczg9um6mb1mof3zd98td2ak99</string></value>
	</param>
	<param>
		<value><string>someAchievement</string></value>
	</param>
	<param>
		<value><int>9</int></value>
	</param>
</params>
</methodCall>

spi.stat

Description

Updates a user's statistic.

Call Structure

uid (int) - The user's id.
sid (string) - The session id of the requested user.
key (string) - The name of the stat.
value (string) - The value to set the stat to. Maximum 80 characters.

Response Structure

<Empty>

Error Codes

1 - User does not exist.
2 - Session is not valid.
6 - Stat does not exist.
5 - User is not registered with this game.
15 - Guest users are not valid for this request.

Examples

Update user with uid of 5 to set statistic "ranking" to a value of "Captain".

<?xml version="1.0"?><methodCall>
<methodName>spi.achievement</methodName>
<params>
	<!-- Header (Excluded for brevity) -->
	
	<!-- Payload -->
	<param>
		<value><int>5</int></value>
	</param>
	<param>
		<value><string>gau2pxfczg9um6mb1mof3zd98td2ak99</string></value>
	</param>
	<param>
		<value><string>ranking</string></value>
	</param>
	<param>
		<value><string>Captain</string></value>
	</param>
</params>
</methodCall>

spi.location

Description

Updates a user's location within the game. Useful for friends being able to join each other's games.

Call Structure

uid (int) - The user's id.
sid (string) - The session id of the requested user.
locationdata (string) - The machine name location of the user. IE "game-34" Maximum 80 characters. An empty string indicates that the user is not in a joinable game.
location (string) - A human friendly version of the location information. IE "Deathmatch". Maximum 80 characters.

Response Structure

<Empty>

Error Codes

1 - User does not exist.
2 - Session is not valid.
15 - Guest users are not valid for this request.

Examples

Update the users location to "Deathmatch" with unique identifier "room-458".

<?xml version="1.0"?><methodCall>
<methodName>spi.achievement</methodName>
<params>
	<!-- Header (Excluded for brevity) -->
	
	<!-- Payload -->
	<param>
		<value><int>5</int></value>
	</param>
	<param>
		<value><string>gau2pxfczg9um6mb1mof3zd98td2ak99</string></value>
	</param>
	<param>
		<value><string>room-458</string></value>
	</param>
	<param>
		<value><string>Deathmatch</string></value>
	</param>
</params>
</methodCall>

The user is no longer in a joinable game.

<?xml version="1.0"?><methodCall>
<methodName>spi.achievement</methodName>
<params>
	<!-- Header (Excluded for brevity) -->
	
	<!-- Payload -->
	<param>
		<value><int>5</int></value>
	</param>
	<param>
		<value><string>gau2pxfczg9um6mb1mof3zd98td2ak99</string></value>
	</param>
	<param>
		<value><string></string></value>
	</param>
	<param>
		<value><string></string></value>
	</param>
</params>
</methodCall>

spi.transaction

Description

Initiates a microtransaction. The user will need to verify that they want this action to go through. Because of the requirement of user interaction this call may hang for upwards of minutes at a time. An empty return value indicates success.

Call Structure

uid (int) - The user's id.
sid (string) - The session id of the user.
microid (string) - The identifier for this microtransaction. Maximum 80 characters.
description (string) - A description of the transaction to display to the user in the prompt.
amount (int) - The amount of credits required for this transaction.

Response Structure

<Empty>

Error Codes

1 - User does not exist.
2 - Session is not valid.
13 - User already has this microtransaction.
14 - User declined the microtransaction.
15 - Guest users are not valid for this request.

Examples

Present the user with a microtransaction dialogue for the transaction uniquely identified by "micro-34" for 35 credits.

<?xml version="1.0"?><methodCall>
<methodName>spi.achievement</methodName>
<params>
	<!-- Header (Excluded for brevity) -->
	
	<!-- Payload -->
	<param>
		<value><int>5</int></value>
	</param>
	<param>
		<value><string>gau2pxfczg9um6mb1mof3zd98td2ak99</string></value>
	</param>
	<param>
		<value><string>micro-34</string></value>
	</param>
	<param>
		<value><string>A human readable description of this microtransaction.</string></value>
	</param>
	<param>
		<value><int>35</int></value>
	</param>
</params>
</methodCall>