文档中心

通过游戏签名加载游戏 ​

本文档介绍如何通过游戏签名启动游戏，并将游戏视图加载到应用页面中。

概述 ​

通过 SUDOP.startGameBySignature 接口，可以根据服务端下发的游戏签名直接启动游戏。

该接口适用于生产环境，是推荐的游戏启动方式。通过游戏签名启动，SDK 可以自动完成游戏标识解析、资源比对、版本校验、资源准备、运行时初始化以及游戏实例创建等流程。

该方式具有以下特点：

  • 启动参数更安全
  • 可由服务端统一控制游戏版本和权限
  • SDK 自动处理资源准备流程
  • 适合正式业务接入场景

开发者只需要在成功回调中获取 gameView，并将其添加到页面容器中即可。

使用前提 ​

在通过游戏签名启动游戏前，必须先完成以下步骤：

  1. 初始化 SDK
  2. 完成用户鉴权
  3. 从服务端获取合法的游戏签名
  4. 调用 startGameBySignature

完整示例 ​

java
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) {
                        // 使用gameSignature时，不会回调此方法
                    }

                    @Override
                    public void onCreated(SUDRTGameHandle gameHandle) {
                        // SUDRTGameHandle创建完成时的回调，一般可以在此处设置自定义的启动参数或注入和游戏交互java对象
                    }

                    @Override
                    public void onSuccess(String gameId, SUDRTGameHandle gameHandle) {
                        // 收到此回调时，表示游戏加载成功，app将游戏View add到自身所需要展示的页面当中即可
                        View gameView = gameHandle.getGameView();
                    }

                    @Override
                    public void onFailure(int retCode, String retMsg) {
                        // 加载游戏失败，通常请检查参数是否正确，以及网络原因
                    }
                });

                // 在业务需要销毁游戏时，调用此方法销毁
//              gameTask.destroy();
            }

            @Override
            public void onFailure(int retCode, String retMsg) {
                // auth接口失败，通常请检查user signature是否正确以及网络原因
            }
        });
    }

    @Override
    public void onFailure(int retCode, String retMsg) {
        // 初始化SDK失败，在appId和appKey正确的情况下，通常是网络原因引起
    }
});

核心接口 ​

startGameBySignature ​

java
public static SUDOPGameTask startGameBySignature(
    String signature,
    SUDOPStartGameListener listener
);

该接口用于根据服务端生成的游戏签名启动游戏，并返回一个 SUDOPGameTask 任务句柄，用于后续管理游戏生命周期。

参数说明 ​

参数类型描述
signatureString必填。通过服务端接口获取的加密游戏签名字符串。
listenerSUDOPStartGameListener必填。游戏启动过程监听器，用于接收启动过程中的状态回调。

启动回调说明 ​

SUDOPStartGameListener ​

void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) ​

游戏包解密回调。

在通过游戏签名启动游戏的场景下，通常不会回调该方法。因为游戏签名方式由 SDK 自动处理资源准备流程，不要求业务侧介入游戏包解密。

参数说明：

参数类型描述
handleGamePkgDecryptHandle解密结果回调句柄。
filePathString当前待处理文件路径。

void onCreated(SUDRTGameHandle gameHandle) ​

游戏实例创建完成回调。

当收到该回调时，说明 SUDRTGameHandle 已创建完成。通常可以在这里：

  • 设置自定义启动参数
  • 注入和游戏交互的 Java 对象
  • 完成启动前的业务准备

参数说明：

参数类型描述
gameHandleSUDRTGameHandle游戏实例句柄。

void onSuccess(String gameId, SUDRTGameHandle gameHandle) ​

游戏启动成功回调。

当收到该回调时，表示游戏已经成功加载，开发者可以通过 gameHandle.getGameView() 获取游戏视图，并将其添加到自身页面容器中进行展示。

参数说明：

参数类型描述
gameIdString当前启动成功的游戏 ID。
gameHandleSUDRTGameHandle游戏实例句柄。

示例：

java
View gameView = gameHandle.getGameView();
// container.addView(gameView);

void onFailure(int retCode, String retMsg) ​

游戏启动失败回调。

通常可以根据错误码和错误信息判断失败原因。

参数说明：

参数类型描述
retCodeint错误码。
retMsgString错误描述。

常见失败原因包括：

  • 游戏签名无效
  • 游戏签名已过期
  • 游戏签名与当前用户或业务上下文不匹配
  • 网络异常
  • 资源准备失败
  • 运行时初始化失败

解密句柄说明 ​

GamePkgDecryptHandle ​

void success(String decryptedFilePath, boolean isDeleteFile) ​

通知 SDK 解密成功。

参数说明：

参数类型描述
decryptedFilePathString解密后的文件路径。
isDeleteFileboolean游戏加载完成后是否删除解密后的文件。

void fail(int retCode, String retMsg) ​

通知 SDK 解密失败。

参数说明：

参数类型描述
retCodeint错误码。
retMsgString错误描述。

运行行为 ​

调用 startGameBySignature 后，SDK 会按以下流程执行：

  1. 校验游戏签名的合法性
  2. 解析签名中对应的游戏标识和版本信息
  3. 检查本地资源是否可复用
  4. 如本地资源不可用，则自动准备所需资源
  5. 初始化运行时环境
  6. 创建游戏实例
  7. 回调返回游戏视图

与通过 gameId、本地文件路径、目录路径或 URL 启动游戏相比，签名方式更强调安全性和服务端控制能力，更适合正式线上场景。

页面集成方式 ​

建议在页面中提前准备好一个用于承载游戏视图的容器，例如 FrameLayout。

示例：

java
FrameLayout container;

在 onSuccess 回调中获取 gameView 后，将其添加到容器中：

java
View gameView = gameHandle.getGameView();
container.addView(gameView);

生命周期管理 ​

startGameBySignature 会返回一个 SUDOPGameTask 对象，业务侧需要持有该对象，并在不再需要游戏时主动销毁。

示例：

java
SUDOPGameTask gameTask = SUDOP.startGameBySignature(signature, listener);

在页面销毁或业务结束时：

java
gameTask.destroy();

注意事项 ​

1. 游戏签名必须由服务端生成 ​

signature 应由服务端安全生成并下发，客户端不应自行拼接、伪造或长期缓存无效签名。

2. 注意签名有效期 ​

游戏签名通常具有时效性。如果用户停留时间过长导致签名过期，可能会导致启动失败，此时需要重新向服务端获取新的签名。

3. 推荐用于正式生产环境 ​

相较于直接通过 gameId、URL、本地包路径或目录路径启动，签名方式更适合生产环境，能够更好地保证启动合法性和资源控制能力。

4. onGamePkgDecrypt 通常不会触发 ​

在签名启动模式下，资源准备流程由 SDK 内部处理，通常不会回调 onGamePkgDecrypt。

5. 同一时间建议只运行一个游戏实例 ​

为了避免资源竞争和页面管理复杂度增加，建议同一时间仅维护一个活跃的游戏实例。

6. 回调可直接操作 UI ​

启动相关回调在主线程执行，开发者可以直接在 onSuccess 中完成 addView 等 UI 操作。

总结 ​

通过游戏签名加载游戏的核心流程如下：

  1. 调用 SUDOP.initSDK 初始化 SDK
  2. 调用 SUDOP.auth 完成鉴权
  3. 从服务端获取合法的游戏签名
  4. 调用 SUDOP.startGameBySignature
  5. 在 onSuccess 中获取 gameView
  6. 将 gameView 添加到页面容器中
  7. 在业务结束时调用 gameTask.destroy() 释放资源