Skip to content

registerExtendedClient ​

Register Extended Client Features ​

registerExtendedClient is a core interface provided by the Android SDK for establishing a custom capability channel between the native layer and the mini-game engine. Through this method, you can inject native-side business objects (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 then directly call the methods of that object through the agreed-upon scope namespace.


Method Declaration ​

java
/**
 * Registers a client custom feature module.
 * @param scope  The scope or namespace the feature belongs to (e.g., "sud", "pay").
 * The game side calls the corresponding methods through this Scope identifier.
 * @param client The Java object implementing the specific feature.
 * The object's methods usually need to use the @SUDSync/@SUDASync annotation or follow a specific protocol convention.
 */
void registerExtendedClient(String scope, Object client);

Runtime Behavior ​

  1. Capability injection: The SDK maps the client object to the specified scope. When the mini-game makes a request under that Scope, the engine automatically routes it to the corresponding native method.
  2. Decoupled design: Through the Scope mechanism, the app can infinitely extend the native capabilities the mini-game can call without modifying the SDK's core logic.
  3. Asynchronous communication: Calls from the game side are usually asynchronous; after the native side finishes processing the business logic, it returns the result to the game via a callback.

Example Code ​

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 the Capability ​

java
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; 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's 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; it is recommended to call release() after use
Object[]ArrayArrays support nesting, up to a depth of 3
Java objects with @SUDSync/@SUDASync methodsobjectThe JS side receives a proxy object, which can also be passed as a parameter

Parameter Count and Type Validation ​

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

Notes ​

  1. Only public methods are exported
  2. Method overloading is not supported
  3. Method names must be unique within the same namespace
  4. @SUDSync is only suitable for lightweight logic; use @SUDASync for time-consuming operations
  5. Arrays are passed to the Java side as Object[]; convert to the specific type yourself if needed