A stable and complete solution for a mobile-website-based app.
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:
npm install -g cordova
cordova platform add android
and/or cordova platform add ios
.cordova requirements
cordova build
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.
LANDING_URL
in www/js/index.js
to point to your mobile website.id
, name
, description
and author
in config.xml
(reference).name
, displayName
, description
and author
in package.json
.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.
This app uses a state machine (machina) to keep track of connection and loading state. The state diagram is as follows:
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).
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>
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:
AppendUserAgent
preference in config.xml
can be used to modify
the user-agent. The website can show and hide certain elements based on this.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.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.
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
This project is licensed under the Apache 2.0 license.