JS API能力注入

Android端客户端能力注入使用说明

客户端能力注入（Extended Client Injection）用于把 Android 侧的能力对象直接暴露给 JS 运行时。开发者只需要在 Java 侧使用 @SUDSync / @SUDASync 标注公开方法，并通过 SUDRTGameHandle.registerExtendedClient 注册，即可在 JS 侧以命名空间的方式调用。

快速接入

定义能力类参考样例

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[] 形式传入，若需具体类型请自行转换