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
| Annotation | JS Behavior | Description |
|---|---|---|
@SUDSync | Synchronous return | The JS thread blocks and waits for the UI thread to finish executing; must return quickly |
@SUDASync | Promise or void | When the method signature includes SUDPromise, the JS side returns a Promise; otherwise it returns undefined |
Notes
- The
SUDPromiseparameter must be placed last in the method parameter list. @SUDSyncexecutes 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 Type | JS Type | Description |
|---|---|---|
int short byte and their wrapper types | number | Handled as 32-bit integers |
double float and their wrapper types | number | Handled as double precision |
boolean | boolean | -- |
char Character String CharSequence | string | -- |
SUDJSCallback | function | JS callback function; calling release() after use is recommended |
Object[] | Array | Arrays support nesting, with a maximum depth of 3 |
Java objects with @SUDSync/@SUDASync methods | object | The JS side obtains a proxy object or can pass it in as a parameter |
Parameter Count and Type Validation
- The number of arguments passed on the JS side must match the number of parameters of the exported method (the
SUDPromiseparameter does not need to be passed by JS). - When a parameter type does not match, JS throws an exception; for asynchronous methods with a Promise, it will reject directly.
FAQ
- Method overloading is not supported.
- Method names must be unique within the same namespace.
@SUDSyncis only suitable for lightweight logic; use@SUDASyncfor time-consuming operations.- Arrays are passed to the Java side as
Object[]; convert them to specific types yourself if needed. - Transferring binary data such as ArrayBuffer and TypedArray is not supported.
