SP用メニューボタン
ソレゾレブログ

技術的な事だったり日常の気になる事だったり

PWA(Progressive web apps) とはいったいどんな機能なのか?manifest作成編

スポンサーリンク

ウェブアプリマニフェストファイル(manifest.json)

WebアプリをPWA化するのにまず必要になるのは、Webアプリに関する情報をjson形式で記載した「manifest.json」ファイルです。この記事では、manifestファイルの書き方と読み込ませ方について検証していきます。

manifestファイルの置き場所と読み込み方

PWA機能の核であるサービスワーカー(詳細後述)がキャッシュできるコンテンツは、サービスワーカーが管理している配下のコンテンツに限るため、サービスワーカーを構成する設定ファイルの一つであるmanifestファイルは、コンテンツさせたいパスの中で一番上位に置かなければいけません。特別な事情が無い限りはドキュメントルート(index.htmlが置かれているパス)に配置します。WordPressならwp-config.phpがある場所です。

manifestファイルを読み込ませるには、head要素内にlinkタグで下記のように設定します。ファイル名は「manifest.json」でなくても読み込めますが、よほどの理由が無い限り一般的なこの名前を使った方が良いと思います。

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

スポンサーリンク

manifestファイルの書き方と最低限必要な設定値

{
	"name" : "PWA設定用のテストサイトです"
	"icons" : [
		{
			"src": "192x192.png",
			"sizes": "192x192",
			"type": "image/png"
		}
	]
}

Chromeで最低限必要な設定値を確かめる検証

「name」「icons」メンバーと、「icons」メンバーのプロパティとして「src」「sizes」「type」メンバーだけ設定したmanifestファイルをChromeに読み込ませてみました。読み込ませ後、開発者モードの [アプリケーション] – [マニフェスト] を開くと下記のようなエラーが出ていました。

manifestファイルChromeでの設定検証例1

尚、「一致する service worker が検出されませんでした。」のエラーは、後述するサービスワーカーの記事で設定しますので一旦忘れます。

「start_url」「display」メンバーを3~4行目に追加したmanifestファイルが下記です。

{
	"name" : "PWAの設定検証用サイトです",
	"start_url" : "/",
	"display" : "standalone",
	"icons" : [
		{
			"src": "/img/icon-192x192.png",
			"sizes": "192x192",
			"type": "image/png"
		}
	]
}

設定反映後に再度ページを読み込ませてみると、下記のように改善しました。「開始URL」「ディスプレイ」の欄を見ると正しく値が表示されています。

manifestファイルChromeでの設定検証例2

検証結果、Chromeでは最低でも「name」「start_url」「display」「icons」メンバーが無ければいけないということがわかりました。

Edgeで最低限必要な設定値を確かめる検証

Edgeは2020/1/15に発表された新EdgeからChromeと同じChromiumエンジンを採用しています。そこから推測するに挙動は同じだと思いますが、一応検証してみます。まずはChromeの検証と同じように「name」「icons」メンバーだけを設定してページを読み込んでみました。開発者モードで確認すると、Chromeと同じようにエラーが出ていました。

manifestファイルEdgeでの設定検証例

「start_url」「display」メンバーを追加してページを再読み込みさせると、エラーは解消していました。結果はChromeと同じで、最低でも「name」「start_url」「display」「icons」メンバーが無ければいけないということになります。

FireFoxで最低限必要な設定値を確かめる検証

FireFoxでも同じようにに「name」「icons」メンバーだけ設定したmanifestファイルを読み込ませてみました。

manifestファイルFireFoxでの設定検証例1

FireFoxの場合はエラーが出力されませんでした。問題なく動作しているように見えます。本当にそうなのか、どこまでメンバーを削るとエラーになるか試してみたくなり、下記のようにmanifestファイルから全部のメンバーを削除して再読み込みさせてみました。

{
}

下記が読み込み結果です。

manifestファイルFireFoxでの設定検証例2

エラーは出力されませんでした。FiraFoxはひとまずmanifestファイルが存在すれば、エラーなく認識してくれるようです。

検証の総括

検証結果からみて、一般的なブラウザでは最低限でも「name」「start_url」「display」「icons」メンバーと、「icons」メンバーのプロパティとして「src」「sizes」「type」メンバーが設定されていれば、manifestファイルの最低限の設定としては事足りると思われます。ただ、実際は他にも設定が必要になりますので、後述を参考に設定してください。

スポンサーリンク

アイコン画像について

iconsメンバーに設定するアイコン画像は、スマホのホームアイコンやWebアプリ起動時のスプラッシュ画面、パソコンのデスクトップに作成されるアイコン、などに使用されます。スプラッシュ画面とは、Webアプリを起動してから表示されるまでの繋ぎや演出に使われる画面の事です。

これらに使われるアイコン画像ですが、設定サイズや作成方法に制限があります。下記に検証結果を書いていきます。

利用できる画像フォーマット

マスクされる前提なので透過可能であり、読み込みが速い軽量な画像フォーマットが望ましいです。pngやwebpなど。

アイコンの背景色

アイコンには必ず背景色を付ける必要があります。下記ページに記載があります。背景色が無い場合は、iphoneでは黒、andoroidでは白の背景が勝手に付与されました。

アイコン画像のサイズ

アイコン画像としてどのサイズのものが必要か、各ブラウザで調査してみました。

Chrome

Chromeの場合、192x192pxと512x512pxのアイコンを用意していれば、指定デバイスに合わせてアイコンを自動的に拡大縮小するようです。より解像度の良い画像を提供したい場合は、48dp単位でより細かに用意すればよいとのこと。

Edge

既に公開が終わっているMicrosoftのページには512pxのものがあれば良いと書いてあった記憶がありますが、現状で明確な記載の資料が見つけられませんでした。Edgeは現在Chromiumエンジンを使っているのでChromeと同じと仮定します。

Safari

iOSアイコンは180×180ピクセルか192×192ピクセルである必要があるとのこと。

FireFox

資料が見つけられず。。。

全ての一般的なブラウザを通して最適なサイズ

調査結果、192x192pxと512x512pxがあれば良さそうでした。念のため、この2サイズのアイコン画像のみを設定したmanifestファイルを各ブラウザに読み込ませてみたところ、自動的に拡大縮小がされて、Webアプリの起動アイコンやスプラッシュ画面に特段不都合はなかったので、この記事を書いている2021年10月現在では192x192pxと512x512pxの2サイズで問題ないと思われます。ただ、ピクセルパーフェクトを目指すなら、より細かいサイズ指定で設定してあげると良いかもしれません。

アイコン画像には安全領域が必要

スマホのアイコンは正方形ではありません。円形だったり角が丸められたり、中には下記のように楕円のようなものもあります。

アイコン画像には安全領域が必要1

正方形のアイコン画像を設定しても、このようにデバイスによっては外側をマスク(隠す)されてしまいます。アイコン画像はマスクされた時も、必要な部分が表示されていなければいけません。その領域を安全領域と言います。

安全領域は画像の中心点からの2/5(40%)の半径を持つ円とされています。逆に言えば、画像の端から10%の余裕(Padding)が必要となります。アイコン画像を作成するときは安全領域に注意して作成しなければいけません。

下記のサイトは、安全領域の設定を画像付きでわかりやく説明にしてくれています。詳しい情報も載ってますので、作成する際の参考にしてみてください。

アイコン画像作成に便利なサイト

Maskable.app

自分のアイコンがマスクされたら、どのように表示されるかシミュレートしてくれる素晴らしいサイトがあります。

私が作成した下記星形のアイコンで試してみました。下記アイコン画像は背景色を付けないで検証してしまいましたが、アイコン画像は背景色を付けることが推奨されていますので、作成する場合は注意してください。

アイコン画像には安全領域が必要2

安全領域の無い画像がマスクされると下記のように表示されます。星の端が削れているのがわかります。

アイコン画像には安全領域が必要3

安全領域を正しく確保した画像がマスクされると下記のように表示されます。 星がバランスよく表示されているのがわかります。

アイコン画像には安全領域が必要4

他の機能として便利なのは「Editor」モードです。このモードではアイコン画像の作成が出来てしまいます。自分の持っているアイコン画像をアップロードすると、安全領域の中に納まるアイコンをカスタマイズして作成書き出しすることが出来ます。背景透過の画像を使った場合でも背景色を設定することが出来てしまいます。これは本当に便利ですので是非使ってみてください。

アイコン画像には安全領域が必要5
favicon generator

スポンサーリンク

manifestファイルの設定値一覧

{
    "キー" : "値",
    "キー" : "値",
    "キー" : "値",
    "キー" : "値",
    "icons" : "値" : [
		{
			"src": "パス",
			"sizes": "192x192",
			"type": "image/png"
		},
		{
			"src": "パス",
			"sizes": "512x512",
			"type": "image/png"
		}
	],
    "キー" : "値",
    "キー" : "値"
}

name

設定要否

必須設定です。

説明

Webアプリの名前を設定します。日本語でも問題ありません。英字の場合45文字(日本語は半分の22文字)までに収める必要があります。

設定例
{
    "name" : "PWA設定用のテストサイトです"
}

short_name

設定要否

任意設定ですが、設定した方が無難です。

説明

スマホのホーム画面、ランチャー、またはスペースが限られている可能性があるその他の場所で使用されます。12文字以内(日本語は6文字)に収めることが推奨されており、超えた場合は状況によってお尻が切り取られます。設定されなければnameが使われるため必須ではありません。

試しに「abcdefghijklmnopqrstuvwxyz」というshort_nameを設定して、Webアプリとしてスマホのホームにインストールしてみたところ、私の手元のandoroid(pixel4a)のChromeで6文字、iphone11ProのSafariでは13文字、ipadのSafariでは13文字まで表示されました。パソコンのChromeとEdgeでは、short_nameではなくnameで登録されました。

12文字と言うのは推奨値で、スマホのブラウザによっては文字数が違うので適宜設定すれば良いと思います。

【設定例】
{
    "short_name" : "PWAテストサイト"
}

start_url

設定要否

必須設定です。

説明

Webアプリが起動したときに表示するURLを指定します。「/」と指定すると「https://ドメイン/」が指定されますし、具体的に「https://ドメイン/」と書くこともできます。また、「../*****.html」などの相対パスも使用できます。単にドキュメントルート(「https://ドメイン/」にアクセスしたときに開く場所)のindex.htmlやindex.phpなどのインデックスファイル(ApacheならDirectoryIndex)を開きたいなら「/」を指定してください。

設定例
{
    "start_url" : "/"
}

icons

設定要否

必須設定です。プロパティの「src」「sizes」「type」メンバーも必須です。

説明

「purpose」は必須ではありません。

設定値

src

画像のパスをドキュメントルートから指定します。必須設定です。

sizes

type

画像の種類をMIMEタイプで指定する必要があります。「タイプ/サブタイプ」の指定となりますが、画像の場合は「タイプ」は「image」となりますので、pngファイルなら「image/png」、webpなら「image/webp」となります。

必須ではなく無くても動きましたが、ブラウザがメディアタイプを素早く認識するのに役立つため、設定したほうが断然良いです。

purpose

画像の用途を指定します。スペース区切りで複数指定が可能です。

マスク用含めすべての用途で一つの画像を使いまわす場合は「”purpose”: “any maskable”」と設定出来ますが、マス用の画像を一般用途に使いまわすと、背景の割合が多くなりすぎて見た目が良くなかったり、正しく表示できなかったりします。マスク用と通常用に分けて設定する事が推奨されています。

設定出来る値は下記となります。

maskable

マスク用画像(スマホアイコンに使う画像)の場合は「maskable」を指定します。

any

マスク画像以外の用途で使用する画像である場合は「any」を設定します。何も設定しなければ初期値「any」となります。パソコンのChromeでインストールした時のAppsのアイコンなどに使われます。

monochrome

単彩色(モノクローム)。Firefox しかサポートしておらず、今後仕様から除去される可能性があるとのこと。

検証

マスク用に作成した画像を「any」で表示させてみました。画像全体がアイコンの中に納まるように表示され、背景が白に設定されます。好ましい設定ではありません。

purpose1

同じくマスク用に作成した画像を「maskable」で設定してみました。正しいマスク表示となりました。

purpose2
設定例
{
	"icons" : [
		{
			"src": "/img/icon-192x192.png",
			"sizes": "192x192",
			"type": "image/png"
		},
		{
			"src": "/img/icon-512x512.png",
			"sizes": "512x512",
			"type": "image/png"
		},
		{
			"src": "/img/icon-maskable-192x192.png",
			"sizes": "192x192",
			"type": "image/png",
			"purpose": "maskable"
		},
		{
			"src": "/img/icon-maskable-512x512.png",
			"sizes": "512x512",
			"type": "image/png",
			"purpose": "maskable"
		}
	]
}

display

設定要否

必須設定です。

説明

インストールしたWebアプリを起動したときの表示方法を設定できます。「fullscreen」「standalone」「minimal-ui」「browser」4つの表示モードがあります。

各モードが対応していない場合は下位にフォールバックする代替表示モード機能があります。「fullscreen」→「standalone」→「minimal-ui」→「browser」のようにフォールバックするようです。

「display」メンバーを設定することで、スマホのSafari/Chrome、パソコンのChrome/Edgeで、どのような表示になるか確認してみました。尚、FireFoxはPWAのインストール機能に対応していないので確認対象外です。safariはホーム画面に追加しか機能対応していないので確認対象外です。

設定値

fullscreen

fullscreenに設定すると、スマホChromeでは単独のアプリケーションとして独立したウィンドウで開きます。下記のようにツールバーなどを除いてコンテンツ部分だけが最大化表示されます。

fullscreen1

パソコンのChromeとEdgeでは下記のように単独ウィンドウで開きます。

fullscreen2

standalone

standaloneに設定すると、スマホChromeでは単独のアプリケーションとして独立したウィンドウで開きます。標準的なツールバーが表示されます。

standalone

パソコンのChromeとEdgeでは、fullscreenの表示と同じように単独のウィンドウで開きます。

minimal-ui

minimal-uiに設定すると、スマホChromeでは単独のアプリケーションとして独立したウィンドウで開きます。拡張されたツールバーが表示されます。

minimal-ui

パソコンのChromeとEdgeでは、fullscreenの表示と同じように単独のウィンドウで開きます。

browser

browserに設定すると、スマホChromeは単独のアプリケーションではなくChrome本体で開きます。

browser1

パソコンのChromeとEdgeではbrowser表示モードには対応しておらず、下記のようにエラーが出力されました。

browser2
設定例
{
    "display" : "standalone"
}

lang

設定要否

任意設定です。書字方向の表示に影響が出た場合は設定してください。

説明

アプリやサイトで使用する言語を設定します。言語を右から書き始めるのか、左から書き始めるか、書字方向を正しく表示するのに役立ちます。”dir”プロパティと共に使用します。日本語の場合は”ja”です。

設定例
{
    "lang" : "ja"
}

dir

設定要否

任意設定です。書字方向の表示に影響が出た場合は設定してください。

説明

言語の書字方向(右から書くのか左から書くのか)を指定します。下記から選択できます。langメンバーとセットで使用されます。

・auto — ユーザーエージェントが判断した書字方向
・ltr — 左から書き始める言語 (left to right)
・rtl — 右から書き始める言語 (right to left)

日本語は左から書き始めるので「ltr」を設定すればよいと思いますが、「lang」と「dir」を他の設定にしたらどうなるのだろうと気になったので、下記の組み合わせで検証をしてみまた。

・「lang」メンバーも「dir」メンバーも設定しない
・「lang」メンバーを「jp」に設定して「dir」メンバーを設定しない
・「lang」メンバーを「jp」に設定して「dir」メンバーを「rtl」に設定(日本語に書字方向右から左に設定)
・「lang」メンバーを「ar」に設定して「dir」メンバーを「rtl」に設定(アラビア文字なので書字方向が右から左)

結果、andoroidとiphoneとパソコンのChromeでWebアプリをインストールして表示を見てみましたが、何ら問題なく日本語が表示されたので、もしかしたらブラウザか他のどこかの機能で補正をかけているのかもしれません。表示上の影響が無ければ設定しなくても良いのかも知れません。

設定例
{
    "dir" : "auto"
}

background_color

設定要否

任意設定ですが、設定した方が良いです。

説明

ホームやデスクトップに作成されたアイコンからWebアプリを起動した場合に、スタイルシートの読み込みまで、スタイルシートに設定した背景色と異なる色が一時的に表示されてしまいます。background_colorを指定すると、スタイルシートの読み込みまでの背景色をスタイルシートの背景色と同じものに設定することができるので、アプリの起動開始から完了まで一貫した背景色を表示することが出来ます。

下記はandroidですが、ホーム画面に出来たアイコンからWebアプリ(Webサイト)を起動します。

background_color1

Webサイトが表示されるまでスプラッシュ画面が表示されますが、この背景(青紫っぽい色)が設定できます。

background_color2
設定例
{
    "background_color" : "green"
}

スポンサーリンク

theme_color

設定要否

任意設定ですが、設定した方が良いです。

説明

Webアプリやサイトをホーム画面やデスクトップにインストールしたアイコンから起動した場合に、画面随所が設定したテーマ色になって表示されます。設定後表示がどう変わるか実際に確認してみました。今回は濃いベージュ色にしてみました。スプラッシュ画面では画面上部が「theme_color」で表示されます。背景は「background_color」メンバーで設定した色になっています。

theme_color1

Webサイトが表示されると、スプラッシュ画面と同じで画面上部が「theme_color」で表示されます。ちなみに写真は我が家の愛犬です。笑

theme_color2

この例では「”display” : “standalone”」(起動すると単独のアプリケーションのように表示される設定)に設定していますが、他の設定だと見え方が違うかもしれません。

設定例
{
    "theme_color" : "green"
}

description

設定要否

任意設定ですが、設定した方が良いです。

説明
description
設定例
{
    "description" : "このサイトはPWAの検証をするためのテスト環境です"
}

orientation

設定要否

任意設定です。初期値のany以外にしたい場合は設定してください。

説明

画面の方向を設定します。

設定値

設定値については私が一部理解できていない部分があります。詳しくは下記に記載があるので気になる方はご参考までに。

any

全方向に画面の回転を許可する。

natural

デバイスが持つ自然な向き。一般的なスマホだと縦向き方向。

portrait

画面の縦幅が長く横幅が短い状態。一般的なスマホだと縦向き方向。

画面をportraitに設定すると、portrait-primaryとportrait-secondaryどちらかまたは両方を表現できる状態だそうなのですが、この意味は理解できていません。

portrait-primary

画面の縦幅が長く横幅が短い状態且つ正方向。一般的なスマホだと縦向き。

portrait-secondary

画面の縦幅が長く横幅が短い状態且つ逆方向。一般的なスマホだと縦向きで画面が180°ひっくり返っている状態。

landscape

画面の横幅が長く縦幅が短い状態。一般的なスマホだと横向き方向。

画面をlandscapeに設定すると、landscape-primaryとlandscape-secondaryどちらかまたは両方を表現できる状態だそうなのですが、この意味は理解できていません。

landscape-primary

画面の横幅が長く縦幅が短い状態且つ正方向。手元のandroidスマホでは横向き方向で充電ポートが右にある状態。

landscape-secondary

画面の横幅が長く縦幅が短い状態且つ逆方向。手元のandroidスマホでは横向き方向で充電ポートが左にある状態。

設定例
{
    "orientation" : "landscape"
}

categories

設定要否

任意設定です。WebアプリへのPWA適用が目的なら、設定した方が良いです。

説明

Webアプリが属するカテゴリーを設定します。複数設定することが可能です。

この設定値はWebアプリをリストするカタログまたはストアへのヒントとして用意されているそうです。将来的にPWAが発展した時にメリットがあるかもしれません。カテゴリーについては下記で管理されていますので、設定するならその中から選ぶか、無いなら追加すればよいかと思います。

WebアプリへのPWA適用だと何となくメリットは感じますが、WebサイトへのPWA適用ならなんとなく設定不要だと思われます。

設定例
{
    "categories": ["books", "entertainment", "magazines"]
}

scope

任意設定です。ユーザーへアクセス許可するURLを一部に制限したい場合は設定してください。

設定要否
説明

ユーザーがアクセス可能な範囲を指定できます。許可したパス配下へのアクセスを許可します。許可されていないパスをアプリで開いた場合は「start_url」にリダイレクトされます。

ドメインを含めて「https://ドメイン/」と設定したり、 「https://ドメイン/アクセスを許可するサブディレクトリ/」 のように書くこともできます。

ドキュメントルートから相対パスで「/」と設定したり、「/アクセスを許可するサブディレクトリ/」のように書くこともできます。「../」のように上位パスを指定することもできます。

「scope」メンバーを省略した場合は「start_url」メンバーの親パスが使用されます。「start_url」メンバーの設定が例えば「/subdir1/file1.html」のようにファイルまで設定されていた場合、「/subdir1/」配下へのアクセスが許可されます。単に「start_url」メンバーが「/subdir1/subdir2/」のようにサブディレクトリまで設定されていたら、「/subdir1/subdir2/」配下へのアクセスが許可されます。

「scope」メンバーを「/subdir1/subdir2/」に設定し、「start_url」メンバーの値を「/subdir1/file1.html」に設定した場合も、「start_url」メンバーの親パスが使用されます。この設定では「scope」メンバーの設定の意味がなくなってしまう為、整合性をとるために、「scope」メンバーのパスは「start_url」メンバーに設定したパスが含まれるように書く必要があります。つまり「start_url」メンバーの値を「/subdir1/file1.html」と設定したいなら、「scope」メンバーは「/subdir1/」と設定すべきという意味です。

設定例
{
    "scope" : "/subdir1/subdir2/"
}

screenshots

設定要否

任意設定です。お好みで設定してください。

説明

Webアプリのインストール画面下部に、スクリーンショット(Webアプリの説明画像)が追加されます。

screenshots

screenshotsの制限と要件を一覧します。

  • この機能はAndroid用Chromeのみ対応しています。
  • 幅と高さはいずれも320px以上3840px以下に収めます。
  • 最大寸法は、最小寸法の2.3倍を超えることはできません。
  • 全てのスクリーンショットは同じアスペクト比である必要があります。
  • JPEGとPNG画像のみ利用できます。
設定例
{
	"screenshots" : [
		{
			"src": "/img/screenshot1.png",
			"type": "image/png",
			"sizes": "1080x2340"
		},
		{
			"src": "/img/screenshot2.png",
			"type": "image/png",
			"sizes": "1080x2340"
		},
		{
			"src": "/img/screenshot3.png",
			"type": "image/png",
			"sizes": "1080x2340"
		}
	]
}

iarc_rating_id

設定要否

IARC認証を受けたWebアプリの場合は設定すべきです。通常は設定不要です。

説明

IARC(the International Age Rating Coalition)は、世界のゲーム評価機関が管理する国際年齢評価連合です。「iarc_rating_id」メンバーは、IARC認証コードが設定できます。IARCについては下記を参照してください。

設定例
{
    "iarc_rating_id" : "IARC認証コード"
}

related_applications

設定要否

公開しているWebアプリと同様もしくは同等のネイティブアプリがある場合は、設定することをお勧めします。通常は設定不要です。

説明

Webアプリと連携関係にあるようなネイティブアプリケーション(アプリストアで公開しているアプリケーション)の紐づけ設定が出来ます。ここで紐づけ設定するWebアプリとネイティブアプリは、同様または同等の機能を提供する関係性のあるアプリです。複数のネイティブアプリが紐づけできます。詳しくは下記URLを参照してください。

設定例

下記URLを参照してください。

prefer_related_applications

設定要否

「related_applications」メンバーを設定していて、且つ複数のネイティブアプリを設定した場合は設定をお勧めします。通常は設定不要です。

説明

「related_applications」メンバーで複数のネイティブアプリを紐づけした場合、そのなかでも推奨されるアプリを指定することが出来ます。詳しくは下記URLを参照してください。

設定例

下記URLを参照してください。