Open Web Apps for Android

What is Open Web Apps for Android?

Open Web Apps for Android enables free Marketplace apps to be packaged into an APK (Android installation package), which is then installed and run in the same way as any other Android app. The APK package consists of web content (in the case of packaged apps) or a pointer to web content (in the case of hosted apps). This content is then enclosed in a thin Java/Android wrapper, which provides the integration with the Android OS. Once installed on an Android device the app is executed by Web Runtime for Android, a component of Firefox for Android.

These packages are created by the APK Factory Service, which is run as a web service by Marketplace. The APK Factory Service makes use of the APK Factory Library to create the actual package and the APK Signer to digitally sign the APK. This service is available to your own Marketplace, should you choose to create one.

You don't need any knowledge of Android development, or to take any extra development steps, to use Open Web Apps for Android: you simply select the option for distribution to Firefox Mobile or Firefox Tablet when submitting your apps to the Firefox Marketplace.

Web Runtime for Android supports 12 APIs to access device capabilities, such as vibration, geolocation, and battery status. You can see a complete list of supported APIs here: APIs showing "A" under "Availability" are those APIs available on Android, with green cells indicating that the API is available in full. You can also mouseover individual cells to get tooltips containing more information.

Web Runtime for Android will continue to add support for other APIs in future releases. Some of the APIs planned are:

• Alarm API
• SimplePush API
• Web Activities

Using Open Web Apps for Android from Firefox Marketplace

This section provides details on how you make use of Open Web Apps for Android from Firefox Marketplace, how they affect the Marketplace experience, and information on app updates.

Submitting an app

When you submit an app to the Firefox Marketplace, you choose the option of making your app available for Firefox Mobile or Firefox Tablet. Choosing either or both of these options will automatically deliver your app as an APK on Android devices.

Approving an app

When your app is reviewed, the reviewer installs your app from the reviewer section in Firefox Marketplace. When they do this from an Android device, the "review" instance of the APK Factory service is invoked to create an APK signed in Android debug mode. This version of the APK is then installed on the app reviewer's device and they complete the review process.

If the app is approved, the "release" instance of the APK Factory service is invoked to generate and sign the APK with a unique APK Signing Key. The resulting signed APK is then cached for delivery when a user chooses to install the app.

Installing an app

When a user selects your app in the Marketplace on their Android device, installation works as follows:

1. Firefox Marketplace displays the app's details and Free install button as normal.
2. When the user taps Free, Apps.install or Apps.installPackage is invoked as usual (depending on whether it's a hosted or packaged app) and a call is made to the APK Factory service to request the APK.
3. The APK is downloaded to the Android device and the standard Android app installation process invoked.
4. If the user hasn't enabled the Security setting Unknown sources, Android will alert the user and give them the option to cancel the installation or open Settings.
5. Once Unknown sources is enabled, the user is shown an install confirmation dialog. The dialog lists the permissions requested by privileged apps.
6. If the user taps Install the app is installed.
7. Once the app has been installed, the user is given the option to Open the app and in Firefox Marketplace the Free button is replaced with a Launch button.

Subsequently the user will find the application in their Apps screen. In addition, the process to use and remove the app is the same as they'd expect for other Android apps. Firefox for Android provides a list of installed apps under Apps on the Tools menu as well.

Keeping apps up to date

Firefox for Android provides a mechanism installing update apps.

If your app is hosted, whenever you make a change on its server, users will pick up changes the next time they run your app.

For all other changes, you need to add a new version to the Firefox Marketplace:

• For a hosted app, the link to the app's hosting server containing the updated manifest file.
• For a packaged app, a zip file containing the updated app manifest and app content.

Firefox for Android makes a daily check on the version number in the app’s manifest and if it has changed silently applies the update.

Using Open Web Apps for Android from your own Marketplace

You're able to create your own Marketplace. Such a Marketplace consists of either a directory of apps in Firefox Marketplace or your own hosted content (app descriptions with the main manifest of hosted apps or the mini manifest with app zip archive in the case of packaged apps).

Your Marketplace will pass the URL of the manifest to be installed to Apps.install / Apps.installPackage that then invokes APK Factory, meaning you don't have to do anything to enable Open Web Apps for Android in your Marketplace. You do, however, need to ensure that your Marketplace only serves apps that include APIs supported by the Web Runtime for Android.

How the APK Factory works

This section describes how the APK Factory works.

• When the APK Factory is invoked, as described above, it determines whether there is a cached copy of the app's APK file. If a cached copy isn't available, APK Factory:
  1. Requests the app's manifest file from the hosting server (the Firefox Marketplace, or wherever else the app is hosted):
     • The main manifest in the case of hosted apps.
     • The mini manifest in the case of packaged apps.
  2. Detects whether the app is hosted or packaged.
  3. If the app is packaged, APK Factory requests the app's zip archive from the Marketplace or other hosting server.
  4. Creates the APK by performing some metadata transcoding for elements such as icons and security requirements, after which it:
     • Wraps the hosting URL in an Android Java container for hosted apps.
     • Wraps the app's content in an Android Java container for packaged apps.
  5. Passes the APK to be signed by the secure APK Signer service:
     • "Review" APKs are signed in Android debug mode.
     • "Release" APKs are signed with an APK signing key.
  6. Caches the signed APK.
• Delivers the signed APK file to the device for installation.

The following diagrams offer an alternative representation of the workflow of the APK Factory:

Package naming and APK signing keys

On installation of an APK the Android device checks the Java package name and signature. It verifies the signature the first time an app is installed (there is no central authority it checks with). Future updates must then have the same package name and signature. If the package name and signature aren't the same, the Android device won't update the installation.

Package naming

The package name for an APK consists of the hosting site and a unique serial number, for example:

• For a hosted app: org.mykzilla.p362b12c70d0556c124908a3c125d3d02:
• For a packaged app: com.firefox.marketplace.p0604c71abc0d4091829d19be9a50453c

APK signing keys

Each APK needs to be identified by an APK signing key before it can be installed on an Android device. APK signing keys are created and owned by the APK Signer service. These signing keys are sensitive, and stored securely in the APK Signer.

This service creates a unique key for each app, applying it to the original release and subsequent updates. The reuse of the key on updated app APKs is important, as without a match in the package name and key Android won't install an update over an earlier version of the app. If you create your own Marketplace, the APK will retain the same name and keys, so that either version will be able to update the other.

FAQ

Here are answers to some frequently asked questions about APKs for Open Web Apps for Android.

What about re-installation of apps installed as bookmarks?

When a user updates to Firefox for Android version 29 or later, their bookmark-style apps will continue to work, and Firefox will prompt users to update apps to their Open Web Apps for Android version.

How will in-app purchases work?

The APK is given access to the trusted UI, mozPay, and all payment processes for in-app purchases, so in-app payments will function as normal.

How do I download a copy of my app's APK?

You can download a copy of your app from the APK Factory service by retrieving a URL in the format:

https://controller.apk.firefox.com/application.apk?manifestUrl=ESCAPED_URL_TO_MANIFEST

where ESCAPED_URL_TO_MANIFEST is an escaped URL to the app's manifest or mini-manifest. That URL causes the APK Factory to return the cached copy of the APK, or create a new one if the app hasn't been submitted to Marketplace.

Examples

For a hosted app:

> wget https://controller.apk.firefox.com/application.apk?manifestUrl=http%3A%2F%2Fmykzilla.org%2Fapp%2Fmanifest.webapp -O mykzilla.apk

For a packaged app:

> wget https://controller.apk.firefox.com/application.apk?manifestUrl=https%3A%2F%2Fmarketplace.firefox.com%2Fapp%2Fa22e0277-35bc-434d-9371-1568c75fc726%2Fmanifest.webapp -O cuttherope.apk
 

Can I generate an APK manually from a different URL?

Yes, by providing the URL to any location for your manifest or mini-manifest files. However, be aware that because the APK is generated from a different URL, the package name will differ from that created when you submit the app to Firefox Marketplace, so the Firefox Marketplace version will be installed as a separate app.

If I setup my own copy of the APK Factory can I use the APKs it generates?

You can, but be aware that the signing keys will differ from those assigned to the APKs generated by Firefox Marketplace. As a result Android will refuse to install whichever version the user tries to install second. (See If I also have an Android native version of my app, can both be installed on an Android device? for more information.)

Can I submit an APK created by the APK Factory to Google Play or other Android store?

You can submit an APK generated by APK Factory to Google Play or an alternative Android store. However, it's your responsibility to:

• Confirm that your app complies with the policies of the store you're submitting it to. Approval for distribution in Firefox Marketplace doesn't imply any approval for Google Play or another Android marketplace.
• When you update your app you'll have to update the APK on any stores you have submitted the APK to; there is no automatic process to deliver updated APKs to Android stores.

Can I use my Android signing keys to sign the APK and choose the package name?

At present you cannot use your own signing keys to sign an APK generated by APK Factory or choose the package name. This is an option being considered. If this is of interest to you, join the discussion on the dev-marketplace mailing list, or the Marketplace IRC channel.

If I also have an Android native version of my app, can both be installed on an Android device?

Unless you choose to use the APK package name created by APK Factory for your native Android app, both can be installed on an Android device. If you choose to use the same package name for your native Android app (which you'll sign with your own key) Android will refuse to install whichever version the user tries to install second. This is because the package names are the same but the signing keys are different, so Android considers the apps to be the same, but from different sources. Therefore Android will refuse to update one app with the other, since that would allow one developer to override another's app. The user will end up with the first version installed on their device.

How can I test/debug APKs?

We're working on a toolchain for testing and debugging an app on an Android device. The initial version will include a Node-based command-line tool for generating an APK you can install on the device and debug using Firefox's Remote Developer Tools.

Also see

• Hacks blog: Firefox OS Apps run on Android
• Hack blog: Testing Your Native Android App