WebView Runtime

The WebView Runtime allows you to easily run web apps (SPAs).

Private beta

The WebView Runtime is currently in private beta with select users. It is planned for public release in Q4 2019 (see the Q4/19 Roadmap Update for more information). To stay up to date about upcoming releases please check out our blog, where we post release notes and roadmap updates.

Contents

Overview

The WebView runtime is a service that reliably runs single-page applications (SPAs) built on HTML, JavaScript, and CSS on edge devices. It is the basis for developing interactive UI-based apps for end-users.

Key capabilities:

  • Reliably serve single-page applications (SPAs) and assets in platform-specific webview container
  • Provide access to auxiliary ActyxOS services (e.g. Event Service)

Basics

Single-page applications

Single-page applications (SPAs) are web-based applications in which pages are dynamically generated on the client-side depending on user interactions. They are traditionally built as a combination of HTML, JavaScript, and CSS.

Popular frameworks and libraries have emerged for building SPAs. They provide a lot of the common boilerplate required for managing state, routing users, etc. For some of the most well known ones, check out React.js, Vue.js, and AngularJS.

Multi-tasking by end-users

The WebView runtime supports multi-tasking. This means that end-users can have multiple apps running simultaneously and can switch between them.

This functionality leverages ActyxOS packaging for Android and the default Android launcher. Upon deployment, an SPA is automatically wrapped in a dedicated native Android APK. This means that end-users can interact as they would with any other Android app. For more information about this, please refer to the Android documentation.

Usage

Building SPAs

You can build your SPA from scratch or use any of the common JavaScript frameworks or libraries. The most popular frameworks/libraries are:

Recommendation: ReactJS

Unless you are very proficient in another framework, we recommend starting with ReactJS using the create-react-app command.

Packaging SPAs

The Actyx CLI provides the ax app:package command for packaging ActyxOS apps for deployment. Based on the app’s manifest (a JSON file), the CLI will automatically validate app properties and assets, and, finally, generate a tarball for deployment.

For SPAs, the manifest (manifest.json) should have the following structure:

{
    "spa": {
        "name": "MySPA", // The name of your application
        "displayName": "My Single-Page App", // The name that will be displayed to end-users
        "version": "1.0.3", // The version of your application
        "appIcon": "./build/assets/app-icon.png", // App icon for your app
        "main": "index.html", // The entry point to your application
        "dist": "./build" // The path to the app's directory
    }
}

The dist property should point to a directory at which the app’s files and assets are located. Here is an example of the project directory based on the above manifest:

my-spa/
    manifest.json
    package.json
    src/
        <source files>
    build/
        index.html
        bundle.js
        styles.css
        assets/
            logo.png
            app-icon.png

Note

The dist directory is usually created automatically by your build process. It is rarely the same as your src directory. Please refer to your environment’s or framework’s instructions for building your app for distribution.

With the above manifest and the given directory structure, you can package your app using the ax app:package command. The Actyx CLI will automatically validate and analyze the manifest, package necessary files and create a tarball for deployment.

# Go to the project directory
$ cd my-spa/
# Package the app
$ ax app:package manifest.json
> Packaging SPA...
> MySPA (1.0.3) successfully packaged (MySPA-1.0.3.tar.gz).

Deploying SPAs

The Actyx CLI provides the ax app:deploy command for deploying apps to edge devices. The CLI will automatically read the manifest file and deploy the built package to the edge device.

Local deployments only

Currently, the Actyx CLI only supports local interaction with devices (using the --local flag). We plan to release remote deployment functionality in 2020. Please check out our blog for release updates.

The following example shows how you can deploy an app to an edge device accessible in the local area network:

# Go to project directory
cd my-spa/
# Deploy the app
$ ax app:deploy --local MySPA-1.0.3.tar.gz EdgeDevice1
> Deploying SPA...
> MySPA (1.0.3) (MySPA-1.0.3.tar.gz) successfully deployed to EdgeDevice1 (10.7.0.32).

Monitoring SPAs

An SPA may generate logs using the global console object. These log messages are automatically captured by ActyxOS and made available to you for monitoring and debugging.

You can access or tail (use the --tail flag) these logs using the Actyx CLI as shown in the following example.

$ ax logs --tail --local EdgeDevice1
> MySPA-1.0.3::console | 2019-09-11T21:46:12.106Z [info] Starting app...
> MySPA-1.0.3::console | 2019-09-11T21:46:12.113Z [debug] Setting route '/activities'
> MySPA-1.0.3::console | 2019-09-11T21:46:12.113Z [debug] 34 activities loaded
> MySPA-1.0.3::console | 2019-09-11T21:46:12.113Z [info] User 'jdoe' registered
> MySPA-1.0.3::console | 2019-09-11T21:46:12.114Z [debug] Setting route '/preferences'

Undeploying SPAs

Undeploying an app means deleting it from the device. This can be done with the ax app:undeploy command.

Example:

# Undeploy an app
$ ax app:undeploy --local MyApp EdgeDevice1
> Undeploying app `MySPA`...
> App 'MySPA' (1.0.3) successfully undeployed from EdgeDevice1 (10.2.8.39)