Market customizations guide

カスタマイズ概要

Firefox OS 1.0.1 ???

Firefox OS は 1.0.1 以降、Firefox 同様のカスタマイズシステムを使っています。この記事に書かれている機能は特に明記されない限り Firefox OS 1.0.1 以降で動作します。

フルセットの Gaia ディストリビューションカスタマイズサンプルを Gaia リポジトリの中に用意しています。ビルド時のカスタマイズで何が出来るかするにはまずこれを直接触ってみるのが良いでしょう。この記事でもあとで言及します。

カスタマイズサンプルのディレクトリ構造は次の通りです:

  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
  ├── device-features.json
  ├── eu-roaming.json
  ├── homescreens.json
  ├── network.json
  ├── settings.json
  ├── sms-blacklist.json
  ├── support.json
  ├── wapuaprof.json
  └── apps.list

後に個々のカスタマイズについて説明しますが、まずはどのように Gaia にカスタマイズを適用するか説明します。

カスタマイズの適用手順

カスタマイズサンプルを Gaia に適用するには次のようにしてください:

1. Gaia のソースコードを https://github.com/mozilla-b2g/gaia からクローンしてください。
2. gaia/customization/ ディレクトリを別のディレクトリにコピーして自分でカスタマイズすることもできますし gaia/customization/ ディレクトリを直接書き換えることもできます。カスタマイズファイルを収めるディレクトリへのパスは下記の <DISTRIBUTION_PATH> で指定できます。任意のディレクトリパスを指定してください。
3. 必要に応じてサンプルを編集してください。
4. Firefox OS デバイスを USB ケーブルでコンピュータに接続し、ADB で接続できることを確認してください。
5. 次のように GAIA_DISTRIBUTION_DIR 環境変数を指定して Gaia をビルドしてください:

6. make production GAIA_DISTRIBUTION_DIR=<DISTRIBUTION_PATH>

7. カスタマイズが適用された Gaia を Firefox OS デバイスにインストールできます。

カスタマイズサンプルディレクトリを gaia/distribution/ ディレクトリにコピーした場合、環境変数を指定する必要はありません:

make production

ビルド時のカスタマイズ

それではサンプルに含まれているさまざまなカスタマイズ例を見ていきましょう。

power/

電源オン・オフ時のアニメーション (あるいは静止画) を含められます。ファイルは MP4 のアニメーションか PNG の静止画です。

次のような名前のファイルを用意してください:

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

ringtones/

カスタム着信音を含められます。次のように list.json ファイルで着信音ファイルのリストを指定します:

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

カスタム着信音は Firefox OS の環境設定アプリの サウンド > 着信 で指定できます。 デフォルトの着信音は DataURI を用いて settings.json で設定します。DataURI は node/npm の datauri コマンドで生成できます:

1. npm install datauri -g コマンドでインストールしてください。
2. datauri <FILE> コマンドでファイルを DataURI に変換してください。

wallpapers/

カスタム壁紙 (PNG ファイル) を list.json ファイルで指定すると、Firefox OS の環境設定アプリの 画面表示 > 壁紙 で指定できるようになります。

デフォルトの壁紙は次のように settings.json で指定してください:

"wallpaper.image": "image location"

browser.json

このファイルではブックマークやデフォルト検索エンジンなど、ブラウザアプリをカスタマイズできます。このファイルの書き方は ブラウザのブックマークとデフォルト検索エンジン をご覧ください。

calendar.json

このファイルでは Firefox OS のカレンダーアプリに独自のカレンダーを指定できます。Google OAuth credentials を指定する必要があります。加えて、カレンダーの CalDav API アクセスが必要になります。API キーとシークレットを生成するには、Google の creating your client ID ページに記載の通り、次の手順で操作してください:

1. API console を開いてください。
2. プロジェクトを開き APIs & auth > APIs で Calendar CalDav API を有効化してください。
3. Credentials をクリックしてください。
4. Create new client ID をクリックしてください。
5. Application type を Installed application に設定し、Installed application type を Other に設定し、Create Client ID. ボタンを押してください。Client ID と Client secret が表示されます。
6. calendar.json ファイルを開き client_id と client_secret に Google API コンソールで表示された Client ID と Client secret を入力して保存してください。

camera-config.js (Gallery and Camera app image sizes)

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

maxImagePixelSize と maxSnapshotPixelSize はギャラリーとカメラアプリで表示する画像の最大ピクセルサイズです。デフォルトは 5 メガピクセル (5*2²⁰ ピクセル) になっています。

requiredEXIFPreviewSize プロパティを追加すればフルスクリーンプレビューで表示されるための最小 EXIF プレビューサイズも指定できます。これを指定しなければ EXIF プレビューはランドスケープとポートレイト (横と縦) モード両方で (高さまたは幅が) 画面サイズ以上になる場合にのみ EXIF プレビューが使用されます。

contacts.json

Gaia ビルド時の連絡帳データベースに含める連絡先のリストを指定できます。

contacts.json ファイルのサンプルは次の通りです:

[
   {
     "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"
       }
     ]
   }
 ]

device-features.json

ハードウェアでサポートする機能を指定します。デフォルトは次の通りです:

{ 
  "ambientLight": true,
  "vibration": true 
}

各機能を無効化するには false を指定してください。

eu-roaming.json

EU のローミング規制に従うべきオペレーターのリストとその APN 設定が含められます。このファイルは 3 つの部分からなり、最初の home では規制に従うべきオペレーターのオペレーターコードを指定します。次の foreign ではローミング前に EU ローミング通知が表示されるべき海外オペレーターのオペレーターコードを指定します。最後の部分では EU ローミングの APN 設定を含めます。デフォルトファイルは次のようになります:

{
  "home": null,
  "foreign": null,
  "defaultApns": []
}

OS にローミング通知を表示させたい場合、次のような形でファイルを用意してください。この例では、ユーザがオペレーターコードが "001, 01" の SIM カードを使っていてオペレーターコード "002, 02" の海外ネットワークにローミング接続するときに  EU ローミング通知が表示されます:

{
  "home": {
    "001": {
      "01": true
    }
  },
  "foreign": {
    "002": {
      "02": true
    }
  },
  "defaultApns": [{
    "apn": "eu.apn",
    "types": ["default"]
  ]}
}

homescreens.json

homescreens.json では Firefox OS のドックとホームスクリーンに表示するアプリとその順序を定義します。デフォルトでは次のような感じです:

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

この設定ではドックに表示される 4 つのアプリを指定しています。配列を追加すると、ホームスクリーンの 1 ページ目に表示されるアプリ、次を追加すると 2 ページ目のものと順次設定できます。

{"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"]
   ]
 ]}

内側の配列の 1 つめの要素にはアプリが入っているフォルダ名 ("apps" や "external-apps" を、2 つめの要素にはアプリのディレクトリ名 ("email" や "browser" など) を指定してください。

コレクション

コレクションはホームスクリーンに独自のアイコンで表示されるアプリのグループです。そのアイコンをタップすると、コレクションに含まれるアプリのアイコン一覧を含む新しい画面が表示されます。デフォルトでどのようなコレクションが用意されているかは ソースコードの collections ディレクトリ をご覧ください:

• funny: 最新のオモシロアプリ
• games: オンラインゲームで遊ぶ
• local: あなたのいる場所に関するアプリ
• music: 好きな音楽を聴こう
• news: 世界の最新ニュースに注目
• shopping: お買い物を楽しもう
• showbiz: エンタメアプリを見つけよう
• social: どこでもソーシャルネットワーク
• sports: スポーツのベストアプリ
• tv: メディア関連アプリ

個別のディレクトリではいろいろな解像度のアイコンファイルと、名前や役割とアイコンへのパスなどコレクションのメタデータが定義されています。

homescreens.json ではコレクションをどのページでどの順番で読み込むか定義できます。例えば、shopping, social, sports および tv コレクションを表示したければ次のように指定します:

{"homescreens": [
   [
     ["apps/collection/collections", "shopping"],
     ["apps/collection/collections", "social"],
     ["apps/collection/collections", "sports"],
     ["apps/collection/collections", "tv"]
   ], [
     ["apps", "communications", "dialer"],
     ["apps", "sms"],
     ["apps", "browser"],
     ["apps", "camera"]
   ]
 ]}

最上部の配列はそれぞれホームスクリーンのページに対応しており、この場合はコレクションのドックに表示され、個別のアプリがホームスクリーンの 1 ページ目に表示されます。

コレクションには何が含まれるか

コレクションには 2 つの種類のアプリがあります。

Local apps は /apps/collection/collections/<collectionName>/manifest.collection のマニフェストファイルでビルド時に定義される物です。各コレクションに含まれるローカルアプリはマニフェストファイルで定義します。例えば、social コレクション (電話、SMS、連絡帳、メールアプリを含む) のマニフェストは次のようになります:

{
  "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 は適応検索のプロバイダにより実行時に、デバイスがオンライン状態の時に提供されます。

コレクションの翻訳方法

コレクションの翻訳はホームスクリーンアプリの apps/collection/locales/  ディレクトリにあるローカルファイルで定義します。各ロケールのファイルは collections.<言語コード>.properties のような名前規則になっており、<言語コード> は例えばフランス語なら fr、日本語なら ja などになります。内容はデフォルトの英語文字列と翻訳バージョンを書いた行が含まれる単純なファイルです。例えばフランス語のロケールファイルは次のようになります:

# 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

カスタムコレクション

Firefox OS 1.3 ???

Firefox OS 1.3 からは独自のカスタムコレクションを定義できます。単に collections ディレクトリ の中に追加し、上記のように collections.json でそれを指定してください。

垂直ホームスクリーンの設定

Firefox OS 2.0 以降では、従来の水平にページめくりするホームスクリーンではなく縦スクロールする垂直ホームスクリーン (vertical homescreen) を選択できます。垂直ホームスクリーンの設定は default-homescreens.json で、表示するアプリやコレクション、ホームスクリーンにアイコンを並べる列の数、ブックマークなどを指定できます。

network.json (カスタマイズフォルダにはありません)

Requires Firefox OS 1.4 or below

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 preferred)
• 'gsm'
• 'wcdma'
• 'wcdma/gsm-auto' (GSM preferred)
• 'cdma/evdo' (CDMA preferred)
• 'cdma'
• 'evdo'
• 'wcdma/gsm/cdma/evdo' (Automatic)

An example is as follows:

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

settings.json

• 一般的な設定: Firefox OS 1.0.1 ???
• ロケットバーのデフォルト検索エンジン: Firefox OS 2.0 ???

このファイルではデフォルトの壁紙、着信音、ロックスクリーンの有効無効、Bluetooth の有効無効などを指定できます。build/config/common-settings.json を見るとどのような設定が可能か分かります。例えば、WiFi をデフォルトで無効にするには "wifi.enabled": false などと設定できます。

カスタム設定は customization/settings.json で指定できます。

ロケットバーのデフォルト検索エンジン

Firefox OS 2.0 以降では、settings.json で次のような設定でロケットバーのデフォルト検索エンジンが指定できるようになります:

"search.urlTemplate": "https://www.google.com/search?q={searchTerms}",
"search.suggestionsUrlTemplate": "https://www.google.com/complete/search?client=firefox&q={searchTerms}",
"search.iconUrl": "data:image/x-icon;base64,AAABAAIAEBAAAAAAAAB9AQAAJ [TRUNCATED FOR BREVITY]

検索プロバイダのカスタマイズ

Firefox OS 2.0 ???

Firefox OS 2.0 以降ではデフォルトの apps/settings/resources/search/providers.json ファイルで検索プロバイダとアイコンファイルのリストを指定できます。ビルド時に customization/search/providers.json ファイルを書き換え、適切なアイコンファイルを同じディレクトリに含めることで変更できます。このディレクトリが存在するとビルド時に app/settings/resources/search の中身を上書きします。

デフォルトホームスクリーンアプリのカスタマイズ

homescreen.appName ではデフォルトのホームスクリーンアプリを指定できます。

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

sms-blacklist.json

このファイルには SMS のブラックリストを記載します: このファイルに書かれた番号には SMS メッセージを送信できません。このリストは SMS アプリ blacklist.json ファイルを上書きします。番号は次のように配列で指定します:

["11223344", "55667788"]

cellbroadcast

Listen するチャンネルを指定できます:

• 利用可能時: 実行時: Settings — ril.cellbroadcast.searchlist
• 型: 文字列
• 有効な書式: \d(-\d)?(,\d(-\d))*

イベントレポートを無効化できます:

• 利用可能時:
  • 実行時: Settings — ril.cellbroadcast.disabled
  • ビルド時: Preference — ril.cellbroadcast.disabled
• 型: 真偽値
• 意味: true にするとセルブロードキャストレポートが完全に無効化されます。

support.json

このファイルにはオンラインサポートや電話サポートなどのサポート先情報を記載します。このファイルがある場合、Settings アプリの support.json を上書きします。このカスタマイズファイルではデフォルト設定を上書きするため、デフォルト設定を残しつつサポートリソースを追加したい場合、組み込みのアプリからコピーして、それを元にカスタマイズをしてください。

JSON ファイルは次のようなものになります:

{
   "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 ユーザエージェントプロファイル (wapuaprof.json)

WAP ユーザエージェントプロファイルでは WAP パケット送信時のユーザエージェント情報を上書きできます。デフォルトの WAP ユーザエージェントプロファイルを MCC/MNC を元に歌が期したい場合などに利用できます (より詳しくは runtime customization をご覧ください)。

apps.list

このリストファイルでは実行時にどのアプリを読み込みたいか指定できます (後述する Applications セクションで説明している  variant.json と同様の形式です)。アプリケーションを次のようにして指定します:

apps/*
external-apps/*
outoftree_apps/*

フォルダ内のアプリ全部ではなく個別のアプリを次のように指定することもできます:

apps/email
apps/settings

その他のカスタマイズ設定

他にもカスタマイズできる項目が多くあるので紹介します。

ブラウザブックマークとデフォルト検索エンジン

• ブックマーク: Firefox OS 1.0.1 ???
• デフォルト検索エンジン: Firefox OS 1.2 ???

デフォルトのブックマークと検索エンジンはビルド時にカスタマイズ可能で、一つのビルドでも国やネットワーク (回線、キャリア) によって異なります。カスタマイズされたデータはブラウザアプリの初回起動時に、デバイスに挿入されている SIM カードの MCC と MNC に応じて読み込まれます。

下の例 (browser.json) ではブラジルの Vivo (724006 という値は 724 がブラジルを、006 が Vivo を MMC/MNC コードで表しています) での設定例です。SIM カードの値にマッチするものが無い場合や SIM カードが挿入されていない場合はデフォルトのフォールバック (000000) が使用されます。

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}'
      }
   }
 };

この例では、ブラウザ初回起動時にブラジルの Vivo の SIM カードが挿入されている場合、Vivo のブックマークが使用され、デフォルト検索エンジンは Yahoo になります。初回起動時に他の SIM カードが挿入されていたり、SIM カードが無い場合は Mozilla のブックマークが使用され、デフォルト検索エンジンは Google になります。以下の点については注意してください:

• defaultSearchEngine プロパティは指定の検索エンジンの uri プロパティと一致する必要があります。この文字列は {searchTerms} プレースホルダのテンプレートとして扱われ、実行時にユーザの検索クエリ文字列で置き換えられます。検索文字列など他の値が URL テンプレート末尾にクエリ文字列として追加されることもあります。
• 上に示す favicon URL は HTTP URL ではなく画像データを Base64 でエンコードした dataURI (長すぎるので省略しています) になります。 ブラウザの初回起動時、ユーザがインターネットに繋がっていなくともアイコンを表示するため、HTTP URL ではなく dataURL にすることが推奨されています。
• 単一のビルドでも複数のカスタマイズを 6 桁の数字のコードで指定されるネットワークや国に応じて適用できます。6 桁コードは MCC コードと MNC コードの組み合わせで、それぞれ桁数が少ない場合は 0 で埋めて 3 桁とします。
• 最初にデフォルト設定を適用するとき、ブラウザはまず MCC と MNC コードに正確に一致するものを探しますが、一致するものが無い場合は MCC+000 のものを探し、それもなければ 000+000 にフォールバックします。
• Gaia をバージョン間でアップグレードする場合、新しいカスタマイズはそのカスタマイズがアップグレード対象となる新バージョンの Gaia での新機能である場合にのみ適用されます。以前のバージョンで指定済みのカスタマイズは上書きされません。

Single variant customization to override list of providers and Rocketbar search provider

Firefox OS 2.0 ???

1. The default Rocketbar search provider and list of providers can also be customized per MCC/MNC — data added the first time the relevant SIM card is inserted into the phone — by specifying them in JSON files in your distribution directory:
   • The list of providers per MCC/MNC is specified in mobizilla_search.json in our customization sample:
   • The default Rocketbar search provider is specified in mobizilla_default_search.json in our customization sample.
2. variant.json then defines which .json file is used to specify the settings for each MCC/MNC pair; see lines 47–48 in our sample:

   "search": "mobizilla/mobizilla_search.json",
   "default_search": "mobizilla/mobizilla_default_search.json",

3. variant.json is placed in the root of your distribution directory.
4. In order to apply the single variant configuration you have to set the GAIA_DISTRIBUTION_DIR variable to the path of your distribution directory when building Gaia.

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 UA profile url of the ic card with MCC = 123 and 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 will now be 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.

Other single variant customizations

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",
         "keyboard": "resources/keyboard_movistar.json",
         "network_type": "resources/network_type_movistar.json",
         "known_networks": "resources/known_networks_movistar.json",
         "data_ftu": true,
         "sms": "resources/sms_movistar.json",
         "topsites": "resources/topsites_movistar.json",
         "bookmarks": "resources/bookmarks_movistar.json",
         "data_roaming": true,
         "power": {
           "poweron": {
             "video": "app://operatorresources/resources/power/latam_power_on.mp4"
           },
           "poweroff": {
             "video": "resources/latam_power_off.mp4"
           }
         },
         "nfc": true
       }        
       ...
     ]
   }

And here are the details of the specific resources for each operator.

Support contacts

Firefox OS 1.2 ???

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"
     }
   }

Default contacts

Firefox OS 1.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
        ],
    }

Ringtone

Firefox OS 1.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.

Wallpaper

Firefox OS 1.2 ???

wallpaper contains the path to the image file (PNG) that will be set as the default wallpaper.

Keyboard settings

Firefox OS 1.4 ???

keyboard contains the path to a file containing keyboard settings configuration information. The file format is as follows:

 {
   "keyboard.vibration": true,
   "keyboard.autocorrect": false,
   "keyboard.clicksound": true,
   "keyboard.wordsuggestion": false
 }

Network Display Indicator

Firefox OS 1.4 ???

network_type contains the path to a file that will hold an associated text that will be shown to the user when that network is being used by the device — for each of the network types supported by the device. The text will be shown on the Settings app, status bar, and quick settings.

The status bar and all the occurrences on the Settings app will use the text value indicated in the file. For quick settings the file must contain a data_sprite key that will point to a css sprite holding the icons for all the supported network types.

The data_sprite key must always be a URL pointing to a preinstalled app on the device. A file format example follows:

 {
  "lte": "4G",
  "ehrpd": "4G",
  "hspa+": "H+",
  "hsdpa": "H",
  "hsupa": "H",
  "hspa": "H",
  "evdo0": "E",
  "evdoa": "E",
  "evdob": "E",
  "1xrtt": "1x",
  "umts": "3G",
  "edge": "E",
  "is95a": "2G",
  "is95b": "2G",
  "gprs": "2G",
  "wcdma/gsm": "2G/3G GSM auto",
  "gsm": "2G GSM",
  "wcdma": "3G GSM",
  "wcdma/gsm-auto": "2G GSM Preferred",
  "cdma/evdo": "2G/3G CDMA auto",
  "cdma": "2G CDMA",
  "evdo": "3G CDMA",
  "wcdma/gsm/cdma/evdo": "2G-3G GSM/CDMA auto",
  "data_sprite": "app://operatorresources/resources/quick_settings/images/data-sprite-latam.png"
 }

Pre-populate WiFi SSIDs

Firefox OS 2.0 ???

known_networks contains the path to a file containing descriptions of known wifi networks. Here is a file format example:

 {
  "OPEN": {
    "ssid": "OPEN"
  },
  "WEP-WITHOUTKEY": {
    "ssid": "wifi-WEP-WITHOUTKEY",
    "keyType": "WEP"
  },
  "WEP_KEY": {
    "ssid": "WEP-KEYOK",
    "keyType": "WEP",
    "capabilities": "",
    "password": "constrasenya1"
  },
  "WEP_KEYOK_WPS": {
    "ssid": "WEP-KEYOK-WPS",
    "keyType": "WEP",
    "capabilities":"WPS",
    "password": "constrasenya1"
  },
  "wpa": {
    "ssid": "macaFirefoxHotspot",
    "keyType": "WPA-PSK"
  },
  "WPA-PSK_KEY": {
    "ssid": "WPA-PSK-KEYOK",
    "keyType": "WPA-PSK",
    "capabilities":"",
    "password": "constrasenya1"
  },
  "WPA-PSK_KEY_WPS": {
    "ssid": "WPA-PSK-KEYOK-WPS",
    "keyType": "WPA-PSK",
    "capabilities":"WPS",
    "password": "constrasenya1"
  },
  "WPA-EAP-PSK_WITHOUTEAP": {
    "ssid": "WPA-EAP-WITHOUTKEY",
    "keyType": "WPA-EAP"
  },
  "WPA-EAP_SIM": {
    "ssid": "WPA-EAP-SIM",
    "keyType": "WPA-EAP",
    "eap": "SIM",
    "password": "constrasenya1"
  },
  "WPA-EAP-KEYOK-WPS": {
    "ssid": "WPA-EAP-KEYOK-WPS",
    "keyType": "WPA-EAP",
    "eap": "PEAP",
    "capabilities": "WPS",
    "password": "constrasenya1",
    "identity": "HI\\usr"
  },
  "WPA-EAP-KEYOK-CAPOK-PHASE2-OK": {
    "ssid": "WPA-EAP-KEYOK-CAPOK-PHASE2",
    "keyType": "WPA-EAP",
    "eap": "PEAP",
    "capabilities":"WPS",
    "phase2": "PAP",
    "password": "constrasenya1",
    "identity": "HI\\usr"
  }
 }

Data enabled/disabled by default during FTU

Firefox OS 2.0 ???

The data_ftu attribute defines if the data setting is enabled or disabled by default during FTU. This is a boolean value (true or false).

Maximum number of SMS to convert to MMS

Firefox OS 2.0 ???

sms contains the path to a file holding some customization details for SMS. Currently the only attribute that can be set is the maximum number of SMS messages that can be converted to MMS. A file format example follows:

 {
  "smsMaxConcat": 9
 }

Pre-populate browser top sites

Firefox OS 2.0 ???

topsites contains the path to a file containing an array of topsite objects. A topsite object has three parameters: the title (string), the uri (url) and the iconPath. Here is a file format example:

{
  "topsites": [
    {
      "title": "Movistar",
      "uri": "https://www.movistar.es",
      "iconPath": "resources/movistar.ico"
    }
  ]
}

Bookmarks

Firefox OS 2.1 ???

bookmarks contains the path to a file containing an array of bookmark objects. The bookmark object has three parameters: the title (string), the uri (url) and the iconPath. File format example:

{
  "bookmarks": [
    {
      "title": "Google",
      "uri": "https://www.google.es",
      "iconPath": "resources/google.ico"
    }
  ]
}

Data roaming on/off by default

Firefox OS 2.0 ???

The data_roaming attribute defines if data roaming is enabled by default; its value is a boolean (true or false).

Power on/off operator animation

Firefox OS 2.0 ???

Custom power on/off animations are configured using an object as a value for the power attribute. The object contains two attributes, one for the boot animation when the device is switched on (poweron) and the other one for the animation when the device shuts down. Both attributes are configured with a key value identifying the resource to be loaded — the resource key should be video and the value is a path to the resource. Note that the path can be a local path to the resource in the build machine filesystem (for example resource/afile.png) or a URI to file inside a Gaia application that will be installed in the device (for example app://name.domain/path/to/video.mp4).

Here is an example of the full structure of a power object:

"power": {
  "poweron": {
    "video": "app://operatorresources/resources/power/latam_power_on.mp4"
  },
  "poweroff": {
    "video": "resources/Power_off_test.mp4"
  }
}

NFC enabled/disabled by default

Firefox OS 2.0 ???

The nfc attribute defines if Near Field Communication is enabled by default; its value is a boolean (true or false).

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 preload-app-toolkit 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 of 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.
• external: This is a required field in Firefox OS 2.1+. The value is true for prebundled apps, and false for non-external apps. This is used for checking if fine tuning the file order in the application.zip is necessary (fine tuning will occur if the value is set to true).

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

• 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.
• external: This is a required field in Firefox OS 2.1+. The value is true for prebundled apps, and false for For non-external apps it should be false. Use for checking if fine tunining file order in the application.zip is needed ( fine tune if the value is true ).
• 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.

Packaged web app auto-updates: 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
       ├── metadata.json
       └── cache
             ├── manifest.appcache
             └── <resources>

FAQ

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

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
  • Home grid app placement
  • 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.

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 can be 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 バグ 809342.