B2G/MarketCustomizations: Difference between revisions

From MozillaWiki
< B2G
Jump to navigation Jump to search
Line 132: Line 132:
* type: boolean,
* type: boolean,
* meaning: true to completely shutdown Cell Broadcast reporting.
* meaning: true to completely shutdown Cell Broadcast reporting.
Default settings are available in [https://mxr.mozilla.org/gaia/source/shared/resources/apn/operator_variant.xml operator_variant.xml].


=== support ===
=== support ===

Revision as of 07:00, 16 July 2013

Customization Overview

Since 1.0.1, Firefox OS use the same mechanism as firefox for customization.

You can download the gaia-distribution-sample.zip to check what can be done with build-time customization.

Below is the tree structure for customize-sample.zip: 

 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
 ├── sensors.json
 ├── settings.json
 ├── sms-blacklist.json
 └── support.json


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

Steps to Apply Customization

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

  1. unzip sample-customize.zip, assume path is <DISTRIBUTION_PATH>
  2. clone gaia source code from https://github.com/mozilla-b2g/gaia
  3. you can just put customization data to GAIA_DIR/distribution/
  4. or you can run command
   GAIA_DISTRIBUTION_DIR=<DISTRIBUTION_PATH> make

or 

   GAIA_DISTRIBUTION_DIR=<DISTRIBUTION_PATH> make production

To assign an specific folder for your customization.

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

Buildtime Customization

power/

customized power on/off animation or static image (can be mp4 for animation or png for static image)

Valid file names are:

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

ringtones

customized ringtones, define the ringtones in list.json

wallpapers/

customized wallpapers, define the wallapers in list.json

browser

customized bookmarks. Will overwrite init.json file in browser.app (further explained in runtime customization)

calendar

Calendar provider information. Specifying your own Google Oauth credentials is required.

we need `Calendar CalDav` API but not `Calendar` API, which is only available for whitelist developer. The limit is 1,000,000/day.

It means if vendors want to use their account to generate the API key, they need to applied this form first to get access permission to `Calendar CalDav` API https://developers.google.com/google-apps/calendar/caldav

After google add their account into whitelist, vendors are able to get Key for `Calendar CalDav`.


Steps:

1. (Use OEM's account) enter API console https://code.google.com/apis/console/b/0

2. create a project, enable `calendar caldev API` in `service` tab

3. click `API Access` tab

4. click `Create an OAuth 2.0 client ID`, Add Product name & logo (will shown in calendar google account authentication page)

5. select `Application type` to `Installed application`, `Other`, then create the key.

6. Click `edit settings` change `Authorized Redirect URIs` to 'https://oauth.gaiamobile.org/authenticated'

7. change client ID and Client secret to customize build's `calendar.json` file

contacts

customized contacts

costcontrol

customized costcontrol. Will overwrite config.json file in costcontrol.app

homescreens

list all bundled apps

sensors

sensor capabilities

settings

set 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

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.

Default settings are available in operator_variant.xml.

support

support contacts (include online support & tel support). Will overwrite support.json in settings.app

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

FYR: The build script is in build/applications-data.js

Runtime Customization

Bookmarks is the only app that support Runtime customization. To ship devices for multiple carrier or for a carrier serving across several regions, Manufacturer can configure several sets of bookmarks in customize folder. While the user first time use his browser, the browser bookmark will be initialized by MNC/MCC settings from SIM card . If SIM card is not inserted at first time user open the browser, the bookmarks will fallback to customized default bookmarks.

Bookmarks can be customized as default bookmarks, Carrier bookmarks(base on MCC), Carrier with region bookmarks(base on MCC+MNC). You can reference standard MCC/MNC code via http://en.wikipedia.org/wiki/Mobile_country_code

The bookmarks are organized in a json file. the first level key always with 6 digits. the default key is "000000", which denotes:

  • mcc:3 digits
  • mnc:3 digits, fill with leading zeros, fill '000' in MNC to provide the carrier default bookmark

customized bookmark looks like: 

   {
     "000000":{
       "bookmarks": [
         { "title": "Vivo Busca",
           "uri": "http://www.google.com.br/m/search?client=ms-hms-tef-br",
           "iconUri": "favicon.png"
         },
         { "title": "Serviços e Downloads",
           "uri": "http://vds.vivo.com.br",
           "iconUri":"favicon.png"
         },
         {
           "title": "Site Vivo",
           "uri": "http://www.vivo.com.br/conteudosmartphone",
           "iconUri": "favicon.png"
         }
       ]
     },
     "123001":{
       "bookmarks": [
       .....
       ]
     }
   }

Preload webapp

We currently have some gaia build-in apps and you might want to bundle more your apps in customization. If you want bundle app you developed, you can follow preload app management section to bundle those app. If you want bundle 3rd party webapp, you can contact the creator and ask for permission to bundle the webapp to your build. In Pre-bundled webapp section, we provide a script to help you pre-bundled webapp to your build.

Preload App management

we are planing to add preload apps to gaia build and choice apps from a configuration file in below bugs:

  • Bug 848064 - Gaia build process needs a better process for abstracting app directories
  • Bug 838098 - Install the apps, external apps in customization package

Pre-bundled webapp

Pre-bundled webapp are not quite the same as usual webapp, since Pre-bundled webapp may be seen before internet is ready. It have to store linked icon to buildin base-64 strings, provide correspondent matadata.json, prefetched appcache..., etc.

To package Pre-bundled webapp, we utilize the gaia-preload-app script that help build pre-bundled webapp from a given .webapp URL.


fetch a single webapp

Find a webapp URL that want to bundled with, and run the command: 

   $ python preload.py http://<webapp url>

It will generate a folder with target webapp name, ex `accuweather`.


batch process to fetch multiple webapp

You can form a list file that batched the process. The format is 

   Facebook,http://fa....
   Twitter,https://twi....

Put `preload.py` script with list file in the same folder, then run the command: 

   $ python preload.py

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

Pre-bundled webapp metadata.json format

Every Pre-bundled webapp should have a `metadata.json` within the `<app name>` folder. Marketplace counts on `metadata.json` file for auto-update.

The `metadata.json` can be auto generated by `preload.py` script.

`metadata.json` file is generated by the `manifest.webapp` and web server flags. `metadata.json` properties are

hosted webapp
  • origin: domain name from the webapp url
  • manifestURL: this is 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 webapp manifest etag used for checking for updates. etag value is retrieved by parse html header while download `.webapp` file from web server.
  • "removable": false, set true to make this app not removable from homescreen
  • "type": "certified", set type as "certified" to get extra permission. "previleged" type is not allowed for hosted webapp.
packaged webapp
  • origin: the origin will be 'app://<app name>' ex: '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 webapp manifest etag used for checking for updates. etag value is retrieved by parse html header while download `.webapp` file from web server.
  • packageEtag: save etag value contained in html header while fetching package from web server
  • "removable": false, set true to make this app not removable from homescreen
  • "type": "privileged", set type as "certified" to get extra permission; Set type as "privileged" to get highest permission of firefox os system.

packaged webapp update.webapp format

packaged webapp has a update.webapp file which is used for auto-update. The format is similar to manifest.webapp, but you have to explicitly address `package_path` and `size` attribute.

  • `package_path` is the path to the packaged(zip) file
  • `size` is package size
   {
   "name": "Game Pack",

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

Pre-bundled webapp Appcache format

If webapp defined the `appcache_path` in `manifest.webapp`. `preload.py` script will fetch the appcache file described in `appcache_path` and pre-fetched all resources described in the appcache file.

The Pre-bundled webapp appcache can be auto generated by `preload.py` script.

The translated file structure is: 

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

Note that the file structure is not the same as the appcache file described, but will be translated to gecko recognizable format. What ever name described in `appcache_path` should be renamed to `manifest.appcache` and saved into `cache` folder.

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
    • MMS message size limitation
    • MMS message retrieval mode
  • 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
    • 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, L10N is controlled by device configs (yet).
    • Category in the Firefox Marketplace specific to the carrier with your operator logo/name in the region.
    • Features apps / promotions in the Firefox Marketplace specified by the Carrier

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?
Retrieved from "https://wiki.allizom.org/index.php?title=B2G/MarketCustomizations&oldid=676566"