Skip to content

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;

参数说明 ​

参数名类型必传描述
gameSignatureNSString *是游戏启动签名,用于授权本次游戏启动操作。
languageNSString *否加载页游戏名称和图标使用的语言,例如 zh-CN;nil 或空字符串使用系统语言。该参数不会修改签名内容。
didGameViewCreatedSUDOPDidGameViewCreatedBlock否游戏视图创建完成后的回调。开发者通常在此回调中获取游戏 View,并将其添加到业务页面中。
didGameHandleCreatedSUDOPDidGameHandleCreatedBlock否游戏句柄创建完成后的回调。开发者通常在此回调中保存游戏句柄、注册业务代理或进行后续通信准备。
progressSUDOPProgressBlock否游戏启动过程中的进度回调,可用于展示加载进度。
completionSUDOPGameOperationCompletionBlock否游戏启动流程完成后的回调。成功时表示游戏已完成启动;失败时返回错误信息。

返回值说明 ​

返回值类型描述
gameTaskid<SUDOPGameTask>游戏启动任务对象,可用于跟踪或管理当前启动流程;创建任务失败时可为 nil。

运行行为 ​

  1. 签名校验
    SDK 会使用传入的 gameSignature 进行启动授权校验。如果签名无效、过期或与当前用户不匹配,启动流程会失败并通过 completion 返回错误。

  2. 创建启动任务
    SDK 会创建游戏启动任务,并立即返回 id<SUDOPGameTask> 对象。

  3. 资源准备
    SDK 会根据签名信息解析对应游戏,并检查游戏资源状态。如果资源未准备完成,SDK 会自动执行必要的下载、校验、加载和初始化流程。

  4. 进度回调
    在资源准备或启动过程中,SDK 会通过 progress 回调返回当前进度,开发者可用于更新加载 UI。

  5. 游戏视图创建
    当游戏 View 创建完成后,SDK 会触发 didGameViewCreated 回调。开发者应在此处将游戏视图添加到自己的页面视图层级中。

  6. 游戏句柄创建
    当游戏 Handle 创建完成后,SDK 会触发 didGameHandleCreated 回调。该句柄通常用于与游戏通信、注册代理、发送状态或控制游戏生命周期。

  7. 启动完成
    游戏启动成功或失败后,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 要求停止游戏或释放相关资源,避免渲染、音频或内存资源残留。