ウェブアプリ マニフェストを追加する

フランソワ ボーフォール
François Beaufort
GitHub
ピート・ルページ
Thomas Steiner 氏
アレクセイ・ロディオノフ
Alexey Rodionov
Twitter GitHub

ウェブアプリ マニフェストは、プログレッシブ ウェブアプリの情報と、ユーザーのパソコンまたはモバイル デバイスにインストールされたプログレッシブ ウェブアプリの動作をブラウザに伝える JSON ファイルです。一般的なマニフェスト ファイルには、アプリ名、アプリで使用するアイコン、アプリの起動時に開く URL などが含まれています。

対応ブラウザ

  • 39
  • 79
  • x
  • x

ソース

マニフェスト ファイルを作成する

マニフェスト ファイルには任意の名前を付けることができますが、一般的には manifest.json という名前で、ルート（ウェブサイトの最上位ディレクトリ）から提供されます。この仕様では拡張機能は .webmanifest にすることが推奨されていますが、ブラウザは .json 拡張機能もサポートしているため、デベロッパーにとってわかりやすい場合があります。

一般的なマニフェストは次のようになります。

{
  "short_name": "Weather",
  "name": "Weather: Do I need an umbrella?",
  "icons": [
    {
      "src": "/images/icons-vector.svg",
      "type": "image/svg+xml",
      "sizes": "512x512"
    },
    {
      "src": "/images/icons-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icons-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "id": "/?source=pwa",
  "start_url": "/?source=pwa",
  "background_color": "#3367D6",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#3367D6",
  "shortcuts": [
    {
      "name": "How's weather today?",
      "short_name": "Today",
      "description": "View weather information for today",
      "url": "/today?source=pwa",
      "icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
    },
    {
      "name": "How's weather tomorrow?",
      "short_name": "Tomorrow",
      "description": "View weather information for tomorrow",
      "url": "/tomorrow?source=pwa",
      "icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
    }
  ],
  "description": "Weather forecast information",
  "screenshots": [
    {
      "src": "/images/screenshot1.png",
      "type": "image/png",
      "sizes": "540x720",
      "form_factor": "narrow"
    },
    {
      "src": "/images/screenshot2.jpg",
      "type": "image/jpg",
      "sizes": "720x540",
      "form_factor": "wide"
    }
  ]
}

主要なマニフェストのプロパティ

short_nameおよび / またはname

少なくとも short_name プロパティまたは name プロパティを指定する必要があります。両方を指定すると、short_name はユーザーのホーム画面やランチャーなど、スペースが限られる場所で使用されます。name は、アプリのインストール時に使用されます。

icons

ユーザーが PWA をインストールするときに、ホーム画面、アプリ ランチャー、タスク スイッチャー、スプラッシュ画面などで使用するブラウザのアイコンのセットを定義できます。

icons プロパティは、画像オブジェクトの配列です。各オブジェクトには、画像の src、sizes プロパティ、type を含める必要があります。マスク可能なアイコン（Android ではアダプティブ アイコンとも呼ばれます）を使用するには、"purpose": "any maskable" を icon プロパティに追加することも必要です。

Chromium の場合は、少なくとも 192x192 ピクセルのアイコンと 512x512 ピクセルのアイコンを提供する必要があります。この 2 つのアイコンサイズのみが指定されている場合、Chrome はデバイスに合わせてアイコンのサイズを自動的に調整します。独自のアイコンのサイズを調整し、ピクセルを完璧に調整したい場合は、48 dp 単位でアイコンを指定します。

id

id プロパティを使用すると、アプリケーションに使用する識別子を明示的に定義できます。マニフェストに id プロパティを追加すると、start_url またはマニフェストの場所への依存関係が解消され、今後更新できるようになります。詳しくは、ウェブアプリ マニフェスト ID プロパティで PWA を一意に識別するをご覧ください。

start_url

start_url は必須で、アプリの起動時に開始する場所をブラウザに指示します。これにより、ユーザーがアプリをホーム画面に追加したときに、どのページからでもアプリは起動できなくなります。

start_url は、商品のランディング ページではなく、ユーザーをアプリに直接誘導する必要があります。ユーザーがアプリを開いたときに何をするつもりなのかを考えて、そこに配置してください。

background_color

background_color プロパティは、アプリがモバイルで初めて起動されたときにスプラッシュ画面で使用されます。

display

アプリの起動時に表示されるブラウザ UI をカスタマイズできます。たとえば、アドレスバーとブラウザのユーザー インターフェース要素を非表示にできます。全画面表示で起動するゲームも作成できます。display プロパティは次のいずれかの値を取ります。

プロパティ 次のコマンドを実行します。
fullscreen ブラウザ UI なしでウェブ アプリケーションを開き、使用可能な表示領域全体を占有します。
standalone ウェブアプリが開き、スタンドアロン アプリと同じように操作できます。アプリはブラウザとは別のウィンドウで実行され、URL バーなどの標準のブラウザ UI 要素は非表示になります。
スタンドアロン表示の PWA ウィンドウの例。
minimal-ui このモードは standalone と似ていますが、ナビゲーションを制御するための UI 要素の最小限のセット（戻るや再読み込みなど）をユーザーに提供します。
最小 UI 表示の PWA ウィンドウの例。
browser 標準的なブラウザ エクスペリエンス。

display_override

ウェブアプリは、上記のようにマニフェストで display モードを設定することで表示方法を選択できます。すべての表示モードをサポートする必要はありませんが、仕様で定義されたフォールバック チェーン（"fullscreen" → "standalone" → "minimal-ui" → "browser"）をサポートすることが必須です。特定のモードをサポートしていない場合は、チェーン内の次の表示モードにフォールバックします。この柔軟性のない動作が問題となることがまれにあります。たとえば、"minimal-ui" がサポートされていない場合は、強制的に "browser" 表示モードに戻ることなく "minimal-ui" をリクエストすることはできません。もう 1 つの問題は、現在の動作では、新しい表示モードを下位互換性のある方法で導入できないことです。タブ形式アプリモードなどのデータ探索では、フォールバック チェーン内の自然な場所がないためです。

こうした問題は、ブラウザが display プロパティの前に考慮する display_override プロパティによって解決されます。その値はリストに記載された順序で考慮される文字列のシーケンスであり、最初にサポートされている表示モードが適用されます。サポートされていない場合、ブラウザは display フィールドの評価にフォールバックします。

以下の例を考えてみましょう。（"window-control-overlay" の詳細は、この記事の対象外です）。

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

前述のように、ブラウザは最初に display_override を確認します。

  1. "window-control-overlay"
  2. "minimal-ui"

どちらのオプションも使用できない場合は、display にフォールバックします。"standalone" を使用できない場合は、その時点から仕様で定義されている Fallabck チェーンを再開します。

  1. "standalone"
  2. "minimal-ui"
  3. "browser"

scope

scope は、ブラウザがアプリ内に存在するとみなす URL のセットを定義し、ユーザーがアプリから離れたタイミングを判断するために使用されます。scope は、ウェブアプリ内のすべてのエントリ ポイントと終了ポイントを含む URL 構造を制御します。start_url は scope 内に存在する必要があります。

scope に関するその他の注意事項:

  • マニフェストに scope を含めない場合、デフォルトで暗黙の scope が開始 URL になりますが、ファイル名、クエリ、フラグメントは削除されます。
  • scope 属性は、相対パス（../）または上位レベルのパス（/）を指定できます。これにより、ウェブアプリ内のナビゲーション範囲を拡大できます。
  • start_url はスコープ内に存在する必要があります。
  • start_url は、scope 属性で定義されたパスからの相対パスです。
  • / で始まる start_url は常にオリジンのルートです。

theme_color

theme_color はツールバーの色を設定し、タスク スイッチャーのアプリのプレビューに反映されます。theme_color は、ドキュメント ヘッドで指定された meta テーマカラーと一致させる必要があります。

カスタムの theme_color が設定されている PWA ウィンドウの例。
カスタムの theme_color が設定されている PWA ウィンドウの例。

Chromium 93 と Safari 15 では、meta テーマカラー要素の media 属性を使用して、メディアクエリでこの色を調整できます。最初に一致するものが選択されます。たとえば、ライトモードとダークモード用に 1 つの色を設定できます。このドキュメントの執筆時点では、これらをマニフェストで定義できません。w3c/manifest#975 GitHub の問題をご覧ください。

<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)"  content="black">

shortcuts

shortcuts プロパティは、アプリ内の主要なタスクにすばやくアクセスできるようにするアプリ ショートカット オブジェクトの配列です。各メンバーは、少なくとも name と url を含む辞書です。

description

description プロパティは、アプリの目的を記述します。

screenshots

screenshots プロパティは、一般的な使用シナリオでアプリを表す画像オブジェクトの配列です。各オブジェクトには、src、sizes プロパティ、画像の type を含める必要があります。form_factor プロパティは省略可能です。ワイド スクリーンのみに適用されるスクリーンショットの場合は "wide"、幅の狭いスクリーンショットの場合は "narrow" に設定します。

Chrome では、画像が特定の条件を満たす必要があります。

  • 幅と高さは 320 ピクセル以上、3,840 ピクセル以下にする必要があります。
  • 最大ディメンションの長さは、最小ディメンションの 2.3 倍以下にする必要があります。
  • 適切なフォーム ファクタに一致するスクリーンショットはすべて、同じアスペクト比である必要があります。
    • Chrome 109 以降では、form_factor が "wide" に設定されているスクリーンショットのみがパソコンに表示されます。
  • Chrome 109 以降、form_factor が "wide" に設定されているスクリーンショットは Android で無視されます。下位互換性のため、form_factor のないスクリーンショットは引き続き表示されます。

パソコン版 Chrome には、上記の条件を満たすスクリーンショットが 1 ～ 8 件表示されます。それ以外は無視されます。

Android 版 Chrome には、上記の条件を満たすスクリーンショットが 1 ～ 5 件表示されます。それ以外は無視されます。

パソコンとモバイルでよりリッチなインストール UI が表示されているスクリーンショット。
デスクトップとモバイルのインストール UI が充実しました。

マニフェストを作成したら、プログレッシブ ウェブアプリのすべてのページに <link> タグを追加します。次に例を示します。

<link rel="manifest" href="/manifest.json">

マニフェストをテストする

マニフェストが正しく設定されていることを確認するには、Chrome DevTools の [Application] パネルの [Manifest] ペインを使用します。

Chrome では、説明の長さがすべてのプラットフォームで 300 文字に制限されています。説明がそれより長い場合は、省略記号で切り捨てられます。Android では、最大 7 行という追加の制限があります。

[Manifest] タブが選択された Chrome DevTools のアプリケーション パネル。
DevTools でマニフェストをテストします。

このペインには、マニフェストの多くのプロパティが人が読めるバージョンが表示されるため、すべての画像が適切に読み込まれていることを簡単に確認できます。

モバイルのスプラッシュ画面

アプリが初めてモバイルで起動したとき、ブラウザがスピンアップして最初のコンテンツがレンダリングされるまでに時間がかかる場合があります。ブラウザは、アプリが停止しているように見える可能性のある白い画面を表示するのではなく、最初の描画までスプラッシュ画面を表示します。

スプラッシュ画面は、マニフェスト プロパティから自動的に作成されます。具体的には、次のようなものです。

  • name
  • background_color
  • icons

スプラッシュ画面からアプリにスムーズに移行できるように、background_color は読み込みページと同じ色にする必要があります。

Chrome により、そのデバイスの解像度に最も近いアイコンが選択されます。ほとんどの場合、192 ピクセルと 512 ピクセルのアイコンを用意するだけで十分ですが、ピクセルを完璧にするために追加のアイコンを用意することもできます。

参考資料

ウェブアプリ マニフェストには、他にもいくつかのプロパティを追加できます。詳しくは、MDN ウェブアプリ マニフェストのドキュメントをご覧ください。