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
- Capability injection: The SDK maps the
clientobject to the specifiedscope. When the mini-game makes a request under that Scope, the engine automatically routes it to the corresponding native method. - 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.
- 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
| Annotation | JS Behavior | Description |
|---|---|---|
@SUDSync | Synchronous return | The JS thread blocks and waits for the UI thread to finish; 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's 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; it is recommended to call release() after use |
Object[] | Array | Arrays support nesting, up to a depth of 3 |
Java objects with @SUDSync/@SUDASync methods | object | The JS side receives a proxy object, which can also be passed as a parameter |
Parameter Count and Type Validation
- The number of arguments passed from the JS side must match the number of parameters of the exported method (the
SUDPromiseparameter does not need to be passed from JS) - When parameter types do not match, JS throws an exception; for asynchronous methods with a Promise, it rejects directly
Notes
- Only
publicmethods are exported - 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 to the specific type yourself if needed
