Firefox OS/Stingray/SmartScreen/

< Firefox OS‎ | Stingray(Redirected from FirefoxOS/Stingray/SmartScreen/)


Smart Screen

Smart Screen is comprised of smart-system, smart-home, app deck, device deck, tv deck, and dashboard. This document tells: how to run the smart-screen in Firefox Nightly and B2G, and the design of Card UI and smart-system.

Run in Firefox Nightly or B2G

clone the repo

Before building the code, we may need to clone the gaia repo with the following command:

 git clone

build the code

The smart screen is a type of TV. We have to use GAIA_DEVICE_TYPE=tv to tell build script to build for TV:


If you had built other builds before, we should suggest you to clean the profile folder:

 make clean

Please note we should have a folder called profile after the make finished and should have profile-debug if we also add DEBUG=1.

Run in Firefox Nightly

Unfortunately, Nightly is no longer a supported developing environment for B2G.

There were some issues in Firefox Nightly to prevent running Gaia in it in past few weeks. There is a new framework called Mulet which enables some missing modules for Firefox OS. We have to download the mulet enabled version, named firefox-36.0a1.en-US.xxxxxx, at:

It is easy to tell the difference between normal one or Mulet enabled one. We may find the default start-up path is chrome://b2g/content/shell.html . If you still get the empty search/url box, you are in normal firefox nightly.

The following is an example to run Smart Screen in Mulet:

 /Applications/ -profile /Users/hchu/gaia/profile

If we want to run the DEBUG build in Mulet, we may use the following commands to build gaia:


Issues in Mulet

  1. There is an issue with Mulet Mac version. We may find the totally black screen after opened. Please press reload to start the loading of shell.html and adaptive web design.
  2. The window size of adaptive web design is not configurable with Mulet. We cannot enlarge the window size to TV size, like 1080P.

Please find more information at .

Run in B2G Desktop

Running in B2G desktop is relative easy to Mulet. We may need to download the B2G desktop, named b2g-36.0a1.multi.xxxxxxx at:

Similar to mulet, we can run the Gaia in B2G desktop with the following command:

 /Applications/ -screen 1920x1080 -profile /.../profile

Issues in B2G Desktop

  1. The default orientation of B2G desktop is portrait. But we may expect the default orientation is landscape in TV. So, we may have a portrait clock app in B2G desktop.

Card UI

Card UI is the main feature of smart screen. It comprised of smart system, smart home, app deck, device deck, tv deck, settings app, browser app, and dashboard app. Bookmarks or short-cuts in smart home are CARDs. All decks has the ability to create a card to smart-home app. All decks and apps are normal app in smart-system app. Their relationships can be found as the following figure:

Relationships among apps

Smart Home

Smart home app is the default home app which hosts decks and cards. Smart home app is the owner of cards data store. It creates a card while a deck sends a mozActivity to smart home. And all decks will listen the change event or read the cards record of data store to determine if their cards are already created.

The card can be deleted from both deck and smart home. If card is asked to be removed from a deck, the deck sends a mozActivity to smart home app to remove it. If a card is removed from smart home, the deck may know it by read the record from data store or listen the change event of data store.

UX spec about unpin from app

As per the design of mozActivity, system app always opens a activity window for it. But card removed from deck app should not have a transition to smart home app, according to UX spec above. We may let data store be writable or send a mozActivity to smart system app and send an IAC message to smart home app to tell that. And this is a workaround to archive that. (THE WORKAROUND IS NOT DECIDED, YET)

Smart System

The smart system app is folk from phone's system app. We may find the smart-system app at {GAIA}/tv_apps/smart-system . The file custom-prefs.js is a pref file which overrides the default preferences in b2g. While booting, B2G reads b2g.system_startup_url, b2g.system_manifest_url and b2g.neterror.url to find the entry point of system app. So, we use the custom-prefs.js to switch to smart-system app in TV build, like:


The main difference between phone's system app and smart system app is we introduce landing app in smart system. Once the device booted, the first app shown to user is LANDING APP which can be any app users want. Smart system app reads a mozSettings, landing_app.manifestURL, to find out the landing app:

  "homescreen.appName": "smart-home",
  "landing_app.manifestURL": "app://"

Another difference is that smart system app removes lots ICC related modules, like icc, callscreen, dialer_agent, etc. We kept the whole window management, popups, dialogs, toast, orientation manager, sound manager, etc in smart system. Most of them are related to window management and background service. So, the smart system may boot a little faster than phone's system app.

According to UX/VD, we will change the behavior of window manager, including the landing app support, animations, launching position, etc. (THE DETAILED CHANGES IS NOT DECIDED, YET.)

Interactive Notification

We have Web Notification in Firefox OS. That is a notification with only one button, called click or open. According to UX/VD, we need an extra notification which support custom buttons, 0~2 buttons. This is Interactive Notification.

Interactive Notification handles all Web Notifications from all apps/webs. If an app wants to use custom buttons feature, it should be certified app because Interactive Notification only supports certified app. Apps can connect to "interactivenotifications" to get port. For showing a normal notification, please use the following message to do it:

     'type': 'notification',
     'message': {
       'title': 'notification title text',
       'text': 'this is a notification',
       'icon': ''
       'buttons': buttons
  • type: notification or alert-notification. If we want to show the alert notification, we should use alert-notification in this field.
  • message: the main message body.
    • title: the title of this notification (optional).
    • text: the body of this notification.
    • icon: the icon shown at this notification (optional). If apps don't specify this field, we will show a default icon.
    • buttons: custom buttons (optional). If apps doesn't specify this field, there is no button at this notification..


Decks are apps with the ability to PIN A CARD TO HOME and the pined cards are grouped by decks. All decks will be shown at smart home app by default.

Pin to Home

Flow of pin to home and unpin from home

A deck can use mozActivity to pin a card to home and should declare the data store permission to query if an launch path is pined as a card.

A launch path may point to the deck app itself or to another app's launch path. Like TV deck, it may pin a channel as a card whose launch path may the same as TV deck with hash included, ie: apps://, please find the following example:

 // From TV deck to pin a channel as a card
 new MozActivity({
   name: 'pin-to-home',
     data: {
       manifestURL: 'app://',
       launchPath: '/index.html#66',
       name: 'Channel 66 - HBO',
       thumbnail: ref-to-blob

Or app deck may pin an app as a card whose launch path may be apps://, like the following example:

 // From app deck to pin an app as a card
 new MozActivity({
   name: 'pin-to-home',
     data: {
       manifestURL: 'app://',
       launchPath: '/index.html',
       name: 'Other App',
       thumbnail: ref-to-icon

Consistent Context Menu

UX spec about unpin from app

As per UX spec above, we need a consistent pin/unpin menu among all decks. To achieve that, we use system context menu which is based on MENU tag. An example can be found at:

 <article contextmenu="ctxmenu">
 <menu type="context" id="ctxmenu">
   <menuitem label="Pin to Home" icon="/icons/pin-to-home.png"></menuitem>
   <menuitem label="Add as Favorite" icon="/icon/favorite.gif"></menuitem>