Load Game by Signature
This document describes how to launch a game via a game signature and load the game view into an application page.
Overview
Through the SUDOP.startGameBySignature interface, you can directly launch a game based on the game signature delivered by the server.
This interface is suitable for production environments and is the recommended way to launch a game. When launching via a game signature, the SDK can automatically complete the game identifier resolution, resource comparison, version validation, resource preparation, runtime initialization, and game instance creation.
This method has the following characteristics:
- Safer startup parameters
- The server can control the game version and permissions in a unified way
- The SDK automatically handles the resource preparation process
- Suitable for formal business integration scenarios
Developers only need to obtain the gameView in the success callback and add it to the page container.
Prerequisites
Before launching a game via a game signature, you must first complete the following steps:
- Initialize the SDK
- Complete user authentication
- Obtain a valid game signature from the server
- Call
startGameBySignature
Full Example
SUDOP.initSDK(context, "Your appId", "Your appKey", new SUDOPInitSDKListener() {
@Override
public void onSuccess() {
SUDOP.auth("Your user signature", new SUDOPAuthListener() {
@Override
public void onSuccess() {
String gameSignature = "SERVER_SIDE_ENCRYPTED_SIGNATURE";
SUDOPGameTask gameTask = SUDOP.startGameBySignature(gameSignature, new SUDOPStartGameListener() {
@Override
public void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) {
// When using gameSignature, this method will not be called back
}
@Override
public void onCreated(SUDRTGameHandle gameHandle) {
// Callback when SUDRTGameHandle is created; you can typically set custom startup parameters or inject Java objects for game interaction here
}
@Override
public void onSuccess(String gameId, SUDRTGameHandle gameHandle) {
// When this callback is received, the game has loaded successfully; the app just needs to add the game View to the page it wants to display
View gameView = gameHandle.getGameView();
}
@Override
public void onFailure(int retCode, String retMsg) {
// Failed to load the game; usually check whether the parameters are correct and check network issues
}
});
// When the business needs to destroy the game, call this method to destroy it
// gameTask.destroy();
}
@Override
public void onFailure(int retCode, String retMsg) {
// auth interface failed; usually check whether the user signature is correct and check network issues
}
});
}
@Override
public void onFailure(int retCode, String retMsg) {
// SDK initialization failed; when appId and appKey are correct, this is usually caused by network issues
}
});Core Interface
startGameBySignature
public static SUDOPGameTask startGameBySignature(
String signature,
SUDOPStartGameListener listener
);
public static SUDOPGameTask startGameBySignature(
String signature,
String language,
SUDOPStartGameListener listener
);This interface launches a game based on the game signature generated by the server and returns a SUDOPGameTask handle used for subsequent game lifecycle management.
To select the SDK loading view game name and icon, use the overload with language and pass the current Activity's complete BCP 47 language tag. The two-argument method remains available; a null or empty language uses the loading view's current locale. See startGameBySignature for parameter details and an example.
Parameters
| Parameter | Type | Description |
|---|---|---|
signature | String | Required. The encrypted game signature string obtained through a server interface. |
language | String | Optional in the three-argument overload. Loading view language, such as en, zh-CN, or zh-Hant-TW. |
listener | SUDOPStartGameListener | Required. The game startup process listener, used to receive state callbacks during startup. |
Startup Callbacks
SUDOPStartGameListener
void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath)
Game package decryption callback.
In the scenario of launching a game via a game signature, this method is usually not called back. This is because in the game signature method the SDK automatically handles the resource preparation process and does not require the business side to intervene in game package decryption.
Parameters:
| Parameter | Type | Description |
|---|---|---|
handle | GamePkgDecryptHandle | Decryption result callback handle. |
filePath | String | Path of the file currently to be processed. |
void onCreated(SUDRTGameHandle gameHandle)
Game instance created callback.
When this callback is received, the SUDRTGameHandle has been created. Here you can typically:
- Set custom startup parameters
- Inject Java objects for game interaction
- Complete business preparation before startup
Parameters:
| Parameter | Type | Description |
|---|---|---|
gameHandle | SUDRTGameHandle | Game instance handle. |
void onSuccess(String gameId, SUDRTGameHandle gameHandle)
Game startup success callback.
When this callback is received, the game has been loaded successfully. Developers can obtain the game view via gameHandle.getGameView() and add it to their own page container for display.
Parameters:
| Parameter | Type | Description |
|---|---|---|
gameId | String | The ID of the game that started successfully. |
gameHandle | SUDRTGameHandle | Game instance handle. |
Example:
View gameView = gameHandle.getGameView();
// container.addView(gameView);void onFailure(int retCode, String retMsg)
Game startup failure callback.
You can usually determine the failure reason from the error code and error message.
Parameters:
| Parameter | Type | Description |
|---|---|---|
retCode | int | Error code. |
retMsg | String | Error description. |
Common failure reasons include:
- Invalid game signature
- Expired game signature
- Game signature does not match the current user or business context
- Network exception
- Resource preparation failure
- Runtime initialization failure
Decryption Handle
GamePkgDecryptHandle
void success(String decryptedFilePath, boolean isDeleteFile)
Notifies the SDK that decryption succeeded.
Parameters:
| Parameter | Type | Description |
|---|---|---|
decryptedFilePath | String | Path of the decrypted file. |
isDeleteFile | boolean | Whether to delete the decrypted file after the game finishes loading. |
void fail(int retCode, String retMsg)
Notifies the SDK that decryption failed.
Parameters:
| Parameter | Type | Description |
|---|---|---|
retCode | int | Error code. |
retMsg | String | Error description. |
Runtime Behavior
After startGameBySignature is called, the SDK executes the following process:
- Validate the legitimacy of the game signature
- Parse the game identifier and version information corresponding to the signature
- Check whether local resources can be reused
- If local resources are unavailable, automatically prepare the required resources
- Initialize the runtime environment
- Create the game instance
- Return the game view via callback
Compared with launching a game via gameId, a local file path, a directory path, or a URL, the signature method places more emphasis on security and server-side control, making it more suitable for formal online scenarios.
Page Integration
It is recommended to prepare a container for hosting the game view in the page in advance, e.g. FrameLayout.
Example:
FrameLayout container;After obtaining gameView in the onSuccess callback, add it to the container:
View gameView = gameHandle.getGameView();
container.addView(gameView);Lifecycle Management
startGameBySignature returns a SUDOPGameTask object. The business side needs to hold this object and actively destroy it when the game is no longer needed.
Example:
SUDOPGameTask gameTask = SUDOP.startGameBySignature(signature, listener);When the page is destroyed or the business ends:
gameTask.destroy();Notes
1. The Game Signature Must Be Generated by the Server
signature should be securely generated and delivered by the server. The client should not assemble, forge, or cache invalid signatures for a long time on its own.
2. Pay Attention to the Signature Validity Period
A game signature is usually time-limited. If the user stays too long and the signature expires, startup may fail; in that case, you need to obtain a new signature from the server again.
3. Recommended for Formal Production Environments
Compared with launching directly via gameId, a URL, a local package path, or a directory path, the signature method is more suitable for production environments and can better ensure startup legitimacy and resource control.
4. onGamePkgDecrypt Is Usually Not Triggered
In signature startup mode, the resource preparation process is handled internally by the SDK, so onGamePkgDecrypt is usually not called back.
5. Running a Single Game Instance at a Time Is Recommended
To avoid resource contention and increased page management complexity, it is recommended to maintain only one active game instance at a time.
6. Callbacks Can Directly Operate the UI
Startup-related callbacks are executed on the main thread, so developers can directly perform UI operations such as addView in onSuccess.
Summary
The core process of loading a game via a game signature is as follows:
- Call
SUDOP.initSDKto initialize the SDK - Call
SUDOP.authto complete authentication - Obtain a valid game signature from the server
- Call
SUDOP.startGameBySignature - Obtain the
gameViewinonSuccess - Add the
gameViewto the page container - Call
gameTask.destroy()to release resources when the business ends
