startGameWithSignature:language:didGameViewCreated:didGameHandleCreated:progress:completion:
Start Game (by Game Signature)
This method starts a game using a game signature (gameSignature). The game signature is usually generated by the server based on information such as the user identity, game ID, and validity period, and is used to authorize this game start operation.
Compared with starting directly via gameID, starting with gameSignature provides more secure authentication and is suitable for formal business scenarios. Developers can obtain the game view through didGameViewCreated, obtain the game handle through didGameHandleCreated, monitor the start progress through progress, and receive the final start result in completion.
Method Declaration
+ (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;Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| gameSignature | NSString * | Yes | The game start signature, used to authorize this game start operation. |
| language | NSString * | No | Language used for the loading name and icon, such as en-US. nil or empty uses the system language. This value does not modify the signature. |
| didGameViewCreated | SUDOPDidGameViewCreatedBlock | No | Callback invoked after the game view is created. Developers typically obtain the game View in this callback and add it to the business page. |
| didGameHandleCreated | SUDOPDidGameHandleCreatedBlock | No | Callback invoked after the game handle is created. Developers typically save the game handle, register the business delegate, or prepare for subsequent communication in this callback. |
| progress | SUDOPProgressBlock | No | Progress callback during the game start process, which can be used to display loading progress. |
| completion | SUDOPGameOperationCompletionBlock | No | Callback invoked after the game start flow finishes. Success indicates the game has completed startup; on failure, error information is returned. |
Return Value
| Return Value | Type | Description |
|---|---|---|
| gameTask | id<SUDOPGameTask> | The game start task object used to track or manage the current start flow. It may be nil if a task cannot be created. |
Runtime Behavior
Signature Validation
The SDK uses the passedgameSignatureto perform start authorization validation. If the signature is invalid, expired, or does not match the current user, the start flow fails and returns an error viacompletion.Create Start Task
The SDK creates a game start task and immediately returns anid<SUDOPGameTask>object.Resource Preparation
The SDK parses the corresponding game based on the signature information and checks the game resource status. If the resources are not ready, the SDK automatically performs the necessary download, verification, load, and initialization flows.Progress Callback
During resource preparation or the start process, the SDK returns the current progress via theprogresscallback, which developers can use to update the loading UI.Game View Creation
When the game View is created, the SDK triggers thedidGameViewCreatedcallback. Developers should add the game view to their own page view hierarchy here.Game Handle Creation
When the game Handle is created, the SDK triggers thedidGameHandleCreatedcallback. This handle is typically used for communicating with the game, registering delegates, sending states, or controlling the game lifecycle.Start Completed
After the game starts successfully or fails, the SDK triggers thecompletioncallback. On success, the game enters a runnable state; on failure, you can handle it based on the error information.
Example Code
NSString *gameSignature = @"your_game_signature";
id<SUDOPGameTask> gameTask = [SUDOP startGameWithSignature:gameSignature
language:@"en-US"
didGameViewCreated:^(UIView * _Nullable gameView) {
if (!gameView) {
return;
}
// Add the game view to the current page
gameView.frame = self.containerView.bounds;
[self.containerView addSubview:gameView];
NSLog(@"Game view created");
} didGameHandleCreated:^(id<SUDRTGameHandle> gameHandle, SUDOPGameInfo *gameInfo) {
if (!gameHandle) {
return;
}
// Save the game handle for subsequent communication with the game or resource release
// self.gameHandle = gameHandle;
// If the business requires it, you can register the game delegate here
// [SUDOP registerWrappedClientWithGameHandle:gameHandle clientDelegate:self];
NSLog(@"Game handle created");
} progress:^(NSInteger progress) {
NSLog(@"Game start progress: %ld", (long)progress);
// You can update the loading progress UI here
// self.progressView.progress = progress;
} completion:^(id<SUDOPGameHandleProvider> _Nullable provider,
NSError * _Nullable error) {
if (error) {
NSLog(@"Game start failed: %@", error);
return;
}
NSLog(@"Game started successfully");
}];
self.gameTask = gameTask;Notes
- gameSignature Required:
gameSignatureis the authorization credential for starting the game and cannot be empty or invalid. - Task Reuse: If a task already exists for the same game, the SDK reuses it and retains the language selected when that task was created. A later call does not replace it.
- Backward Compatibility: The overload without
languageremains available and preserves the previous default-language behavior. - Signature Is Time-sensitive: The game signature usually has a validity period; it is recommended to use it as soon as possible after obtaining it. If the signature expires, the start will fail.
- Recommended to Call on Main Thread: This interface involves game View creation and UI operations, so it is recommended to call it on the main thread.
- Add the Game View Promptly: After receiving the
didGameViewCreatedcallback, add the game View to the page; otherwise, the user may not see the game screen. - Save the Game Handle Promptly: After receiving the
didGameHandleCreatedcallback, it is recommended to save the game handle for subsequent communication, state synchronization, or resource release. - Register the Business Delegate as Needed: If the business needs to receive game events or send commands to the game, it is recommended to complete delegate registration in the
didGameHandleCreatedcallback. - Handle Start Failure: If
completionreturns an error, check whether the signature is valid, whether the network is normal, whether the SDK has completed initialization and authentication, and whether the corresponding game resources are available. - Clean Up Resources on Page Exit: When the user leaves the game page, stop the game or release related resources as required by the SDK to avoid leftover rendering, audio, or memory resources.
