SPI reference-Cloud Gaming (Deprecated)-阿里云帮助中心

The server-side Service Provider Interface (SPI) of the cloud gaming platform provides services for session authentication, game access control, and container lifecycle notifications. This topic describes the SPI integration steps and interface standards.

Integration instructions

The Cloud Gaming Platform as a Service (PaaS) calls your business system in scenarios such as session authentication and game access control. You must integrate your system according to the standards defined by the Cloud Gaming PaaS. The standards are as follows:

Provide an HTTPS service that the Cloud Gaming PaaS platform can call.
Use the standard templates provided by the Cloud Gaming PaaS platform to format input and output data.
Use the server-side AppKey obtained from the Cloud Gaming Operations Hub to verify and sign data.
Meet the quality standards set by the Cloud Gaming PaaS platform.

Integration steps

1. Request a server-side AppKey

Log on to the Cloud Gaming PaaS console with your Alibaba Cloud account and go to the Operations Hub. In the project list, select the project that you want to integrate. Click Application List Management, and then click Create Application. Set Device Type to Server-side (SPI).

You can create only one Server-side (SPI) application for each project. The server-side interface uses the AppKey and AppSecret of this application to sign data and verify signatures.

2. Create an SPI interface

Log on to the Cloud Gaming PaaS console with your Alibaba Cloud account and go to the Operations Hub. In the project list, select the project that you want to integrate. Click SPI Configuration Management, and then click Create SPI Interface.

Enter a template name.
Select a template type.
HTTPS service access URL
Enter a unique version number. If multiple online versions of an SPI interface exist for the same template type, the cloud gaming platform calls the interface with the highest version number.
Enter extension parameters. This step is optional and is required only by some interfaces.
Enter a method name. This step is optional and is required only by some interfaces.

3. Debug and publish the interface

After you complete development and debugging, go to the SPI Configuration Management page. Select the interface that you want to publish and click Publish. On the debug and publish page, enter the debug parameters. After debugging is successful, click Publish. After the interface is published, the cloud gaming platform calls this SPI service for the relevant business flows. Ensure that the interface is ready before you publish it.

4. Ensure stability

Provide an estimate of the interface traffic. The technical staff of the Cloud Gaming PaaS platform sets stability metrics, such as traffic throttling and circuit breaking, at the project level.
If your interface does not meet the stability requirements, the Cloud Gaming PaaS platform takes measures such as traffic throttling and service degradation to ensure the stability of the platform.

Interface standards

Interface protocol: HTTPS
Host: Defined by your business.
Interface name: Defined by your business.

1. Common request parameters

Parameter	Type	Description	Value description
action	String	Template type	Required. The value varies based on the interface.
version	Integer	Interface version	Required. Default value: 1. The platform requests the online interface with the highest version number.
timestamp	String	The timestamp of the call. The value must follow the ISO 8601 standard and be in UTC (+00:00).	Required. Example: 2016-02-23T12:46:24Z.
accessKey	String	Server-side AppKey	Required. Issued by the Cloud Gaming PaaS platform.
signatureMethod	String	Signature method	Required. HMAC-SHA1.
signatureVersion	String	Method version	Required. 1.0.
signatureNonce	String	Random data	Required. A random number generated on the client. The length must be between 8 and 32 characters. You can decide how to generate it.
format	String	Return value type	Required. JSON.
signature	String	Signature	Required. For information about how to generate a signature, see the following sections.

2. Common response parameters

Parameter	Type	Description	Example
code	Int	Return code	0: success -1: failed
message	String	Return description	OK: success
data		Detailed data
data.signature	String	Signature	Required. Sign the data in the data field using the AccessSecret issued by the Cloud Gaming PaaS platform.
data.signatureNonce	String	Random data for signature	Required. A random number. The length must be between 8 and 32 characters. You can decide how to generate it.
data.timestamp	String	The timestamp of the call. The value must follow the ISO 8601 standard and be in UTC (+00:00).	Required. 2016-02-23T12:46:24Z

Return code

Code	Description
0	Success
-1	Failure

Return description (message)

Code	Description
OK	Success
Other custom text	Failure

Interface templates

1. Session authentication

Template description

The session authentication interface uses a unified standard to identify your session and account system. The following figure shows the session authentication flow.

Request parameters (including common parameters)

Parameter	Type	Description	Value description
action	String	Template type	Required. AUTH_CHECK.
accountToken	String	The userToken parameter from the client software development kit (SDK).	Required. The token data of your business. You must parse it yourself.
accountId	String	The userId parameter from the client SDK.	Optional. The AccountId data of your business. You must parse it yourself.
frontAppKey	String	Client AppKey	Required. The AppKey used on the client.

Response (including common parameters)

Parameter	Type	Description	Example
code	Integer	Return code	Common parameter
message	String	Return description	Common parameter
data		Detailed data	Common parameter
data.sessionState	Integer	Session state. 0: Unidentified or expired. 1: Identified.	Required
data.accountId	String	Unique user ID	Required when sessionState is 1. Optional when sessionState is 0.
data.ttl	Integer	The cache duration for the identity information, in seconds.	Optional. Default value: 60 seconds. A value of 0 is not allowed in this scenario. You must specify a cache duration.
data.accountDomain	Integer	Account type	Optional. If your business has multiple account types, return the type in this field. Default value: 0.

Degradation policy

The platform trusts the userId that is actively passed by the client SDK.

2. Game access control

Template description

The game access control interface template uses a unified standard to request final authorization from your service when a game starts. The following figure shows the game access control flow.

Request parameters (including common parameters)

Parameter	Type	Description	Value description
action	String	Template type	Required. GAME_ACCESS.
gameId	String	Game ID on the Cloud Gaming PaaS platform.	Required
accountToken	String	The userToken parameter from the client SDK.	Required. The token data of your business. You must parse it yourself.
frontAppKey	String	Client AppKey	Required. The AppKey used on the client.
ip	String	Client request IP address	Optional
userLevel	Integer	User scheduling level	Optional. The user scheduling level specified when the game is started on the client.

Response (including common parameters)

Parameter	Type	Description	Value description
code	Int	Return code	Common parameter
message	String	Return description	Common parameter
data		Detailed data	Common parameter
data.accessState	Integer	Access state	Required. 0: Start is not allowed. 1: Start is allowed.
data.ttl	Integer	The cache duration for the access state, in seconds.	Optional. Default value: 60 seconds. If the value is 0, caching is not required. If the value is less than 0 or empty, the default value is used.
data.message	String	Reason description	Optional
data.trialTag	Integer	Trial tag. 1: Skip trial. 0: Enter trial. null: Enter trial.	Optional. This parameter takes effect only when a trial policy is configured for the current project.

Degradation policy

The platform skips the game access authorization, which allows all games to be started. If a trial policy is configured for the current project, all game sessions are considered trials.

3. Container lifecycle notifications

Template description

The container lifecycle notification interface template uses a unified standard to send status feedback to your service at different stages of the game container lifecycle. The container lifecycle represents the complete flow of a game session.

Request parameters (including common parameters)

Parameter	Type	Description	Value description
action	String	Template type	Required. CONTAINER_STATE_MESSAGE.
messageType	String	Message type	Required. CONTAINER_START: The game container starts (the game server process starts). CONTAINER_START_FAILED: The game container fails to start. CONTAINER_QUIT: The game container exits and the game server process starts. PLAYER_START: The game starts (a player enters the game).
projectId	String	Project ID	Required. The ID of the project where the game is running.
accountId	String	Account ID	Required. The account ID of the player who started the game.
accountDomain	String	Account domain	Optional. The account domain of the player who started the game. Default value: 0.
gameSessionId	String	Game session ID	Required. The unique ID of a game scheduling.
gameId	String	Game ID	Required. The ID of the running game.
time	Long	Time of the current behavior	Required. UNIX timestamp in milliseconds.
startTime	Long	Container start time	Required. UNIX timestamp in milliseconds.
linkedAccountIdList	String	A collection of account IDs for players currently in the game.	Optional. Multiple IDs are separated by commas.
playerDetailList	String	A collection of information about all players who have joined the game.	Optional. JSON format: accountId: User ID. isInitiator: Indicates whether the user is the game initiator. startTime: The UNIX timestamp when the player joined the game, in milliseconds. Example: [{"isInitiator":true,"startTime":1606113124250,"accountId":"test1"},{"isInitiator":false,"startTime":1606113124250,"accountId":"test2"}, ....]
tags	String	Custom tags passed when the game starts.	Optional. If there are multiple tags, they are separated by commas.

Response (including common parameters)

Parameter	Type	Description	Value description
code	Int	Return code	Common parameter
message	String	Return description	Common parameter
data		Detailed data	Common parameter
data.consumeState	Integer	Consumption state	Required. 0: Consumption failed. 1: Consumption successful.
data.message	String	Reason description	Optional

Degradation policy

The platform discards the message. The degradation process is triggered if your service fails to respond, the response failure rate exceeds a certain threshold, or the queries per second (QPS) exceeds the maximum threshold.

Extension parameters

This interface requires you to use extension parameters to specify the message types to which you want to subscribe. You can specify the message types as needed. All types are optional. Subscribed messages must be consumed successfully. If consumption fails, the cloud gaming platform retries the delivery up to 16 times. After 16 failed retries, the message is discarded. The following example shows the extension parameters:

{"subscribeContainerMessage":["CONTAINER_START","CONTAINER_START_FAILED","CONTAINER_QUIT","PLAYER_START"]}

Interface notes

For better link performance, subscribe to only the message types that you need.
Calls to the container lifecycle notification interface are not guaranteed to be in real-time. You can use the `time` and `startTime` fields in the message body as the reference time.
If you return a consumption failure, the message is redelivered. To prevent redelivery, you must return a consumption success.
The platform makes a best effort to deliver the container exit message "CONTAINER_QUIT". If a request fails, the platform retries the request.

4. Batch stop game callback notification

Template description

When you call the batch stop game API that is provided by the cloud gaming platform, this callback notifies your service of the progress. This SPI interface must be used with the batch stop game API.

Request parameters (including common parameters)

Parameter	Type	Description	Value description
action	String	Template type	Required. BATCH_STOP_GAME_SESSIONS_CALLBACK.
projectId	String	Project ID	Required. The ID of the project that initiated the call.
gameId	String	Game ID	Required. The ID of the game for which the call was initiated.
queuersCount	Long	Remaining number of players in the queue	Required. The number of players remaining in the queue for the game being stopped.
playersCount	Long	Remaining number of players in the game	Required. The number of players remaining in the game being stopped.
trackInfo	String	Additional link information	Optional
timeStamp	Long	Current time	Required. UNIX timestamp in milliseconds.

Response (including common parameters)

Parameter	Type	Description	Value description
code	Int	Return code	Common parameter
message	String	Return description	Common parameter
data		Detailed data	Common parameter
data.consumeState	Integer	Consumption state	Required. 0: Consumption failed. 1: Consumption successful.
data.message	String	Reason description	Optional

Degradation policy

The platform discards the message. The degradation process is triggered if your service fails to respond, the response failure rate exceeds a certain threshold, or the QPS exceeds the maximum threshold.

5. Game scheduling event callback notification

Template description

During the game queuing and scheduling process, this callback notifies your service of the result.

Request parameters (including common parameters)

Parameter	Type	Description	Value description
action	String	Template type	Required. GAME_DISPATCH_EVENT_CALLBACK.
projectId	String	Project ID	Required. The ID of the project where the game is running.
gameId	String	Game ID	Required. The ID of the running game.
gameSessionId	String	Game session ID	Optional. The unique ID of a game scheduling.
accountId	String	Account ID	Required. The account ID of the player who started the game.
accountDomain	String	Account domain	Optional. The account domain of the player who started the game. Default value: 0.
eventCode	String	Event code	Required. 10000: Scheduling successful. 20000: Abnormal exit.
eventMessage	String	Event description	Optional. Example: Scheduling successful, container allocated.
timeStamp	Long	Time of the current behavior	Required. UNIX timestamp in milliseconds.
dispatchInfo	String	Detailed scheduling information	Optional

Description of the dispatchInfo field:

Parameter	Type	Description	Value description
dispatched	Boolean	Indicates whether a container has been allocated.	Required
failCode	String	Error code	Optional. WAITING_TIMEOUT: The player timed out while in the queue. CONNECT_TIMEOUT: A game container was allocated, but the player connection timed out.
queued	Boolean	Indicates whether the player has joined the queue.	Required

Return (common parameters required)

Parameter	Type	Description	Value description
code	Int	Return code	Common parameter
message	String	Return description	Common parameter
data		Detailed data	Common parameter
data.consumeState	Integer	Consumption state	Required. 0: Consumption failed. 1: Consumption successful.
data.message	String	Reason description	Optional

Degradation policy

The platform discards the message. The degradation process is triggered if your service fails to respond, the response failure rate exceeds a certain threshold, or the QPS exceeds the maximum threshold.

Signature verification and signing method

Requests that are initiated by the Cloud Gaming PaaS platform are signed. You must also sign the value in the `data` field of your response parameters. For more information about the signing method, see https://help.aliyun.com/document_detail/25492.html?spm=5176.product25365.6.804.NbGBng.