文档中心

通过游戏包URL加载游戏 ​

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

概述 ​

通过 SUDOP.startGameByUrl 接口，可以根据远程游戏包地址直接启动游戏。

该接口适用于以下场景：

  • 业务侧通过自定义 CDN 分发游戏包
  • 需要动态加载指定版本的游戏资源
  • 测试环境需要通过固定 URL 快速验证游戏包
  • 不依赖平台侧的游戏包版本管理，由业务侧自行控制资源地址

调用后，SDK 会自动完成以下流程：

  • 下载远程游戏包
  • 校验游戏包完整性
  • 解压游戏资源
  • 初始化运行时环境
  • 创建游戏实例
  • 回调返回游戏视图

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

使用前提 ​

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

  1. 初始化 SDK
  2. 完成用户鉴权
  3. 准备好远程游戏包 URL
  4. 构造 SUDOPGamePackageParams
  5. 调用 startGameByUrl

完整示例 ​

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 url = "https://cdn.example.com/games/v2/test_game.zip";

                SUDOPGamePackageParams params = new SUDOPGamePackageParams();
                params.version = "gamePkgVersion";
                params.fid = "2e7ca170f33629c7baf4dc430c541c43";
                params.fidType = FIDType.MD5;
                params.appGameID = "appGameID";
                params.appCPID = "Game Developer id";
                params.appGroupID = "Game developer group id";

                SUDOPGameTask gameTask = SUDOP.startGameByUrl(url, params, new SUDOPStartGameListener() {
                    @Override
                    public void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) {
                        // 如果游戏包有加密，请解密之后调用handle.success(String decryptedFilePath, boolean isDeleteFile);来返回新的文件路径
                    }

                    @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正确的情况下，通常是网络原因引起
    }
});

核心接口 ​

startGameByUrl ​

java
public static SUDOPGameTask startGameByUrl(
    String url,
    SUDOPGamePackageParams params,
    SUDOPStartGameListener listener
);

该接口用于根据远程游戏包 URL 启动游戏，并返回一个 SUDOPGameTask 任务句柄，用于后续管理游戏生命周期。

参数说明 ​

参数类型描述
urlString必填。远程游戏资源压缩包的完整下载地址，通常为 .zip 文件。
paramsSUDOPGamePackageParams必填。游戏包相关参数信息，用于标识版本、校验信息及业务侧附加信息。
listenerSUDOPStartGameListener必填。游戏启动过程监听器，用于接收启动过程中的状态回调。

SUDOPGamePackageParams 说明 ​

SUDOPGamePackageParams 用于描述当前远程游戏包的元数据信息。

示例中的参数含义如下：

字段类型描述
versionString游戏包版本号。
fidString游戏包文件标识，一般用于文件校验。
fidTypeFIDType文件标识类型，例如 MD5。
appGameIDString业务侧自定义游戏 ID
appCPIDString游戏开发者 ID。
appGroupIDString游戏开发者分组 ID。

启动回调说明 ​

SUDOPStartGameListener ​

void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) ​

游戏包解密回调。

当下载完成后的游戏包存在加密逻辑时，可以在该回调中完成解密，并通过 handle 返回解密结果。

参数说明：

参数类型描述
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错误描述。

常见失败原因包括：

  • URL 不可访问
  • 网络异常
  • 下载中断
  • 游戏包校验失败
  • 游戏包格式不合法
  • 参数不正确
  • 运行时初始化失败

解密句柄说明 ​

GamePkgDecryptHandle ​

void success(String decryptedFilePath, boolean isDeleteFile) ​

通知 SDK 解密成功。

参数说明：

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

void fail(int retCode, String retMsg) ​

通知 SDK 解密失败。

参数说明：

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

运行行为 ​

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

  1. 检查目标 URL 对应的本地缓存
  2. 如果本地无可用缓存，则下载远程游戏包
  3. 如有需要，进入解密流程
  4. 校验游戏包完整性
  5. 解压游戏资源到工作目录
  6. 初始化运行时环境
  7. 创建游戏实例
  8. 回调返回游戏视图

与通过 gameId 启动游戏相比，该接口不依赖平台侧的游戏包定位逻辑，而是直接使用业务侧提供的远程包地址。

页面集成方式 ​

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

示例：

java
FrameLayout container;

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

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

生命周期管理 ​

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

示例：

java
SUDOPGameTask gameTask = SUDOP.startGameByUrl(url, params, listener);

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

java
gameTask.destroy();

注意事项 ​

1. URL 必须可访问 ​

传入的 url 必须是一个完整且可正常访问的远程地址。若使用带签名或鉴权参数的下载链接，请确保链接在调用时仍然有效。

2. 建议提供正确的文件标识信息 ​

建议在 params 中提供准确的 fid 和 fidType，便于 SDK 对下载文件进行校验，提高资源可靠性。

3. 注意网络环境 ​

该接口会触发远程下载流程。如果游戏包较大，建议业务侧根据当前网络环境做好提示或控制策略。

4. 游戏包格式必须合法 ​

远程下载得到的游戏包必须是 SDK 支持的标准包格式，否则会导致解压或启动失败。

5. 临时文件由 SDK 管理，业务逻辑文件由业务侧关注 ​

下载、校验、解压过程中产生的运行期资源由 SDK 管理，但如果业务侧在解密流程中生成了额外文件，则需要根据自身逻辑决定是否删除。

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

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

7. 回调可直接操作 UI ​

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

总结 ​

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

  1. 调用 SUDOP.initSDK 初始化 SDK
  2. 调用 SUDOP.auth 完成鉴权
  3. 准备远程游戏包 URL 和 SUDOPGamePackageParams
  4. 调用 SUDOP.startGameByUrl
  5. 在 onSuccess 中获取 gameView
  6. 将 gameView 添加到页面容器中
  7. 在业务结束时调用 gameTask.destroy() 释放资源