Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazonアプリストア
Ring
AWS
ドキュメント
Support
Contact Us
My Cases
開発
設計と開発
公開
リファレンス
サポート
ネイティブ
Skip to main content
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(クラッシュが発生):
❌ ワイルドカードによるインポート(クラッシュが発生):
‘DeviceInfo’ could 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. このエラーは、問題のモジュールを直接インポートしていなくても発生することがあります。次のような場合に発生します。
  • 問題のモジュールをインポートするモジュールを使用している。
  • サポートされていないライブラリを使用しようとしている。
  • モジュールのインポートが正しくない。
たとえば、ヘッドレス JS のコードを書くときに、@amazon-devices/react-native-w3cmediaヘッドレスエクスポートを使用する代わりに直接インポートすると、このエラーが表示されます。
のヘッドレスエクスポートには、ヘッドレス JS @amazon-devices/react-native-w3cmedia で安全に動作するモジュールのみが含まれます。このエクスポートをスキップすると、コードが DeviceInfo from などのサポートされていない機能に依存する UI 関連モジュールをロードしようとするため@amazon-devices/react-native-kepler、エラーが発生します。 今後、サポートされていないモジュールをビルド時に検出するツールの追加を予定していますが、現時点では、VegaでヘッドレスJavaScript用に承認されているモジュールのみを使用するようにしてください。

ヘッドレスJSタスクおよびサービスのビルド

ヘッドレスJSタスクおよびヘッドレスJSサービスを登録するには、以下の手順を実行する必要があります。

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

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

ログ

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

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

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

行単位のデバッグ

ヘッドレスJSタスク/サービスは行単位でデバッグできますが、いくつかの制限があります。
  • Vega StudioのDev Toolsでのみ機能します。
  • Dev Toolsには最後に起動されたJSコンポーネントだけが表示されます。
たとえば、ヘッドレスJSメディア再生アプリでは次のようになります。
  • UIとサービスの両方が同時に実行されます。
  • サービスが最後に起動するため、Dev Toolsにはservice.bundleが表示されます。
  • 代わりにUIをデバッグするには、次の手順を実行する必要があります。
    • 最初に以下を使用してヘッドレスサービスを起動します
    • 次にUIコンポーネントを起動します。
    • これでDev Toolsにindex.bundleが表示されます。
行単位のデバッグを使用するには、次の手順に従います。
  1. アプリ(UIとヘッドレスJSコンポーネント)をデバッグモードでビルドします。注: UIコンポーネントと同様に、行単位のデバッグはリリースビルドでは機能しません。
  2. アプリをインストールします。
  3. プロジェクトルートから Metro サーバー (npm start) を実行します。
  4. ポート8081(またはアプリとMetroに構成したポート)に、デバイス(targettarget)から開発コンピューター(hosthost)への逆方向のポートフォワーディングを設定します。この手順を実行しないと、アプリからMetroサーバーに接続してDev Toolsとやり取りすることはできません。
  5. デバッグするヘッドレスJSタスクまたはサービスを起動します。
    • 次のコマンドで手動で起動します:.
    • UIコンポーネントを起動します。
  6. Vega Studioでコマンドパレットを開き、「Vega: Launch Dev Tools」を選択します。[Sources] タブに移動し、[React Native] を選択します。
  7. リストされているバンドル (index.bundle/service.bundle/task.bundle) がデバッグ対象のバンドル (/) であり、そのソースがロードされていることを確認します。注: Dev Toolsでは、ソースマップの読み込みの失敗に関するエラーが表示されますが、これは無視して構いません。
  8. ブレークポイントを設定するには、ターゲットのコードを検索し、ブレークポイントを追加する行番号をクリックします。ブレークポイントがヒットするのは、そのブレークポイントの設定後に実行されるコードに対してだけです。つまり、起動直後に実行されるコード(ヘッドレスJSタスクのdoTaskdoTaskや、ヘッドレスJSサービスのonStartServiceonStartServiceなど)にブレークポイントを設定してもトリガーされません。このような場合のデバッグには、引き続きログを使用してください。
  9. Dev Toolsは自動的には更新されないため、アプリを起動し直す合間に、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
シナリオ1: // 正しいインポート
正しいインポートの視覚化結果を示すスクリーンショット。 シナリオ // 間違ったインポート
正しくないインポートの視覚化結果を示すスクリーンショット。 シナリオ 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コンテキストでサポートされていないモジュールを検出し、それらのモジュールの読み込み元をトレースします。 検証ツールは次の目的にも使用できます。
  • トラブルシューティングのために依存関係グラフを生成する。
  • 問題のあるインポートチェーンを開発者が追跡することを支援する。
  • パッケージ内のバンドルの存在を検証する。
ダウンロード: 128MB
代替手段: デバッグバンドルを手動で検査する
サービス/タスク(エラーが発生しているもの)の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統合で利用されています。 ヘッドレスJSサービスは、次のユースケースで利用されています。
最終更新日 2025年3月20日