ヘッドレスJSタスクおよびサービスのJSランタイム
ヘッドレスJSタスクとヘッドレスJSサービスは、バックグラウンドでVegaアプリコンポーネントを利用します。アプリコンポーネントは、JSコードの実行を可能にするために最上位にセカンダリJSランタイム(Hermesで動作)を追加し、コードからライフサイクルイベントをリッスンできるようにします。ヘッドレスJSタスク/サービスの各インスタンスには、それぞれ独自のJavaScriptランタイムインスタンスが保持されます。ヘッドレスJSコンテキストでサポートされるモジュール
ヘッドレスランタイムは、メモリフットプリントを小さく保つために、ユーザーインターフェイスで利用できる機能を簡易化したものです。次の表に示すモジュールのみがサポートされます。ヘッドレスJSコンテキストでサポートされるReact Nativeライブラリ
ヘッドレスJSランタイムでサポートされるモジュールは限られており、次の表に示す特定のReact Nativeライブラリのセットのみがサポートされます。インポートのガイドライン
ヘッドレスランタイムでは、インポートできるものに厳密な制限があります。UIコンポーネントやサポートされていないライブラリをインポートすると、クラッシュが発生します。 以下の一覧に、安全にインポートできるユーティリティと、安全でないユーティリティの例を示します。安全なインポート
✅ React Native標準の非UIユーティリティ:安全でないインポート
❌ UIコンポーネント(クラッシュが発生):Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'DeviceInfo' could not be found」のようなエラーが表示される場合は、ヘッドレスコンテキストで使用できないUIコンポーネントやUI関連のAPIがインポートされています。インポートを確認し、この記事のトラブルシューティングのセクションを参照してください。
サポートされていないモジュールを使用した場合
上記以外のモジュールやライブラリを使用すると、次の例のようなランタイムエラーが発生します。この例は、ヘッドレスJSコンテキストでは使用できないDeviceInfoモジュールに関するエラーを示しています。
E Volta:[KeplerScript-JavaScript] Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'DeviceInfo' could not be found. Verify that a module by this name is registered in the native binary., js engine: hermes.
このエラーは、問題のモジュールを直接インポートしていなくても発生することがあります。このエラーが発生するのは以下の場合です。
- 使用しているモジュールが、問題のあるモジュールをインポートしている。
- サポートされていないライブラリを使用している。
- モジュールのインポートが正しくない。
@amazon-devices/react-native-w3cmediaを直接インポートすると、このエラーが発生します。
@amazon-devices/react-native-w3cmediaのヘッドレスエクスポートには、ヘッドレスJSで安全に動作するモジュールのみが含まれています。このエクスポートを経由しないと、コードでは、@amazon-devices/react-native-keplerのDeviceInfoなど、サポートされていない機能に依存するUI関連のモジュールの読み込みが試みられ、エラーが発生することになります。
今後、サポートされていないモジュールをビルド時に検出するツールの追加を予定していますが、現時点では、VegaでヘッドレスJavaScript用に承認されているモジュールのみを使用するようにしてください。
ヘッドレスJSタスクおよびサービスのビルド
ヘッドレスJSタスクおよびヘッドレスJSサービスを登録するには、以下の手順を実行する必要があります。手順1:アプリのマニフェスト(manifest.toml)でコンポーネントをアドバタイズする
マニフェストファイルの違い
さまざまなヘッドレスJSタスク/サービスに応じて、manifest.tomlファイルには異なる設定が必要になります。以下に例を示します。- EPG同期タスクには「
"runtime-module = /com.amazon.kepler.headless.runtime.loader_2@IKeplerScript_2_0"」を使用します。 - ヘッドレスJS再生には「
"runtime-module = /com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"」を使用します。
- ヘッドレスJS再生はUIと同じプロセスで実行されます。
- EPG同期タスクは別のプロセスで実行されます。
手順2:エントリポイントを登録する
タスクとサービスのエントリポイント(タスクではdoTask関数、サービスではonStartServiceおよびonStopService関数を使用)を登録するには、task.jsとservice.jsという2つのファイルを個別に作成することをお勧めします。これらのファイルは、index.js(AppRegistry.registerComponentを使用してUIのエントリポイントを登録するファイル)と一緒に配置します。task.jsファイルとservice.jsファイルを使用して、複数のヘッドレスJSタスク/サービスのエントリポイントを登録できます。
- ヘッドレスタスクのtask.js
- ヘッドレスサービスのservice.js
- タスクのtask.hermes.bundle
- サービスのservice.hermes.bundle
react-native build-vegaを使用しない場合は、次の手順を手動で実行する必要があります。
- エントリポイントファイル(
task.jsとservice.js)からHermesバイトコードバンドルを生成します。 - これらのバンドルを手動でアプリパッケージ(VPKG)に追加します。
ヘッドレスJSタスクおよびサービスのデバッグ
ログ
ヘッドレスJSタスク/サービスのコードをデバッグするには、コンソールログ(console.log)を使用し、その出力をデバイスログで確認できます。
デバイスまたはシミュレーターシェルから次のコマンドを実行します。
再ビルドなしでのJSバンドルのクイック更新
ヘッドレスJSタスクおよびサービスで、アプリを再ビルドして再インストールしなくても、更新されたJSバンドルを取得できるようになりました。 ヘッドレスJSタスク/サービスでは、再起動せずに変更を反映できるホットリロードや高速リフレッシュはサポートされません。代わりに、ヘッドレスJSタスク/サービスを再起動して、更新されたJSバンドルを取り込む必要があります。 この機能を使用するには、次の手順に従います。- アプリ(UIとヘッドレスJSコンポーネント)をデバッグモードでビルドします。注:UIコンポーネントと同様に、行単位のデバッグはリリースビルドでは機能しません。
- アプリをインストールします。
-
プロジェクトルートからMetroサーバーを実行します(
npm start)。 -
アプリとMetroで使用するように構成されているポート(通常は
8081)に、デバイス(target)から開発コンピューター(host)への逆方向のポートフォワーディングを設定します。この手順を実行しないと、アプリからMetroサーバーに接続することはできません。 - アプリを起動します。これで、すべてのJSバンドル(UIとヘッドレスJSの両方)がMetroによって提供されるようになります。
行単位のデバッグ
ヘッドレスJSタスク/サービスは行単位でデバッグできますが、いくつかの制限があります。- Vega StudioのDev Toolsでのみ機能します。
- Dev Toolsには最後に起動されたJSコンポーネントだけが表示されます。
- UIとサービスの両方が同時に実行されます。
- サービスが最後に起動するため、Dev Toolsにはservice.bundleが表示されます。
- 代わりにUIをデバッグするには、次の手順を実行する必要があります。
- vega device launch-app -a <ヘッドレスJSコンポーネント名>を使用して、最初にヘッドレスサービスを起動します。
- 次にUIコンポーネントを起動します。
- これでDev Toolsにindex.bundleが表示されます。
- アプリ(UIとヘッドレスJSコンポーネント)をデバッグモードでビルドします。注:UIコンポーネントと同様に、行単位のデバッグはリリースビルドでは機能しません。
- アプリをインストールします。
-
プロジェクトルートからMetroサーバーを実行します(
npm start)。 -
ポート8081(またはアプリとMetroに構成したポート)に、デバイス(
target)から開発コンピューター(host)への逆方向のポートフォワーディングを設定します。この手順を実行しないと、アプリからMetroサーバーに接続してDev Toolsとやり取りすることはできません。 -
デバッグするヘッドレスJSタスクまたはサービスを起動します。
- 手動で起動するために、vega device launch-app -a <ヘッドレスJSコンポーネント名>というコマンドを実行します。
- UIコンポーネントを起動します。
- Vega Studioでコマンドパレットを開き、「Vega: Launch Dev Tools」を選択します。[Sources] タブに移動し、[React Native] を選択します。
-
デバッグしようとしている目的のバンドル(
index.bundle/service.bundle/task.bundle)が表示され、そのソースが読み込まれていることを確認します。注:Dev Toolsでは、ソースマップの読み込みの失敗に関するエラーが表示されますが、これは無視して構いません。 -
ブレークポイントを設定するには、ターゲットのコードを検索し、ブレークポイントを追加する行番号をクリックします。ブレークポイントがヒットするのは、そのブレークポイントの設定後に実行されるコードに対してだけです。つまり、起動直後に実行されるコード(ヘッドレスJSタスクの
doTaskや、ヘッドレスJSサービスのonStartServiceなど)にブレークポイントを設定してもトリガーされません。このような場合のデバッグには、引き続きログを使用してください。 - Dev Toolsは自動的には更新されないため、アプリを起動し直す合間に、Dev Toolsインスタンスを閉じて再起動してください。
クラッシュレポート
ヘッドレスJSタスクまたはサービスから未処理のJSエラーが発生すると、アプリがクラッシュし、集約クラッシュレポート(ACR)が生成されます。この動作は現在、ヘッドレスJSタスク/サービスのリリースビルドにのみ適用されます。ヘッドレスJSタスク/サービスのデバッグビルドで未処理のJS例外を検出するには、引き続きデバイスログを使用してください。ヘッドレスJSタスクおよびサービスに関する問題のトラブルシューティング
デバッグモードではヘッドレスJSタスク/サービスが動作するが、リリースモードでは起動しないかエラーが発生する
ログに次のようなエラーが表示される場合は、タスク/サービスバンドルが、ヘッドレスJSコンテキストでサポートされていないモジュールを初期化または使用しようとしています。手順1:react-native-bundle-visualizerを使用して、ヘッドレスJSタスク/サービスバンドルの構成を確認する
たとえば、サポートされていないモジュールをタスクバンドルが@amazon-devices/react-native-keplerから誤って取り込んでいる場合は、task.bundleの構成を比較します。
シナリオ2:間違ったインポート
シナリオ2のtask.bundleの構成は、このバンドルに@amazon-devices/react-native-keplerから多数のモジュールが取り込まれ、ヘッドレスJSコンテキストでサポートされていないモジュールも含まれていることを示しています。サポートされていないモジュールがタスク/サービスバンドルに含まれていることを確認したら、手順2に進んで、それらのモジュールが取り込まれた原因を特定します。
手順2:Headless JS Bundle Validatorを使用してデバッグビルドのtask.bundle/service.bundleを検査する
Headless JS Bundle Validator
インポートに関する問題に対処するには、Headless JS Bundle Validatorを使用します。このツールは、ヘッドレスJSタスク/サービスのバンドルから、ヘッドレスJSコンテキストでサポートされていないモジュールを検出し、それらのモジュールの読み込み元をトレースします。 検証ツールは次の目的にも使用できます。- トラブルシューティングのために依存関係グラフを生成する。
- 問題のあるインポートチェーンを開発者が追跡することを支援する。
- パッケージ内のバンドルの存在を検証する。
手順3:Amazonの担当者に連絡する
サポートされていないモジュールを検出できずに行き詰まった場合は、Amazonが問題の診断をお手伝いします。Amazonの担当者にお問い合わせのうえ、サポートを依頼してください。ヘッドレスJSタスクおよびサービスの現在の利用状況
ヘッドレスJSタスクは、次のFire TV統合で利用されています。- 電子番組表
- アプリのインストール時またはアップデート時の処理のスケジュール:EPGの更新、アプリマニフェストのタスク

