ヘッドレス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 foundnot be found」のようなエラーが表示される場合は、ヘッドレスコンテキストで使用できないUIコンポーネントやUI関連のAPIがインポートされています。インポートを確認し、この記事のトラブルシューティングのセクションを参照してください。
サポートされていないモジュールを使用した場合
上記以外のモジュールやライブラリを使用すると、次の例のようなランタイムエラーが発生します。この例では、ヘッドレスJSコンテキストでは使用できないDeviceInfoDeviceInfoモジュールに関するエラーを示しています。
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 で安全に動作するモジュールのみが含まれます。このエクスポートをスキップすると、コードが DeviceInfo from などのサポートされていない機能に依存する UI 関連モジュールをロードしようとするため@amazon-devices/react-native-kepler、エラーが発生します。
今後、サポートされていないモジュールをビルド時に検出するツールの追加を予定していますが、現時点では、VegaでヘッドレスJavaScript用に承認されているモジュールのみを使用するようにしてください。
ヘッドレスJSタスクおよびサービスのビルド
ヘッドレスJSタスクおよびヘッドレスJSサービスを登録するには、以下の手順を実行する必要があります。手順1: アプリのマニフェスト(manifest.tomlmanifest.toml)でコンポーネントをアドバタイズする
- React Native 0.72
- React Native 0.83
マニフェストファイルの違い
さまざまなヘッドレスJSタスク/サービスに応じて、manifest.tomlファイルには異なる設定が必要になります。以下に例を示します。- EPG 同期タスクユーザ
"runtime-module = /com.amazon.kepler.headless.runtime.loader_2@IKeplerScript_2_0"(RN 0.72) または"runtime-module = /com.amazon.kepler.runtime.react_native_kepler_headless_4@IReactNativeKeplerHeadless_0"(RN 0.83) - ヘッドレス JS 再生ユーザ
"runtime-module = /com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"(RN 0.72) または"runtime-module = /com.amazon.kepler.runtime.react_native_kepler_4@IReactNativeKepler_0"(RN 0.83)
- ヘッドレスJS再生はUIと同じプロセスで実行されます。
- EPG同期タスクは別のプロセスで実行されます。
手順2: エントリポイントを登録する
タスク (関数を使用) とサービス (doTaskおよび関数を使用) のエントリポイントを登録するには、onStartService``onStopServiceとの 2 task.js つのファイルを個別に作成することをお勧めしますservice.js。ファイルを横に置くとindex.js、AppRegistry.registerComponent使用するUIのエントリポイントが登録されます。task.jstask.jsファイルとservice.jsservice.jsファイルを使用して、複数のヘッドレスJSタスク/サービスのエントリポイントを登録できます。
- ヘッドレスタスクのtask.js
- ヘッドレスサービスのservice.js
- タスクのtask.hermes.bundle
- サービスのservice.hermes.bundle
react-native build-vega、次のことを手動で行う必要があります。
- エントリポイントファイルから Hermes バイトコードバンドルを生成 (および)
task.jsservice.js - これらのバンドルを手動でアプリパッケージ(VPKG)に追加します。
ヘッドレスJSタスクおよびサービスのデバッグ
ログ
ヘッドレスJSタスク/サービスのコードをデバッグするには、コンソールログ(console.logconsole.log)を使用し、その出力をデバイスログで確認できます。
デバイスまたはシミュレーターシェルから次のコマンドを実行します。
再ビルドなしでのJSバンドルのクイック更新
ヘッドレスJSタスクおよびサービスで、アプリを再ビルドして再インストールしなくても、更新されたJSバンドルを取得できるようになりました。 ヘッドレスJSタスク/サービスでは、再起動せずに変更を反映できるホットリロードや高速リフレッシュはサポートされません。代わりに、ヘッドレスJSタスク/サービスを再起動して、更新されたJSバンドルを取り込む必要があります。 この機能を使用するには、次の手順に従います。- アプリ(UIとヘッドレスJSコンポーネント)をデバッグモードでビルドします。注: UIコンポーネントと同様に、行単位のデバッグはリリースビルドでは機能しません。
- アプリをインストールします。
-
プロジェクトルートから Metro サーバー (
npm start) を実行します。 -
アプリとMetroで使用するように構成されているポート(通常は
80818081)に、デバイス(targettarget)から開発コンピューター(hosthost)への逆方向のポートフォワーディングを設定します。この手順を実行しないと、アプリからMetroサーバーに接続することはできません。 - アプリを起動します。これで、すべてのJSバンドル(UIとヘッドレスJSの両方)がMetroによって提供されるようになります。
行単位のデバッグ
ヘッドレスJSタスク/サービスは行単位でデバッグできますが、いくつかの制限があります。- Vega StudioのDev Toolsでのみ機能します。
- Dev Toolsには最後に起動されたJSコンポーネントだけが表示されます。
- UIとサービスの両方が同時に実行されます。
- サービスが最後に起動するため、Dev Toolsにはservice.bundleが表示されます。
- 代わりにUIをデバッグするには、次の手順を実行する必要があります。
- 最初に以下を使用してヘッドレスサービスを起動します
- 次にUIコンポーネントを起動します。
- これでDev Toolsにindex.bundleが表示されます。
- 最初に以下を使用してヘッドレスサービスを起動します
- アプリ(UIとヘッドレスJSコンポーネント)をデバッグモードでビルドします。注: UIコンポーネントと同様に、行単位のデバッグはリリースビルドでは機能しません。
- アプリをインストールします。
-
プロジェクトルートから Metro サーバー (
npm start) を実行します。 -
ポート8081(またはアプリとMetroに構成したポート)に、デバイス(
targettarget)から開発コンピューター(hosthost)への逆方向のポートフォワーディングを設定します。この手順を実行しないと、アプリからMetroサーバーに接続してDev Toolsとやり取りすることはできません。 -
デバッグするヘッドレスJSタスクまたはサービスを起動します。
- 次のコマンドで手動で起動します:.
- UIコンポーネントを起動します。
- Vega Studioでコマンドパレットを開き、「Vega: Launch Dev Tools」を選択します。[Sources] タブに移動し、[React Native] を選択します。
-
リストされているバンドル (
index.bundle/service.bundle/task.bundle) がデバッグ対象のバンドル (/) であり、そのソースがロードされていることを確認します。注: Dev Toolsでは、ソースマップの読み込みの失敗に関するエラーが表示されますが、これは無視して構いません。 -
ブレークポイントを設定するには、ターゲットのコードを検索し、ブレークポイントを追加する行番号をクリックします。ブレークポイントがヒットするのは、そのブレークポイントの設定後に実行されるコードに対してだけです。つまり、起動直後に実行されるコード(ヘッドレスJSタスクの
doTaskdoTaskや、ヘッドレスJSサービスのonStartServiceonStartServiceなど)にブレークポイントを設定してもトリガーされません。このような場合のデバッグには、引き続きログを使用してください。 - Dev Toolsは自動的には更新されないため、アプリを起動し直す合間に、Dev Toolsインスタンスを閉じて再起動してください。
クラッシュレポート
ヘッドレスJSタスクまたはサービスから未処理のJSエラーが発生すると、アプリがクラッシュし、集約クラッシュレポート(ACR)が生成されます。この動作は現在、ヘッドレスJSタスク/サービスのリリースビルドにのみ適用されます。ヘッドレスJSタスク/サービスのデバッグビルドで未処理のJS例外を検出するには、引き続きデバイスログを使用してください。ヘッドレスJSタスクおよびサービスに関する問題のトラブルシューティング
デバッグモードではヘッドレスJSタスク/サービスが動作するが、リリースモードでは起動しないかエラーが発生する
ログに次のようなエラーが表示される場合は、タスク/サービスバンドルが、ヘッドレスJSコンテキストでサポートされていないモジュールを初期化または使用しようとしています。手順1: ヘッドレス JS タスク/サービスreact-native-bundle-visualizerバンドルの構成を確認するのに使用します
たとえば、task.bundleからサポートされていないモジュールを誤って取り込んだ場合の a の構成を比較します。@amazon-devices/react-native-kepler
シナリオ // 間違ったインポート
シナリオ 2 の構成はtask.bundle、ヘッドレス JS コンテキストでサポートされていないモジュールも含めて@amazon-devices/react-native-kepler、バンドルに多数のモジュールが含まれていることを示しています。サポートされていないモジュールがタスク/サービスバンドルに含まれていることを確認したら、手順2に進んで、それらのモジュールが取り込まれた原因を特定します。
手順2: ヘッドレス JS task.bundle/service.bundle バンドルバリデーターを使用してビルドされたデバッグを検査します
Headless JS Bundle Validator
インポートに関する問題に対処するには、Headless JS Bundle Validatorを使用します。このツールは、ヘッドレスJSタスクまたはサービスのバンドルから、ヘッドレスJSコンテキストでサポートされていないモジュールを検出し、それらのモジュールの読み込み元をトレースします。 検証ツールは次の目的にも使用できます。- トラブルシューティングのために依存関係グラフを生成する。
- 問題のあるインポートチェーンを開発者が追跡することを支援する。
- パッケージ内のバンドルの存在を検証する。
代替手段: デバッグバンドルを手動で検査する
サービス/タスク(エラーが発生しているもの)のJSバンドル(Hermesバイトコードバンドルではありません)を開きます。通常はにありますbuild/lib/rn-bundles/Debug。そうだとしましょうtask.bundle。これは任意のエディターを使用して開くことができます。
たとえば、前の手順で示した間違ったインポートを含むtask.bundletask.bundleがあり、次のエラーが発生しているとします。
TurboModuleRegistry.getEnforcing``DeviceInfo入力として使用されるコールを検索できます。
呼び出しが見つかったら、そのコードが含まれているモジュールを特定できます。
たとえば、task.bundle上記では次のようになります。
@amazon-devices/react-native-kepler/Libraries/Utilities/NativeDeviceInfo.js。
次のステップは、何がこのモジュールに依存しているかを特定することです。そのためには、247でモジュール ID を検索できますtask.bundle。
上記のtask.bundletask.bundleには、モジュールID 247に依存するモジュールが2つあります。
node_modules/@amazon-devices/react-native-kepler/index.js
task.jstask.jsからインポートされています。
手順3: Amazonの担当者に連絡する
サポートされていないモジュールを検出できずに行き詰まった場合は、Amazonが問題の診断をお手伝いします。Amazonの担当者にお問い合わせのうえ、サポートを依頼してください。ヘッドレスJSタスクおよびサービスの現在の利用状況
ヘッドレスJSタスクは、次のFire TV統合で利用されています。- 電子番組表
- アプリのインストール時またはアップデート時の処理のスケジュール: EPGの更新、アプリマニフェストのタスク

