There has been quite a bit of recent press about the upcoming Firefox OS mobile phone operating system. One of the interesting things about this new operating system is that the “apps” are basically HTML5 webapps, which makes converting Ryuzine to Firefox OS apps a breeze!
Get the Simulator
Before we go any further, make sure you are using the Firefox desktop web browser and point it to the Firefox Marketplace page for the Firefox OS Simulator. It’s a fairly large download for an add-on but it’s relatively simple to use.
When you install apps in the Simulator the “Dashboard” will tell you what kind of app it is – either a “Hosted” or “Packaged.” If you are trying to install a manifest for either kind and it there is a problem with it you’ll see it installed as a “Generated app” instead, meaning you need to fix your manifest file.
The simplest solution doesn’t require any work from you, the publisher. The Ryuzine webapps are already coded to support being bookmarked to the home screen on various devices where they act more like an installed app than a web page.
The images above show you a Ryuzine publication in the Firefox OS web browser. Press the star to bookmark it, select “Add to Homescreen,” edit the name (if necessary), and hit the “Add to Home Screen” button.
Generated apps appear with an automatically created icon. When you open them you’ll see they don’t go fullscreen (the status bar still shows and a small toolbar is at the bottom). The toolbar at the bottom gives you limited browser controls because, unlike bookmarking to the home screen on iOS, anything linked to within the publication will open within the Generated App context, not the web browser.
A hosted app for Firefox OS means you are hosting the content on a web server somewhere. If you are publishing with Ryuzine Press this is your only option for creating a Firefox OS app.
Create a manifest file
In order to tell Firefox OS that what is hosted at your site is a webapp you need to create a “manifest” file. This is just a simple text file and, if you’ve followed our tutorial on creating a Google Chrome Extension is pretty similar but not identical. Here is the bare minimum you need in your manifest file to make it work:
"name": "My App",
"description": "Description of your webapp goes here."
But you’re probably going to want a nice icon and maybe encode your publisher/developer info. We turned our own “Library” on this site into a hosted Firefox OS webapp with the following manifest file:
"name": "Ryuzine Rack",
"description": "The official Ryuzine newsstand at Ryu Maru",
"name": "Ryu Maru",
As you can see this one is a little more complex, but pretty self-explanatory. Firefox OS uses 60×60 and 30×30 icons so we just resized the existing ones, and if we ever submit it to the official Firefox Marketplace they require the 128×128 icon, so we’re all set!
The “launch_path” parameter is set to the root level (“/”) of the webapp URL. This would also be a good time to talk about an interesting requirement for a Firefox OS “Hosted” app – the “origin” of it. You can only have one app per origin! What that means is you can’t just put them in sub-folders under your main domain name, they have to be under their own sub-domains. So the following are NOT the same origin:
Even though they both point into the exact same folder they are not treated the same way by Firefox OS. So, using your webhost control panel make sure you create a subdomain for each webapp you want to host for Firefox OS or it will cause you problems. If you tried to reference each one in a sub-folder they are all considered part of the same origin. The subdomains make each origin unique.
The other important part is the “installs_allowed_from” parameter which, in our example, is still set to the default “[*]” which is a wildcard meaning “anywhere” (never, ever leave the brackets empty or it will disallow installation from everywhere, including your own site!). Ideally you could put the URL of your own site if you’re hosting it for installation, or your site and the Firefox Market if you submit it, or any other sites you want to authorize to host your manifest for “installation.” The primary purpose of this is to make sure only authorized sites can install and issue receipts for sales of your app, but the e-commerce component of Firefox OS apps is beyond the scope of this tutorial. If you want to know more about it read the MDN documentation.
The “default_locale” simply tells it that the main language is English (“en”) but if that’s not the case for your content change it to the code for your language. Note that it does not translate your publication’s text and should be the same as the language setting in the HTML file.
We included the optional “fullscreen” : “true” to make our Firefox OS webapp use all the available space, because we think it looks nicer. If you’d prefer that your webapp not hide the phone’s status bar omit this option.
Then you need to save it to the root location of your webapp, ideally with the filename “manifest.webapp” (though it can be more descriptive so long as it ends in .webapp). You can use Mozilla’s manifest validator to make sure it is formatted correctly, though it will really only inform you if there are errors or it passes validation. It doesn’t tell you what the error is or the line on which it occurs. If you’re not very familiar with these kinds of files you can use the JSONLint validator, which is far more detailed.
Lastly, though the manifest files are just JSON format your web server may need to be configured to properly deliver .webapp files.
Once all of those things are in place you can test your hosted webapp in the Firefox OS Simulator by providing the full path to the manifest. In the case of our Library this is http://library.ryumaru.com/manifest.webapp. In the Simulator, if you don’t see it change the button from “Add URL” to “Add Manifest” it isn’t recognizing your manifest file for some reason.
The packaged apps are nothing more than ZIP files containing all the assets. Since Ryuzine Writer can produce these packages for you it’s pretty easy to export your publications, except they’ll be missing the important manifest file! So you’ll have to unzip the package, add the manifest, and then re-zip it.
Ryuzine publications and newsstands don’t require any special permissions or use any Web APIs so you can create the simplest “Plain Packaged App” that doesn’t require or have enforced against it the Content Security Policy applied to “Priveleged” or “Certified” packaged apps, so we’re not going to cover adding a CSP to your package manifest.
For testing purposes we actually took the folder we used to create a packaged Chrome Extension of our “Add-Ons” manual supplement and all we did was duplicate and resize some icons and drop our manifest.webapp file into the folder:
"name": "Add-Ons Supplement",
"description": "Supplemental developer manual for Ryuzine Writer",
"name": "Ryu Maru",
You’ll notice the only major change was that we had to put the name of the HTML file in the launch_path (otherwise it would just show us a file list of what was in the package). Before we zip our package up again we can test it in the simulator by pointing the “Add Directory” to the manifest file in the unzipped package.
Submit to Firefox Marketplace
If you want to submit your Firefox OS app to the official marketplace (i.e., “app store”) there are specific guidelines in the MDN Documentation on how to do this. Remember, if you plan to charge for your app (which really only makes sense for packaged apps) you need to also purchase the Commercial Use License for Ryuzine from us. If you’re just giving your webapp away, though, that doesn’t cost anything.