registerExtendedClient:client:
注册扩展客户端接口
registerExtendedClient:client: 用于在原生层和小游戏引擎之间建立自定义能力通道。通过该方法,您可以将原生端的业务对象(如内购组件、社交分享插件、或特定的硬件控制类)注入到小游戏运行环境中。小游戏脚本可以通过约定的 scope 命名空间直接调用该对象的方法。
方法声明
objectivec
/**
* 注册扩展客户端。
* @param scope 命名空间字符串。小游戏通过该标识符访问对应的功能(如 "PayClient")。
* @param client 实现特定扩展协议的 NSObject 实例。
*/
- (void)registerExtendedClient:(NSString *)scope client:(NSObject *)client;参数说明
| 参数名 | 类型 | 必传 | 描述 |
|---|---|---|---|
| scope | NSString | 是 | 唯一标识符:建议使用驼峰命名(如 LiveStream)。游戏端将通过此 key 获取接口。 |
| client | NSObject | 是 | 原生实例:通常需要实现 SDK 定义的扩展基类或协议,包含供游戏调用的方法。 |
运行行为
- 注入映射:SDK 内部维护一个映射表。当 JavaScript 层尝试访问该
scope时,指令会被路由到关联的client实例。 - 方法转换:JavaScript 层的异步调用(Promise)会被转换为原生端的方法执行。
- 生命周期绑定:注册的扩展客户端通常随
gameHandle的销毁而解绑,确保内存安全。
代码示例
实现一个自定义的“震动反馈”扩展:
objectivec
// 1. 定义扩展客户端类
@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) {
// 实现native端流程
NSLog(@"say hello:%@", options.name);
// 成功
NSMutableDictionary *dicResult = NSMutableDictionary.new;
dicResult[@"state"] = @"";
[options handleSuccessWithJsonData:dicResult];
// 失败
NSEerror *error = xxxx;
[options handleFailWithError:error];
}
@end
// 2. 注册到游戏实例
DemoExtendClient *demoExtendClient = [[DemoExtendClient alloc] init];
[self.gameHandle registerExtendedClient:@"demoClient" client:demoExtendClient];
// 3. 小游戏端调用示例 (JS)
// sudRuntime.getExtendedClient("demoClient").sayHello({ name: "Jack" });注意事项
- 命名冲突:
scope必须全局唯一。如果重复注册相同的scope,后注册的实例通常会覆盖前者。 - 线程安全:小游戏引擎的回调可能发生在子线程。如果
client内部涉及 UI 操作(如弹出分享面板),务必手动切换到主线程执行。 - 协议匹配:
client实例中的方法名和参数格式必须与小游戏端的调用约定保持一致,否则会导致调用失败或崩溃。 - 注册时机:建议在调用
start:之前完成注册,以确保游戏启动后的逻辑能够立即使用这些扩展能力。
