Skip to content

startGame:didGameViewCreated:didGameHandleCreated:progress:completion: ​

启动游戏(通过 Game ID) ​

该方法通过游戏唯一标识符(Game ID)启动游戏。SDK 会根据传入的 gameID 创建游戏任务,完成游戏资源准备、游戏视图创建、游戏句柄创建以及最终启动流程。

该接口是启动游戏的核心方法之一。开发者可以通过 didGameViewCreated 获取游戏视图并添加到业务页面中,通过 didGameHandleCreated 获取游戏句柄并注册业务代理,通过 progress 监听启动进度,并在 completion 中处理最终启动结果。


方法声明 ​

objectivec
+ (id<SUDOPGameTask>)startGame:(NSString *)gameID
            didGameViewCreated:(nullable SUDOPDidGameViewCreatedBlock)didGameViewCreated
          didGameHandleCreated:(nullable SUDOPDidGameHandleCreatedBlock)didGameHandleCreated
                      progress:(nullable SUDOPProgressBlock)progress
                    completion:(nullable SUDOPGameOperationCompletionBlock)completion;

+ (id<SUDOPGameTask>)startGame:(NSString *)gameID
                      language:(nullable NSString *)language
            didGameViewCreated:(nullable SUDOPDidGameViewCreatedBlock)didGameViewCreated
          didGameHandleCreated:(nullable SUDOPDidGameHandleCreatedBlock)didGameHandleCreated
                      progress:(nullable SUDOPProgressBlock)progress
                    completion:(nullable SUDOPGameOperationCompletionBlock)completion;

参数说明 ​

参数名类型必传描述
gameIDNSString *是游戏的唯一标识符。
languageNSString *否新重载中的可选语言标识,例如 zh-CN。用于签名请求及加载页名称和封面,详见下方语言规则。
didGameViewCreatedSUDOPDidGameViewCreatedBlock否游戏视图创建完成后的回调。开发者通常在此回调中获取游戏 View,并将其添加到自己的页面视图层级中。
didGameHandleCreatedSUDOPDidGameHandleCreatedBlock否游戏句柄创建完成后的回调。开发者通常在此回调中注册业务代理,或保存游戏句柄用于后续通信。
progressSUDOPProgressBlock否游戏启动过程中的进度回调,可用于展示加载进度。
completionSUDOPGameOperationCompletionBlock否游戏启动流程结束后的回调。成功时表示游戏已完成启动;失败时返回错误信息。

返回值说明 ​

返回值类型描述
gameTaskid<SUDOPGameTask>游戏启动任务对象,可用于跟踪当前启动流程。开发者可根据 SDK 提供的能力对任务进行管理。

运行行为 ​

  1. 创建启动任务:SDK 会根据传入的 gameID 创建一个游戏启动任务,并立即返回 id<SUDOPGameTask> 对象。
  2. 资源准备:SDK 会检查游戏资源是否已存在。如果游戏资源未准备完成,SDK 会自动执行必要的下载、加载或初始化流程。
  3. 进度回调:在游戏启动过程中,SDK 会通过 progress 回调返回当前加载进度,开发者可用于更新加载 UI。
  4. 游戏视图创建:当游戏 View 创建完成后,SDK 会触发 didGameViewCreated 回调。开发者应在此处将游戏视图添加到页面中。
  5. 游戏句柄创建:当游戏 Handle 创建完成后,SDK 会触发 didGameHandleCreated 回调。该句柄通常用于后续与游戏通信、注册代理或发送状态。
  6. 启动完成:游戏启动成功或失败后,SDK 会触发 completion 回调。成功后游戏进入可交互状态;失败时可根据错误信息进行处理。

语言与加载页展示 ​

  • 原方法继续可用,等价于传入 language:nil。
  • 传入非空语言时,SDK 将其透传给 /v1/game/signature,并按该语言从 game_name 选择加载页名称、从 icon 选择封面 URL。
  • 传入 nil 或空字符串时,签名请求使用服务端默认值;加载页名称和封面使用系统首选语言(NSLocale.preferredLanguages.firstObject)选择。
  • 选择沿用现有语言工具:精确匹配、父级语言(例如 zh-Hans-CN → zh-Hans)、语言前缀、同前缀的其他条目、default,最后取任意非空字符串。没有可用的多语言图标时,封面回退到 game_icon。
  • 相同游戏 ID 会复用已有任务;后续调用不会覆盖已启动任务的语言。

代码示例 ​

objectivec
NSString *gameID = @"game_999";

id<SUDOPGameTask> gameTask = [SUDOP startGame:gameID
                                     language:@"zh-CN"
                           didGameViewCreated:^(UIView * _Nullable gameView) {
    if (!gameView) {
        return;
    }

    // 将游戏视图添加到当前页面
    gameView.frame = self.view.bounds;
    [self.view addSubview:gameView];

    NSLog(@"游戏视图已创建");
} didGameHandleCreated:^(id _Nullable gameHandle) {
    if (!gameHandle) {
        return;
    }

    // 保存游戏句柄,或注册业务代理
    // self.gameHandle = gameHandle;
    // [SUDOP registerWrappedClientWithGameHandle:gameHandle clientDelegate:self];

    NSLog(@"游戏句柄已创建");
} progress:^(CGFloat progress) {
    NSLog(@"游戏启动进度: %.2f", progress);

    // 可在此更新加载进度 UI
    // self.progressView.progress = progress;
} completion:^(id<SUDOPGameHandleProvider> _Nullable gameHandleProvider, NSError * _Nullable error) {
    if (error) {
        NSLog(@"游戏启动失败: %@", error);
        return;
    }

    NSLog(@"游戏启动成功");
}];

self.gameTask = gameTask;

说明:示例中的 Block 参数类型请以 SDK 中对应 typedef 的实际定义为准。


注意事项 ​

  • gameID 必传:gameID 是启动游戏的核心参数,不能为空或无效。
  • 建议在主线程调用:该接口涉及游戏视图创建和 UI 操作,建议在主线程调用。
  • 及时添加游戏视图:收到 didGameViewCreated 回调后,应将游戏 View 添加到业务页面中,否则用户可能无法看到游戏画面。
  • 及时注册业务代理:如果业务需要接收游戏事件或向游戏发送状态,建议在 didGameHandleCreated 回调中完成代理注册。
  • 关注启动进度:progress 可用于展示加载进度,提升用户等待过程中的体验。
  • 处理启动失败:如果 completion 返回错误,请检查网络状态、游戏资源状态、gameID 是否有效,以及 SDK 是否已完成初始化和认证。
  • 页面退出需清理资源:当用户离开游戏页面时,应按照 SDK 要求停止游戏或释放相关资源,避免渲染、音频或内存资源残留。