B2G/MarketCustomizations

Customization Overview

Since 1.0.1, Firefox OS provide more simpler way for build-time customization. (The next primary version will replace this by using same mechanism as firefox for customization)

At this time you can download the customize-sample.zip to check what can be done with build-time customization.

Below is tree structure for customize-sample.zip:

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

Note that all files are optional. If you don't provide that file, it will fallback to the system default settings.

Explanations

• browser: customized bookmarks. Will overwrite init.json file in browser.app
• contacts: customized contacts
• costcontrol: customized costcontrol. Will overwrite config.json file in costcontrol.app
• homescreens: apps arrangement. Will overwrite init.json file in browser.app
• power/: customized power on animation or static image (mp4 for animation and png for static image)
• ringtones: customized ringtones
• settings: default wallpaper/ringtones, lockscreen enable/disable, bluetooth on/off.. etc
• sms-blacklist: customized sms blocklist, blocks senders in this file. Will overwrite blacklist.json file in sms.app
• support: support contacts (include online support & tel support). Will overwrite support.json in settings.app
• wallpapers/ : customized wallpapers

​ Note that these customization will overwrite the default settings. So if you want to keep default settings and add some extra resources. You should copy the settings from build-in apps and add your own customization upon them.

Steps to Apply Customization

Here are steps to apply sample-customize.zip to gaia custom build:

1. unzip sample-customize.zip, assume path is <CUSTOMIZE_PATH> 2. clone gaia source code from https://github.com/mozilla-b2g/gaia 3. run command

   CUSTOMIZE=<CUSTOMIZE_PATH> make

or

   CUSTOMIZE=<CUSTOMIZE_PATH> make production

if you connected a firefox os device. Then you will get the gaia build with customization.

FAQ

(... means Donovan will fill in)

(Many variables will be handled by customize.py (815517))

What can be customized?

• Brand
  • Start up & Power off animations
    • ...
  • Network name on Lock screen and in Utility Tray.
    • (I think this is controlled remotely from the cell tower?)
  • 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
    • (What does this mean?)
  • 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
• Media preloads
  • Wallpapers
  • Music
  • Videos
  • Gallery
    • see make install-media-samples for example of how to populate these
• 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?

• It's currently 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 that are 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 app to the build?

• In gaia/external-apps
• Many 3rd party apps will not be added to the Gaia repo, so need to determine how to add them. Build step?
  • customize.py will allow entry of the URL to a packaged app or a hosted app manifest, and will download into the correct place and create metadata.json. This will serve as the "build step"

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

• They are also added to gaia/external-apps. We have different meta-data for packaged and hosted apps to distinguish them.

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, and the appcache manifest.

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 here https://wiki.mozilla.org/WebAPI/WebPayment#Testing
  • For example, Mozilla B2G phones will ship with our implementation of the payment provider (https://github.com/mozilla/webpay#readme) 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 here https://wiki.mozilla.org/WebAPI/WebPaymentProvider
  • 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
  • None of currency, regional taxation, L10N is controlled by device configs (yet). 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.
  • In the future we may have a device setting to store the user's preferred currency or something like that.
  • What is your operator logo/name in the region?
  • Who is point of contact for featured apps?

There are many other considerations when adding a region or carrier. See https://wiki.mozilla.org/Marketplace/AddingRegionsAndCarriers

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

• Store each of the files changed only.
• Currently these are in various locations in the filesystem.
• For v2, we should consolidate to 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 and then 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?

• Uses Android bootanimation.zip/desc.txt format.
• An explanation of this format can be found here: http://www.droidforums.net/forum/droid-hacks/33932-bootanimation-zip-file-explained.html
• 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.
• Size on disk of current animation: 8.2 mb (looping) + 3.6 mb (frame 18 transition) = 11.8 mb total
• Currently, the shutdown animation is a custom css animation based on a design specified in this bug: https://bugzilla.mozilla.org/show_bug.cgi?id=809342

Process Questions

• Is it better to have specific bugs for each app on a homescreen grid, or just one bug per layout per market?

• How to deliver/retrieve code for pre-loading? Manual delivery of assets, or suck it from a live app?
• Who owns gathering the values for these customizations from the carriers?
  • Karen Ward (Content Program Manager) owns it for Pre-installed Apps.
  • Remaining localizations/customizations?