registerExtendedClient

注册扩展客户端功能

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

---

方法声明

/**
 * 注册客户端自定义功能模块
 * @param scope  功能所属的范围或命名空间（例如："wx"、"pay"）。
 * 游戏端将通过此 Scope 标识符来调用对应的方法。
 * @param client 实现具体功能的 Java 对象。
 * 该对象的方法通常需要使用 @SUDSync\@SUDASync 注解或遵循特定的协议约定。
 */
void registerExtendedClient(String scope, Object client);

---

运行行为

1. 能力注入：SDK 会将 client 对象映射到指定的 scope。当小游戏发起该 Scope 下的请求时，引擎会自动路由到对应的原生方法。
2. 解耦设计：通过 Scope 机制，App 可以在不修改 SDK 核心逻辑的情况下，无限扩展小游戏能够调用的原生能力。
3. 异步通信：游戏端的调用通常是异步的，原生端处理完业务逻辑后，通过回调（Callback）将结果返回给游戏。

---

代码示例

import global.sud.runtime.annotation.SUDASync;
import global.sud.runtime.annotation.SUDSync;
import global.sud.runtime.api.SUDJSCallback;
import global.sud.runtime.api.SUDPromise;

public final class BannerFeature {

    @SUDSync
    public Banner createBanner(String placementId) {
        return new Banner(placementId);
    }

    @SUDASync
    public void preload(String placementId, SUDPromise<Boolean> promise) {
        boolean ok = true;
        if (ok) {
            promise.resolve(true);
        } else {
            promise.reject("preload failed");
        }
    }

    @SUDASync(name = "track")
    public void trackEvent(String eventName, SUDJSCallback callback) {
        callback.invoke("ok", eventName);
        callback.release();
    }

    public static final class Banner {
        private final String placementId;

        public Banner(String placementId) {
            this.placementId = placementId;
        }

        @SUDSync
        public int getWidth() {
            return 320;
        }

        @SUDASync
        public void show(SUDPromise<Boolean> promise) {
            promise.resolve(true);
        }
    }
}

注册能力

boolean ok = gameHandle.registerExtendedClient("sud", new BannerFeature());

JS 侧调用

const banner = sud.createBanner("home");
const w = banner.getWidth();

sud.preload("horme").then(function name(params) {
    console.log(params);
});

sud.track("open", (status, name) => {
  // status: "ok"
  console.log(status);
  console.log(name);
});

注解与线程模型

注解	JS 表现	说明
@SUDSync	同步返回	JS 线程阻塞等待 UI 线程执行完成，必须快速返回
@SUDASync	Promise 或 void	方法签名包含 SUDPromise 时，JS 侧返回 Promise；否则返回 undefined

说明

1. SUDPromise 参数必须放在方法参数列表的最后一位
2. @SUDSync 会在 UI 线程执行，并有 2 秒超时保护，超时会导致调用失败

类型与参数规则

参数与返回类型映射

Java 类型	JS 类型	说明
int short byte 及包装类型	number	按 32 位整数处理
double float 及包装类型	number	按双精度处理
boolean	boolean	--
char Character String CharSequence	string	--
SUDJSCallback	function	JS 回调函数，使用完建议调用 release()
Object[]	Array	数组支持嵌套，最大深度 3
带 @SUDSync/@SUDASync 方法的 Java 对象	object	JS 侧获得代理对象或可作为参数传入

参数数量与类型校验

1. JS 侧传参个数必须与导出方法的参数个数一致（SUDPromise 参数不需要由 JS 传入）
2. 参数类型不匹配时，JS 会抛出异常；若为带 Promise 的异步方法，则会直接 reject

---

注意事项

1. 只导出 public 方法
2. 不支持方法重载
3. 同一命名空间下方法名必须唯一
4. @SUDSync 只适用于轻量逻辑，耗时操作请改为 @SUDASync
5. 数组在 Java 侧以 Object[] 形式传入，若需具体类型请自行转换

---