ウェブアプリ マニフェストは、ユーザーのパソコンまたはモバイル デバイスにインストールされたプログレッシブ ウェブアプリ(PWA)の動作をブラウザに伝える JSON ファイルです。一般的なマニフェスト ファイルには、少なくとも次のものが含まれます。
- アプリの名前
- アプリで使用するアイコン
- アプリの起動時に開く URL
マニフェスト ファイルを作成する
マニフェスト ファイルには任意の名前を付けることができますが、通常は 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 the 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 the 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
のうち少なくとも 1 つを指定する必要があります。両方を指定すると、アプリのインストール時に name
が使用され、ユーザーのホーム画面やランチャーなど、スペースが限られる場所で short_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 |
ウェブアプリを開くと、スタンドアロン アプリのような外観になります。アプリはブラウザとは別の独自のウィンドウで実行され、アドレスバーなどの標準のブラウザ UI 要素は非表示になります。 |
minimal-ui |
このモードは standalone と似ていますが、[戻る] ボタンや再読み込みボタンなど、ナビゲーションを制御するための UI 要素の最小限のセットをユーザーに提供します。
|
browser |
標準的なブラウザ エクスペリエンス。 |
display_override
ウェブアプリの表示方法を選択するには、前述のように、マニフェストで display
モードを設定します。ブラウザはすべてのディスプレイ モードをサポートする必要はありませんが、仕様で定義されているフォールバック チェーン("fullscreen"
→ "standalone"
→ "minimal-ui"
→ "browser"
)をサポートする必要があります。特定のモードをサポートしていない場合は、チェーン内の次のディスプレイ モードにフォールバックします。まれに、このフォールバックによって問題が発生することがあります。たとえば、"minimal-ui"
がサポートされていない場合、デベロッパーは強制的に "browser"
表示モードに戻さない限り、"minimal-ui"
をリクエストできません。また、現在の動作では、フォールバック チェーン内に場所がないため、下位互換性のある方法で新しい表示モードを導入することもできません。
display_override
プロパティを使用して、独自の代替シーケンスを設定できます。ブラウザでは、このプロパティを display
プロパティの前に考慮します。この値は、リストされた順序で考慮される文字列のシーケンスであり、最初にサポートされている表示モードが適用されます。サポートされていない場合、ブラウザはフォールバックして display
フィールドを評価します。display
フィールドがない場合、ブラウザは display_override
を無視します。
display_override
の使用方法の例を次に示します。"window-control-overlay"
の詳細は、このページの対象外です。
{
"display_override": ["window-control-overlay", "minimal-ui"],
"display": "standalone",
}
このアプリを読み込むとき、ブラウザはまず "window-control-overlay"
を使用しようとします。使用できない場合は "minimal-ui"
にフォールバックし、その後、display
プロパティから "standalone"
にフォールバックします。いずれも使用できない場合、ブラウザは標準のフォールバック チェーンに戻ります。
scope
アプリの scope
は、ブラウザがアプリの一部と見なす URL のセットです。scope
は、アプリへのすべてのエントリ ポイントと出口ポイントを含む URL 構造を制御し、ブラウザはこれを使用してユーザーがアプリから離れたかどうかを判断します。
scope
に関するその他の注意事項:
- マニフェストに
scope
を含めない場合、デフォルトの暗黙のscope
が開始 URL になりますが、ファイル名、クエリ、フラグメントは削除されます。 scope
属性には、相対パス(../
)または上位レベルのパス(/
)を指定できます。これにより、ウェブアプリのナビゲーションの範囲を拡大できます。start_url
はスコープ内に存在する必要があります。start_url
は、scope
属性で定義されたパスからの相対パスです。/
で始まるstart_url
は常にオリジンのルートです。
theme_color
theme_color
はツールバーの色を設定し、タスク スイッチャーのアプリのプレビューに反映できます。theme_color
は、ドキュメント ヘッドで指定された meta
テーマカラーと一致する必要があります。
メディアクエリでのtheme_color
メディアクエリで theme_color
を調整するには、meta
テーマカラー要素の media
属性を使用します。たとえば、ラ���トモード用とダークモード用の別の色を、この方法で定義できます。ただし、マニフェストでこれらの設定を定義することはできません。詳しくは、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
プロパティは、アプリの目的を記述します。
Chrome では、すべてのプラットフォームで説明の最大文字数は 300 文字です。 説明がそれより長い場合、ブラウザは省略記号で切り捨てます。Android では、説明文にも最大 7 行のテキストを使用する必要があります。
screenshots
screenshots
プロパティは、一般的な使用シナリオでアプリを表す画像オブジェクトの配列です。各オブジェクトには、src
、sizes
プロパティ、画像の type
を含める必要があります。form_factor
プロパティは省略可能です。ワイド スクリーンのみに適用できるスクリーンショットの場合は "wide"
に設定し、幅の狭いスクリーンショットにのみ適用する場合は "narrow"
に設定します。
Chrome では、画像が次の条件を満たしている必要があります。
- 幅と高さは 320 ピクセル以上、3,840 ピクセル以下にする必要があります。
- 最大ディメンションは、最小ディメンションの長さの 2.3 倍以下にする必要があります。
- 適切なフォーム ファクタに一致するすべてのスクリーンショットは、同じアスペクト比である必要があります。
- Chrome 109 以降では、
form_factor
が"wide"
に設定されているスクリーンショットのみがパソコンに表示されます。
- Chrome 109 以降では、
- Chrome 109 以降、
form_factor
が"wide"
に設定されているスクリーンショットは Android で無視されます。下位互換性のため、form_factor
のないスクリーンショットは引き続き表示されます。
パソコン版 Chrome には、これらの条件を満たすスクリーンショットが 1 ~ 8 枚表示されます。残りは無視されます。
Android 版 Chrome には、これらの条件を満たすスクリーンショットが 1 ~ 5 個表示されます。残りは無視されます。
ウェブアプリ マニフェストをページに追加する
マニフェストを作成したら、プログレッシブ ウェブアプリのすべてのページに <link>
タグを追加します。次に例を示します。
<link rel="manifest" href="/manifest.json">
マニフェストをテストする
マニフェストが正しく設定されていることを確認するには、Chrome DevTools の [Application] パネルの [Manifest] ペインを使用します。
このペインには、人が読めるバージョンのマニフェストの多くのプロパティが表示され、すべてのイメージが正しく読み込まれていることを確認できます。
モバイルのスプラッシュ画面
モバイルで初めてアプリを起動したときに、ブラウザが起動して最初のコンテンツのレンダリングが開始されるまでに時間がかかることがあります。アプリが動作していないとユーザーに思わせるような白い画面を表示する代わりに、ブラウザは最初のペイントまでスプラッシュ画面を表示します。
Chrome は、マニフェストで指定された name
、background_color
、icons
からスプラッシュ画面を自動的に作成します。スプラッシュ画面からアプリにスムーズに移行するには、background_color
を読み込みページと同じ色にします。
Chrome では、スプラッシュ画面のデバイス解像度に最も近いアイコンが選択されます。ほとんどの場合、192 ピクセルと 512 ピクセルのアイコンで十分ですが、別のアイコンを指定して一致させることもできます。
関連情報
ウェブアプリ マニフェストに追加できるその他のプロパティについては、MDN ウェブアプリ マニフェストのドキュメントをご覧ください。