視聴アクティビティ

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

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

送信する内容
- イベントタイプの詳細
送信するタイミング
送信方法
- [Continue Watching] 行にコンテンツが何も表示されない
- 一部のコンテンツが見つからない、間違った順序で表示される、誤って削除されている
ユーザーエクスペリエンスの検証
トラブルシューティング
- [Continue Watching] 行にコンテンツが何も表示されない
- 一部のコンテンツが見つからない、間違った順序で表示される、誤って削除されている

送信する内容

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

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

イベントタイプの詳細

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がアプリからデバイス外データをリクエストした場合の処理方法の詳細については、バックグラウンドまたはデバイス外のデータ用にデータプルサービスを実装する（英語のみ）を参照してください。

送信方法

視聴アクティビティを送信するには、以下のサンプルコードを使用します。

Java
Kotlin

 AmazonPlaybackReceiver receiver = AmazonPlaybackReceiver.getInstance(context);
 AmazonPlaybackEvent playbackInfo = AmazonPlaybackEvent
     .builder()
     .playbackPositionMs(0)
     .creditsPositionMs(1000)
     .state(AmazonPlaybackState.PLAYING)
     .durationMs(2000)
     .contentId(AmazonContentId.builder()
         .id("string")
         .namespace(AmazonContentId.NAMESPACE_CDF_ID)
         .build())
     .profileId(AmazonProfileId.builder()
         .id("myProfileId1")
         .namespace(AmazonProfileId.NAMESPACE_APP_INTERNAL)
         .build())
     .buildActiveEvent();
 receiver.addPlaybackEvent(playbackInfo);

val receiver: AmazonPlaybackReceiver = AmazonPlaybackReceiver.getInstance(context)
val playbackInfo: AmazonPlaybackEvent = AmazonPlaybackEvent
    .builder()
    .playbackPositionMs(0)
    .creditsPositionMs(1000)
    .state(AmazonPlaybackState.PLAYING)
    .durationMs(2000)
    .contentId(
        AmazonContentId.builder()
            .id("string")
            .namespace(AmazonContentId.NAMESPACE_CDF_ID)
            .build()
    )
    .profileId(
        AmazonProfileId.builder()
            .id("myProfileId1")
            .namespace(AmazonProfileId.NAMESPACE_APP_INTERNAL)
            .build()
    )
    .buildActiveEvent()
receiver.addPlaybackEvent(playbackInfo)

[Continue Watching] 行にコンテンツが何も表示されない

一般的なトラブルシューティング： [Continue Watching] 行にコンテンツが何も表示されないを参照してください。

一部のコンテンツが見つからない、間違った順序で表示される、誤って削除されている

統合で問題を引き起こす可能性のあるよくある誤りを以下に示します。

CDF IDが正しくない: SDKで使用されているカタログデータ形式（CDF）のIDが、カタログ統合に使用されているIDと完全に一致していることを確認することが重要です。CDF IDはSDKログには含まれないため、開発中、そのIDを含むデバッグログをアプリに追加して、想定どおりのCDF IDが送信されていることを確認することを推奨します。カタログ統合についてを参照してください。
再生イベントの報告が正しくない: すべての再生イベントは、状態を正確に表している必要があります。[Continue Watching] 行は、アプリから報告された正確なデータに基づいて構築されます。次のような動作は避けてください。

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

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

デバイス外のアクティビティで [Continue Watching] 行が更新されない: 現在、Fire TVサービスでは、デバイス外のアクティビティは [Continue Watching] 行の構築に使用されません。
複数のアプリ内プロフィールからのコンテンツが[Continue Watching] 行に表示される: [Continue Watching] 行は、現在アクティブなFire TVプロフィールから記録された再生イベントに基づいています。ユーザーがアプリ内でプロフィールを変更しても、同じFire TVプロフィールを使用し続けた場合は、それらのイベントも同じプロフィールに含められます。これは想定された動作です。

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

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

注：コンテンツがすぐに [Continue Watching] 行に表示されない場合、行が更新されるまでに最大5分ほどかかることがあります。行を強制的に更新するには、[設定] > [アカウントとプロフィールの設定] > [Amazonコンテンツを同期] の順にクリックします。

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

トラブルシューティング

[Continue Watching] 行にコンテンツが何も表示されない

一般的なトラブルシューティング： [Continue Watching] 行にコンテンツが何も表示されないを参照してください。

一部のコンテンツが見つからない、間違った順序で表示される、誤って削除されている

統合で問題を引き起こす可能性のあるよくある誤りを以下に示します。

CDF IDが正しくない: SDKで使用されているカタログデータ形式（CDF）のIDが、カタログ統合に使用されているIDと完全に一致していることを確認することが重要です。CDF IDはSDKログには含まれないため、開発中、そのIDを含むデバッグログをアプリに追加して、想定どおりのCDF IDが送信されていることを確認することを推奨します。カタログ統合についてを参照してください。
再生イベントの報告が正しくない: すべての再生イベントは、状態を正確に表している必要があります。[Continue Watching] 行は、アプリから報告された正確なデータに基づいて構築されます。次のような動作は避けてください。

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

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

デバイス外のアクティビティで [Continue Watching] 行が更新されない: 現在、Fire TVサービスでは、デバイス外のアクティビティは [Continue Watching] 行の構築に使用されません。
複数のアプリ内プロフィールからのコンテンツが[Continue Watching] 行に表示される: [Continue Watching] 行は、現在アクティブなFire TVプロフィールから記録された再生イベントに基づいています。ユーザーがアプリ内でプロフィールを変更しても、同じFire TVプロフィールを使用し続けた場合は、それらのイベントも同じプロフィールに含められます。これは想定された動作です。

次は、別のデータの種類である個別のコンテンツエンタイトルメントについて説明します。

Last updated: 2024年3月1日