Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazonアプリストア
Ring
AWS
ドキュメント
Support
Contact Us
My Cases
開発
設計と開発
公開
リファレンス
サポート
メインコンテンツへスキップ
JavaScript(JS)は、ヘッドレスタスクとヘッドレスサービスという2つの方法により、ユーザーインターフェイス(UI)を表示せずにバックグラウンドで実行することができます。タスクは独立して動作する1回限りの操作であるのに対し、サービスは継続的な対話を可能にします。たとえば、タスクでは、アプリを開かずにTVチャンネルデータを取得して番組ガイドを更新できます。サービスはメディア再生などの機能を処理します。UIはサービスにコマンド(再生や一時停止など)を送信でき、サービスはメディアのストリーミングと処理を別のランタイムで管理します。このアプローチにより、負荷の高い処理をバックグラウンドに移動して、メインインターフェイスの応答性を維持することができます。

ヘッドレスJSタスクおよびサービスのJSランタイム

ヘッドレスJSタスクとヘッドレスJSサービスは、バックグラウンドでVegaアプリコンポーネントを利用します。アプリコンポーネントは、JSコードの実行を可能にするために最上位にセカンダリJSランタイム(Hermesで動作)を追加し、コードからライフサイクルイベントをリッスンできるようにします。ヘッドレスJSタスク/サービスの各インスタンスには、それぞれ独自のJavaScriptランタイムインスタンスが保持されます。

ヘッドレスJSコンテキストでサポートされるモジュール

ヘッドレスランタイムは、メモリフットプリントを小さく保つために、ユーザーインターフェイスで利用できる機能を簡易化したものです。次の表に示すモジュールのみがサポートされます。

ヘッドレスJSコンテキストでサポートされるReact Nativeライブラリ

ヘッドレスJSランタイムでサポートされるモジュールは限られており、次の表に示す特定のReact Nativeライブラリのセットのみがサポートされます。

インポートのガイドライン

ヘッドレスランタイムでは、インポートできるものに厳密な制限があります。UIコンポーネントやサポートされていないライブラリをインポートすると、クラッシュが発生します。 以下の一覧に、安全にインポートできるユーティリティと、安全でないユーティリティの例を示します。

安全なインポート

✅ React Native標準の非UIユーティリティ:
✅ Vega固有のヘッドレスライブラリ:
✅ コアJavaScript API:

安全でないインポート

❌ UIコンポーネント(クラッシュが発生):
❌ UI関連のAPI(クラッシュが発生):
❌ ワイルドカードによるインポート(クラッシュが発生):
ログに「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. このエラーは、問題のモジュールを直接インポートしていなくても発生することがあります。次のような場合に発生します。
  • 問題のモジュールをインポートするモジュールを使用している。
  • サポートされていないライブラリを使用しようとしている。
  • モジュールのインポートが正しくない。
たとえば、ヘッドレスJSのコードを記述しているときに、ヘッドレスエクスポートではなく@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"(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同期タスクは別のプロセスで実行されます。
実装する各機能の固有のドキュメントを必ず確認してください。わずかな違いが大きい問題につながることがあるため、異なるヘッドレスJS機能間で設定をコピーしないでください。

手順2:エントリポイントを登録する

タスクとサービスのエントリポイント(タスクではdoTask関数、サービスではonStartServiceおよびonStopService関数を使用)を登録するには、task.jsとservice.jsという2つのファイルを個別に作成することをお勧めします。これらのファイルは、index.js(AppRegistry.registerComponentを使用してUIのエントリポイントを登録するファイル)と一緒に配置します。task.jsファイルとservice.jsファイルを使用して、複数のヘッドレスJSタスク/サービスのエントリポイントを登録できます。
react-native build-vegaを使用してアプリをビルドする場合は、このプロセスによってヘッドレスJSバンドルが自動的に処理されます。次のファイルをプロジェクトのルートに配置してください。
  • ヘッドレスタスクのtask.js
  • ヘッドレスサービスのservice.js
ビルドシステムは、これらのファイルを検出して以下を作成します。
  • タスクのtask.hermes.bundle
  • サービスのservice.hermes.bundle
これらのバンドルが自動的にアプリパッケージ(VPKG)に含められます。
react-native build-vegaを使用しない場合は、次の手順を手動で実行する必要があります。
  • エントリポイントファイル(task.jsとservice.js)からHermesバイトコードバンドルを生成します。
  • これらのバンドルを手動でアプリパッケージ(VPKG)に追加します。

ヘッドレスJSタスクおよびサービスのデバッグ

ログ

ヘッドレスJSタスク/サービスのコードをデバッグするには、コンソールログ(console.log)を使用し、その出力をデバイスログで確認できます。 デバイスまたはシミュレーターシェルから次のコマンドを実行します。
ログが切り捨てられないようにするには、デバイスまたはシミュレーターシェルから次のコマンドを実行します。

再ビルドなしでのJSバンドルのクイック更新

ヘッドレスJSタスクおよびサービスで、アプリを再ビルドして再インストールしなくても、更新されたJSバンドルを取得できるようになりました。 ヘッドレスJSタスク/サービスでは、再起動せずに変更を反映できるホットリロードや高速リフレッシュはサポートされません。代わりに、ヘッドレスJSタスク/サービスを再起動して、更新されたJSバンドルを取り込む必要があります。 この機能を使用するには、次の手順に従います。
  1. アプリ(UIとヘッドレスJSコンポーネント)をデバッグモードでビルドします。注:UIコンポーネントと同様に、行単位のデバッグはリリースビルドでは機能しません。
  2. アプリをインストールします。
  3. プロジェクトルートからMetroサーバーを実行します(npm start)。
  4. アプリとMetroで使用するように構成されているポート(通常は8081)に、デバイス(target)から開発コンピューター(host)への逆方向のポートフォワーディングを設定します。この手順を実行しないと、アプリからMetroサーバーに接続することはできません。
  5. アプリを起動します。これで、すべてのJSバンドル(UIとヘッドレスJSの両方)がMetroによって提供されるようになります。

行単位のデバッグ

ヘッドレスJSタスク/サービスは行単位でデバッグできますが、いくつかの制限があります。
  • Vega StudioのDev Toolsでのみ機能します。
  • Dev Toolsには最後に起動されたJSコンポーネントだけが表示されます。
たとえば、ヘッドレスJSメディア再生アプリでは次のようになります。
  • UIとサービスの両方が同時に実行されます。
  • サービスが最後に起動するため、Dev Toolsにはservice.bundleが表示されます。
  • 代わりにUIをデバッグするには、次の手順を実行する必要があります。
    • vega device launch-app -a <ヘッドレスJSコンポーネント名>を使用して、最初にヘッドレスサービスを起動します。
    • 次にUIコンポーネントを起動します。
    • これでDev Toolsにindex.bundleが表示されます。
行単位のデバッグを使用するには、次の手順に従います。
  1. アプリ(UIとヘッドレスJSコンポーネント)をデバッグモードでビルドします。注:UIコンポーネントと同様に、行単位のデバッグはリリースビルドでは機能しません。
  2. アプリをインストールします。
  3. プロジェクトルートからMetroサーバーを実行します(npm start)。
  4. ポート8081(またはアプリとMetroに構成したポート)に、デバイス(target)から開発コンピューター(host)への逆方向のポートフォワーディングを設定します。この手順を実行しないと、アプリからMetroサーバーに接続してDev Toolsとやり取りすることはできません。
  5. デバッグするヘッドレスJSタスクまたはサービスを起動します。
    • 手動で起動するために、vega device launch-app -a <ヘッドレスJSコンポーネント名>というコマンドを実行します。
    • UIコンポーネントを起動します。
  6. Vega Studioでコマンドパレットを開き、「Vega: Launch Dev Tools」を選択します。[Sources] タブに移動し、[React Native] を選択します。
  7. デバッグしようとしている目的のバンドル(index.bundle/service.bundle/task.bundle)が表示され、そのソースが読み込まれていることを確認します。注:Dev Toolsでは、ソースマップの読み込みの失敗に関するエラーが表示されますが、これは無視して構いません。
  8. ブレークポイントを設定するには、ターゲットのコードを検索し、ブレークポイントを追加する行番号をクリックします。ブレークポイントがヒットするのは、そのブレークポイントの設定後に実行されるコードに対してだけです。つまり、起動直後に実行されるコード(ヘッドレスJSタスクのdoTaskや、ヘッドレスJSサービスのonStartServiceなど)にブレークポイントを設定してもトリガーされません。このような場合のデバッグには、引き続きログを使用してください。
  9. Dev Toolsは自動的には更新されないため、アプリを起動し直す合間に、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の構成を比較します。
シナリオ1:正しいインポート
正しいインポートの視覚化結果を示すスクリーンショット。 シナリオ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コンテキストでサポートされていないモジュールを検出し、それらのモジュールの読み込み元をトレースします。 検証ツールは次の目的にも使用できます。
  • トラブルシューティングのために依存関係グラフを生成する。
  • 問題のあるインポートチェーンを開発者が追跡することを支援する。
  • パッケージ内のバンドルの存在を検証する。
ダウンロード: (77.4 MB)
代替手段: デバッグバンドルを手動で検査する
サービス/タスク(エラーが発生しているもの)のJSバンドル(Hermesバイトコードバンドルではありません)を開きます。これは通常、build/lib/rn-bundles/Debugにあります。ここでは、例としてtask.bundleを取り上げます。これは任意のエディターを使用して開くことができます。 たとえば、前の手順で示した間違ったインポートを含むtask.bundleがあり、次のエラーが発生しているとします。
この場合、DeviceInfoを入力として受け取るTurboModuleRegistry.getEnforcing呼び出しを検索します。 呼び出しが見つかったら、そのコードが含まれているモジュールを特定できます。 たとえば、上記のtask.bundleでは次のようになります。
このコードは@amazon-devices/react-native-kepler/Libraries/Utilities/NativeDeviceInfo.jsにあります。 次のステップは、何がこのモジュールに依存しているかを特定することです。そのためには、task.bundleでモジュールID247を検索します。 上記のtask.bundleには、モジュールID 247に依存するモジュールが2つあります。
および
これらのいずれかに着目し、どこで使用されているかを検索します。これを数回繰り返すと、node_modules/@amazon-devices/react-native-kepler/index.jsというモジュールが表示されます。
これはtask.jsからインポートされています。

手順3:Amazonの担当者に連絡する

サポートされていないモジュールを検出できずに行き詰まった場合は、Amazonが問題の診断をお手伝いします。Amazonの担当者にお問い合わせのうえ、サポートを依頼してください。

ヘッドレスJSタスクおよびサービスの現在の利用状況

ヘッドレスJSタスクは、次のFire TV統合で利用されています。 ヘッドレスJSサービスは、次のユースケースで利用されています。
最終更新日 2026年10月26日