com.sg.util

Interface SGGameServerInterface

public interface SGGameServerInterface

Game server interface.

This interface communiates with game server via HTTP/HTTPS with no UI stuff. It is called by background thread of SGAgent.

Game server is provided by CP. It manages appliation products and user orders. It may involve information of user accounts and applications, but should work together with SG server.

First, in user's point of view, there should be only one login screen. This login screen should only provided by channel SDK and channel server. User enters account and password at login screen and clock "confirm" button to start login. If the login progress finished successfully, channel server will return session information to client and, client will pass the information to SG server, SG server then use it to make login verification with channel server. If the information is confirmed to be a real and successful login, SGGameServerInterface.init will be called with necessary session and application information, which may be used to initialize parameters for consequent login, pay and logout operation. Similarly, game server should query SG server about the validity of the session information and return success if the information is proved. Thus the whole user login progress completes. Therefore only channel server manages account information the users know, while SG server and game server need to create bound accounts for convenience of information management.

Second, channel server manages information of applications published by CPs. These information usually include application names, CP names, application IDs, application keys, application secrets, payment keys, URLs for payment result notification, etc. SG server needs to these information and associate with its self-managed information, which may include appID, appKey and appSecret etc. As game server does not communicate with channel server directly, it may only care about, associate, manage and utilize information generated by SG server.

There are 3 methods in SGGameServerInterface that communiates with SG server, which are login, getOrder and getOrderState.

A successful login flow contains the following steps.

Step	Side	Action
1	Application	User starts login progress
2	Application	Call SGAgent.login()
3	SGAgent	Start login screen
4	Channel SDK	User enters login information and confirms to continue
5	Channel SDK	Send login request to channel server
6	Channel server	Create session, return session information to channel SDK
7	Channel SDK	Receive session information and return to SGAgent
8	SGAgent	Send information to SG server for login verification
9	SG server	Make login verification with channel server and return result to SGAgent
10	SGAgent	Call SGServerInterface.login() to login to game server
11	Application	Send login request to game server in SGServerInterface.login
12	Game server	Make login verification with SG sever and return result to application
13	Application	Finish login progress and show consequent screen

where the API used in step 12 to make login verification with SG server is depicted below.

Item			Value	Remark
URL			https://www.sgstudios.cn:8443/user/verifyAccount
Request
	Method		POST
	MIME type		application/x-www-form-urlencoded
	Parameters	userID	Call session.getUserID() passed when SGGameServiceInterface.init is called
		token	Call session.getToken() passed when SGGameServiceInterface.init is called
		sign	MD5("userID=" + userID + "token" + token + appKey)	lower case
Response
	MIME type		text/json
	Content		{"state":<state>, "data":{"userID":<userID>,"username":<username>,"channelID":<channelID>}}	Angle brackets indicate values of various fields. The values of 'state' are: 1 - success 6 - unknown user 8 - token is empty 9 - unknown session 12 - bad signature userID, username and channelID are user ID, user name and channel ID respectively managed by SG server.

A successful order generation flow contains following steps.

Step	Side	Action
1	Application	User starts buying a product
2	Application	Call SGAgent.buyProduct()
3	SGAgent	Call SGGameServerInterface.getOrder()
4	Application	Send game server request of order generation in SGGameServerInterface.getOrder
5	Game server	Send SG server the request of order generation
6	SG server	Create order, return back order ID and other information
7	Game server	Save order information. return order ID and other information
8	Application	Return order information to SGAgent
9	SGAgent	Start channel payment screen

where the API used in step 5 to ask SG server to generate order is depicted below.

Item			Value	Remark
URL			https://www.sgstudios.cn:8443/pay/getOrderID
Request
	Method		POST
	MIME type		application/x-www-form-urlencoded
	Parameters	userID	Call session.getUserID() passed when SGGameServerInterface.init is called
		productID	UProduct.getProductID()
		productName	UProduct.getProductName()
		productDesc	UProduct.getProductDesc()
		money	UProduct.getPrice() * UPayParams.getBuyNum()	Refer to UProduct.getPrice and UPayParams.getBuyNum。 As copies to buy must be 1 at present, money equals to UProduct.getPrice()
		roleID	UProduct.getRoleID()
		roleName	UProduct.getRoleName()
		serverID	UProduct.getServerID()
		serverName	UProduct.getServerName()
		extension	Any string	Can be a string indicating trade properties for convenience of future query
		notifyUrl	A URL for receiving asynchronous order result notification from SG server.	SG server will POST notification to this URL when it gets to know the order result.
		signType	"md5"
		sign	MD5("userID=" + userID + "&productID=" + productID + "&productName=" + productName + "&productDesc=" + productDesc + "&money=" + money + "&roleID=" + roleID + "&roleName=" + roleName + "&serverID=" + serverID + "&serverName=" + serverName + "&extension=" + extension + "&notifyUrl=" + notifyUrl + appSecret)	lower case appSecret is stored in game server and should not be embedded in client
Response	MIME type		text/json
	Content		{"state":<state>, "data":{"orderID":<orderID>,"extension":<extension>}}	Angle brackets indicate values of various fields. The values of 'state' are: 1 - success 6 - unknown user 10 - money is negative 11 - unknown channel 12 - bad signature 13 - payment feature is off orderD is order ID, extension is extended information

A successful order generation flow constains following steps.

Step	Side	Action
1	Application	Automatic and user-initiated query
2	Application	Call SGAgent.getProductState()
3	SGAgent	Call SGGameServerInterface.getOrderState()
4	Application	Query game server about order state in SGGameServerInterface.getOrderState
5	Game server	SG server will send game server the order result asynchronously (relevant to purchase UI operation) notified by channel server. The notification usually arrives very quickly, but if it does not arrive for a long time then there may be problems in communication or purchase processing itself. If the order result is already known ("succeeded", "failed" and "cheated"), you may jump to step 7 and return result to application. Otherwise you may query SG server about the order state and return result to application. Because SG server will transfer the query to channel server on game server's request, you should not make such query frequently. You have to wait for 30s before raising a query, and you can raise at most 20 effective queries (meaning the query interval is long enough and SG server made query communication to channel server). It indicates there are problem in purchase processing or communication chain if order result is unknown after 20 query tries. Please use human service in this case.
6	SG server	Query channel server about order state and return result to game server
7	Game server	Save order state and return result to application
8	Application	Show consequent screen

where the API used in step 5 to query SG server about order state is depicted below.

Item			Value	Remark
URL			https://www.sgstudios.cn:8443/pay/getOrderState
Request
	Method		POST
	MIME type		application/x-www-form-urlencoded
	Parameters	userID	Call session.getUserID() passed when SGGameServerInterface.init is called
		queryOrderID	order ID
		loginExtension	Call session.getLoginExtension() passed when SGGameServerInterface.init is called
		signType	"md5"
		sign	MD5("userID=" + userID + "&queryOrderID=" + queryOrderID + "&loginExtention=" + loginExtention + appSecret)	lower case appSecret is stored in game server and should not be embedded in client
应答	MIME type		text/json
	内容		{"state":<state>, "data":{"money":<money>,"realMoney":<realMoney>,"currency":<currency>}}	Angle brackets indicate values of various fields. The values of 'state' are: -1 - query failed 1 - order generated 2 - payment succeeded 3 - succeeded to notify game server 4 - payment failed 'money' is the amount of order, 'realMoney' is amount received (please do not deliver product if 'realMoney' is less than 'money'), 'currency' is the type of currency ("RMB", etc.).

Besides calling SG server's APIs, the game server interface should implement an API to receive order state notification from SG server. The specification is as follows.

Item			Value	Remark
URL			notifyUrl	Value passed to SG server in order generation query
Request
	Method		POST
	MIME type		text/json
	Parameters	state	order state	values and meanings 1 - order generated 2 - order payment succeeded 3 - order succeeded to notify game server 4 - order payment failed
		data	order data	data itself is a JSON object containing various data of order
		channelID	application's channel ID managed by SG server	item in data
		currency	type of currenty	item in data
		extension	string passed to SG server in order generation request (returned as is	item in data
		gameID	appID passed when SGGameServerInterface.init is called	item in data
		money	amount of order	item in data
		orderID	order ID	item in data
		productID	UPayParams.getProductID()	item in data
		realMoney	amount of money received	item in data
		serverID	UProduct.getServerID()	item in data
		userID	Call session.getUserID() passed when SGGameServerInterface.init is called	item in data
		signType	"md5"	item in data
		sign	MD5("channelID=" + channelID + "&currency=" + currency + "&extension=" + extension + "&gameID=" + gameID + "&money=" + money + "&orderID=" + orderID + "&productID=" + productID + "&realMoney=" + realMoney + "&serverID=" + serverID + "&userID=" + userID + appSecret)	item in data lower case appSecret is stored in game server and should not be embedded in client
Response	MIME type		text/plain
	Content		result string (no quotation marks)	Meanings: SUCCESS - succeeded FAIL - failed

Field Summary

Fields

Modifier and Type	Field and Description
static char	SGGAMESERVER_LOG_ACTION_DECVALUE
static char	SGGAMESERVER_LOG_ACTION_INCVALUE
static char	SGGAMESERVER_LOG_ACTION_LOG
static char	SGGAMESERVER_LOG_ACTION_LOGIN
static char	SGGAMESERVER_LOG_ACTION_LOGOUT
static char	SGGAMESERVER_LOG_ACTION_MAXVALUE
static char	SGGAMESERVER_LOG_ACTION_MINVALUE
static char	SGGAMESERVER_LOG_ACTION_STARTGAME
static char	SGGAMESERVER_LOG_ACTION_STOPGAME
static char	SGGAMESERVER_LOG_ACTION_UPDATEVALUE

Method Summary

Modifier and Type	Method and Description
String	deliverOrder(String orderID, String productID, int buyNum) Inform game server to mark the order as delivered.
String	getLogValue(String key, int defaultValue) Get value of remote log key.
UOrderTicket	getOrder(UProduct product, UPayParams pp) Ask game server to generate order.
List<UOrder>	getOrderInfoList(String filter) Get user's order list.
String	getOrderState(String orderID, String productID, int buyNum) Query game server about order state.
String	getPlayerDetails() Get detailed description of player.
List<UProduct>	getProductList(String filter) Get product list of application.
String[]	getTreasureList(String filter) Get user's treasure list.
int	incTreasure(String name, int value) Increase user's treasure.
void	init(SGAgent agent, Map<String,String> params, String cookie)
boolean	log(char action, String key, int value, String message, boolean waitForResp) Remote logging.
UAccount	login() Login to game server.
String	logout(UAccount account) Logout from game server.
void	notifyOrderAccepted(String orderID, String productID, int buyNum) Inform game server that the order was accepted by channel server.
boolean	startGame() Start game.
boolean	stopGame() Stop game.

Field Detail

SGGAMESERVER_LOG_ACTION_DECVALUE

static final char SGGAMESERVER_LOG_ACTION_DECVALUE

See Also:

Constant Field Values

SGGAMESERVER_LOG_ACTION_INCVALUE

static final char SGGAMESERVER_LOG_ACTION_INCVALUE

See Also:

Constant Field Values

SGGAMESERVER_LOG_ACTION_LOG

static final char SGGAMESERVER_LOG_ACTION_LOG

See Also:

Constant Field Values

SGGAMESERVER_LOG_ACTION_LOGIN

static final char SGGAMESERVER_LOG_ACTION_LOGIN

See Also:

Constant Field Values

SGGAMESERVER_LOG_ACTION_LOGOUT

static final char SGGAMESERVER_LOG_ACTION_LOGOUT

See Also:

Constant Field Values

SGGAMESERVER_LOG_ACTION_MAXVALUE

static final char SGGAMESERVER_LOG_ACTION_MAXVALUE

See Also:

Constant Field Values

SGGAMESERVER_LOG_ACTION_MINVALUE

static final char SGGAMESERVER_LOG_ACTION_MINVALUE

See Also:

Constant Field Values

SGGAMESERVER_LOG_ACTION_STARTGAME

static final char SGGAMESERVER_LOG_ACTION_STARTGAME

See Also:

Constant Field Values

SGGAMESERVER_LOG_ACTION_STOPGAME

static final char SGGAMESERVER_LOG_ACTION_STOPGAME

See Also:

Constant Field Values

SGGAMESERVER_LOG_ACTION_UPDATEVALUE

static final char SGGAMESERVER_LOG_ACTION_UPDATEVALUE

See Also:

Constant Field Values

Method Detail

deliverOrder

String deliverOrder(String orderID,
                    String productID,
                    int buyNum)

Inform game server to mark the order as delivered. The order state will be "delivered" after game server succeeded to handle this requent. However, "delivered" state must not be the sole criteria that where product should be delivered to user due to communication and other problems. One case is that call of deliverOrder fails after application unlocked the product (order). Application must handle these cases carefully.

Parameters:

orderID - order ID

productID - product ID

buyNum - copies bought

Returns:

"OK" when success, null otherwise.

getLogValue

String getLogValue(String key,
                   int defaultValue)

Get value of remote log key.

Parameters:

key - key to match

defaultValue - default value to return in case of failure

Returns:

value of key or defaultValue and log content text, separated by ","

getOrder

UOrderTicket getOrder(UProduct product,
                      UPayParams pp)

Ask game server to generate order.

Parameters:

product - product information

pp - payment parameters

Returns:

order ticket when success, null otherwise.

getOrderInfoList

List<UOrder> getOrderInfoList(String filter)

Get user's order list.

Parameters:

filter - filter string

Returns:

order list when success, null otherwise.

getOrderState

String getOrderState(String orderID,
                     String productID,
                     int buyNum)

Query game server about order state. Game server should initiate query to SG server if order payment UI operation succeeded but there is no order state notification from SG server after waiting for a period. USession.loginExtension is needed to submit query. Please see server integation document for details.

Parameters:

orderID - order ID

productID - product ID

buyNum - copies bought

Returns:

order state. One of "generated", "succeeded", "delivered", "failed" and "cheated" when success, null otherwise. "generated" means order is generated but game server does not know the result yet. "succeeded" means payment succeeded. "delivered" means the order was delivered. "failed" means payment failure. "cheated" means the paid money is less than price. Please note that the state here and UProduct.state are different things.

getPlayerDetails

String getPlayerDetails()

Get detailed description of player.

Returns:

Text string that describes player details.

getProductList

List<UProduct> getProductList(String filter)

Get product list of application.

Parameters:

filter - filter string

Returns:

product list when success, null otherwise.

getTreasureList

String[] getTreasureList(String filter)

Get user's treasure list.

Parameters:

filter - filter string

Returns:

treasure list when success, null otherwise.

incTreasure

int incTreasure(String name,
                int value)

Increase user's treasure.

Parameters:

name - Treasure name

value - increment

Returns:

updated treasure count, -1 otherwise.

init

void init(SGAgent agent,
          Map<String,String> params,
          String cookie)

log

boolean log(char action,
            String key,
            int value,
            String message,
            boolean waitForResp)

Remote logging.

Parameters:

action - action code (SGGAMESERVER_LOG_ACTION_xxx)

key - used to match (and update) existing record with the same key

value - integer value

message - additional information

waitForResp - whether or not wait for and return server response

Returns:

success or not

login

UAccount login()

Login to game server.

Returns:

Game server account information when success, null otherwise.

logout

String logout(UAccount account)

Logout from game server.

Parameters:

account - account information

Returns:

"OK" for success, null otherwise.

notifyOrderAccepted

void notifyOrderAccepted(String orderID,
                         String productID,
                         int buyNum)

Inform game server that the order was accepted by channel server. This method is called to notify game server order state change if payment UI operation succeedes. It may be a dummy if game server does not support receiving notification.

Parameters:

orderID - order ID

productID - product ID

buyNum - copies bought

startGame

boolean startGame()

Start game.

Returns:

success or not

stopGame

boolean stopGame()

Stop game.

Returns:

success or not