Skip to content

registerExtendedClient:client: ​

注册扩展客户端接口 ​

registerExtendedClient:client: 用于在原生层和小游戏引擎之间建立自定义能力通道。通过该方法,您可以将原生端的业务对象(如内购组件、社交分享插件、或特定的硬件控制类)注入到小游戏运行环境中。小游戏脚本可以通过约定的 scope 命名空间直接调用该对象的方法。


方法声明 ​

objectivec
/**
 * 注册扩展客户端。
 * @param scope 命名空间字符串。小游戏通过该标识符访问对应的功能(如 "PayClient")。
 * @param client 实现特定扩展协议的 NSObject 实例。
 */
- (void)registerExtendedClient:(NSString *)scope client:(NSObject *)client;

参数说明 ​

参数名类型必传描述
scopeNSString是唯一标识符:建议使用驼峰命名(如 LiveStream)。游戏端将通过此 key 获取接口。
clientNSObject是原生实例:通常需要实现 SDK 定义的扩展基类或协议,包含供游戏调用的方法。

运行行为 ​

  1. 注入映射:SDK 内部维护一个映射表。当 JavaScript 层尝试访问该 scope 时,指令会被路由到关联的 client 实例。
  2. 方法转换:JavaScript 层的异步调用(Promise)会被转换为原生端的方法执行。
  3. 生命周期绑定:注册的扩展客户端通常随 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: 之前完成注册,以确保游戏启动后的逻辑能够立即使用这些扩展能力。