手順4： EPG同期タスクを実装する

電子番組表（EPG）同期タスクの設計ガイドライン

1. EPG同期タスクを実装する前に、Vegaヘッドレスタスクおよびサービスを確認してください。
2. クラウドカタログを使用してタスクを軽量化します。
3. getLastCommittedLineupVersion関数を活用して軽量なバージョンチェックを実行し、システムに既に最新のラインナップが統合されている場合は、統合をスキップします。コミットバージョンは不透明型の文字列で、開発者に最適なアルゴリズムを使用して設定できます。ラインナップのハッシュ、タイムスタンプ、その他のバージョン管理方法を使用できます。
4. タスクのメモリ使用量がシステムのしきい値を超えたりタスクが終了したりしないように、メモリ使用量を制限します。
   1. API統合に必要なデータのみをダウンロードします。
   2. HTTP 1.1 Rangeリクエストヘッダー（RFC 7233、セクション3）などの手法を使用して、バックエンドからデータをチャンクまたはページ単位でダウンロードします。
   3. EPGデータにはXMLデータスキーマを使用しないでください。JSで解析する場合、JSONスキーマの方が簡単でメモリ効率にも優れています。
5. EPG同期タスクが何らかの理由によってPromise.reject(error)で失敗した場合、システムは指数関数的バックオフを使用して、最大8回まで自動的に再試行します。

Vega EPGプロバイダーAPIのガイドライン

1. 最適なパフォーマンスを実現し、最新の機能を利用するには、インターフェイスの最新バージョンを使用してください。インターフェイスのバージョン管理は、名前の末尾にサフィックスを付けて行っています。たとえば、ProgramLineupProviderの推奨アップグレード版はProgramLineupProvider2です。インターフェイスまたはAPIに関する全記述は、最新バージョンを使用していることを前提としています。
2. ChannelLineupProviderインターフェイスは、チャンネルラインナップ全体を想定しています。これは、現在のリストの完全なセットまたは置き換えを表します。
3. LiveEventProviderインターフェイスは、ライブイベントのラインナップ全体を想定しています。これは、現在のリストの完全なセットまたは置き換えを表します。
4. ChannelLineupProviderインターフェイス、ProgramLineupProviderインターフェイス、LiveEventProviderインターフェイスはトランザクション型です。
   1. トランザクションを完了するには、最後にcommit APIを呼び出す必要があります。commit()を呼び出した後は、オブジェクトを再利用することはできません。必要に応じて新しいオブジェクトを作成する必要があります。
   2. commitを呼び出さずにChannelLineupProviderオブジェクト、ProgramLineupProviderオブジェクト、LiveEventProviderオブジェクトを破棄すると、トランザクションは中止されます。
   3. ProgramLineupProviderを使用して番組を更新する前に、必要に応じて新しいチャンネルラインナップのcommitを実行します。チャンネルと番組の更新を交互に行うことはできません。
   4. 番組のChannelDescriptorに対応するチャンネルがコミットされていない場合、ProgramLineupProvider.upsert()操作は失敗します。
5. ラインナッププロバイダー関数は、同一スレッドで呼び出す必要があります（スレッドセーフではありません）。
6. ChannelMetadata.nameフィールドには、FireTVのカルーセルに表示されるチャンネルのマーケティング名が表示されます。このフィールドがない場合または空の文字列が指定されている場合、チャンネルの統合は失敗します。Fire TVでは最大25文字の英数字が表示されますが、文字数がこの制限を超えると、完全なチャンネル名は表示されません。この上限は、半角・全角のどちらの文字セットにも適用されます。例：
   1. The Walking Dead Universe（最大文字数内-表示される）。
   2. Ed's Purple Plane（最大文字数内-表示される）。
   3. How Sally Fell off her Horse and Learned to Play Piano on a Saturday（25文字を超えるため、最大文字数外-表示されない）。
   4. エドのパープルプレイン（最大文字数内-表示される）。
7. ProgramLineupProviderを使用する場合は、少なくとも48時間分のプログラムデータを提供します。
8. ユーザーがサブスクリプションパッケージをアップグレードまたはダウングレードすると、それに応じて視聴権限のあるチャンネルとライブイベントの数が変わります。これらの変更に対応するには、定期購入の変更時に、チャンネル、番組、ライブイベントを統合するAPI（それぞれingestChannelLineup()、ingestProgramLineup()、ingestLiveEvents()）が呼び出されるようにしてください。
9. ProgramLineupProviderを使用する場合は、少なくとも48時間分のプログラムデータを提供する必要があります。
10. ChannelMetadata.logoUrlに指定するチャンネルロゴは、サイズが120x68ピクセルのマルチトーン画像である必要があります。

エラー処理

データ統合中のすべてのエラーをキャッチして、バックエンドにプッシュする必要があります。アラームを作成して、エラーにできるだけ早く対処できるようにします。

1. ProgramLineupProviderとLiveEventProviderは部分的に成功したコミットをサポートし、コミットに失敗した番組とライブイベントに対してエラーフィードバックを提供します。
   1. ProgramLineupProviderのアップサートとLiveEventProviderの追加操作は、コミットキューへの追加に失敗したIUpsertProgramFailureオブジェクトまたはIAddLiveEventFailureオブジェクトのリストを返します。すべての番組またはライブイベントがコミットキューに正常に追加された場合は、空のリストが返されます。
   2. 失敗した番組とライブイベントはバックエンドにプッシュし、アラームをトリガーして、次回の同期の前に無効なデータの問題にすばやく対処できるようにください。
   3. 失敗した場合は、プログラムまたはライブイベントの統合プロセスを中断して失敗に対処して再試行するか、成功した番組またはライブイベントを部分的にコミットします。
2. プロバイダーに割り当てられたストレージのサイズ制限を超えて書き込もうとすると、EPG同期タスク中にStorageLimitErrorがスローされます。
   1. 統合を中止し、アラームをトリガーします。
   2. このエラーが発生した場合は、Amazonの担当者にお問い合わせください。
3. ChannelLineupProvider.add()を呼び出したときに、提供されたチャンネルのいずれかが無効な場合は、InvalidArgumentErrorがスローされます。エラーメッセージには、失敗した挿入の合計数と、失敗した最初の5つのチャンネルの理由が含まれます。
   1. このエラーメッセージの形式は次のとおりです。

      コードをコピー クリップボードにコピーしました。

      Found 1 invalid channels in provided data, list some examples: [{"channelIdentifier":"xxx","channelMajorNumber":xx,"channelMinorNumber":xx,"errorMessage": "xxx"}]
      

4. すべての文字列フィールドにはサイズ制限があります。フィールドの制限を超えた場合は、文字列が切り捨てられて末尾に「...」が追加されるか、InvalidArgumentErrorがスローされます。各フィールドの詳細は、EPGプロバイダーのインターフェイスのインラインドキュメントに記載されています。
5. EPG同期タスクが何らかの理由によってPromise.reject(error)で失敗した場合、システムは指数関数的バックオフを使用して、最大8回まで自動的に再試行します。

クラウドカタログとオンデバイス統合

前提条件に記載されているように、AmazonカタログサービスやGracenoteなどのクラウドサービスとカタログを統合することをお勧めします。CDFやGracenote統合モデルを活用することには、いくつかの利点があります。

• 非常に大規模で解析が難しい番組ラインナップを統合する必要がなくなります。
• チャンネルの統合時にChannelType以外のチャンネルメタデータを提供する必要がなくなります。残りはクラウドサービスを通じて自動的に取得されます。
• ユーザー数が増加したときのスケーラビリティが向上します。

CDFは最も直接的な統合であり、これによりレイテンシが短縮され、将来の機能をより迅速に有効化できます。クラウドベースのカタログを使用するか、オンデバイス番組ラインナップ統合を使用するかは、個々のチャンネルごとに選択する必要があることに注意してください。つまり、1つのチャンネルでGracenote IDを使用し、別のチャンネルではCDFを使用して、3つ目のチャンネルではオンデバイス番組ラインナップ統合を使用できます。

以下は、Fire TVでサポートされているファーストパーティ機能について、CDF、Gracenote、オンデバイス番組表統合を機能レベルで比較したものです。

機能	CDF	Gracenote	オンデバイス番組表統合
専用カルーセルの閲覧
[ライブプロバイダー] 行	✓	✓	✓
App Peak	✓	✓	✓
混合カルーセルの閲覧
[視聴履歴]	✓	✓	✓
[ホーム] の [放映中のチャンネル]	✓	✓	✓
[ジャンル] 行	✓	✓	✓
閲覧
電子番組表	✓	✓	✓
検索
チャンネル	✓	✓	✓
番組	✓	✓
音声
チャンネル名でチューニング	✓	✓	✓
番組名によるチューニング（新着／ライブのみ）	✓	✓
スケジュールの更新方法
カタログ検索により自動	✓	✓
オンデバイス			✓

CDFステーションIDの指定（推奨）

CDFステーションIDを指定すると、ライブTVアプリを通じて情報が毎日クラウドと同期されます。Fire TVカタログでチャンネルを検索する際に、指定したCDFステーションIDが使用されます。Fire TVカタログには、最大14日間の番組情報が含まれています。この情報は、[ホーム] タブ、[ライブ] タブのほか、番組表にも表示されます。この情報は自動的に更新され、常に最新の状態に保たれます。また、検索機能やAlexaを使用した音声操作でも検出可能になります。

このデータソースに使用する対応する値については、データの種類のリファレンスページの外部IDセクションを参照してください。

Gracenote IDの指定

GracenoteチャンネルID（onTVまたはGVD（グローバルビデオデータ））を指定すると、ライブTVアプリを通じて情報が毎日クラウドと同期されます。Gracenote IDが見つかった場合は、最大14日間の番組情報を含むFire TVカタログ内でチャンネルを検索する際に使用されます。この情報は、[ホーム] タブ、[ライブ] タブのほか、番組表にも表示されます。この情報は自動的に更新され、常に最新の状態に保たれます。また、検索機能やAlexaを使用した音声操作でも検出可能になります。

このデータソースに使用する対応する値については、データの種類のリファレンスページの外部IDセクションを参照してください。

オンデバイス番組表統合

チャンネルのCDFステーションIDまたはGracenoteチャンネルIDを指定しない場合は、以下を挿入してください。

• すべてのチャンネルメタデータ
• 使用するロゴのURL
• すべてのチャンネルの今後の番組情報（番組ラインナッププロバイダーを使用して定期的に配信）

Vegaサンプルアプリには、これを行う方法の例が示されています。

メタデータ値

チャンネル、番組、ライブイベントのさまざまなメタデータフィールドでサポートされている値については、データの種類のリファレンスページを参照してください。

チャンネルとライブイベントの順序

チャンネルの順序

チャンネルの順序によって、Fire TVデバイスのUIに表示されるチャンネルのランクが決まります。基本の順序はプロバイダーが決定します。ユーザーはコンテキストメニューやチャンネルマネージャーを使用して、チャンネルをお気に入りとして設定できます。こうすると、そのチャンネルが最も高い優先順位で表示されます。したがって、優先順位はお気に入り＞チャンネルの順序オプションとなります。

Fire TVには、次の種類のチャンネル順序が用意されています。

1. アルファベット順： Fire TV UIのチャンネルは、nameフィールドに基づき昇順で表示されます。これはデフォルトの順序です。
2. カスタムのチャンネルの順序： Fire TV UIのチャンネルは、チャンネルの統合中に提供されたチャンネルメタデータのSortRankフィールド値に基づく順序で表示されます。SortRankが指定されていない場合、チャンネルは順序の一番下に配置されます。優先順位が同じ場合は、チャンネルのnameのアルファベット順に並べられます。このチャンネル順序を使用する場合は、Amazonの担当者にお知らせください。
3. チャンネル番号順： Fire TV UIのチャンネルは、指定されているチャンネル記述子のメジャー番号とマイナー番号に従って昇順で表示されます。チャンネルは、最初にメジャー番号で並べ替えられ、次にマイナー番号で並べ替えられます。たとえば、チャンネル3.1はチャンネル3.10より前に表示されます。順位が同じ場合は、チャンネル名のアルファベット順に並べられます。このチャンネル順序を使用する場合は、Amazonの担当者にお知らせください。

一貫したエクスペリエンスを実現するには、アプリ内の順序に最も近いチャンネルの順序を選択してください。オンボーディングプロセスの一環として、Amazonの担当者と協力し、チャンネル順序の決定方法を選択してください。

ライブイベントの順序

Fire TV UI上のライブイベントは、ライブイベントの統合中に提供されたLiveEventメタデータのSortRankフィールド値に基づく順序で表示されます。SortRankが指定されていない場合、そのライブイベントは順序の一番最後に配置されます。同じ順位のライブイベントは、タイトルに従ってアルファベット順に並べられます。最も重要なコンテンツは、最も目立つように先頭に配置してください。

最大ロールアウトレート

ユーザーに対するチャンネルの段階的ロールアウトは、1時間あたり最大50万のレートで実行されます。

この値は、チャンネルの視聴権限があるユーザーのFire TVデバイスの数を示します。チャンネルの視聴権限がある状態とは、Fire TV内のリニアTV統合のUXからワンクリックで全画面再生を行うことができる状態を指します。

例：

• ABCアプリはビデオオンデマンドを提供していますが、プレミアムアドオンとしてライブTV機能も備えています。この場合、ライブTVのアドオンを利用しているABCユーザーのみがロールアウトの対象となります。
• XYZアプリには、無料の基本チャンネルパッケージに加えて、さらに多くのチャンネルを視聴できる有料プランが用意されています。有料プランのチャンネルラインナップが更新された場合、その有料プランのユーザーのみがロールアウトの対象となります。

UXフィールドの一覧

ここでは、Fire TV UXでメタデータフィールドがどのように使用されるかの例を示し、値を設定するときの参考となるコンテキストを提供します。

UXフィールド	説明	認定に必須（○/×）	関連メタデータフィールド
番組名	番組の名前。画面の左上に表示される大きなテキストです。	○	Program.title
再生時間	放送時間（例： 午後11:00～午前12:00）。番組名のすぐ下に表示されます。	○	Program.startTimeMs Program.endTimeMs
エピソード名	放映中のエピソードの名前。再生時間とバッジの下に太字で表示されます。	○	Program.subtitle
エピソードの説明	エピソードの説明。エピソード名の後に続くセクションに、表示可能な範囲で表示されます。	○	Program.description
シーズンとエピソードの情報	シリーズに共通の情報（ホームコメディなど）。この放送に関して提供されるシーズンとエピソードの情報です。この情報は、エピソード名の後に続くミニ詳細に含まれます。	×	Program.seriesInfo.season Program.seriesInfo.episode
レーティング	エピソードの地域のレーティング（バッジ形式）。再生時間と同じ行に表示されます。	×	Program.ratings
バッジに使用されるさまざまな属性	データの種類のリファレンスページの「属性」セクションを参照してください。	×	Program.attributes
番組画像	カルーセルタイルに表示される16:9の番組／映画の画像。解像度は768x432以上である必要があります。	○	Program.thumbnailUrl
背景画像	ミニ詳細セクションの隣にある右上隅のセクション全体に表示される16:9の番組／映画の画像。解像度は1280x720以上である必要があります。	○	Program.posterArtUrl
チャンネル名	カルーセル内でタイル表示されるチャンネルの名前。表示名の制限に関するガイダンスについては、EPG統合のベストプラクティスを参照してください。	○	ChannelMetadata.name
チャンネルロゴ	EPGで使用される120x68のマルチトーン画像。チャンネルロゴがない場合は、（マーキー内の）チャンネル名にフォールバックされます。	○	ChannelMetadata.logoUrl または、ChannelMetadataにロゴのURLを指定できない場合は、Amazonの連絡先に連絡して情報を提供してください。
チャンネルジャンル	チャンネルにジャンルを割り当てることができます。これにより、Fire TV UIの追加の入り口となるポイントでチャンネルが表示されるようになります。	×	ChannelMetadata.genres

• 前へ - 手順3： タスクを定義する
• 次へ - 手順5： EPG同期タスクをスケジュールする

---

Last updated: 2025年9月30日