Skip to content

JS API Capability Injection ​

Guide to Client Capability Injection on Android ​

Client capability injection (Extended Client Injection) is used to expose Android-side capability objects directly to the JS runtime. Developers only need to annotate the public methods on the Java side with @SUDSync / @SUDASync and register them via SUDRTGameHandle.registerExtendedClient; they can then be called from the JS side using a namespace.

Quick Integration ​

Reference Example of Defining a Capability Class ​

java
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);
        }
    }
}

Registering Capabilities ​

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

Calling from the JS Side ​

javascript
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);
});

Annotations and Threading Model ​

AnnotationJS BehaviorDescription
@SUDSyncSynchronous returnThe JS thread blocks and waits for the UI thread to finish executing; must return quickly
@SUDASyncPromise or voidWhen the method signature includes SUDPromise, the JS side returns a Promise; otherwise it returns undefined

Notes

  1. The SUDPromise parameter must be placed last in the method parameter list.
  2. @SUDSync executes on the UI thread and has a 2-second timeout protection; a timeout causes the call to fail.

Type and Parameter Rules ​

Parameter and Return Type Mapping ​

Java TypeJS TypeDescription
int short byte and their wrapper typesnumberHandled as 32-bit integers
double float and their wrapper typesnumberHandled as double precision
booleanboolean--
char Character String CharSequencestring--
SUDJSCallbackfunctionJS callback function; calling release() after use is recommended
Object[]ArrayArrays support nesting, with a maximum depth of 3
Java objects with @SUDSync/@SUDASync methodsobjectThe JS side obtains a proxy object or can pass it in as a parameter

Parameter Count and Type Validation ​

  1. The number of arguments passed on the JS side must match the number of parameters of the exported method (the SUDPromise parameter does not need to be passed by JS).
  2. When a parameter type does not match, JS throws an exception; for asynchronous methods with a Promise, it will reject directly.

FAQ ​

  1. Method overloading is not supported.
  2. Method names must be unique within the same namespace.
  3. @SUDSync is only suitable for lightweight logic; use @SUDASync for time-consuming operations.
  4. Arrays are passed to the Java side as Object[]; convert them to specific types yourself if needed.
  5. Transferring binary data such as ArrayBuffer and TypedArray is not supported.