Skip to content

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 ​

ParameterTypeRequiredDescription
scopeNSStringYesUnique identifier: camelCase naming is recommended (e.g. LiveStream). The game side obtains the interface via this key.
clientNSObjectYesNative instance: usually needs to implement the SDK-defined extension base class or protocol, containing the methods to be called by the game.

Runtime Behavior ​

  1. Injection mapping: The SDK maintains an internal mapping table. When the JavaScript layer tries to access this scope, the instruction is routed to the associated client instance.
  2. Method conversion: Async calls (Promise) from the JavaScript layer are converted into native method executions.
  3. Lifecycle binding: The registered extended client is usually unbound when the gameHandle is 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: scope must be globally unique. If the same scope is 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 client involves 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 client instance 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.