市场自定义指南

定制概览

Requires Firefox OS 1.0.1

从 1.0.1 开始， Firefox OS 所采用的定制机制都是相同的。

We have created a full-featured Gaia distribution customization sample as part of the gaia repo: study this to learn first-hand what can be done with build-time customization. It will also be referenced in the article below.

Below is the tree structure for the customization sample:

  customize-sample
  ├── power
  │   ├── carrier_power_on.png
  │   └── carrier_power_off.png
  ├── ringtones
  │   ├── list.json
  │   └── ringer_dream_theme.ogg
  ├── wallpapers
  │   ├── customize.png
  │   └── list.json
  ├── browser.json
  ├── calendar.json
  ├── contacts.json
  ├── costcontrol.json
  ├── homescreens.json
  ├── network.json
  ├── sensors.json
  ├── settings.json
  ├── sms-blacklist.json
  ├── support.json
  ├── wapuaprof.json
  └── apps.list

We will discuss all these optional customizations in the sections that follow, but first let's see how to apply the customization to Gaia.

定制步骤

要将定制样例应用在 Gaia：

1. 从 https://github.com/mozilla-b2g/gaia 地址 Clone Gaia 源码
2. 你可以将  gaia/customization/ 文件夹拷贝到新的文件夹来进行你自己的本地化，或者是编辑  gaia/customization/ 文件夹本身。这个路径就是指下面所讲的  <DISTRIBUTION_PATH>; 将该目录更改为你自己的文件路径。
3. 通过 USB 附加在 Firefox OS 设备上，并检查是否它是否可以通过 USB  辨认
4. 构建 Gaia， 使用  GAIA_DISTRIBUTION_DIR 环境变量指定定制样例的位置，如下所示：

   GAIA_DISTRIBUTION_DIR=<DISTRIBUTION_PATH> make production

5. 现在就应该在你的 Firefox OS 设备上应用了你的定制的修改。

如果你将定制样例文件夹拷贝到了 gaia/distribution/， 就可以在没有指定环境变量运行 make 命令：

make production

构建时定制

Let's now go through the different options available in the sample.

power/

Custom power on/off animations (or static images) are included here. Files can be MP4 for animations or PNG for static images.

Valid file names are:

• carrier_power_on.png
• carrier_power_on.mp4
• carrier_power_off.png
• carrier_power_off.mp4

ringtones/

Custom ringtones are included here. list.json should contain the filenames of the ringtones, like this:

  {
    "ringer_classic_courier.opus": "",
    "ringer_dream_theme.ogg": "",
    "ringer_loud_windchimes.opus": "",
    "ringer_bitbounce.opus": ""
  }

Custom ringtones are selectable in the Firefox OS settings app through Sound > Ringer. The default ringtone must be set in settings.json, using DataURI, you can use datauri command which is available on node/npm, install it by npm install datauri -g and convert file to DataURI by datauri <FILE>

wallpapers/

Custom wallpapers (PNG files) should be included here and listed in list.json, after which they can be selected in the Firefox OS settings app through Display > Wallpaper.

The default wallpaper must be set in settings.json, using the following line:

"wallpaper.image": "image location"

browser.json

This file allows you to add customizations into the actual Browser app, such as bookmarks and default search engine. See the section Browser bookmarks & default search engine for more details on what to put in this file.

calendar.json

This file allows you to use your own custom calendars in the Firefox OS Calendar app. You'll need to specify your own Google Oauth credentials.  In addition, calendar CalDav API access is needed: To  generate the required API key and secret, you need to apply at Google's creating your client ID page; follow these instructions:

1. Open the API console.
2. Create a project and enable Calendar CalDav API in APIs & auth > APIs.
3. Click on Credentials.
4. Click on Create new client ID
5. Set the Application type to Installed application, and Installed application type to Other, then press Create Client ID. This should give you a Client ID and Client secret.
6. Open the calendar.json file, change the client_id and client_secret to the Client ID and Client secret you got from the Google API console, and save and close.

camera.json (Gallery and Camera app image sizes)

{
  "maxImagePixelSize": 6000000,
  "maxSnapshotPixelSize": 4000000,
  "requiredEXIFPreviewSize": {
    "width": 1200,
    "height": 1222
  }
}

maxImagePixelSize and maxSnapshotPixelSize are maximum pixel sizes of an image Gallery and Camera is allowed to view. Default to 5 mega-pixels (5*2²⁰ pixels; 5mp).

Optionally, you can also define variables to specify the minimum EXIF preview size that will be displayed as a full-screen preview by adding requiredEXIFPreviewSize property. If you do not specify this property then EXIF previews will only be used if they are big enough to fill the screen in either width or height in both landscape and portrait mode.

contacts.json

Contacts listed here will be included in the phone's contacts database as soon as Gaia is built.

Here's an example contacts.json file:

[
   {
     "name": ["John Doe"],
     "givenName": ["John"],
     "familyName": ["Doe"],
     "nickname": ["Johnny"],
     "category": ["Work", "Racing Team"],
     "email": [
       {
         "type": ["personal"],
         "value": "[email protected]",
         "pref": true
       },
       {
         "type": ["work"],
         "value": "[email protected]"
       }
     ],
     "adr": [
       {
         "type": ["personal"],
         "streetAddress": "123 Foopy St.",
         "locality": "San Francisco",
         "region": "Downtown",
         "postalCode": "94030",
         "countryName": "US"
       }
     ]
   },
   {
     "name": ["CarrierX"],
     "email": [
       {
         "type": ["work"],
         "value": "[email protected]"
       }
     ],
     "url": [
       {
         "type": ["work"],
         "value": "https://www.carrierx.com"
       }
     ]
   }
 ]

homescreens.json

homescreens.json defines what apps to show in the Firefox OS dock and homescreen, and in which order. By default the file looks like this:

{"homescreens": [
   [
     ["apps", "communications", "dialer"],
     ["apps", "sms"],
     ["apps", "browser"],
     ["apps", "camera"]
   ]
 ]}

This causes the four described apps to appear in the dock. If we added another array, that set of apps would appear on page 1 of the homescreen, the next set on page 2, etc.

{"homescreens": [
   [ // We're in the dock!
     ["apps", "communications", "dialer"],
     ["apps", "sms"],
     ["apps", "browser"],
     ["apps", "camera"]
   ],
   [ // We're on Page 1 of the homescreen
     ["apps", "email"],
     ["apps", "settings"],
     ["apps", "clock"],
     ["apps", "calendar"]
   ],
   [ // We're on Page 2 of the homescreen
     ["external-apps", "customapp1"],
     ["external-apps", "customapp2"],
     ["external-apps", "customapp3"],
     ["external-apps", "customapp4"]
   ]
 ]}

The first item inside each sub-array is the folder the app appears inside; the second is the app directory name.

Collections

Collections are groups of apps that have their own icon that appears on the homescreen. When this icon is tapped, a new screen appears containing all the icons for the apps in the collection. Have a look at the collections directory in the source code to get more of an idea of how these work.

By default, four Collections are prefilled on the first page of the Gaia homescreen: Social, Games, Music, and Entertainment. In homescreens.json it's possible to define what collections to load, what pages they should appear in and in what order. For example, if we wanted to specify these four default collections to appear, we would write this:

{"homescreens": [
   [
     ["apps/homescreen/collections", "social"],
     ["apps/homescreen/collections", "games"],
     ["apps/homescreen/collections", "music"],
     ["apps/homescreen/collections", "showbiz"]
   ], [
     ["apps", "communications", "dialer"],
     ["apps", "sms"],
     ["apps", "browser"],
     ["apps", "camera"]
   ]
 ]}

Each top level array position refers to a page of the homescreen. Here, the collections would appear in the dock, and the individual apps would appear on page 1 of the homescreen.

Collections can be chosen from the following list:

• showbiz: Discover entertainment apps.
• funny: Enjoy the latest funny apps.
• games: Play games online.
• local: What's happening around you?
• music: Listen to favorite songs.
• news: Keep updated with your world news sources.
• shopping: Follow shopping trends.
• social: Follow you social networks in everywhere.
• sports: The best apps about sports.
• tv: Apps related to media.

What collections contain

Collections are composed of two types of app.

Local apps are defined at build time by means of manifest files, located at /apps/homescreen/collections/<collectionName>/manifest.collection. The local apps contained within each collection are defined in the mainfest file. For example, the social collection (contains dialer, sms, contacts and email apps) manifest looks like so:

{
  "name": "Social",
  "role": "collection",
  "provider_id": "289", // adaptive search identifier
  "apps": [
    ["apps", "communications", "dialer"],
    ["apps", "sms"],
    ["apps", "communications", "contacts"],
    ["apps", "email"]
  ],
  "default_locale": "en-US",
  "icons": {
    "60": "/collections/social/icon.png",
    "90": "/collections/social/[email protected]",
    "120": "/collections/social/[email protected]"
  }
 }

Remote apps are supplied by the adaptive search provider at runtimee, when the device is online.

How to translate collections

Collection translations have to be defined in locale files in within the homescreen app, in the apps/homescreen/locales/. directory. Each different locale file has a name structure looking like collections.<langCode>.properties — where <langCode> is for example fr for French — and contains simple lines containing the default English string and translated version. An example from the French locale file follows:

# Add bookmark to homescreen
add-to-home-screen=Ajouter à l’écran d’accueil
add-to-home-screen-header=Ajouter un lien
website-name=Nom du site web
address=Adresse
added-to-home-screen=Ajouté à l’écran d’accueil

network.json (not in customization folder)

In Firefox OS < 1.4, this file can be created in gaia/apps/settings/resources, and it allows you to set the network types supported by the device. Firefox OS supports the following types:

• 'wcdma/gsm' (WCDMA preffered)
• 'gsm'
• 'wcdma'
• 'wcdma/gsm-auto' (GSM preffered)
• 'cdma/evdo' (CDMA preffered)
• 'cdma'
• 'evdo'
• 'wcdma/gsm/cdma/evdo' (Automatic)

An example is as follows:

{
  "types":  [
    "cdma/evdo",
    "cdma", "evdo"
  ]
}

sensors.json

Defines the sensor capabilities of the device. By default it contains:

{ "ambientLight": true }

You can set the value to false if you want to disable device sensor capabilities.

settings.json

This file allows you to set default wallpaper/ringtones, lockscreen enable/disable, bluetooth on/off, etc. You can consult build/config/common-settings.json to find out what settings can be set in settings.json;  for example you can set "wifi.enabled": false to disable wifi by default.

Customize default Homescreen APP

homescreen.appName allows you to set specific APP as default Homescreen APP.

{ "homescreen.appName": "homescreen-stingray" }

sms-blacklist.json

This file contains a custom SMS blacklist: numbers specified in this file can't have SMS message sent to them. This list will overwrite blacklist.json file in the SMS app. The numbers are specified in an array, like so:

["11223344", "55667788"]

cellbroadcast

Listening Channels:

• availability: runtime: Settings — ril.cellbroadcast.searchlist
• type: string
• valid format: \d(-\d)?(,\d(-\d))*

Disable event reporting:

• availability:
  • run time: Settings — ril.cellbroadcast.disabled
  • build time: Preference — ril.cellbroadcast.disabled
• type: boolean
• meaning: true to completely shutdown Cell Broadcast reporting.

support.json

This file contains support contacts, including online support & telephone support. When included, this file will overwrite support.json in the Settings app. Since these customizations will overwrite the default settings, if you want to keep default settings and add some extra resources you should copy those settings from the built-in apps and add your own customization onto them.

Here's an example of what the JSON should look like:

{
   "onlinesupport": {
     "href": "https://support.mozilla.org/",
     "title": "Mozilla Support"
   },
   "callsupport": [
     {
       "href": "tel:12345678",
       "title": "Call Support 1"
     },
     {
       "href": "tel:87654321",
       "title": "Call Support 2"
     }
   ]
 }

WAP user agent profile (wapuaprof.json)

The WAP user agent profile overrides the user agent information when sending WAP packets. If you want to override the default WAP user agent profile based on MCC/MNC, you can use this one to do it  (further explained in runtime customization).

apps.list

This allows you to specify which apps you want to load up at runtime (in a similar manner to variant.json, as explained in the Applications section below.) The applications are specified like so:

apps/*
external-apps/*
outoftree_apps/*

You can specify individual apps rather than whole folders of apps, like this:

apps/email
apps/settings

Other customization options

There are many other customizations that can be made, which we should explore more. Let's look at them now.

Browser bookmarks and default search engine

The default bookmarks and default search engine can be customised at build time, with different variants for each country and network in a single build. The customised data is inserted into the browser app the first time it is run, based on the MCC and MNC codes of the SIM card present in the device at the time.

The example below (browser.json) shows a configuration for Vivo in Brazil (724006, where 724 is Brazil and 006 is Vivo according to the MCC and MNC codes), along with a default fallback (000000) in case a non-matching SIM card or no SIM card is present.

content = {
   '000000': {
     'bookmarks': [
       { 'title': 'Mozilla',
         'uri': 'https://mozilla.org',
         'iconUri':
           'data:image/png;base64,AAABAAIAEBAAAAEAIABo[truncated]'
       },
       { 'title': 'Firefox OS',
         'uri': 'https://mozilla.org/firefoxos',
         'iconUri':
           'data:image/png;base64,AAABAAIAEBAAAAEA[truncated]'
       }
     ],
     'searchEngines' : [
        {
          'title': 'Google',
          'uri': 'https://www.google.com/search?q={searchTerms}',
          'iconUri':
            'data:image/png;base64,AAABAAIAEBAAAAEAIABoBAA[truncated]'
        }
      ],
      'settings' : {
        'defaultSearchEngine': 'https://www.google.com/search?q={searchTerms}'
      }
   },
 
   '724006': {
     "bookmarks": [
       { "title": "Vivo Busca",
         "uri": "https://www.google.com.br/m/search",
         "iconUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAC[truncated]"
       },
       { "title": "Serviços e Downloads",
         "uri": "https://vds.vivo.com.br",
         "iconUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACA[truncated]"
       },
       {
         "title": "Site Vivo",
         "uri": "https://www.vivo.com.br/conteudosmartphone",
         "iconUri": "data:image/jpg;base64,/9j/4AAQSkZJRg[truncated]"
       }
     ],
     'searchEngines' : [
        {
          'title': 'Yahoo',
          'uri': 'https://search.yahoo.com/search?q={searchTerms}',
          'iconUri':
            'data:image/png;base64,AAABAAIAEBAAAAEAIABoBAA[truncated]'
        }
      ],
      'settings' : {
        'defaultSearchEngine': 'https://search.yahoo.com/search?q={searchTerms}'
      }
   }
 };

In the example, if a Vivo SIM card from Brazil is entered on first run the user will see Vivo bookmarks and Yahoo as the default search engine. If another SIM card or no SIM card is entered on first run the user will see Mozilla bookmarks and Google as the default search engine. There are a few important parts to note:

• The defaultSearchEngine property must match the uri property of the search engine specified. This string acts as a template for the {searchTerms} placeholder, which will get replaced with the user's search query at run time. Other values such as search strings may be appended to the query string in the URL template.
• The favicon URLs shown are base64 encoded data URLs of the image data (truncated for brevity) rather than HTTP URLs. This is recommended so that the icons will still appear the first time the browser is run, even if the user has not connected to the Internet yet.
• Notice that multiple customisations can be applied for different networks and different countries in a single build, with a different 6 digit code representing each variant. The 6 digit code is constructed from the MCC code plus the MNC code, each padded with zeros to ensure it is 3 digits long.
• When populating the default data the browser will first look for an exact match with the MCC and MNC codes, then if there is no match it will look for MCC+000, and finally if there's still no match it will fall back to 000+000.
• When upgrading between versions of Gaia, new customisations will only be applied if that type of customisation is a new feature in the new version of Gaia being upgraded to. Previous customisations will not be overwritten.

Data and messaging settings

Device data and messaging settings are runtime customizable.

To apply specific settings, change gaia/shared/resources/apn/apns_conf_local.xml, simply adding or editing carrier blocks as required:

 <apn carrier="Test Network"
      mcc="001"
      mnc="01"
      apn="internet"
      user="user"
      password="password"
      proxy="127.0.0.1"
      port="8080"
      mmsc="https://127.0.0.1"
      mmsproxy="127.0.0.1"
      mmsport="8080"
      authtype="0"
      type="default,supl,mms"
  />

Voicemail and cell broadcast settings

To apply specific voicemail and cell broadcast settings, change gaia/shared/resources/apn/operator_variant.xml. Add or edit a carrier block, changing attributes as needed:

   <operator carrier="Test Network with Operator Variant Settings"
       mcc="001"
       mnc="01"
       cellBroadcastSearchList="0,1,2,3"
       voicemail="999999"
   />

WAP user agent profile

The WAP user agent profile is another app that supports runtime customization. It overrides the user agent information when sending WAP packets, based on MCC/MNC. The profile overriding has url and tagname parts, but we only support url in our current implementation.

The WAP user agent profile uses the same coding style for its key as the browser app, although "000000" is used as the default profile. An example follows:

   {
     "000000": {
       "url": "https://example.url/default.xml"
     },
     "123001": {
       "url": "https://example.url/custom123001.xml"
     }
   }

In this example, the url of the default profile is https://example.url/default.xml; for mcc = 123 and mnc = 001, the url is https://example.url/custom123001.xml. If there was another ic card with mcc = 123 and mnc=100, its url would be https://example.url/default.xml.

If the 000000 is removed from this example, like so:

  {
     "123001": {
       "url": "https://example.url/custom123001.xml"
     }
   }

the url of UA profile of ic card with mcc = 123, mnc = 001 is now overridden as https://example.url/custom123001.xml. No others will be overridden.

If we have the "000000" as before, but we also have a "123001" case with no url inside it, like so:

   {
     "000000": {
       "url": "https://example.url/default.xml"
     },
     "123001": {}
   }

All UA profile urls are now overridden as https://example.url/default.xml

Applications

Applications installed in Firefox OS can be customized at runtime, in a number of ways (see also Customizing the build-time apps). Perhaps the most powerful way is to edit the variant.json configuration file, which allows apps to be selectively installed and placed in the desired position in the homescreen, depending on the MCC/MNC. The customized applications will be added to the standard applications list.

The relevant part of the variant.json file typically looks like so.

   {
     "apps": {
       "puzzle":
         {
           "manifestURL": "https://owd.tid.es/store/packages/fe8e4a866c518a42db9d2041568684c1.webapp"
         },
       "store":
         {
           "manifestURL": "https://owd.tid.es/store/manifest.webapp",
           "installOrigin": "https://www.openwebdevice.com"
         }
     },
     "operators": [
       {
         "id": "movistar-co",
         "mcc-mnc": [
           "214-01",
           "214-02"
         ],
         "apps": [
           {
             "id": "store",
             "screen": 0,
             "location": 2
           }
         ]
       },
       {
         "id": "movistar-mx",
         "mcc-mnc": [
           "215-23"
         ],
         "apps": [
           {
             "id": "store",
             "screen": 0,
             "location": 2
           },
           {
             "id": "puzzle"
           }
         ]
       }
     ]
   }

• The first object of the JSON is called apps, and defines the custom applications to be copied at buildtime. The example uses two applications, one hosted (store) and one packaged (puzzle). Notice that while packaged apps only require the manifestURL, hosted ones also need the installOrigin in order to download them.
• The second object, called operators, is responsible of the configuration based on MCC/MNC. The object contains an array of objects for each MCC/MNC pair. These objects define the id of the operator, a MCC/MNC list for the configuration and a list of apps objects defining which applications are going to be installed at runtime in each case.
• Each apps object requires an id property and has two optional arguments to set the position in the homescreen:
  • The screen property sets the screen number.
  • The location property sets the position on that screen.

Support contacts, default contacts, wallpaper & ringtone

The same file variant.json file — used to configure applications at runtime depending on the MCC/MNC — also allows you to configure specific resources by adding some attributes under each operator object. Thus, an operator can have the following settings:

   { apps: ...
     "operators": [
       {
         "id": "movistar-co",
           "mcc-mnc": [
             "214-01",
             "214-02"
           ],
         "apps": [
           {
             "id": "store",
             "screen": 0,
             "location": 2
           }
         ],
         "support_contacts": "resources/support_contacts_movistar.json",
         "default_contacts": "resources/contacts_movistar.json",
         "ringtone": {
           "path": "resources/Movistar_Mid_ABR_128kbps.ogg",
           "name": "Tono Movistar"
         },
         "wallpaper": "resources/customize.jpg"
       },
       ...
   }

For each operator:

1. support_contacts specifies a path to a file containing contacts to be shown on the help screen (Settings > Help), offering the same functionality as support.json. The file format is:

      {
        "onlinesupport": {
          "title": "Mozilla Support",
          "href": "https://test.mozilla.org/support"
        },
        "callsupport1": {
          "title": "Call Support (Primary)",
          "href": "tel:14155550001"
        },
        "callsupport2": {
          "title": "Call Support (Secondary)",
          "href": "tel:14155550002"
        }
      }

2. default_contacts contains the path to a file containing contacts that will be preloaded to the Contacts application, depending on the MCC/MNC pair present at run time. The section names are the MCC/MNC pair, and section contents should be an array of contacts following the same format as contacts.json. For example:

       {
           "123123":
           [
               {name: ["John Doe"]},
               // etc
           ],
       }
   

3. ringtone sets the default ringtone and contains two attributes, both mandatory:
   • path: The path to the ringtone audio file.
   • name: The name to display when the ringtone is shown in settings.
4. wallpaper contains the path to the image file (PNG) that will be set as a default wallpaper.

Building Prebundled web apps

Earlier on, we discussed the apps.list file, and how this can be used to add built-in apps to your build. These apps need to be built in a certain way, then added to the gaia/external-apps directory.

To build Prebundled web apps, you can utilize our gaia-preload-app script, which builds a prebundled webapp from a given .webapp URL. It can accept hosted web app manifests, or packaged app mini-manifests.

To bundle a single web app

Find a .webapp URL that want to bundle, and run the command to bundle it, as follows:

python preload.py https://<webapp url>

This will generate a directory with the same name as the target webapp's name, e.g. accuweather.

Batch process to bundle multiple web apps

You can create a file called list, containing all the app names and .webapp locations you want to bundle all together in a batch. The format is:

    myFirstApp,https://www.firstapp.com/manifest.webapp
    mySecondApp,https://www.secondapp.com/manifest.webapp
    etc.

You need to save this list file in the same directory as our preload.py script, then run the following command:

    $ python preload.py

The preload.py script will parse the list file and do the batch conversion for you.

Prebundled web app metadata.json

Every Prebundled webapp should have a metadata.json file contained within its root directory. The Firefox Marketplace counts on this metadata.json file for auto-updating. This file is auto-generated by the preload.py script.

For a hosted webapp, the properties of metadata.json are:

• origin: The domain name from the webapp url.
• manifestURL: The location of the web app manifest for a hosted app.
• installOrigin(hosted): The location the app was installed from in the customization. For customizations, this should always be https://marketplace.firefox.com.
• etag: this is the webapp manifest etag used for checking for updates. The etag value is retrieved by the parse html header when downloading the .webapp file from the server.
• "removable": false; Set this to true to make this app not removable from the homescreen.
• "type": "hosted"; Set the type to hosted to get standard web permissions for your app. privileged and certified types are not allowed for hosted webapps.

For a packaged webapp, the properties of metadata.json are:

• origin: The origin will be app://<app name>, e.g. app://poppit.
• manifestURL: This should be the location of the mini-manifest. For customizations right now, the manifestURL will always be a mini-manifest from marketplace.firefox.com.
• installOrigin(hosted): The location the app was installed from in the customization. For customizations, this should always be https://marketplace.firefox.com.
• etag: This is the webapp manifest etag used for checking for updates. The etag value is retrieved by the parse html header when downloading the .webapp file from the server.
• packageEtag: This is the app package's etag, retrieved by the parse html header when downloading the package from the server once an update has been detected.
• "removable": false; Set this to true to make this app not removable from the homescreen.
• "type": "privileged"; Set the type to privileged to get extra permissions; set the type as certified to get the highest permission level available for Firefox OS system resources.

Packaged web app update.webapp format

Packaged webapps have an update.webapp file, which is used for auto-updates. The format is similar to manifest.webapp, but you have to include additional attributes:

• package_path is the path to the packaged (zip) file.
• size is the package size, in bytes.

  {
    "name": "Game Pack",
    "icons": {"60": "/icon-60.png", "128": "/icon-128.png"},
    "version": "1.1.2",
    "package_path": "/application.zip",
    "developer": {"url": "https://abc.com", "name": "abc Inc."},
    "release_notes": "2nd release",
    "locales": {"es": {"launch_path": "/index-es.html", "description": "show me customization."}},
    "size": 5460141
  }

Pre-bundled web app AppCache format

If your web app's manifest.webapp has an appcache_path included in it, the preload.py script will fetch the AppCache file  pointed to, and pre-fetch all the resources described in the AppCache file. The Pre-bundled webapp AppCache is a bit different, as Gecko recognizes a different format, but this is auto generated by the preload.py script.

The translated file structure is:

    <app name>
       ├── manifest.webapp
       └── cache
             ├── manifest.appcache
             └── <resources>

FAQ

The following is a list of common questions about market customizations, and their answers.

What can be customized?

• Brand
  • Start up & Power off animations
  • Network name on Lock screen and in Utility Tray.
  • First Run Experience logos
• Localization
  • Installed locales (shared/locales)
  • Default locale (GAIA_DEFAULT_LOCALE)
  • Default keyboard layouts (Multiple keyboards can be enabled, not tied to locale)
• Apps
  • Preinstalled third party apps (Handled by customize.py)
  • Home grid app placement (Handled by customize.py)
  • Licensing
  • In-app payment provider configuration
• Settings
  • Default screen brightness
  • Device Information — Model (name or #)
  • Device Information — Legal Information link or content
  • Help — Online support link
  • Help — Call support phone number
  • Help — User guide link
  • APN
  • MMS message size limitation
  • MMS message retrieval mode
• Media preloads
  • Wallpapers
  • Music
  • Videos
  • Gallery
• Sounds
  • Start up & Power off
  • Ring tone
  • Message tone
• Everything.me
  • Option to enable or disable the feature
  • Set of default categories and apps
• Browser
  • Default bookmarks
  • Default search engine

How and where do you define a customized app grid layout?

This is currently defined in gaia/apps/homescreen/js/init.json. customize.py takes care of building this in the correct format.

Is it possible to define whether an app is removable in the homescreen configuration?

No. All apps in /system/b2g are non removable, those in /data are removable. Since all preloaded apps come from /system, we need to move them to /data if we want them to be removable.

How do you add a preloaded packaged or hosted app to the build?

These should both be added to gaia/external-apps. customize.py will allow entry of the URL to a packaged app or a hosted app manifest, and will download it into the correct place and create metadata.json. This will serve as the "build step".

We have different metadata for packaged and hosted apps to distinguish them.

See Building Prebundled web apps for more details.

How do you prepare a preloaded hosted app for initial offline support?

You need to provide all the files to cache in the directory external-apps/MY_APP/cache, along with the AppCache manifest.

Again, see Building Prebundled web apps for more details.

What Marketplace Customizations Are Possible?

• On-device
  • The customization on the device regarding payments is limited to populating a whitelist of payment providers. There are a couple prefs for this, documented on Web Payments.
  • For example, Mozilla B2G phones will ship with our implementation of the payment provider in a whitelist so that it is accessible to the Marketplace and third party apps for in-app purchases via navigator.mozPay. Some more info on providers is available at Web Payment Providers.
  • If any carrier wants to implement their own payment processor and whitelist it, they are free to do so. However, the Firefox Marketplace is only configured to enable purchases through Mozilla's payment provider at this time.
• On-server
  • The merchant app sets a price point for the product and Mozilla's backend payment processor chooses the currency based on the user's network. None of currency, regional taxation, or L10N is controlled by device configs (yet).
  • Category in the Firefox Marketplace specific to the carrier with your operator logo/name in the region.
  • Featured apps / promotions in the Firefox Marketplace, specified by the Carrier.

There are many other considerations when adding a region or carrier.  See Adding Regions and Carriers for more details.

How do I package and store per-market customization changes?

Store only the files changed; currently these are in various locations in the filesystem. In B2G v2, we are considering consolidating these into a single location, similar to the branding directories we have for Gecko.

How do you build the product with a specific market's configuration?

Copy your changed files into a checkout of Gaia, and build using that modified Gaia. customize.py will provide a UI for setting relevant switches, create the appropriate files in the appropriate places in the gaia checkout, and then build the profile from that gaia.

How to customize power on / off animation?

• This animation uses Android's bootanimation.zip/desc.txt format.
• This lets us create multi-part animation sequences where we can specify things like size, framerate, and number of times an animation sequence loops for each part.
• There is also an animated PNG transition animation that bridges the gap between this bootanimation.zip sequence and the transition to the lockscreen, which is performed by Gaia.
• The size on disk of the default animation is 8.2MB (looping) + 3.6MB (frame 18 transition) = 11.8MB total.
• Currently, the shutdown animation is a custom css animation based on a design specified in bug 809342.