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;参数说明
| 参数名 | 类型 | 必传 | 描述 |
|---|---|---|---|
| gameID | NSString * | 是 | 游戏的唯一标识符。 |
| language | NSString * | 否 | 新重载中的可选语言标识,例如 zh-CN。用于签名请求及加载页名称和封面,详见下方语言规则。 |
| didGameViewCreated | SUDOPDidGameViewCreatedBlock | 否 | 游戏视图创建完成后的回调。开发者通常在此回调中获取游戏 View,并将其添加到自己的页面视图层级中。 |
| didGameHandleCreated | SUDOPDidGameHandleCreatedBlock | 否 | 游戏句柄创建完成后的回调。开发者通常在此回调中注册业务代理,或保存游戏句柄用于后续通信。 |
| progress | SUDOPProgressBlock | 否 | 游戏启动过程中的进度回调,可用于展示加载进度。 |
| completion | SUDOPGameOperationCompletionBlock | 否 | 游戏启动流程结束后的回调。成功时表示游戏已完成启动;失败时返回错误信息。 |
返回值说明
| 返回值 | 类型 | 描述 |
|---|---|---|
| gameTask | id<SUDOPGameTask> | 游戏启动任务对象,可用于跟踪当前启动流程。开发者可根据 SDK 提供的能力对任务进行管理。 |
运行行为
- 创建启动任务:SDK 会根据传入的
gameID创建一个游戏启动任务,并立即返回id<SUDOPGameTask>对象。 - 资源准备:SDK 会检查游戏资源是否已存在。如果游戏资源未准备完成,SDK 会自动执行必要的下载、加载或初始化流程。
- 进度回调:在游戏启动过程中,SDK 会通过
progress回调返回当前加载进度,开发者可用于更新加载 UI。 - 游戏视图创建:当游戏 View 创建完成后,SDK 会触发
didGameViewCreated回调。开发者应在此处将游戏视图添加到页面中。 - 游戏句柄创建:当游戏 Handle 创建完成后,SDK 会触发
didGameHandleCreated回调。该句柄通常用于后续与游戏通信、注册代理或发送状态。 - 启动完成:游戏启动成功或失败后,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 要求停止游戏或释放相关资源,避免渲染、音频或内存资源残留。
