registerExtendedClient:client:
Register an extended client interface
registerExtendedClient:client: is used to establish a custom capability channel between the native layer and the mini game engine. Through this method, you can inject a native business object (such as an in-app purchase component, a social sharing plugin, or a specific hardware control class) into the mini game runtime environment. The mini game script can directly call the object's methods through an agreed-upon scope namespace.
Method Declaration
objectivec
/**
* Register an extended client.
* @param scope The namespace string. The mini game accesses the corresponding capability via this identifier (e.g. "PayClient").
* @param client An NSObject instance implementing a specific extension protocol.
*/
- (void)registerExtendedClient:(NSString *)scope client:(NSObject *)client;Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| scope | NSString | Yes | Unique identifier: camelCase naming is recommended (e.g. LiveStream). The game side obtains the interface via this key. |
| client | NSObject | Yes | Native instance: usually needs to implement the SDK-defined extension base class or protocol, containing the methods to be called by the game. |
Runtime Behavior
- Injection mapping: The SDK maintains an internal mapping table. When the JavaScript layer tries to access this
scope, the instruction is routed to the associatedclientinstance. - Method conversion: Async calls (Promise) from the JavaScript layer are converted into native method executions.
- Lifecycle binding: The registered extended client is usually unbound when the
gameHandleis destroyed, ensuring memory safety.
Example
Implement a custom "haptic feedback" extension:
objectivec
// 1. Define the extended client class
@interface DemoExtendBaseOptions : NSObject
- (void)handleSuccessWithJsonData:(id)jsonData;
- (void)handleFailWithError:(NSError *)error;
- (NSDictionary *)jsonObject;
@end
@interface DemoExtendBaseOptions()
@property (nonatomic, strong, nullable) id<SUDRTJSCallback> successcb;
@property (nonatomic, strong, nullable) id<SUDRTJSCallback> failcb;
@end
@implementation DemoExtendBaseOptions
SUDRT_ASYNC(success, success:(id<SUDRTJSCallback>)cb) {
NSLog(@"LoginDemo success");
if (_successcb) {
[_successcb releaseCallback];
}
_successcb = cb;
}
SUDRT_ASYNC(fail, fail:(id<SUDRTJSCallback>)cb) {
NSLog(@"LoginDemo fail");
if (_failcb) {
[_failcb releaseCallback];
}
_failcb = cb;
}
- (void)dealloc {
if (_successcb) {
[_successcb releaseCallback];
_successcb = nil;
}
if (_failcb) {
[_failcb releaseCallback];
_failcb = nil;
}
}
- (void)handleSuccessWithJsonData:(id)jsonData {
if (_successcb) {
NSMutableArray *arr = NSMutableArray.new;
if (jsonData) {
[arr addObject:jsonData];
}
[_successcb invoke:arr];
}
}
- (void)handleFailWithError:(NSError *)error {
if (_failcb) {
NSMutableArray *arr = NSMutableArray.new;
NSMutableDictionary *errDic = [[NSMutableDictionary alloc]init];
errDic[@"errCode"] = @(error.sud_errCode);
errDic[@"errMsg"] = error.sud_errMsg;
[arr addObject:errDic];
[_failcb invoke:arr];
}
}
- (NSDictionary *)jsonObject {
return [self sud_modelToJSONObject];
}
@end
@interface DemoSayHelloOptions: DemoExtendBaseOptions
@property(nonatomic, strong)NSString *name;
@end
@interface DemoExtendClient : NSObject
@end
@implementation DemoExtendClient
SUDRT_ASYNC(sayHello, sayHelloWithOptions:(DemoSayHelloOptions *)options) {
// Implement the native-side flow
NSLog(@"say hello:%@", options.name);
// Success
NSMutableDictionary *dicResult = NSMutableDictionary.new;
dicResult[@"state"] = @"";
[options handleSuccessWithJsonData:dicResult];
// Failure
NSEerror *error = xxxx;
[options handleFailWithError:error];
}
@end
// 2. Register to the game instance
DemoExtendClient *demoExtendClient = [[DemoExtendClient alloc] init];
[self.gameHandle registerExtendedClient:@"demoClient" client:demoExtendClient];
// 3. Mini game side call example (JS)
// sudRuntime.getExtendedClient("demoClient").sayHello({ name: "Jack" });Notes
- Naming conflicts:
scopemust be globally unique. If the samescopeis registered repeatedly, the later-registered instance usually overrides the earlier one. - Thread safety: The mini game engine's callbacks may occur on a background thread. If the
clientinvolves UI operations internally (such as presenting a share sheet), be sure to manually switch to the main thread to execute them. - Protocol matching: The method names and parameter formats in the
clientinstance must match the call conventions on the mini game side; otherwise the call will fail or crash. - Registration timing: It is recommended to complete registration before calling
start:, so that the logic after the game starts can immediately use these extended capabilities.
