Webview <-> app.js Communication

In order to communicate between app.js and any WebView that gets instantiated, we allow users to create custom events or custom JS RPC methods.

Custom Events

You can send events from app.js to javascript in WebViewPlugin instances, and vice-versa. These events are produced and consumed with a simple on() and trigger() API, with some slight variation between the web views themselves and app.js.

eventEmitter.trigger(eventName, params)

• eventName: String name of the event
• params: JSON-serializeable Object of parameters that should be passed to callbacks that handle this event

eventEmitter.on(eventName, callback)

• eventName: String name of the event
• callback: a callback function that takes a parameters object passed from the trigger call.

In the web views, you will have to have astro-client.js loaded, and the Astro object itself will emit events sent from the app, and send events we admit to app.js. In the app, web view plugin instances will emit events from their corresponding web views, and can be used to trigger events in them.

Examples:

In the WebViews:

Send an event to app.js:

Astro.trigger('loadedImage', {
    url: 'http://www.example.com/img/a.jpg'
})

Register a handler for events from app.js:

Astro.on('loggedIn', (data) => {
    var userName = data.userName
    $('.userName').text(userName)
})

In app.js:

Send an event to the web view:

webViewPluginInstance.trigger('loggedIn', {
    userName: "Steve"
})

Receive an event from the web view:

webViewPluginInstance.on('loadedImage', (data) => {
    imageUrls.push(data.url)
})

Custom JS RPC Methods

If you need to invoke something on app.js which needs to return a response, you should setup a custom JS RPC method.

App.js

To setup a JS RPC method, you need to first register an RPC method.

Astro.registerRpcMethod(methodName, methodArgs, callback)

• methodName: String name of the RPC method
• methodArgs: The arguments that the RPC method accepts.
• callback: a callback function take takes a response object as the first argument, and then all of the method args as the following arguments.

Astro.registerRpcMethod('sum', ['a', 'b'], (res, a, b) => {
    res.send(null, a+b)
})

WebView

To call an JS RPC method, you must create a proxy method that matches the RPC method you registered in app.js.

Astro.jsRpcMethod(eventName, parameters)

• methodName: String name of the RPC method that matches the one registered in app.js.
• methodArgs: The arguments that the RPC method accepts that matches the one registered in app.js.
• Returns: A function that takes methodArgs and returns a promise that is fulfilled when the worker responds.

Example:

try {
    const sum = Astro.jsRpcMethod('sum', ['a', 'b'])
    const result = await sum(1, 2)
    console.log(`The sum of 1 and 2 is: ${result}`);
} catch (error) {
    console.log(`An error occurred: ${error}`)
}

Native Information injected into WebViews

Astro injects an object into it's web views in order for the web views to have some knowledge about the native app in which they are running. The injected object is called AstroNative and is available in the global namespace of the web view. Note that in Android, AstroNative won't be available until astro-client.js or astro-full.js loads.

AstroNative contains the following information:

• AstroNative.OSInfo: platform and version of the operating system
• AstroNative.Configuration
  • AstroNative.Configuration.DEBUG: build type of the app
  • AstroNative.Configuration.ASTRO_PREVIEW: astro preview enablement

In Android, AstroNativeObject.isPreviewEnabled() is available to check the preview status.