startGame:didGameViewCreated:didGameHandleCreated:progress:completion:
Start Game (by Game ID)
This method starts a game via the game's unique identifier (Game ID). The SDK creates a game task based on the passed gameID and completes game resource preparation, game view creation, game handle creation, and the final start flow.
This interface is one of the core methods for starting a game. Developers can obtain the game view through didGameViewCreated and add it to the business page, obtain the game handle through didGameHandleCreated and register the business delegate, monitor the start progress through progress, and handle the final start result in completion.
Method Declaration
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;Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| gameID | NSString * | Yes | The unique identifier of the game. |
| language | NSString * | No | Optional language in the new overload, such as zh-CN. Used for the signature request and the loading name and cover. See the language rules below. |
| didGameViewCreated | SUDOPDidGameViewCreatedBlock | No | Callback invoked after the game view is created. Developers typically obtain the game View in this callback and add it to their own page view hierarchy. |
| didGameHandleCreated | SUDOPDidGameHandleCreatedBlock | No | Callback invoked after the game handle is created. Developers typically register the business delegate in this callback, or save the game handle for subsequent communication. |
| 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, which can be used to track the current start flow. Developers can manage the task based on the capabilities provided by the SDK. |
Runtime Behavior
- Create Start Task: The SDK creates a game start task based on the passed
gameIDand immediately returns anid<SUDOPGameTask>object. - Resource Preparation: The SDK checks whether the game resources already exist. If the game resources are not ready, the SDK automatically performs the necessary download, load, or initialization flows.
- Progress Callback: During the game start process, the SDK returns the current loading progress via the
progresscallback, which developers can use to update the loading UI. - Game View Creation: When the game View is created, the SDK triggers the
didGameViewCreatedcallback. Developers should add the game view to the page here. - Game Handle Creation: When the game Handle is created, the SDK triggers the
didGameHandleCreatedcallback. This handle is typically used for subsequent communication with the game, registering delegates, or sending states. - Start Completed: After the game starts successfully or fails, the SDK triggers the
completioncallback. On success, the game enters an interactive state; on failure, you can handle it based on the error information.
Language and Loading View
- The original method remains available and is equivalent to passing
language:nil. - A nonempty language is forwarded to
/v1/game/signatureand used to select the loading name fromgame_nameand cover URL fromicon. - With
nilor an empty string, the signature request uses the server default. The loading view uses the first system preferred language (NSLocale.preferredLanguages.firstObject) to select both the name and cover. - Selection uses the existing language helper: exact language, parent language (for example,
zh-Hans-CN→zh-Hans), language prefix, another entry with the same prefix,default, then any nonempty string. If no usable localized icon exists, the cover falls back togame_icon. - An existing task for the same game ID is reused. A later call does not overwrite an already started task's language.
Example Code
objectivec
NSString *gameID = @"game_999";
id<SUDOPGameTask> gameTask = [SUDOP startGame:gameID
language:@"zh-CN"
didGameViewCreated:^(UIView * _Nullable gameView) {
if (!gameView) {
return;
}
// Add the game view to the current page
gameView.frame = self.view.bounds;
[self.view addSubview:gameView];
NSLog(@"Game view created");
} didGameHandleCreated:^(id _Nullable gameHandle) {
if (!gameHandle) {
return;
}
// Save the game handle, or register the business delegate
// self.gameHandle = gameHandle;
// [SUDOP registerWrappedClientWithGameHandle:gameHandle clientDelegate:self];
NSLog(@"Game handle created");
} progress:^(CGFloat progress) {
NSLog(@"Game start progress: %.2f", progress);
// You can update the loading progress UI here
// self.progressView.progress = progress;
} completion:^(id<SUDOPGameHandleProvider> _Nullable gameHandleProvider, NSError * _Nullable error) {
if (error) {
NSLog(@"Game start failed: %@", error);
return;
}
NSLog(@"Game started successfully");
}];
self.gameTask = gameTask;Note: For the Block parameter types in the example, refer to the actual definitions of the corresponding typedefs in the SDK.
Notes
- gameID Required:
gameIDis the core parameter for starting the game and cannot be empty or invalid. - 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 business page; otherwise, the user may not see the game screen. - Register the Business Delegate Promptly: If the business needs to receive game events or send states to the game, it is recommended to complete delegate registration in the
didGameHandleCreatedcallback. - Watch the Start Progress:
progresscan be used to display loading progress and improve the user experience during waiting. - Handle Start Failure: If
completionreturns an error, check the network status, game resource status, whethergameIDis valid, and whether the SDK has completed initialization and authentication. - 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.
