App development FAQ

App Development and publishing

What is an Open Web App, technically?

An Open Web App basically an HTML website or application, with some more functionality built on top of it. Think of Open Web Apps (OWA) as Web-standards-built applications or "Web runtime" applications. A Web runtime application runs outside a normal browser and can be launched from the desktop (or device equivalent) on any of the popular internet-connected devices. Of course, Web runtime applications can be run inside the browser too if the user prefers.

For an Open Web App, you can use:

• HTML5 as the declarative syntax to define the structure of the application's user interface.
• CSS3 as the declarative syntax to define layout, visual aesthetics and portions of the UI behavior. Using CSS3, you can custom-tailor the visual experience to any device that needs a specific presentation without having to re-implement structure or programmatic logic.
• JavaScript as the imperative syntax to implement logic to be executed on the client device.
• New technologies that are part of the HTML5 wave if not the HTML5 markup specification such as AppCache, WebStorage, WebSockets, WebWorkers, Server-Sent Events, Crypto API, etc.

When appropriate, you can augment Web runtime applications with server-side logic, for use when the user's device is in a connected state. Though Web runtime applications can run whether or not they can connect to the worldwide Web, you can offer an enhanced experience when connected. You can choose any server-side platform and technology that you like, since the application and the server communicate over HTTP/S using standard mechanisms such as JSON and XML.

I've already built a Web application. How do I make it into an installable app?

The steps ar generally quite simple. You can find an easy guide to the basics at Building apps for Firefox OS.

How can I protect business-critical assets/code?

Fact: Every bit of code on the client side can be "compromised". Developers need to understand and design accordingly.

You can make this harder via obfuscation with advanced compression (like Google closure compiler), and "bitcode"-style JavaScript generation via Emscripten and asm.js.

Some developers frown on JavaScript because native code requires obfuscation of source during compilation to run; JavaScript doesn't have to be obfuscated to run, but it can be, easily. Obfuscated JavaScript is analogous to compiled native code. Someone could de-obfuscate JavaScript just as they could de-compile compiled native code, but there's still a loss of information (spacing, comments, variable names) in both cases. And it is certainly possible for someone to analyze the obfuscated JavaScript code to fully understand what the code is doing, just as someone could analyze the bytecode of a compiled native binary; Rome wasn't built in a day, however.

For more detailed information and specific techniques, read Protecting your Firefox OS app code.

Can I have protected/encrypted storage on the phone for code/assets?

No, packaged apps are not encrypted. Developers can implement their own algorithms to store encrypted data but storing the secrets is another problem.

Why is the phone too slow to run my game?

Develop it with low-powered mobile phones in mind.

The best first step is to profile it maybe with the Firefox profiler or Webkit profiler, but this is better done through the phone.

General bottlenecks to avoid:

• Reduce/remove some optional "juice" (effects, particles, blending/composition, post processing)
• Don't scale images in your render loop with drawImage.
• Don't scale the oversized canvas down with CSS to fit device.
• Don't use heavy-weight libraries like Box2D, write physics to your own needs.
• Be aware of garbage collection and the pauses it can introduce while creating/destroying game entities, re-use object from pools.
• Use WebGL for rendering, Canvas still uses a lot of CPU!

For more information and specific code examples, read Optimizing your JavaScript game for Firefox OS.

How do I submit an updated version of my packaged App?

1. Go to the Firefox Marketplace
2. Sign in
3. View submissions
4. Click your app
5. Click "Manage Status & Version" on left
6. Click "Select a File..." under Upload New Version
7. Submit updated .zip file

Why doesn't my app update, even though I have updated the appcache manifest?

Please check if you send Cache Headers for your appcache manifest. If you don't, Gecko will use heuristic caching and will serve it from its cache for a few hours. We recommend that you configure an immediate expiration for your appcache manifest. The following Apache config will do just that:

AddType text/cache-manifest .appcache
ExpiresByType text/cache-manifest "access"

This might be a good idea for your webapp manifest too:

AddType application/x-web-app-manifest+json .webapp
ExpiresByType application/x-web-app-manifest+json "access"

How can I replace my hosted app with a packaged app?

You have to upload it as a new app and disable the old app. There is no upgrade path for users provided by Marketplace at the moment.

To get the same URL/slug for the new app:

1. Rename the old app's slug: Edit the listing page, click [Edit] on Basic Information and change the App URL, e.g. by appending -hosted
2. Delist the old app on the Manage Status & Versions page
3. Submit the new packaged app

How do I push a packaged app to a device?

The best way is to use the Firefox OS App Manager, which requires Firefox OS 1.2 or above.

You can also using the Firefox OS Simulator if needed:

1. Install the latest version of the Firefox OS Simulator Add-on in Firefox
2. Open the simulator through the Firefox Menu: Tools > Web Developer > Firefox OS Simulator
3. Add your app's manifest to the simulator dashboard (by pointing the simulator to either your hosted manifest or a local copy of it)
4. Connect the device
5. Make sure that remote debugging is enabled on the device (Settings > Device Information > More Information > Developer > check Remote Debugging)
6. With adb installed, run adb devices from the terminal and you should see your device listed. The simulator will recognize the device
7. Click "Push to Device" for your app

Device APIs and Capabilities

How can I do cross domain requests?

There are a few different potential solutions here:

• Proxy Server: Use a server to proxy all cross origin requests. This requires you to maintain such a server.
• JavaScript Object Notation with Padding (JSONP): This is good in many circumstances, but is vulnerable to CSRF, and disabled with CSP in privileged apps.
• Cross Origin Resource Sharing (CORS): This requires modified response headers, which you can’t control if it’s not your server. Enable CORS has some useful introductory information, and the MDN HTTP access control (CORS) page contains detailed guide and reference information. For installable apps, you need to set the origin property in your manifest to set packaged apps to a known origin.
• SystemXHR-enabled XHR: Installable apps require privileged type and systemXHR in manifest.webapp permissions. Initialize your XHR object with

  new XMLHttpRequest({mozSystem: true});

  This is a powerful permission and will get extra scrutiny during review, use with caution! See the MDN XMLHttpRequest page for more information.

How can I display a notification?

You can use system notifications on desktop Firefox, Firefox for Android, Firefox OS, Chrome and Safari. Read Using Web Notifications for a basic introduction, and Notifying users via the Notification and Vibration APIs for a more detailed example.

Note that the Notification API changed as of Firefox OS 1.2 (Gecko 26). See the Using Web Notifications Gecko notes for more specifics, and this example from the Firefox OS IRC app for a cross-version solution.

Can I get network speed or differ between wifi/mobile broadband?

Yes, when Network Information API lands. See bug 713199 for more information.

Marketplace Review cited my app for not opening links in a new window!

Your app will run in a chromeless runtime, without URL bar or navigation elements. When users navigate within your app to external websites, they can’t get back.

Within a running instance of a web app on Firefox OS, there is no browser chrome such as the navigation bar, refresh, home, or back buttons. It’s important then to make sure that usage of your app does not depend on these features. You can try disabling the browser chrome in Firefox by unchecking View > Toolbars > Navigation Toolbar and then navigating around your app. If you link to a site outside of your own, with no means to return, then the user must close the app and restart it just to go back. This is a poor user experience that we should try our best to avoid.

So how can we fix it? One way is to open all links to external domains in a new tab using the target="_blank" attribute. Find a target blank example. If you are not able to change all links, you can use an automated script that assigns the attribute on click. See also another example, which forces external links to open in a new window in Firefox OS.

How can I get push notifications?

Push notifications are available in Firefox OS 1.1 and above via the proprietary Simple Push API; note that the W3C Push API is now available on some platforms; Firefox OS should support this at some poin in the future.

How can I detect country/region and carrier from SIM card?

For privileged apps, the Mobile Connection API provides access to carrier and region codes; these need to be translated to the actual country codes. For a snippet that allows you to do this, look at Detect carrier and region from `mozMobileConnection`'s `MNC` and `MCC`.

How can I use a web activity to send an email?

Mozilla Hacks has an in-depth blog post about web activities, with technical details and several examples.

Specific example code:

new MozActivity({
    name: "new",
    data: {
           type: "mail",
           url: "mailto:?Subject=hello&body=world"
}
});

See also:

• Firefox OS boilerplate app
• Web activities guide on MDN

How can I share URLs through email?

This is not implemented correctly yet.

How can I open my listing in the marketplace?

Use web activities. See the Firefox Marketplace Web Activities guide for more specifics.

How can I detect whether an app is privileged or certified?

In your app, you can use Apps.getSelf() to get a DOMRequest object, and then onsuccess the request result will be an application object representing the app itself. You can then use the manifest property on the app object and the type property on the manifest to tell you if your app is privileged, certified, etc. An example follows:

var request = window.navigator.mozApps.getSelf();
request.onsuccess = function() {
    console.log("Your app's name is: " + request.result.manifest.name);
    console.log(request.result.manifest.name + " is a " + request.result.manifest.type + " app.");
};

How can my app detect that it is in the Web runtime?

There are a few ways you can check this:

• Use the navigator.mozApps.checkInstalled() function.
• Use the navigator.mozApps.getSelf() function.
• Use window.locationbar.visible. See Navigation.
• To detect if the app is running in Firefox OS, you can use code like this:
  https://github.com/mozilla/zamboni/blob/master/media/js/mkt/capabilities.js#L64

Media

How should I do media presentation?

Currently, for security reasons, the h.264 decoder on Firefox OS devices is only available to privileged code. Because of that, you can't use the <video> element to present h.264 content at this time. You can, however, use a Web Activity. Here's a code snippet that can help:

var activity = new MozActivity({
  name: "view",
  data: {
    type: [
      "video/webm",
      "video/mp4",
      "video/3gpp",
      "video/youtube"
    ],
    url: "https://example.com/myvideo.mp4"
  }
});

This asks Firefox OS to present the MP4 video at the specified URL. You can include one or more video format types in the type list to permit.

Do we support MP4/H264/MP3/AAC/etc?

Firefox OS and Firefox on Android support additional codecs through hardware playback.

Support summary:

• Video: OGG, WebM, MPEG 4 & H.264 (AAC or MP3)
• Audio: MP3, AAC, M4A, OGG Vorbis, WAV

Read Supported media formats for more detail.

We recommend H.264 and MP3 for Firefox OS as it’s using hardware playback and therefore will use less CPU and battery.

See also:

• Starting an activity
• Media presentation tips
• B2G limitations

How can I play music in the background?

This requires the audio-channel-content permission in manifest and setting the following property on audio objects/elements:

audio.mozAudioChannelType = 'content';

Permission is available to all apps.

This is subject to change in the future, as the behaviour is not well defined.

How can I store downloaded files to the phone?

The Device Storage API allows writing, reading and manipulation of files on the phones SD card, including access to the users music, videos and photos.

This API is privileged; it requires a packaged app and allows fine-grained permissions: see the device-storage:* permissions in our App permissions reference page.

Does Firefox OS Support HTTP Live Streaming (HLS)?

While HLS (HTTP Live Streaming) is a fantastic protocol, it's exclusive to Apple and Apple has taken no steps to standardize it other than an initial submission to the IETF. There is the possibility of using another transmission protocol, but requiring adaptive bitrate streaming; to this end, we have implemented experimental support for Media Source Extensions; you also have the options of streaming data over HTTP or WebSockets.

How can I have DRM for music/video?

We are evaluating the feasibility of EME.

Can I record video?

Yes, with MediaRecorder.

Debugging

How can I debug my app on the phone?

The best way is to use the Firefox OS App Manager, which is compatible with Firefox OS 1.2 and above.

Alternatively, Install ADB and run adb logcat (Remote Debugging and Console needs to be enabled on the phone’s Developer Settings). Remote debugging from Firefox will be enabled in later versions.

logcat output can be filtered (only showing console logs, JS errors and filter out CSS warnings):

adb logcat GeckoConsole:* *:F | grep -vE "parsing value|Unknown property|declaration|invalid source| but found |pseudo-"

Why is my App fast in the Simulator but painfully slow on the device?

Profiling results are very different between Desktop and phone, due to different Firefox versions and hardware. We recommend profiling on the device!

• Using Firefox built-in Profiler on device
• New Profiler for B2G (requires building and flashing)

Why is my app being killed right on start-up?

Your app got killed probably due to excessive memory use or memory spikes (Out-Of-Memory; OOM).

Causes:

• localStorage access causing memory spikes
• Loading and processing large images
• Memory leaks

How do I debug memory use and OOM?

Look for sigkill being sent to your app. The size is listed in pages (4 KB/page). This is done via

adb shell dmesg | tail -20

The following shows the memory usage of processes on the device, at a high level.

adb shell b2g-procrank

There is also a script available: get_about_memory, which gets about:memory information off the phone. It's the same info we get in the browser if you type about:memory into the location bar. This doesn't work on Windows.

Steps to investigate OOM crashes:

• Check adb shell dmesg to ensure that the crash is actually due to OOM. If it is, you'll see something about the LMK sending SIGKIL to the app process.
• Run get_about_memory every few seconds. Getting a memory report is not very expensive (if you don't have DMD enabled), so if you can get a memory report soon before the app crashes, we can get a lot of info that way.

For more information, read Debugging out of memory errors on Firefox OS.

Why do I get a different user agent?

Some websites are on a whitelist to send a different user agent. This is to force the website to serve the mobile website if it doesn’t recognize the B2G user agent.

Check if the website is on this whitelist.

Why does my app stop rendering on load without error?

This may be due to

• GPU Out Of Memory or Long-running script got stopped without notice (see bug 921519 for more details)
• View contains many scaled down images

How can I tell where my phone is going for updates?

Browse the phone storage using adb shell and look in:

• /system/b2g/defaults/pref/user.js
• /data/b2g/mozilla/[profile]/prefs.js

mozilla-central/b2g/app/b2g.js -> https://update.boot2gecko.org/[channel]/update.xml

Marketplace doesn’t launch or shows an error page

The time in your device probably isn’t set correctly. it is highly likely that it is still set to some date in 1980. The big year difference causes invalid HTTPS certificates.

Set the correct time, date and timezone in Settings > Time & Date

I accidentally uninstalled the Marketplace, how do I get it back?

To re-install the marketplace:

1. In the browser application on device go to the Firefox Marketplace
2. Click the gear icon in the top right to open settings
3. Change the region dropdown to Worldwide, hit ok, then Save Changes
4. After settings are saved, use the Marketplace search "marketplace" without the quotes
5. If you successfully changed your region to worldwide then Marketplace should be the first result
6. Click Free, then Install

What are useful commands during development?

In the commands below, the output is piped through colored-logcat, remove if not used.

Heavily filtered log (only JS logs and errors)

alias b2g-log='adb logcat GeckoConsole:* *:F | grep -vE "parsing value|Unknown property|declaration|invalid source| but found |pseudo-" | ~/bin/coloredlogcat.py'

Mostly log (no CSS warnings)

alias b2g-log-all='adb logcat | grep -vE "parsing value|Unknown property|declaration|invalid source| but found |pseudo-" | ~/bin/coloredlogcat.py'

Show running processes

alias b2g-ps='watch -n1 adb shell b2g-ps'

Restart B2G on device (faster than a power cycling)

alias b2g-restart='adb shell stop b2g && adb shell start b2g'

Edit device prefs (Sublime), store them and restart device

alias b2g-pref='adb pull /system/b2g/defaults/pref/user.js ~/Downloads/user.js && 
subl ~/Downloads/user.js --wait && 
adb shell mount -o rw,remount /system && 
adb push ~/Downloads/user.js /system/b2g/defaults/pref/user.js && 
adb shell mount -o ro,remount /system && 
adb reboot'

Why does my <meta name="viewport"> not work?

This is currently only supported in the browser and not in installable apps. For more information, read bug 830306 and bug 845690.

Why am I getting an "address wasn't understood" error or broken images with AngularJS?

If you have developed a packaged app with AngularJS, you may see a broken image or run into this error message:

The address wasn't understood 
Firefox doesn't know how to open this address, because the protocol (unsafe) isn't associated with any program. 

When you use Angular data binding to generate a URL, Angular will match the URL against its whitelist. If the URL does not match, Angular prefixes the url with "unsafe:" (see the Angular documentation). To make you app work with AngularJS, you can add "app:/"--the protocol FirefoxOS packaged apps use--to Angular's whitelist. In your app's configuration, this is how to whitelist "app:/":

var app = angular.module( 'myApp', [] ).config(['$compileProvider', function($compileProvider) {
        $compileProvider.urlSanitizationWhitelist(/^\s*(https?|ftp|mailto|app):/);
    }
]);

Or in AngularJS 1.1+

var app = angular.module( 'myApp', [] ).config(['$compileProvider', function($compileProvider) {
        $compileProvider.aHrefSanitizationWhitelist(/^\s*(https?|ftp|mailto|app):/);
        $compileProvider.imgSrcSanitizationWhitelist(/^\s*(https?|ftp|mailto|app):/);
    }
]);

Devices

How do I edit the preferences on the device?

These steps depend on Sublime Text being installed.

1. Pull the configuration file from the phone into your Downloads folder (edit target folder if needed):

   adb pull /system/b2g/defaults/pref/user.js ~/Downloads/user.js &&
   

2. Open the user.js file which is now in ~/Downloads/ in your favorite code editor to add or edit preferences.
3. Upload the file back to the phone and restart the main process:

   adb shell mount -o rw,remount /system &&
   adb push ~/Downloads/user.js /system/b2g/defaults/pref/user.js &&
   adb shell mount -o ro,remount /system &&
   adb reboot

If you have Sublime Text installed you can also execute this one-liner which pulls the file, opens Sublime, waits until you close Sublime and uploads the edited file back to the phone:

adb pull /system/b2g/defaults/pref/user.js ~/Downloads/user.js &&
subl ~/Downloads/user.js --wait &&
adb shell mount -o rw,remount /system &&
adb push ~/Downloads/user.js /system/b2g/defaults/pref/user.js &&
adb shell mount -o ro,remount /system &&
adb reboot

How do I update a Geeksphone Keon or Peak?

See Updating and Tweaking your Firefox OS Developer Preview phone/Geeksphone

The easy way: Geeksphone provide updates on a public download server:

1. Go to the Geeksphone download server.
2. Download the latest stable or nightly build for your device
3. Unzip the downloaded assets
4. Connect device
5. Enable remote debugging on device (Settings > Device Information > More Information > Developer > Remote Debugging)
6. Run ./flash.sh from the unzipped downloaded assets

The hard way: Replace app.update.url with B2G Nightly updates:

1. Grab and edit the user.js preferences from the phone (the following command uses Sublime, change if needed):

   adb pull /system/b2g/defaults/pref/user.js ~/Downloads/user.js &&
   subl ~/Downloads/user.js --wait &&
   adb shell mount -o rw,remount /system &&
   adb push ~/Downloads/user.js /system/b2g/defaults/pref/user.js &&
   adb shell mount -o ro,remount /system &&
   adb reboot

2. Find pref("app.update.url", "https://gpfos.s3.amazonaws.com/keon/update.xml");
3. Change the URL value to https://update.boot2gecko.org/nightly/update.xml
4. Save and close your editor, the previous command will put the updated prefs back and relaunch b2g

You can force OTA updates using Check Now in the Firefox OS Settings. Changes in user.js should be persisted between updates, but I am not sure.

The hardest way: Flash only gecko and gaia.

App Manifests

How can my app access device-level APIs?

Different APIs have different permission levels — See App permissions for more information. To use some APIs, you may need to declare them in the app manifest permissions field, declare them to be privileged/certified apps in the manifest type field, or more besides.

Why does my app need an app manifest?

The app manifest provides useful information about an app (such as name, author, icon, and description) in a simple document usable by both users and app stores. Most importantly, it will contain a list of Web APIs (such as geolocation) that your App needs. This allows users to make informed decisions about apps before installing them.

Is the Firefox OS manifest format the same as for Google Chrome extensions, or the W3C manifest?

No. The Firefox OS manifest uses a proprietary fomat that was developed early on out of neccesity. It hoped that in future Firefox OS will adopt the W3C manifest format.

Can Firefox OS apps be installed on other platforms?

Yes. They can be installed on Firefox for Android and Firefox Desktop 29+. For details of how, read these:

• Open web apps for Android
• Open web apps for Desktop

What is an origin?

The origin of an app is the protocol, domain, and port of the URL together. Each of the following URLs is a different origin:

• https://example.com
• https://example.com:8080 (different port)
• https://example.com (different protocol)
• https://www.example.com
• https://myapp.example.com (subdomain)

The following URLs are the same origin:

• https://Example.com:80
• https://example.com
• https://example.com/drawingApp

See Same-origin policy for more information.

Why do I have to host the app manifest at the same origin as my app?

We assume that only you can host an app manifest at the same origin as your app. This means your users can install your app with confidence, knowing that the installation is based on your app manifest and not someone else's. Users should have this confidence whether they're installing your app from Firefox Marketplace, from some other app store, or from your own website if you are self-publishing your app.

If the app manifest were not hosted at the same origin as the app itself, there would be nothing to prevent third parties from making apps directly out of content hosted at your origin. Even worse, third parties could create an app manifest using your branding that would trick users into installing an app that was a facade for stealing passwords or other improper behavior.

Does this mean I can't embed images or JavaScript from other origins?

No. The origin restriction is on content (HTML pages) only. Images and other embedded resources can be located elsewhere (for example, on a content delivery network), except for the app's icon, which must be served from the app's origin.

Can I have more than one app at one origin?

It used to be the case that you could not host more than one app at the same origin (Apps.install would fail with a MULTIPLE_APPS_PER_ORIGIN_FORBIDDEN error). However, the single-app-per-origin restriction has been lifted (see bug 778277) — this change was landed in Gecko 34, meaning that Firefox OS 2.1+, Firefox Desktop 34+ and Firefox for Android 34+ are able to install multiple apps from the same origin.

Note that allowing multiple apps at the same origin doesn't affect our permission model. Say we have three apps at example.com: A, B and C. All three apps have different permissions. If the user installs apps A and B, pages inside app A's context will have A's permissions, pages inside app B's context will have B's permissions, and no pages will have C's permissions.

However, there are some subtle security implications to consider. Any page uploaded to example.com might get navigated to by App A, App B, or App C. That means that such a page *might* potentially run with A's, B's, or C's permissions. So for example there is a chance that the user will install App A, and that App A might navigate to an uploaded page outside the app, in which case the page would run with As permissions, which might not be what the developer of App A expected.

So hosting an app with lots of permissions on the same server as other content that you don't expect to have the same level of permissions is a bad idea, especially if we are talking about apps that deal with sensitive data (e.g. credit card information, customer records.) This could lead to an exploitable vulnerability. You should follow the same security best practices as you would with regular web content — e.g. you would put a sensitive web app on its own domain anyway.

Why not just upload the app manifest directly to the Firefox Marketplace?

There are several benefits to hosting the manifest at your domain and providing the app manifest URL to the Marketplace:

• We intend that the Marketplace (and other app stores) will periodically revisit all the app manifests at the provided URLs and check them for updates. This avoids the need for you to re-upload your app manifest for each update.
• The Marketplace will pass both the original app manifest contents as well as its URL to the user's device. This allows the device to check for unexpected changes in the app manifest that might indicate tampering. This will be especially important for apps that use Web APIs (for geolocation for example).

Why does my Web server have to use the proper HTTP Content-Type header when serving my app manifest?

This restriction prevents users of a website that allows user-generated content (for example, a pastebin site) from inadvertently or inappropriately claiming that entire website as their app.

Should I use HTTPS to serve my app manifest?

Yes, it is a good idea. We anticipate that the Firefox Marketplace will require any app using Web APIs (such as Geolocation) to serve its app manifest over HTTPS as an additional defense against man-in-the-middle attacks. If you use HTTPS for your manifest, you must also use it for all the pages on your site.

What if someone else submits my app to the Firefox Marketplace?

In the unfortunate event that someone guesses the URL to your app manifest and submits it to the Firefox Marketplace before you do, please file a complaint with the Marketplace support team.