PWAツールとパッケージング 更新日時: 2025/03/27
LIMITED PWA DISTRIBUTION
現在、Meta Horizonストアでは2Dと没入型のWebXR Progressive Web App (PWA)の両方をサポートしています。ハイブリッド(2Dと没入型間を切り替え可能)PWAのサポートは、後から追加される予定です。 このページでは、パッケージングツールを使って、ウェブエクスペリエンスをストア提出用のAPKに変換する方法を説明します。
PWAをパッケージ化する前に、開発者ダッシュボードでアプリの場所を作成することをおすすめします。アプリページを作成するには、
アプリの作成 のステップに従ってください。それによりアプリIDも生成されます。PWAのAPKをアプリ内購入対応で作成するには、まずアプリページを作成し、アプリIDを取得する必要があります。
Bubblewrapは、Progressive Web AppをAndroid App Bundleに変換する作業を、数回のCLIコマンドで簡単に行えるオープンソースツールです。このツールは、PWAを
信頼できるウェブアクティビティ として起動するAndroidプロジェクトを生成します。Metaは、没入型の起動体験やMeta HorizonストアAPIの接続、アプリ内購入APIをサポートするために、カスタムフォーク版のBubblewrap CLIを使っています。
bubblewrapディレクトリを解凍し、該当ディレクトリに移動して依存ライブラリをインストールします。注: Windowsデバイスを使用する場合は、NodeJSバージョンが 21.0.0であることを確認してください。 :
cd bubblewrap
npm install
npm run build
以下でbubblewrapコマンドのエイリアスを作成します。
MacOS
alias bubblewrap="/YOUR_DIRECTORY/bubblewrap/packages/cli/bin/bubblewrap.js"
Windows
function bubblewrap-aux {node c:\open\fbsource\third-party\bubblewrap-chrome\packages\cli\bin\bubblewrap.js $args};
set-alias -name bubblewrap -value bubblewrap-aux;
PWAアプリパッケージ(APK)を作成してインストールする まだ作成していない場合は、
https://domain.com/manifest.webmanifest にドメイン用のウェブマニフェストファイルを作成してください。このマニフェストファイルは、PWAの設定を生成するためのベースラインとして使われます。PWAに必要な値を入力します。詳しくは、
利用を開始する のセクションを参照してください。
{
"short_name": "PWA Name",
"name": "Full name of your PWA",
"icons": [
{
"src": "/images/icons-192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "/images/icons-512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"start_url": "https://domain.com/startpage/",
"scope": "https://domain.com/",
}
CLIを使うには、プロジェクトディレクトリを作成し、そのディレクトリに移動します。
mkdir my-pwa && cd my-pwa
bubblewrap initコマンドを実行し、ウェブサイトのURLを指定します。
bubblewrap init --manifest=https://domain.com/manifest.webmanifest --metaquest
これにより、ウェブアプリマニフェストからデフォルトのAndroidウェブアプリプロジェクトが生成されます。コンソール内ウィザードが起動し、デフォルト設定を上書きすることができます。
ANDROID SDK AND JDK INSTALLATION
Bubblewrapを初めて実行すると、Java Development Kit (JDK)とAndroidコマンドラインツールのダウンロードを求められます。各依存関係の正しいバージョンがダウンロードされるようにするため、コンピューターにすでにあるものではなく、Bubblewrapに正しいバージョンをダウンロードさせることを強くおすすめします。 Horizon OSでPWAのアプリモードを選択するよう求められます。これは2Dかimmersiveのどちらかになります。
このCLIツールを使ってPWAを作成する場合、パッケージの名前(アプリケーションID)を指定する必要があります。アプリケーションIDはストアへのアップロードにおいて重要です。送信するたびに、その後のアップデートでは同一のアプリケーションIDが必要となります 。
2Dアプリで推奨される表示モードは、landscapeのstandaloneです。縦長のパネルが必要な場合は、portraitを選択することもできます。
PWA内でアプリ内購入機能を利用したい場合は、Meta Horizonストアの請求機能が有効になっていることを確認してください。
Meta開発者ダッシュボードから取得したアプリID番号を入力します。ここでは正しいIDを入力する必要があります。これにより、PWA内でアプリ内購入機能が正常に動作します。アプリID番号は、
Meta開発者ダッシュボード の[App Manager (アプリマネージャ)]ページを表示したとき、Browserに表示されるURLバーで確認することができます。例: developers.meta.com/horizon/manage/applications/
0000000000000000 /.
Meta Horizonストアでは、アプリケーションパッケージをアップロードする際に、証明書でデジタル署名されている必要があります。すべての開発者は、承認を得るためアプリをMetaに提出する前に、独自の一意のデジタル署名を作成して署名する必要があります。詳しくは、
Androidアプリケーションの署名 ページをご覧ください。Bubblewrapはアプリケーション作成時にキーのパスを要求します。
注 : 既存のMeta Horizonストアに掲載されているアプリケーション向けにAPKを作成する場合は、そのアプリケーションで使われた同じキーのパスを追加する必要があります。
既存の署名キーがなく、新しいMeta Horizonストアのリスティングを作成する場合は、Bubblewrapが提供するデフォルト値を使って、新しいリリース署名キーを作成できます。アプリケーションに署名するために使うキーストアファイルを必ず保存してください。これ以降のアプリのアップデートはすべて同じ証明書ファイルで署名する必要があります。
Signing key information (5/5)
Please, enter information about the key store containing the keys that will be used
to sign the application. If a key store does not exist on the provided path,
Bubblewrap will prompt for the creation of a new keystore.
- Key store location: The location of the key store in the file
system.
- Key name: The alias used on the key.
Read more about Android signing keys at:
https://developer.android.com/studio/publish/app-signing
? Key store location: /YOUR_PATH/android.keystore
? Key name: android
Androidウェブアプリプロジェクトを初期化した後、Bubblewrapの初期化コマンドを実行したのと同じディレクトリ内でアプリのAPKをビルドできます。
注 : このステップでは、署名キーのパスワードが必要です。
ディレクトリ内にapp-release-signed.apk ファイルが生成されていることを確認してください。
デジタルアセットリンクプロトコルとAPIは、アプリやウェブサイトがほかのアプリやウェブサイトに関する公開かつ検証可能な声明を作成できるようにします。例えば、ウェブサイトが特定のAndroidアプリと関連付けられていることを宣言したり、ほかのウェブサイトとユーザー認証情報を共有したいことを宣言したりすることができます。PWAのケースでは、このファイルはウェブアプリとPWAの両方が利用者の所有であることを証明するために使われます。
Meta Horizon OSでは、デジタルアセットリンクの検証が通らない場合、WebXR PWAは起動しません 。
PWA APKをビルドする際に使った署名キーのSHA-256フィンガープリントは、以下のJava keytoolコマンドで取得します。
keytool -list -v \
-keystore <keystore-file-path> \
-alias <key-alias> \
-keypass <key-password> \
-storepass <store-password> | grep SHA256
$ Signature algorithm name: SHA256withRSA
$ SHA256: BD:92:64:B0:1A:B9:08:08:FC:FE:7F:94:B2...
PWAをBubblewrapで処理した際に作成したディレクトリ内で、以下のコマンドを使ってデジタルアセットリンクファイルを作成します。<fingerprint>を、前のステップで取得したフィンガープリント(例: BD:92:64:B0:1A:B9:08:08:FC:FE:7F:94:B2...)に置き換えます。
bubblewrap fingerprint add <fingerprint> このコマンドは、フィンガープリントをアプリケーションのフィンガープリントリストに追加し、assetlinks.json ファイルを生成します。このファイルを、PWAと同じウェブサイトドメインの.well-knownディレクトリにアップロードします。(https://domain.com/.well-known/assetlinks.json )
注: keytoolコマンドは、OSにJDKがインストールされていない場合、使えない可能性があります。この問題に直面した場合、Bubblewrapによって作成されたJDKディレクトリ内に実行可能なバイナリを見つけることができます。例えば、Mac OSでは、keytoolスクリプトは以下の場所にあります
${USER_HOME}/.bubblewrap/jdk/jdk-11.0.9.1+1/Contents/Home/bin
assetlinks.jsonファイルは、パッケージ名とフィンガープリントのJSON配列です。単一のドメイン内で複数のPWAアプリの所有権を追加することが可能です。そのためには、以下のようにアセットリンクステートメントを配列内に連結します。
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "pwa.application.id.1",
"sha256_cert_fingerprints": [
"BD:92:64:B0:1A:B9:08:08:FC:FE:7F:94:B2..."
]
}
},
{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "pwa.application.id.2",
"sha256_cert_fingerprints": [
"B3:FE:E9:E1:5C:1A:E8:68:5C:1A:16:99:E8..."
]
}
}]
adb install [path to the app package]
インストールが完了したら、Quest上のアプリライブラリからPWAを起動できます。アプリライブラリで、アプリフィルターを発行元不明 に変更すると、リストに該当アプリが表示されるはずです。アプリをクリックして起動します。
テスト用のWebXR PWAアプリをヘッドセットにインストールしたのですが正常に起動できません。どうすればよいですか。 WebXR PWAが起動しない場合、主な原因としてデジタルアセットリンクの検証がうまくいかないことが挙げられます。この場合、TWA verification was unsuccessful!というログがデバイスログに出力されます。パッケージ名と署名キーの指紋が、 https://domain.com/.well-known/assetlinks.json ファイルに記載されているものと一致しているかどうかを再度確認してください。
2D PWAアプリで、パネルの上部にURLバーが表示されます。これを取り除くにはどうすればよいですか? カスタムタブバー が表示される最も一般的な原因は、デジタルアセットリンクの検証の失敗です。この場合、
TWA verification was unsuccessful!というログがデバイスログに出力されます。パッケージ名と署名キーの指紋が、
https://domain.com/.well-known/assetlinks.json ファイルに記載されているものと一致しているかどうかを再度確認してください。
2D PWAアプリが起動しない、または読み込み中画面が表示されたままになってしまいます。 最も一般的な原因は、アプリが没入型アプリとして正しく設定されていないことです。生成されたtwa-manifest.jsonを開き、horizonOsAppModeが「2D」になっていることを確認してください。マニフェストを更新し、bubblewrap buildを再度実行します。
cli ERROR spawn EINVALというエラーが発生します。どうすればよいですか。bubblewrapランタイムを実行しているNodeJSバージョンを確認してください。Windowsデバイスでbubblewrap.jsファイルを実行するには、NodeJS 21.0.0 を使う必要があります。
Android Gradle plugin requires Java 17 to run. You are currently using Java 11.というエラーが発生します。どうすればよいですか。これは、デバイスにすでにインストールされているbubblewrapツールのJDKバージョンの競合によるものだと考えられます。config.jsonファイルの"jdkPath"フィールドを編集して、Java 17 JDKを参照するようにしてください(ファイルのデフォルトパスはMacでは~/.bubblewrap/config.json、Windowsでは C:\Users\<username>\.bubblewrap\config.json)。または、config.jsonファイルの"jdkPath"フィールドを削除して、bubblewrapコマンドを実行することにより、互換性のあるJDKファイルを自動でインストールすることもできます。
WindowsでGradleのビルドが失敗します。 これは、Windows上で動作するオリジナルのbubblewrapプロジェクトにおいて発生する
既知の問題 です。この問題を解決するには、プロジェクトの
gradle.propertiesファイル内の
org.gradle.jvmargs=-Xmx1536mプロパティを削除するか、コメントアウトする必要があります。このフィールドは、プロジェクトを生成または更新するたびに追加されます。
bubblewrap buildを実行する前に必ず修正してください。