startGameWithSignature:language:didGameViewCreated:didGameHandleCreated:progress:completion:
启动游戏(通过游戏签名)
该方法使用游戏签名(gameSignature)启动游戏。游戏签名通常由服务端根据用户身份、游戏 ID、有效期等信息生成,用于授权本次游戏启动操作。
相比直接通过 gameID 启动,使用 gameSignature 启动可以提供更安全的鉴权能力,适合正式业务场景。开发者可以通过 didGameViewCreated 获取游戏视图,通过 didGameHandleCreated 获取游戏句柄,通过 progress 监听启动进度,并在 completion 中接收最终启动结果。
方法声明
objectivec
+ (nullable id<SUDOPGameTask>)startGameWithSignature:(NSString *)gameSignature
language:(nullable NSString *)language
didGameViewCreated:(nullable SUDOPDidGameViewCreatedBlock)didGameViewCreated
didGameHandleCreated:(nullable SUDOPDidGameHandleCreatedBlock)didGameHandleCreated
progress:(nullable SUDOPProgressBlock)progress
completion:(nullable SUDOPGameOperationCompletionBlock)completion;
+ (nullable id<SUDOPGameTask>)startGameWithSignature:(NSString *)gameSignature
didGameViewCreated:(nullable SUDOPDidGameViewCreatedBlock)didGameViewCreated
didGameHandleCreated:(nullable SUDOPDidGameHandleCreatedBlock)didGameHandleCreated
progress:(nullable SUDOPProgressBlock)progress
completion:(nullable SUDOPGameOperationCompletionBlock)completion;参数说明
| 参数名 | 类型 | 必传 | 描述 |
|---|---|---|---|
| gameSignature | NSString * | 是 | 游戏启动签名,用于授权本次游戏启动操作。 |
| language | NSString * | 否 | 加载页游戏名称和图标使用的语言,例如 zh-CN;nil 或空字符串使用系统语言。该参数不会修改签名内容。 |
| didGameViewCreated | SUDOPDidGameViewCreatedBlock | 否 | 游戏视图创建完成后的回调。开发者通常在此回调中获取游戏 View,并将其添加到业务页面中。 |
| didGameHandleCreated | SUDOPDidGameHandleCreatedBlock | 否 | 游戏句柄创建完成后的回调。开发者通常在此回调中保存游戏句柄、注册业务代理或进行后续通信准备。 |
| progress | SUDOPProgressBlock | 否 | 游戏启动过程中的进度回调,可用于展示加载进度。 |
| completion | SUDOPGameOperationCompletionBlock | 否 | 游戏启动流程完成后的回调。成功时表示游戏已完成启动;失败时返回错误信息。 |
返回值说明
| 返回值 | 类型 | 描述 |
|---|---|---|
| gameTask | id<SUDOPGameTask> | 游戏启动任务对象,可用于跟踪或管理当前启动流程;创建任务失败时可为 nil。 |
运行行为
签名校验
SDK 会使用传入的gameSignature进行启动授权校验。如果签名无效、过期或与当前用户不匹配,启动流程会失败并通过completion返回错误。创建启动任务
SDK 会创建游戏启动任务,并立即返回id<SUDOPGameTask>对象。资源准备
SDK 会根据签名信息解析对应游戏,并检查游戏资源状态。如果资源未准备完成,SDK 会自动执行必要的下载、校验、加载和初始化流程。进度回调
在资源准备或启动过程中,SDK 会通过progress回调返回当前进度,开发者可用于更新加载 UI。游戏视图创建
当游戏 View 创建完成后,SDK 会触发didGameViewCreated回调。开发者应在此处将游戏视图添加到自己的页面视图层级中。游戏句柄创建
当游戏 Handle 创建完成后,SDK 会触发didGameHandleCreated回调。该句柄通常用于与游戏通信、注册代理、发送状态或控制游戏生命周期。启动完成
游戏启动成功或失败后,SDK 会触发completion回调。成功后游戏进入可运行状态;失败时可根据错误信息进行处理。
代码示例
objectivec
NSString *gameSignature = @"your_game_signature";
id<SUDOPGameTask> gameTask = [SUDOP startGameWithSignature:gameSignature
language:@"zh-CN"
didGameViewCreated:^(UIView * _Nullable gameView) {
if (!gameView) {
return;
}
// 将游戏视图添加到当前页面
gameView.frame = self.containerView.bounds;
[self.containerView addSubview:gameView];
NSLog(@"游戏视图已创建");
} didGameHandleCreated:^(id<SUDRTGameHandle> gameHandle, SUDOPGameInfo *gameInfo) {
if (!gameHandle) {
return;
}
// 保存游戏句柄,便于后续与游戏通信或释放资源
// self.gameHandle = gameHandle;
// 如业务需要,可在此注册游戏代理
// [SUDOP registerWrappedClientWithGameHandle:gameHandle clientDelegate:self];
NSLog(@"游戏句柄已创建");
} progress:^(NSInteger progress) {
NSLog(@"游戏启动进度: %ld", (long)progress);
// 可在此更新加载进度 UI
// self.progressView.progress = progress;
} completion:^(id<SUDOPGameHandleProvider> _Nullable provider,
NSError * _Nullable error) {
if (error) {
NSLog(@"游戏启动失败: %@", error);
return;
}
NSLog(@"游戏启动成功");
}];
self.gameTask = gameTask;注意事项
- gameSignature 必传:
gameSignature是启动游戏的授权凭证,不能为空或无效。 - 任务复用:同一游戏已有任务时,SDK 会复用该任务并保留任务创建时的语言;后续调用传入的新语言不会覆盖它。
- 兼容旧接口:不含
language参数的重载继续可用,并保持原有默认语言行为。 - 签名具有时效性:游戏签名通常有有效期,建议获取后尽快使用。若签名过期,启动会失败。
- 建议在主线程调用:该接口涉及游戏 View 创建和 UI 操作,建议在主线程调用。
- 及时添加游戏视图:收到
didGameViewCreated回调后,应将游戏 View 添加到页面中,否则用户可能无法看到游戏画面。 - 及时保存游戏句柄:收到
didGameHandleCreated回调后,建议保存游戏句柄,用于后续通信、状态同步或资源释放。 - 按需注册业务代理:如果业务需要接收游戏事件或向游戏发送指令,建议在
didGameHandleCreated回调中完成代理注册。 - 处理启动失败:如果
completion返回错误,请检查签名是否有效、网络是否正常、SDK 是否已完成初始化和认证,以及对应游戏资源是否可用。 - 页面退出需清理资源:用户离开游戏页面时,应按照 SDK 要求停止游戏或释放相关资源,避免渲染、音频或内存资源残留。
