Mobile Platform as a Service:Custom JSAPIs

A JavaScript API (JSAPI) is an interface that provides native capabilities for HTML5 applications. Use JSAPIs to access native features and controls, extending what your HTML5 pages can do inside the mPaaS HTML5 container.

The HTML5 container provides two layers of JSAPI support:

• Built-in JSAPIs for common tasks such as page push, page pop, and title configuration. For details, see Built-in JSAPIs.

• Custom JSAPIs and plugins to cover business requirements beyond the built-in set.

This topic explains how to implement custom JSAPIs and plugins in mPaaS.

Custom JSAPI plugin design

Custom JSAPI plugins have the following design characteristics:

• The HTML5 container exposes a plugin registration mechanism so external services can integrate without modifying the container itself.

• Plugin code lives in its own bundle, separate from the HTML5 container. The container initializes the plugin object only when a page first calls it, not at startup.

• Plugin implementation and registration can reside in different bundles, decoupling dependencies. Inject plugins into the container at runtime using H5Service.

Call native from a frontend page

Use the following steps to register a custom JSAPI on the native side and invoke it from a frontend HTML5 page.

1. Register the JSAPI with MPNebula's plugin registration interface.

   Note

   For the full source of MyJSApiPlugin, see Code examples.

   • The registration method signature is:

     /**
     * Registers a custom HTML5 plugin (JSAPI).
     *
     * @param className  The class name of the plugin. The full path (package + class) is required.
     * @param bundleName The bundle name. You can view the bundle name in the main module/build/intermediates/bundle/META-INF/BUNDLE.MF file. If the plugin is written in the portal project, set bundleName to an empty string ("").
     * @param scope      The scope. Default value: page.
     * @param events     The events to register.
     */
     public static void registerH5Plugin(String className, String bundleName, String scope, String[] events)

   • Register the plugin during app initialization:

     MPNebula.registerH5Plugin(
       MyJSApiPlugin.class.getName(),
       BuildConfig.BUNDLE_NAME,
       "page",
       new String[]{"myapi1","myapi2",H5Plugin.CommonEvents.H5_PAGE_SHOULD_LOAD_URL}
     );

2. Call the JSAPI from the frontend page.

   Pass the event name that matches one of the registered events. The plugin retrieves the value via event.getParam() and parses the data.

   The AlipayJSBridge.call() method takes three arguments:

   • event — the event name registered in the plugin (for example, myapi2)

   • param — an object containing the parameters to pass to the native side

   • callback — a function invoked with the result returned by the plugin

     AlipayJSBridge.call('myapi2', {
      param2: 'World'
     },
     function(result) {
      console.log(result);
     });

Call a frontend page from native

Native code can push events to a frontend HTML5 page through the HTML5 container bridge. The example below shows a network-change notification: the frontend listens for the event, and native sends it when connectivity changes.

All calls use sendDataWarpToWeb(eventName, params, callbackContext):

• eventName — the event name the frontend listener is registered on (for example, h5NetworkChange)

• params — a JSONObject containing the data to send to the page

• callbackContext — pass null for fire-and-forget notifications

  1. Register a listener on the frontend.

     document.addEventListener('h5NetworkChange',
     function(e) {
      alert("The network environment has changed. You can call the getNetworkType API to obtain details.");
     },
     false);

  2. When the client detects a network change, send the event to the page.

     JSONObject param = new JSONObject();
     // Set custom parameters for param.
     param.put("data", param);
     H5Page h5Page = h5Service.getTopH5Page();
     if (h5Page != null) {
      h5Page.getBridge().sendDataWarpToWeb("h5NetworkChange", param, null);
     }

Debug with Chrome Inspect

Use Chrome's built-in inspect tool to verify that your custom JSAPI calls work correctly.

Prerequisites: connect your mobile device to your computer. Make sure you are running the latest version of Chrome — older versions show a blank screen on the inspect page.

1. Open Chrome on your computer and go to chrome://inspect.

2. In the mPaaS demo app, open the Ant Financial homepage. The Chrome inspect page displays the connected device and page, as shown below:

   Note

   If chrome://inspect shows a blank screen, upgrade Chrome to the latest version.

   

3. Click inspect. The DevTools panel opens:

   

4. Click Console in the toolbar to enter the page debugging mode, then call your custom JSAPI methods to verify they work as expected.

Related topics

• Code examples

• FAQ