アプリマニフェスト

アプリマニフェストの作成

本項では、アプリマニフェストの作成、使用にあたって知っておくべき重要な事柄について解説します。

規約: ファイル名、場所、形式

• 名前: manifest.webapp (拡張子は必ず .webapp にしてください)
• 場所: アプリのルートディレクトリ
• 形式: JSON (有効な JSON 形式でなければなりません)

パスの扱い

• マニフェストやアイコンなどの内部パスは、アプリのルートではなく、アプリ配信元からの絶対パスでなければなりません。例えば、マニフェストが https://www.mysite.com/myapp/manifest.webapp にある場合、インストールパスは /manifest.webapp ではなく /myapp/manifest.webapp となります。
• 内部パスはアプリと 同一の配信元 から提供されるものでなければなりません。
• 外部パスは完全修飾パスでなければなりません。例えば、Firefox Marketplace に パッケージ型アプリ を登録していて、アイコンが独自サーバ上でホストされている場合、アイコンのパスは https://mywebapp/images/myicon.png のような形式になるでしょう。

Firefox Marketplace 登録時の必要条件

アプリを Firefox Marketplace で公開したい場合、アプリマニフェストには以下の項目を含める必要があります。

• name
• description
• launch_path (パッケージ型アプリのみ)
• icons (128×128 のアイコンが必須、512×512 のアイコンが推奨)
• developer
• default_locale (locales が定義されている場合)
• type (特権付きおよび内部 (公認) アプリのみ)

一般的な Open Web App の必要条件

Firefox Marketplace で公開しない一般的な Open Web App を作成する場合、アプリマニフェストには以下の項目を含める必要があります。

• name
• description
• icons (128×128 のアイコンが必須、512×512 のアイコンが推奨)

アプリマニフェストの検証

Firefox Marketplace にアプリを登録する場合、アプリマニフェストは Marketplace の検証に合格する必要があります。

あらゆるエラーの特定に役立つ アプリバリデータ を試してください。また この API を使って マニフェストを検証することもできます。

マニフェストの更新

アプリの更新に関する情報は アプリの更新 を参照してください。

マニフェストの例

以下が最小限のマニフェストです。これをテキストファイルへコピーし、それぞれの値を独自の情報に置き換えてください。

{
  "name": "マイアプリ",
  "description": "アプリの簡潔な説明をここに書きます",
  "launch_path": "/index.html",
  "icons": {
    "512": "/img/icon-512.png",
    "128": "/img/icon-128.png"
  },
  "developer": {
    "name": "あなたの名前もしくは組織名",
    "url": "https://your-homepage-here.org"
  },
  "default_locale": "ja"
}

アプリマニフェストの必須項目

マニフェスト内の項目は順序を問いません。ここに書かれていない項目がマニフェストに含まれていても無視されます。

name

人間が読み取れるアプリの名称。最長 128 文字。

配布後にアプリの名称を変更した場合、ユーザの端末にインストールされている既存のアプリについては名称が更新されません。

"name": "The Open Web!"

description

人間が読み取れるアプリの説明。最長 1024 文字。

"description": "Exciting Open Web App!"

launch_path

アプリの起動時に読み込まれる、アプリの配信元内でのパス。

そのパッケージ型アプリを含んだ ZIP ファイルを起点とするコンテンツの開始点を指定します。例えば launch_path が /mywebapp/index.html の場合、アプリの起動時に /mywebapp/index.html にあるファイルが開かれます。

"launch_path": "/index.html"

icons

アイコンの URI に対するアイコンサイズを示すマップ。

なお、アイコンへの内部パスはアプリ配信元からの絶対パスでなければならず、外部でホストされているアイコンへのパスは完全修飾パスでなければなりません。

アイコンは正方形で、.png 形式でなければなりません。アイコンには、その画像の 4 つの角すべてに広がる無地の背景を敷いてはいけません。

必須アイコンサイズ

128×128

Firefox Marketplace と端末上での表示に使われます。

推奨アイコンサイズ

512×512

Firefox 2.0 以降では、スマートフォンとタブレットの画面サイズ、画面解像度、3 列もしくは 4 列のレイアウトを含む様々な異なる組み合わせにおいて鮮明な表示を実現するため、より大きなアイコンが必要となります。512×512 のアイコンが推奨で、これは端末上のあらゆる使用箇所で自動的に縮小表示されます。このサイズは、Android など、アプリが対応する他のプラットフォームでの表示にも最適でしょう。

役に立つと思われる他のアイコンサイズ

60×60

Firefox OS 旧バージョンでの実機アイコンサイズ。

16×16、32×32、48×48、64×64、90×90、128×128、256×256

これらのアイコンは、Windows、OS X、Android など、アプリが対応する他の様々なプラットフォームで使用されます。

"icons": {
  "128": "/img/icon-1.png",
  "512": "/img/icon-2.jpg"
}

developer

• name: 開発者の名前。すべてのアプリマニフェストについて必須項目です。
• url: アプリの開発者についての情報を記載した Web サイトの URL。任意。

"developer": {
    "name": "The Open Web!",
    "url": "https://www.mywebapp.com"
}

default_locale

アプリマニフェスト内の項目の値に使用している言語を定義する言語タグ (RFC 4646)。

default_locale はロケールを持たないアプリについては必須ではないものの、常に含めることを推奨します。default_locale が定義されていない場合、Firefox Marketplace はアプリの言語を推測します。

例えば、アプリで英語を使用している場合、その default_locale は以下のようになります。

"default_locale": "en"

type

アプリの種類。これは慎重に扱うべき端末 WebAPI へのアクセスレベルを定義するものです。type が定義されていない場合、既定の type である web が使用されます。

• web: 通常のホスト型アプリ。この種類のアプリには WebAPI への最低限のアクセスが提供されます。
• privileged: Firefox Marketplace などのアプリストアによって承認された、認証済みアプリ。この種類のアプリには Web アプリよりも広範な WebAPI へのアクセスが提供されます。
• certified: スマートフォン上の既定通話アプリやシステム設定アプリなど、重要なシステム機能の提供を目的とした認証済みアプリ。これはアプリストアに登録されたサードパーティ製アプリに与えられる権限ではありません。この種類のアプリには WebAPI への最大限のアクセスが提供されます。

"type": "certified"

アプリマニフェストの任意項目

以下の項目は任意です。

activities

アプリが対応している一連の Web Activities を指定します (全一覧)。これは以下のような構造を取ります。

• この項目内の各プロパティはひとつのアクティビティです
• アクティビティ名は自由形式テキストです
• 各アクティビティはひとつのオブジェクトで表されます

以下は share というアクティビティを 1 つ含んだアクティビティ項目の例です。

"activities": {
  "share": {
    "filters": {
      "type": [ "image/png", "image/gif" ]
    },
    "href": "foo.html",
    "disposition": "window",
    "returnValue": true
  }
}

この例では、share アクティビティのオブジェクトは、filters、href、disposition、returnValue というプロパティを持っています。これらの意味は アクティビティハンドラの説明 に書かれています。

appcache_path

アプリケーションキャッシュ (AppCache) マニフェストへの絶対パス。Open Web App がインストールされる際、この AppCache マニフェストが取得、解析され、CACHE ヘッダ以下の静的ファイルがキャッシュされます。

"appcache_path": "/cache.manifest"

chrome

Firefox OS 1.1 ???

戻る、進む、再読み込み、お気に入りボタンを備えたナビゲーションコントロールを画面下部に追加します。

"chrome": { "navigation": true }

csp

この項目は、アプリ内の全ページに適用される Content Security Policy (CSP) を定義するために使用されます。CSP へ追加可能なポリシーの一覧は CSP ポリシー命令 に記載されており、アプリに関しては、以下のように 1 行でそれらを含める必要があります。

"csp" : "default-src *; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'"

Firefox OS 向けの特権付き、内部・公認アプリへ適用される既定のポリシーは以下のようになります。

特権付き CSP

default-src *; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'

内部・公認 CSP

default-src *; script-src 'self'; object-src 'none'; style-src 'self'

これらの規定値は上書きできず、追加のみ可能となっています。つまり、マニフェスト内の CSP ポリシーは、特権付き・内部アプリの場合に、実際に適用される CSP をより制約のあるものにするだけです。

datastores-owned

Data Store API を活用する場合、データを所有するアプリはその所有権を主張するため、datastores-owned 項目をマニフェストに含める必要があります。例えば、

"datastores-owned": {
  "myData": {
    "access": "readwrite",
    "description": "my data store"
  }
}

別々のデータストアを表すために複数のプロパティを含めることができ、各プロパティは readonly もしくは readwrite の access を使って、そのデータストアが他のアプリケーションから読み取り、編集可能であることを指定することができます。データストアの目的を説明するために description も含められます。

datastores-access

Data Store API を活用する場合、データにアクセスしたい所有者以外のアプリは、datastores-access 項目をマニフェストに含める必要があります。例えば、

"datastores-access": {
  "myData": {
    "access": "readwrite",
    "description": "Read and modify my data store"
  }
}

この項目が指定されていない場合、既定の動作は「アクセスなし」となります。ここでも、複数のデータストアにアクセスしたい場合は複数のプロパティを含めることができ、readonly もしくは readwrite の access を設定することで、そのアプリが必要とするアクセスの種類を宣言できます。

fullscreen

ランタイムがそのアプリを全画面モードで起動するかどうかを示します。

ほとんどのアプリが全画面で実行するため、これは true に設定することを推奨します。

"fullscreen": "true"

installs_allowed_from

アプリのインストール実行を許可するひとつ以上のサイトの URL。

この項目はエンドユーザが購入可能な有料アプリ向けです。この項目は開発者が商取引を持っているアプリストアを特定します。特に指定しないと、アプリはどこからでもインストール可能となります。

例えば、アプリを Firefox Marketplace からインストール可能とする場合、installs_allowed_from は以下のようになります。

"installs_allowed_from": [
  "https://marketplace.firefox.com"
]

注: 配列を ["*"] のような形式にした場合、このアプリのインストールはすべてのサイトに許可されます。これが既定値です。なお、空の配列 [] にした場合、自分のサイトを含め、すべてのサイトからのインストールを禁止することになります。

locales

マニフェストに含まれる項目値のひとつ以上のロケール固有の上書きを示すマップ。

各 locales エントリには、その特定言語で上書きしたいアプリマニフェストの項目一覧が含まれます。locales のキーは default_locale と同様の言語タグです (RFC 4646)。

例えば、アプリの既定言語が英語の場合、default_locale は en となるでしょう。そのアプリの name と description を イタリア語圏と日本語圏のユーザ向けに翻訳された name と description で上書きしたいという場合、locales 内のエントリは以下のようになるでしょう。

"locales": {
  "it": {
    "name": "L'Open Web",
    "description": "Eccitante azione di sviluppo web open!"
  },
  "ja": {
    "name": "オープン Web",
    "description": "エキサイティングな Open Web アプリ！"
  }
}

messages

アプリから捕捉可能とするシステムメッセージと、それらのメッセージが送信された場合に表示するアプリ内のページを指定します。

以下は Firefox OS 電話アプリの例です。電話の着信があるたびに (システムメッセージ: telephony-new-call) 端末は電話アプリのキーパッドを表示します (URL: /dialer/index.html#keyboard-view)。

"messages": [
  { "telephony-new-call": "/dialer/index.html#keyboard-view" }
]

moz-firefox-accounts

Firefox OS 2.0 ???

この許可設定は navigator.mozId API 使用時に Firefox Accounts の使用を許可します。詳しくは Firefox OS 上の Firefox Accounts を参照してください。

"moz-firefox-accounts": {}

orientation

アプリケーションの向きを固定する位置。

取り得る値の説明図:

値	アプリの固定位置
portrait-primary
portrait-secondary
portrait これを宣言した場合、-primary や -secondary を記述する必要はありません
landscape-primary
landscape-secondary
landscape これを宣言した場合、-primary や -secondary を記述する必要はありません

"orientation": [ "landscape-primary" ]

origin

Firefox OS 1.1 ???

パッケージ型アプリは app://UUID という特別な内部プロトコルを持ち、ここでの UUID はアプリがインストールされている各端末固有の文字列となります。現時点で UUID を簡単に取得する方法はありません。origin 項目は、各インストール済みアプリが使用する単独のドメイン名でこの UUID を置き換えられるようにするものです。

"origin": "app://mywebapp.com"

permissions

アプリが必要とする慎重に扱うべき端末 API のユーザ許可設定。例えばユーザの連絡先へのアクセスなどが該当します。WebAPI の許可設定と機能に関する完全な一覧 も参照してください。

各許可設定は以下のプロパティを必要とします。

• name: 許可設定の名称
• description: アプリがこの許可設定を使わなければならない理由
• access: 必要なアクセスレベル。readonly、readwrite、readcreate、createonly のいずれかを取ります。これが必要なのは Data Store など一部の API のみです。

以下は、端末の contacts と alarms を使用する許可設定が必要なアプリのマニフェスト項目の例です。

"permissions": {
  "contacts": {
    "description": "Required for autocompletion in the share screen",
    "access": "readcreate"
    },
  "alarms": {
    "description": "Required to schedule notifications"
  }
}

API は多数あり、その一部は特権付きもしくは内部 (公認) アプリのみに提供されています。例えば systemXHR を使用するには、以下のように type 項目が privileged に設定されていなければなりません。

  "type": "privileged",
  "permissions": {
    "systemXHR": {
      "description": "Required to download podcasts."
    }
  }

precompile

Firefox OS 1.4 ???

インストール時にコンパイルしたい asm.js コードを含む JavaScript ファイルへのパス。

インストール時のコンパイルによってインストール時間は長くなりますが、アプリの起動時間は短縮されます。

"precompile": [
  "game.js",
  "database.js"
]

redirects

アプリが外部プロセスの処理に使用する内部 URL。

例えば、Facebook の OAuth 認証を使って、ユーザの連絡先情報を取得するアプリもあるでしょう。認証が完了すると、サーバは通常、アプリ開発者があらかじめ指定した URL へアプリをリダイレクトし返します。パッケージ型アプリは Web 上でホストされていないことから、リダイレクト先として指定可能な正規の URL を持っていません。そこで、redirects 項目を使って、外部 URL を内部アプリ URL へリダイレクトします。

上記のシナリオでは、redirects 項目は以下のようになるでしょう。

"redirects": [
  {"from": "https://facebook.com/authentication/success.html",
    "to": "/app/main_interface.html"}
]

redirects によって宣言されるリダイレクトの範囲は、それを宣言したアプリ自体に制限されます。これは、複数のアプリが同じ公開 URL を独自のローカルリソースへリダイレクトできるようにするためであり、また特定のアプリケーションによる公開 URL のグローバルハイジャックを防ぐための措置でもあります。

role

この role 項目は主に Gaia エンジニアチームによる内部使用向けです。アプリがどのように B2G によって使用されるべきか、つまりシステム上の役割を指定することができます。例えば、キーボードなのか、ホームスクリーンを置き換えるものなのか、といったことです。

"role": "system",

以下のオプションがあります。

• system: アプリをホームスクリーン上で非表示にします。これは元々システムアプリの置き換え用でしたが、実際のところシステムアプリと同等ではなく、ユーザが直接使用しないアプリ (例えば Bluetooth アプリなど) を隠すためだけに使われています。
• input: 置き換え可能なキーボードとして設定アプリ上に表示します。またホームスクリーン上で非表示にします。
• homescreen: 置き換え可能なホームスクリーンオプションとして設定アプリ上に表示します。またホームスクリーン上で非表示にします。.
• search: ホームスクリーン上に表示しますが... (要更新)

version

マニフェストのバージョンを表す文字列。

この項目は開発者の便宜のために用意されているもので、ランタイムは使用しません。そのため version は任意の値を取ることができます。定義しておくことを推奨します。

"version": "2.1"

マニフェストの配信

アプリマニフェストはアプリと 同一の配信元 から配信する必要があります。

マニフェストはファイル拡張子 .webapp 付きで保存しなければなりません。また、Content-Type ヘッダを application/x-web-app-manifest+json として配信する必要があります。これは今のところ Firefox では必須ではありませんが、Firefox Marketplace では必須です。Firefox OS は、ユーザがインストールを実行したページの origin がアプリ自体の origin と異なる場合のみ、この確認を行います。Content-Security-Policy や X-UA-Compatible といった他のヘッダは必要ありません。

特定の攻撃リスクを軽減するため、SSL 通信を通じてマニフェストを配信することも可能です。マニフェストは HTTP 圧縮 で配信することもできますが、キャッシュされるべきではありません。

Firefox Marketplace へアプリを登録する場合、マニフェストの文字エンコーディングは UTF-8 とする必要があります。バイトオーダーマーク (BOM) は省略することをお勧めします。他のエンコーディングは、Marketplace では評価されませんが、Content-Type ヘッダの charset パラメータで指定可能です (例: Content-Type: application/x-web-app-manifest+json; charset=ISO-8859-4)。

ユーザエージェントは、可能な場合、アプリのインストールをユーザに確認する際、サイト識別情報と TLS ステータスを意味のある形で伝えます。

Apache からの配信

.htaccess ファイルに以下の行を追加します。

AddType application/x-web-app-manifest+json .webapp

.htaccess ファイルへの追加でうまくいかない場合、同じディレクティブを Apache の設定ファイルへ追加してみてください。設定ファイルは、OS の種類や構成によって、httpd.conf もしくは 000-default.conf のようなファイル名となっています。

IIS からの配信

web.config ファイルを編集する必要があります。これはおそらく Web サイトのルートディレクトリにあるでしょう。

<configuration> <system.webServer> <staticContent> セクションに新しい項目を追加する必要があります。

<remove fileExtension=".webapp" />
<mimeMap fileExtension=".webapp" mimeType="application/x-web-app-manifest+json; charset=UTF-8" />

nginx からの配信

設定ディレクトリにある mime.types ファイルを編集する必要があります。これはおそらく /etc/nginx/ か /opt/nginx/ にあります。

以下のような設定が見つかるはずです。最後の行を追加してください。

types {
  text/html   html htm shtml;
  text/css    css;
  text/xml    xml;
  application/x-web-app-manifest+json   webapp;
}

GitHub からの配信

マニフェストファイルを GitHub Pages から提供する場合、GitHub が自動的に application/x-web-app-manifest+json の Content-Type ヘッダで提供してくれます。

Python からの配信

Python がインストールされている場合は、Python を起動し、以下のコードを実行することで、ローカルディレクトリから簡単にサーバを実行できます。

import SimpleHTTPServer
import SocketServer
SimpleHTTPServer.SimpleHTTPRequestHandler.extensions_map['.webapp'] = 'application/x-web-app-manifest+json'
httpd = SocketServer.TCPServer(("", 3000), SimpleHTTPServer.SimpleHTTPRequestHandler)
httpd.serve_forever()

Rack (Ruby) からの配信

config/initializers/mime_types.rb に以下の行を追加します。

Rack::Mime::MIME_TYPES['.webapp'] = 'application/x-web-app-manifest+json'

仕様