Console

Settings

Sign out

Notifications

Alexa

Amazonアプリストア

AWS

ドキュメント

Support

My Cases

Console

Vega開発者向けドキュメント

ホーム

開発

設計と開発

公開

リファレンス

サポート

視聴アクティビティ

オープンベータ版ドキュメント：本テクニカルドキュメントは、リリース前のオープンベータ版の一部としてAmazonから提供されるものです。ここで説明されている機能は、Amazonがフィードバックを受け取り、機能の開発を繰り返す過程で変更される可能性があります。最新の機能の情報については、リリースノートを参照してください。

視聴アクティビティデータは、複数のコンテンツ再生イベントで構成されます。このデータは、ユーザーがアプリで以前に視聴していたコンテンツに簡単に戻る手段を提供するために使用されます。将来的には、このデータを使用して、[次のおすすめの作品] などのおすすめのカルーセルを表示する可能性もあります。

視聴アクティビティは、Fire TVデバイスでローカルに発生することも、別のデバイスでリモートで発生することもあります。同じデバイスで発生した視聴アクティビティについては、再生開始、再生の進行状況、一時停止／再開、再生終了の各イベントを送信します。リモートの視聴アクティビティでは、終了状態（再生終了）のイベントのみを送信します。これらはUIを更新するために必要です。たとえば、ユーザーが視聴していたTV番組の次のエピソードを表示したり、既に視聴したコンテンツを削除したりするために使用されます。

送信する内容

トリガーごとに（「送信するタイミング」を参照）、以下のフィールドを含むイベントを送信します。送信するデータをフィルタリングしたり、重複をチェックしたりする必要はありません。これは必要に応じてAmazonが行います。

フィールド名	必須（○／×）	説明
コンテンツID	○	Amazonのカタログ統合を通じて指定された、ユーザーが視聴しているコンテンツのID。
ライブチャンネル記述子	○*	カタログ統合を通じて指定された、コンテンツを再生しているライブリニアチャンネルのチャンネル記述子。 * ライブコンテンツでのみ必要です。
内部プロフィールID	○	Fire TVがアクティビティを正しいアプリユーザーに関連付けることができるように、難読化されたプロフィールIDを提供します。
時間	○	コンテンツの長さ（ミリ秒）。
現在の再生位置	○	インタースティシャルコンテンツ（プレビューや広告など）を除く、コンテンツの開始位置からのオフセット（ミリ秒）を示します。
クレジットの位置	×	コンテンツ内のクレジットの位置。インタースティシャルコンテンツ（プレビューや広告など）を除く、コンテンツの開始位置からのオフセット（ミリ秒）を示します。このフィールドは、ユーザーがコンテンツを視聴し終えたことをFire TVで検出するために役立ちます。
イベントのタイムスタンプ	×*	* Off-Deviceイベントでは必須ですが、Activeイベントでは必須ではありません。
再生状態	○	コンテンツの再生状態を表す列挙型。APIドキュメントを参照してください。

イベントタイプの詳細

提供される再生イベントには、addPlaybackEvent関数： ActiveとOff-Deviceの2つのタイプがあります。

Activeイベントは、同じデバイス上でリアルタイムに発生します。たとえば、ユーザーがFire TVでアプリ内のタイトルを再生したときに発生します。イベントをActiveとしてマークできるのは、そのイベントが現在時刻にデバイス上で発生した場合だけです。再生イベントのタイムスタンプフィールドは、Activeイベントには使用されません。このタイムスタンプは、イベントが報告された瞬間にシステムによってキャプチャされます。

Off-Deviceイベントは、別のデバイスで別の時刻に発生する再生を表します。これは主に、ユーザーによる最新の視聴の進行状況をキャプチャするために使用されます。これにより、複数のデバイスにわたるユーザーの最新のエンゲージメントデータがFire TV UIに反映されます。Fire TVのオンデバイスサービスは、このタイプのデータを定期的な間隔で要求します。このタイプのイベントにはタイムスタンプが必要です。

同じFire TVデバイス上であっても、アクティブな再生以外の場所で発生した再生イベントを送信する場合は、それらをOff-Deviceとしてマークし、発生時の正確なタイムスタンプを指定します。同じデバイス上で発生したアクティブ以外のイベントを除外しないでください。Activeイベントの重複排除はAmazonが行います。

送信するタイミング

以下のトリガーが発生したときにイベント情報を送信します。

再生状態（開始、停止、一時停止、終了）が変更されたとき。
新しい再生位置にシークしたとき。
再生状態にかかわらず、プレーヤーの実行中は60秒間に1回。
ほかの種類のデバイスで発生したアクティビティの場合：
- Fire TVのオンデバイスサービスが定期的に動作し、このデータを同期するようにアプリに要求します。この要求には、データを共有するタイムウィンドウを示すパラメーターが含まれます。そのタイムウィンドウで発生したすべての再生イベントを送信する代わりに、再生終了イベントを送信します。これにより、コンテンツと最後の視聴時の進行状況をAmazonに伝えます。
- Fire TVデバイスでフォアグラウンドになっている場合。アプリでこのデータをサービスから同期し、Amazonに最新の視聴状況を送信します。
注： Amazonがアプリからデバイス外のデータを要求する場合の処理方法の詳細については、手順6：バックグラウンドまたはデバイス外のデータ用にデータプルサービスを実装するを参照してください。

送信方法

ユーザーがアプリを操作しているときに視聴アクティビティイベントを送信するには、次のサンプルコードを使用します。

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

// ユーザーがライブコンテンツの視聴を開始したときに生成される再生イベントの例

const playbackEvent: IPlaybackEvent = new PlaybackEventBuilder()
   .playbackPositionMs(0)
   .playbackState(PlaybackState.PLAYING)
   .durationMs(2000)
   .eventTimestamp(new Date())
   .contentId(
   new ContentIdBuilder()
      .id('content_CDF_ID')
      .idNamespace(ContentIdNamespaces.NAMESPACE_CDF_ID)
      .build(),
   )
   .channelDescriptor(new ChannelDescriptorBuilder()
      .majorNumber(0)
      .minorNumber(1)
      .identifier('channelID')
      .build(),
   )
   .profileId(
   new ProfileIdBuilder()
      .id('myProfileId')
      .idNamespace(ProfileIdNamespaces.NAMESPACE_APP_INTERNAL)
      .build(),
   )
   .buildActiveEvent();

// イベントを送信します
ContentPersonalizationServer.reportNewPlaybackEvent(playbackEvent);

次のTypeScriptのサンプルコードを使用して、コンテンツパーソナライゼーションデータサービスを通じてアプリが呼び出されたときに、デバイス外での視聴アクティビティデータを送信します。

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

const playbackEventsHandler: IPlaybackEventsHandler = {
    getPlaybackEventsSince: (
      sinceTimestamp: Date,
      playbackEventsProvider: IPlaybackEventsProvider,
    ) => {
        let playbackEvents: IPlaybackEvent[] = [];
        
        const playbackEvent: IPlaybackEvent = new PlaybackEventBuilder()
            .playbackPositionMs(0)
            .creditsPositionMs(1000)
            .playbackState(PlaybackState.EXIT)
            .durationMs(2000)
            .eventTimestamp(new Date())
            .contentId(new ContentIdBuilder()
                .id('content_CDF_ID')
                .idNamespace(ContentIdNamespaces.NAMESPACE_CDF_ID)
                .build(),
             )
            .profileId(new ProfileIdBuilder()
                .id('myProfileId')
                .idNamespace(ProfileIdNamespaces.NAMESPACE_APP_INTERNAL)
                .build(),
            )
            .buildOffDeviceEvent();
            
        playbackEvents.add(playbackEvent);
        
        playbackEventsProvider.addPlaybackEventChunk(playbackEvents);
        playbackEventsProvider.commit();
    }
};

// HeadlessServiceのonStart関数で再生イベントハンドラーを設定することを忘れないでください
ContentPersonalizationServer.setPlaybackEventsHandler(
        playbackEventsHandler,
);

ユーザーエクスペリエンスの検証

送信するタイミングの各項目に対してSDK呼び出しを実装したら、以下のアクションを実行し、結果を検証します。

デバイスのセットアップ

Fire TVデバイスをセットアップして登録します。
アプリのコンテンツは、Fire TVと統合されているカタログである必要があります。
Vegaコンテンツパーソナライゼーション対応アプリをデバイスにインストールし、アプリを起動します。
このアカウントで、続きを観る機能に同意する必要があります。これを行うには、次の手順に従ってください。
1. [設定] > [環境設定] > [プライバシー設定] > [アプリからの共有を管理] に移動して [アプリの視聴状況とコンテンツ情報の共有] を [オン] にします
2. [設定] > [環境設定] > [プライバシー設定] > [アプリからの共有を管理] に移動して [デバイス間での同期] を [オン] にします

[続きを観る] 行でのコンテンツ更新の確認

アプリは、ビデオ再生中の視聴アクティビティイベントを定期的に報告する必要があります。ユーザーがコンテンツの視聴を開始すると、システムはそのコンテンツを [続きを観る] 行に追加します。

アプリで、ビデオを開いて再生します。動画の2%以上を視聴またはスクロールします。
停止または戻るボタンをクリックして、ビデオの再生を停止します。

ログをチェックして、再生イベントが正常に報告されたことを確認します。正常に報告されると、次のログ行が表示されます。

INFO com.amazon.com_amazon_tv_developer_dataservice.vega.vega_alberto_service:VegaAlbertoBinderService PlaybackEventsVegaMessage → message.sent_timestamp: <タイムスタンプ>, page_index : 0, total_page_count: 1, content_id id : <コンテンツID>, content_id namespace : cdf_id, event_timestamp_ms: <タイムスタンプ>, playback_state :0, duration_ms : <コンテンツの長さ>, credits_position_ms :<コンテンツのクレジット位置>

リモコンを使用して、アプリを終了するかまたはホームボタンをクリックして、ホーム画面に戻ります。
更新された [続きを観る] 行が表示されます。視聴していたビデオが表示されるはずです。表示されれば、正しく動作しています。
[続きを観る] 行が更新されない場合は、[ホーム] タブから別の任意のタブに移動し、[ホーム] タブに戻ります。
次の操作により、[続きを観る] 行からタイルを削除することもできます。
1. タイルにカーソルを合わせ、リモコンのメニューボタンをクリックし、[「続きを観る」から削除] を選択します。この方法によって、同じコンテンツでテストできます。

[続きを観る] 行からのコンテンツ削除の確認

ビデオの再生中、アプリは視聴アクティビティイベントを定期的に報告する必要があります。また、再生が完了したときや中断したときにも報告する必要があります。現在の再生位置が合計時間に近い場合は、ユーザーが動画の視聴を完了したことを示し、システムは [続きを観る] 行からコンテンツを削除します。

アプリを開いて、[視聴を続ける] 行に既にコンテンツが表示されているビデオの視聴を開始します。
ビデオの最後までシークするか、リモコンの進む（»）スクロールボタンを繰り返しクリックして、ビデオの最後まで移動します。

ログをチェックして、再生停止イベントが正常に報告されたことを確認します。正常に報告された場合、ログは次のようになります。

INFO com.amazon.com_amazon_tv_developer_dataservice.vega.vega_alberto_service:VegaAlbertoBinderService PlaybackEventsVegaMessage → message.sent_timestamp:  <タイムスタンプ> , page_index : 0, total_page_count: 1, content_id id : <コンテンツID>, content_id namespace : cdf_id, event_timestamp_ms: <タイムスタンプ>, playback_state :2, duration_ms : <コンテンツの長さ>, credits_position_ms : <コンテンツのクレジット位置>

[ホーム] タブに戻ります。
[続きを観る] 行にコンテンツが表示されなくなるはずです。
[続きを観る] 行が更新されない場合は、[ホーム] タブから別の任意のタブに移動し、[ホーム] タブに戻ってUIを更新します。

検証シナリオ

以下の該当する手順に従って、[続きを観る] 行のタイルを追加または削除します。それぞれのシナリオを検証してください。

想定される検証結果	検証手順
タイトルがまだ [続きを観る] 行に追加されない	1. 視聴途中でない映画タイトルの再生を開始します。 2. すぐに一時停止します。 3. Fire TVのホームページに移動します。
タイトルがホームの [続きを観る] 行の最初のエントリとして表示される	1. 映画タイトルの再生を再開します。 2. 映画を2%以上先まで早送りします。 3. Fire TVのホームページに移動します。
タイトルが [続きを観る] 行から削除される	1. TV番組の新しいエピソードの再生を開始します。 2. すぐに一時停止します。 3. Fire TVのホームページに移動します。
TV番組のエピソードがまだ [続きを観る] 行に追加されない	1. TV番組の新しいエピソードの再生を開始します。 2. すぐに一時停止します。 3. Fire TVのホームページに移動します。
TV番組の正しいシーズンとエピソード番号のエピソードが、[続きを観る] 行の最初のエントリとして追加される	1. TV番組のエピソードの再生を再開します。 2. タイトルを2%以上先まで続けて再生します。 3. Fire TVのホームページに移動します。
TV番組の正しいシーズンとエピソード番号のエピソードが、[続きを観る] 行の最初のエントリとして残る	1. 視聴途中だったTV番組のエピソードの再生を再開します。 2. すぐにFire TVのホームページに移動します。
TV番組の次のエピソードが [続きを観る] 行に表示される	1. 視聴途中だったTV番組のエピソードの再生を再開します。 2. エピソードの最後まで早送りします。 3. Fire TVのホームページに移動します。

トラブルシューティング

統合で発生する可能性のある一般的な問題は次のとおりです。

CDF IDが正しくない

SDKで使用されるカタログデータ形式（CDF）のIDは、カタログ統合で使用されているIDと完全に一致している必要があります。CDF IDはログには含まれないため、開発中、このIDを含むデバッグログをアプリに追加して、想定どおりのCDF IDが送信されていることを確認することをお勧めします。カタログ統合についてを参照してください。

再生イベントの報告が正しくない

すべての再生イベントは、状態を正確に表している必要があります。[続きを観る] 行は、アプリから報告された正確なデータに基づいて構築されます。避けるべき動作と、推奨される動作は次のとおりです。

禁止事項	推奨事項
プレーヤーにユーザーの実際の再生位置が読み込まれる前に、現在位置の再生イベントを送信する。	プレーヤーが読み込まれてから、ユーザーの正しい位置を使用して再生イベントを送信する。
インタースティシャル（広告、イントロ、プレビューなど）の再生中に現在の再生位置を進める。	コンテンツの現在の再生位置を使用して、インタースティシャル再生イベントを送信する。
コンテンツの再生中に、更新された再生位置を定期的に報告しない。	コンテンツの再生中に、60秒ごとに再生イベントを送信する。
コンテンツの終了時にPAUSEイベントを送信する。	再生の完了時にEXIT再生イベントを送信する。

イベントを送信するタイミングの詳細については、送信するタイミングを参照してください。

デバイス外のアクティビティで [続きを観る] 行が更新されない

これは想定された動作です。Fire TVサービスでは、デバイス外のアクティビティは [続きを観る] 行の構築に使用されません。

複数のアプリ内プロフィールのコンテンツが [続きを観る] 行に表示されている

[続きを観る] 列は、現在アクティブなFire TVプロフィールから記録された再生イベントに基づいています。ユーザーがアプリでプロフィールを変更しても、同じFire TVプロフィールを引き続き使用する場合、それらのイベントもそのプロフィールに含められます。これは想定された動作です。

Last updated: 2025年9月30日