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 eventparams
: JSON-serializeable Object of parameters that should be passed to callbacks that handle this event
eventEmitter.on(eventName, callback)
eventName
: String name of the eventcallback
: 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 systemAstroNative.Configuration
AstroNative.Configuration.DEBUG
: build type of the appAstroNative.Configuration.ASTRO_PREVIEW
: astro preview enablement
In Android, AstroNativeObject.isPreviewEnabled()
is available to check the preview status.