lguzzon-scratchbook / cordova-web-wrap

A stable and complete solution for a mobile-website-based app.

Cordova Web Wrap

This app is a light-weight Cordova wrapper around a mobile website. It can be useful to add functionality that only works in apps, like barcode scanning, to a mobile website. While Cordova does a lot to make this possible, a polished, well-working app is not yet trivial. This project simplifies that.

Note that it's best to create a single page application, so that the website code only needs to be loaded once. This allows the user to have fast interaction with the app.

Features:

• Loads the website in an app, safely (inAppBrowser).
• Meant for single page applications.
• Works when online, a notice is shown when offline (with a state-machine to track state).
• Opens external links in the system web browser, internal links in the app.
• Website can indicate which links to open in the app.
• Allows scanning a barcode, initiated from the website.
• Works on Android and iOS.

Build

1. Install Cordova: npm install -g cordova
2. Add platforms: cordova platform add android and/or cordova platform add ios.
3. Check (and install) requirements: cordova requirements
4. Build: cordova build

iOS

On iOS cordova build ios may not be enough. After running this, you can open the folder platforms/ios in Xcode. In the warnings shown there are two items about updating build settings. Accept the modifications (ignoring the warning about uncommited changes), and build it from Xcode.

Configure

• Change LANDING_URL in www/js/index.js to point to your mobile website.
• Update id, name, description and author in config.xml (reference).
• Modify name, displayName, description and author in package.json.
• Edit title, h1 and other texts in www/index.html.

Then build and install. If you want more beautiful icons (recommended), run

npm install cordova-icon
node_modules/.bin/cordova-icon --icon=res/icon.png

To use your own icons, update res/icon.png and www/img/logo.png before doing so.

State machine

This app uses a state machine (machina) to keep track of connection and loading state. The state diagram is as follows:

Opening external links

External links are opened in the system web browser, internal links in the app. Which links are internal is determined by LOCAL_URLS in index.js, which is a space-separated list of URLs. All listed links are considered to be internal. Full URLs are allowed (to allow multiple hosts), as are URLs relative to the host (and protocol) of LANDING_URL, with leading slash. Query string and hash are not part of the comparison.

For example, if you have a mobile website where you want to open the index, an about page, and product pages, you could use / /about /products/*. All other links on your website would be opened in the system web browser.

This attribute can also be set by the website by any element with a data-app-local-urls attribute (so the website can evolve without having to update this setting in the app).

Barcode scanner

The website can initiate a barcode scan by pointing to the custom url app://mobile-scan. When this link is followed, the barcode scanner is opened. On successful scan, it will return to the page indicated by the ret query string parameter passed that triggered opening the scanner. This is a URL template where {CODE} is replaced by the scanned barcode. Links can be relative or absolute.

An example. When following the link in the HTML shown below, a barcode scanner will be opened, and when barcode 12345 is scanned, the link http://x.test/scan/12345 will be opened in the app.

<a href="app://mobile-scan?ret=http%3A%2F%2Fx.test%2Fscan%2F%7BCODE%7D">
  Scan
</a>

Adapating a website for the app

This app shows a mobile website. Most of it would also work in a regular web browser, but certain features may only make sense when embedded in the app. The barcode-scan feature comes to mind, and it may be desirable to hide large documentation pages from navigation.

This can easily be done in two ways:

1. User-Agent - the AppendUserAgent preference in config.xml can be used to modify the user-agent. The website can show and hide certain elements based on this.
2. LANDING_URL - the app's landing page could include a query parameter or be a specific page for the app. It can be useful to pass through the query parameter to links, so that any modified navigation remains so in the app.

Testing on the emulator

To test the barcode scanner with the Android emulator, you can use the following procedure on Linux (based on this).

# Check which video devices are available. Use the next number for 'video_nr' and in 'device'.
$ ls /dev/video*
/dev/video0
# Load the loopback video device
$ sudo modprobe v4l2loopback video_nr=1 card_label="mockcam"
# Create virtual webcam out of the image, substitute 'image.png' with your picture.
$ gst-launch-1.0 filesrc location=image.png ! pngdec ! imagefreeze ! v4l2sink device=/dev/video1

Then launch the emulator with the additional argument -camera-back webcam1 (use same number as above). You may want to scale the image to 800x600 if you have a large one. One online barcode generator is this one.

Lodash

The state machine requires lodash, and to reduce the footprint we use a custom build (527K to 132K for version 4.17.5). The methods included are just those used in the state machine code plus debounce (so if you get missing functions there after a machina upgrade, check if a missing method is used):

npm install -g lodash-cli
lodash -d -o www/js/lodash.custom.js include=apply,defaults,cloneDeep,debounce,difference,each,extend,filter,isPlainObject,merge,transform,without

Notes

• If the inAppBrowser would support opening external links without messing up the internal inAppBrowser, the app-launcher plugin could be removed (see also CB-13198).
• On iOS, opening the barcode scanner briefly shows a opening barcode scanner screen because of this issue (marked wontfix).

Links

• Going Mobile: Wrapping an existing web application in Cordova/Phonegap
• HTML-5 Cordova webapp
• Is This Thing On?, on state management for connection status
• Cordova documentation

License

This project is licensed under the Apache 2.0 license.