本文へ移動
Engineer
メニュー
デザイン
日本語

Engineer / 用語集

ウェブアプリマニフェスト

サイトをインストール可能なアプリとして記述するJSONファイル

どのようなものか

ウェブアプリマニフェストは、ウェブサイトをアプリケーションとして記述するJSON文書です。名前、起動時に開くアドレス、アプリに含まれるアドレスの範囲、ウィンドウの表示方法、アプリを表す画像を指定します。ページは、link要素のrelにmanifestを指定して、このファイルを指します。インストール機能を持つブラウザーは、それを読み、インストールするアプリの内容を決めます。定義元のW3C仕様も、普段の会話でも、単にマニフェストと呼ぶことが多くあります。

ファイル自体は通常のJSONです。登録されているメディアタイプはapplication/manifest+json、拡張子は.webmanifestですが、仕様はJSONのメディアタイプなら受け付け、多くのサイトはmanifest.jsonを配信しています。すべてのメンバーは省略可能です。架空の潮汐表サイト向けの、小さな例を示します。

{
    "name": "Harbour Tide Tables",
    "short_name": "Tides",
    "start_url": "/tides/",
    "display": "standalone",
    "background_color": "#ffffff",
    "icons": [
        {
            "src": "/icons/tides-512.png",
            "sizes": "512x512",
            "type": "image/png"
        }
    ]
}

見た目とは別に、アプリそのものを決めるメンバーが3つあります。start_urlは、インストールしたアプリの起動時に開くページの候補です。ブラウザーは無視しても、利用者による変更を認めても構いません。scopeは、アプリの内側とみなすアドレスの範囲です。省略した場合、仕様は起動URLからファイル名、クエリ、フラグメントを除いたものを使うため、上の例では/tides/配下全体がアプリに含まれます。idはアプリの識別情報で、省略すると起動URLを使います。相対指定のアイコンのアドレスと起動URLは、リンク元のページではなく、マニフェスト自身のURLを基準に解決します。一方、相対指定のidは、起動URLのオリジンを基準に解決します。

残りは表示に関する指定です。displayでfullscreen、standalone、minimal-ui、browserのいずれかを要求し、対応できないブラウザーは、この順で次の候補に移ります。各アイコンにはpurposeを付けられます。省略時はanyで、切り抜きに耐えるよう描いた画像はmaskable、色を捨ててアルファチャンネルだけを使う画像はmonochromeです。theme_colorは、アプリの周囲のウィンドウに色を付けます。関連するW3Cノートでは、インストール画面やストアが表示できるdescription、categories、screenshotsも定めています。

なぜ重要なのか

マニフェストは、サイト側が管理するインストール用メタデータを提供します。仕様は、インストールの判断をブラウザーに委ねています。ブラウザーはインストール手段を提供してもよく、その条件は各ブラウザーが決めます。特定のメンバーを必須にするものもあります。チームは判断材料を提供し、ブラウザーが使い方を決めます。そのため、役に立つ問いは、マニフェストを用意するかどうかより、それによって何を約束するかです。

識別情報は、ファイルの更新後も守るべき約束です。仕様は、ブラウザーがマニフェストを再取得した際、idの一致を、すでにインストールしたアプリのマニフェストを新しいファイルで置き換える合図にすべきだとしています。idを省くと起動URLを使うため、起動ページを移すと、意図せず識別情報も変わります。その場合、ブラウザーは利用者の端末にあるアプリとは別のアプリケーションとして扱うべきことになります。最初のリリースでidを固定しておけば、1行でこの危険を避けられます。

スコープは、どこまでをアプリのウィンドウ内で扱うかを決めます。範囲内の移動は、インストールしたウィンドウ内にとどまります。範囲外へのリンクも開けますが、仕様は、アプリの外に出たことをブラウザーが利用者に示すよう想定しています。そのため、サイトより狭いスコープでは、セクション間の普通のリンクまで、アプリから出る操作に見えてしまいます。

見た目の問題が最も起きやすいのはアイコンです。ランチャーはアイコンを円、角丸の四角などに切り抜くため、正方形いっぱいに描いたロゴは端が欠けます。仕様が定めるmaskableアイコンの安全領域は、中央に置いた、短辺の5分の2を半径とする円です。その外側は切り落とされることがあります。monochromeアイコンではアルファチャンネルしか使わないため、不透明な背景の上に描いたアイコンは、塗りつぶした四角になってしまいます。

色の指定が働く範囲は、見た目の印象より狭いものです。background_colorは、スタイルシートが届くまでの短い時間のためにあります。仕様は、スタイルシートが利用可能になった後に、ブラウザーがこの値を使うことを禁じています。最初の描画の色であって、それ以後の色ではありません。

実際の活用例

このサイトでは、マニフェストを手作業で保管せず、テンプレートから生成します。Hugo設定でapplication/manifest+jsonに拡張子webmanifestを登録し、各言語のホームページの出力にマニフェストを加えています。各言語が独自のファイルを持ち、各ページのheadがその言語のファイルにリンクします。設定には理由も記されています。共通のマニフェストでは起動URLを1つしか指定できず、デンマーク語の訪問者がサイトをインストールしたところ、英語のホームを開くアプリになってしまったためです。

テンプレートはマニフェストをマップとして組み立て、HugoのJSONエンコーダーに渡します。エスケープとカンマはエンコーダーが扱うため、カンマの抜けたファイルを公開することはありません。アイコンのアドレスはすべてホストのルートから始めます。コメントにも理由があります。/da/manifest.webmanifest内の相対アドレスは/da/配下として解決され、デンマーク語のアイコンがすべて404になるためです。アイコン本体は、用途ごとの3つのフォルダーから読み取ります。それぞれ36から512ピクセルまで10サイズあり、サイズはファイル名から得るので、生成ツールがサイズを追加しても、マニフェストを編集する必要はありません。

idは各言語のホームのアドレスに固定し、scopeはオリジン全体にしています。そのため、別の言語へのリンクでも、インストールしたウィンドウ内にとどまります。スクリーンショットの名前は<lang>-<form_factor>-<WxH>.webpで、テンプレートは言語、画面形状、サイズの3つをファイル名から読み取ります。英語とデンマーク語には、それぞれ1,280×800の横長画像と780×1,688の縦長画像が1枚ずつあります。スクリーンショットがない言語では、空のリストではなく、screenshotsメンバー自体を省きます。

クレジットページは、サイトが従う標準の1つとしてW3C仕様を挙げ、誰でも実行できる外部検査の1つとしてPWABuilderを挙げています。これは、Microsoftのコンピューターからマニフェストや、サイトのインストールに必要なほかの要素を読み取るサービスです。

インストールページは、同じファイルを利用者側から説明するものです。各ブラウザーのインストール操作の場所を案内し、Appleのブラウザーが自動的にインストールを勧めることはないと記しています。Firefoxには通常のブラウザーとは別のウェブアプリ用ウィンドウ機能があり、Windowsでは143以降、Microsoft Storeからのインストールでは150以降で、初期状態から有効です。Mozillaの実装文書によれば、Linuxでは初期状態で無効、macOSでは未対応です。このページは、このサイトへの期待も調整しています。インストールされるのは、独自のアイコンとウィンドウを持つアプリです。サイトはサービスワーカーも、管理されたオフライン用コピーも公開していないため、通常の利用には接続が必要です。

問題が起きるところ

翻訳版のパスでアイコンがすべて404になる。 相対指定のsrcはマニフェストのURLを基準に解決されるため、言語の接頭パス配下で配信したマニフェストは、アイコンもその配下に要求します。アイコンのアドレスは、ホストのルートから、または完全なURLで指定します。

インストールしたアプリが別の言語で開く。 1つのマニフェストでは起動URLを1つしか指定できず、全員が同じホームページをインストールすることになります。言語ごとにstart_urlとidを持つマニフェストを配信し、各ページから対応するものにリンクします。

インストール済みのアプリが新しいマニフェストを無視する。 idがなければ起動URLが識別情報になるので、起動ページを移すとファイルの識別情報も変わります。その場合、ブラウザーはインストール済みのものとは別のアプリとして扱うべきことになります。最初のリリース前にidを設定し、それ以後は変えません。

ランチャーがロゴを切り抜く。 用途がanyのアイコンは、プラットフォームの判断で配置または切り抜かれます。短辺の40%を半径とする中央の円に重要な部分をすべて収めた、maskableアイコンを追加します。

マニフェストを編集しても何も変わらない。 HTML標準では、link要素のうち、relにmanifestを含む最初のものしか使いません。そのため、テーマやプラグインが先に独自のリンクを入れていると、編集しているファイルは一度も読まれません。マニフェストへのリンクは、1ページに必ず1つだけにします。

参考資料

お問い合わせ

必要なことを整理している段階ですか?

うまくいっていないことや、つくりたいものをお聞かせください。何が必要か、おおよそいくらかかるか、私たちが適任かどうかをお伝えします。

時間単価は1,400 DKKから(VAT別)で、ご依頼期間が長いほど下がります。

welcome@engineer.company +45 50 10 61 84 デンマーク、コペンハーゲン