視聴アクティビティ - Amazon Vega Docs

視聴アクティビティデータは、コンテンツ再生イベントで構成されます。このデータは、ユーザーがアプリで以前に視聴していたコンテンツに簡単に戻る手段を提供するために使用されます。将来的には、このデータを使用して、[次のおすすめの作品] などのおすすめのカルーセルを表示する可能性もあります。視聴アクティビティは、Fire TVデバイスでローカルに発生することも、別のデバイスでリモートで発生することもあります。同じデバイスで発生した視聴アクティビティについては、再生開始、再生の進行状況、一時停止／再開、再生終了の各イベントを送信します。リモートの視聴アクティビティでは、終了状態（再生終了）のイベントのみを送信します。これらはUIを更新するために必要です。たとえば、ユーザーが視聴していたTV番組の次のエピソードを表示したり、既に視聴したコンテンツを削除したりするために使用されます。

送信する内容

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

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

イベントタイプの詳細

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

送信するタイミング

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

再生状態（開始、停止、一時停止、終了）が変更されたとき。
新しい再生位置にシークしたとき。
再生状態にかかわらず、プレーヤーの実行中は60秒間に1回。

送信方法

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

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

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

// コンテンツインタラクションイベントの例

auto contentInteractionBuilder = serverComponent->makeContentInteractionBuilder()
    ->interactionTimestamp(Utils::getRealTimeInstant("2023-12-16T12:00:00Z"))
    ->contentInteractionType(IContentInteractionTypeEnum::INGRESS);

// サンプルのコンテンツ識別子を追加します。
auto contentId = serverComponent->makeContentIdBuilder()
    ->id("content_CDF_ID")
    ->idNamespace(IContentIdBuilder::NAMESPACE_CDF_ID)
    ->build();
contentInteractionBuilder->contentId(contentId);

// サンプルのプロファイル識別子を追加します。
auto profileId = serverComponent->makeProfileIdBuilder()
    ->id("myProfileId")
    ->idNamespace(IProfileIdBuilder::NAMESPACE_APP_INTERNAL)
    ->build();
contentInteractionBuilder->profileId(profileId);

auto contentInteraction = contentInteractionBuilder->build();

/ /新しいコンテンツインタラクションを報告します
contentPersonalizationServer->reportNewContentInteraction(contentInteraction);

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

送信するタイミングの各項目に対して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: <your_time_stamp>, page_index : 0, total_page_count: 1, content_id id : <your_content_id>, content_id namespace : cdf_id, event_timestamp_ms: <your_time_stamp>, playback_state :0, duration_ms : <your_content_duration>, credits_position_ms :<your_content_credit_position>

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

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

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

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

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

INFO com.amazon.com_amazon_tv_developer_dataservice.vega.vega_alberto_service:VegaAlbertoBinderService PlaybackEventsVegaMessage → message.sent_timestamp:  <your_time_stamp> , page_index : 0, total_page_count: 1, content_id id : <your_content_id>, content_id namespace : cdf_id, event_timestamp_ms: <your_time_stamp>, playback_state :2, duration_ms : <your_content_duration>, credits_position_ms : <your_content_credit_position>

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

トラブルシューティング

ここでは、統合時に発生する可能性のある一般的な問題について説明します。

AmazonコンテンツIDが正しくない

SDKの統合で使用するAmazonコンテンツIDが、カタログで使用するIDと完全に一致していることを確認することが重要です。SDKログにはコンテンツIDは含まれません。そのため、開発中は、IDを含むデバッグログをアプリに追加することを検討してください。このログを使用して、想定どおりのコンテンツIDが送信されているかどうかを確認します。カタログ統合の詳細については、EMBERカタログ統合の概要を参照してください。

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

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

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

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

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

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

​送信する内容

​イベントタイプの詳細

​送信するタイミング

​送信方法

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

​デバイスのセットアップ

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

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

​検証シナリオ

​トラブルシューティング

​AmazonコンテンツIDが正しくない

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

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