Cocos Example Projects

The native-script-bridge provides a simplified mechanism for bidirectional communication between the JavaScript layer and the Native layer (Android/Java and iOS/Objective-C).

Key Constraints

• Data Type: Currently, only string data is supported. To transmit complex objects, serialize them into a JSON string in the sender layer and parse them in the receiver layer.
• Callback Lifecycle: The onNative property in JavaScript can only hold one callback function at a time; setting it again will overwrite the previous handler.
• Communication Model: sendToNative (JS to Native) is a one-way communication. It does not wait for a response or notify the JS layer of success or failure.

// JavaScript API Surface
export namespace bridge {
    /**
     * Send data to the native layer.
     * @param arg0 First string argument
     * @param arg1 Optional second string argument
     */
    export function sendToNative(arg0: string, arg1?: string): void;

    /**
     * Register a callback to receive data from the native layer.
     * Overwrites any existing callback.
     * @param args Received from native
     */
    export function onNative(arg0: string, arg1?: string | null): void;
}

Because jsb.bridge.onNative and the native setCallback can only hold one reference at a time, you should use a MethodManager pattern to route different native calls to specific JavaScript functions.

1. Create a MethodManager singleton to store a map of method names to functions.
2. In your Cocos Creator component's start() method, assign a single handler to jsb.bridge.onNative that calls MethodManager.instance.applyMethod(methodName, arg).
3. Register your specific logic functions with the manager using addMethod.

export class MethodManager {
    private methodMap: Map<String, Function>;
    public static instance: MethodManager = new MethodManager;

    public addMethod(methodName: String, f: Function): boolean {
        if (!this.methodMap.get(methodName)) {
            this.methodMap.set(methodName, f);
            return true;
        }
        return false;
    }

    public applyMethod(methodName: String, arg?: String): boolean {
        const f = this.methodMap.get(methodName);
        if (!f) return false;
        try {
            f?.call(null, arg);
            return true;
        } catch (e) {
            return false;
        }
    }

    public removeMethod(methodName: String): any {
        return this.methodMap.delete(methodName);
    }

    constructor() {
        this.methodMap = new Map<String, Function>();
        MethodManager.instance = this;
    }
}

// Usage in a Component
@ccclass('CallNative')
export class CallNative extends Component {
    start() {
        new MethodManager();
        jsb.bridge.onNative = (methodName: string, arg1?: string | null) => {
            MethodManager.instance.applyMethod(methodName, arg1!);
        };
        
        // Register specific methods
        MethodManager.instance.addMethod("changeLabelContent", (usr: string) => {
            this.changeLabelContent(usr);
        });
    }

    public changeLabelContent(user: string): void {
        // Logic to update UI
    }
}

To receive calls from JavaScript in Android, you must register a callback using JsbBridge.setCallback.

1. Initialize your bridge logic in onCreate of your CocosActivity using a helper class (e.g., JsbBridgeTest.start()).
2. Use a HashMap to map string keys to specific callback logic.
3. In the JsbBridge.ICallback.onScript(String arg0, String arg1) implementation, retrieve the corresponding callback from your map and execute it.
4. To send data back to JavaScript, use JsbBridge.sendToScript(methodName, argument).

// In AppActivity.java
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    JsbBridgeTest.start();
}

// In JsbBridgeTest.java
public class JsbBridgeTest {
    public interface MyCallback {
        void onTrigger(String arg);
    }
    public static HashMap<String, MyCallback> myCallbackHashMap = new HashMap<>();

    public static void start() {
        // Map a string key to a specific action that calls JS
        JsbBridgeTest.myCallbackHashMap.put("requestLabelContent", arg -> {
            JsbBridge.sendToScript("changeLabelContent", "Charlotte");
        });

        // Register the global bridge callback
        JsbBridge.setCallback(new JsbBridge.ICallback() {
            @Override
            public void onScript(String arg0, String arg1) {
                JsbBridgeTest.myCallbackHashMap.get(arg0).onTrigger(arg1);
            }
        });
    }
}