Android でのコア再生の追跡

このドキュメントでは、バージョン 2.x の SDK でのトラッキングについて説明しています。

1. トラッキングの初期設定

   いつユーザーが再生の意図をトリガーする（ユーザーが再生をクリックする、または自動再生がオンになる）かを識別し、MediaObject インスタンスを作成します。

   createMediaObject API

   変数名	説明	必須
   name	メディア名	○
   mediaId	メディアの一意の ID	○
   length	メディアの長さ	○
   streamType	ストリームタイプ（後述の StreamType 定数 を参照）	○
   mediaType	メディアタイプ（後述の​MediaType 定数 を参照）	○

   StreamType定数：

   定数名	説明
   VOD	ビデオオンデマンドのストリームタイプ。
   LIVE	Live コンテンツのストリームタイプ。
   LINEAR	Linear コンテンツのストリームタイプ。
   AOD	オーディオオンデマンドのストリームタイプ。
   AUDIOBOOK	オーディオブックのストリームタイプ。
   PODCAST	ポッドキャストのストリームタイプ。

   MediaType定数：

   定数名	説明
   Audio	オーディオストリームのメディアタイプ。
   Video	ビデオストリームのメディアタイプ。

   MediaHeartbeat.createMediaObject(<MEDIA_NAME>,
     <MEDIA_ID>, <MEDIA_LENGTH>, <STREAM_TYPE>, <MEDIA_TYPE>);
   

2. メタデータのアタッチ

   オプションで、コンテキストデータ変数を使用して標準またはカスタムメタデータオブジェクトをトラッキングセッションにアタッチします。

   • 標準メタデータ

     Android での標準メタデータの実装

     メモ

     メディアオブジェクトへの標準メタデータオブジェクトのアタッチはオプションです。

     • メディアメタデータキー API リファレンス - 標準メタデータキー - Android
     • 利用可なビデオメタデータの包括的なセットについては、オーディオおよびビデオパラメーターを参照してください。

   • カスタムメタデータ

     カスタム変数のディクショナリを作成し、このメディアのデータを設定します。次に例を示します。

     HashMap<String, String> mediaMetadata =
       new HashMap<String, String>();
     mediaMetadata.put("isUserLoggedIn", "false");
     mediaMetadata.put("tvStation", "Sample TV Station");
     mediaMetadata.put("programmer", "Sample programmer");
     

3. 意図を追跡して再生を開始

   メディアセッションの追跡を開始するには、メディアハートビートインスタンスの trackSessionStart を呼び出します。次に例を示します。

   public void onVideoLoad(Observable observable, Object data) {
       _heartbeat.trackSessionStart(mediaInfo, mediaMetadata);
   }
   

   ヒント

   2 つ目の値は、手順 2 で作成した、カスタムのメディアメタデータオブジェクトの名前です。

   重要

   trackSessionStart では、再生の開始ではなく、ユーザーの再生の意図を追跡します。この API は、メディアのデータ／メタデータを読み込み、開始時間の QoS 指標（trackSessionStart () と trackPlay () の間の時間）を見積もるために使用します。

   メモ

   カスタムのメディアメタデータを使用しない場合は、trackSessionStart の 2 番目の引数に空のオブジェクトを送信します。

4. 実際の再生開始を追跡

   メディアの再生開始（メディアの最初のフレームが画面に表示）に関するイベントをメディアプレーヤーから識別し、trackPlay を呼び出します。

   // Video is rendered on the screen) and call trackPlay.
   public void onVideoPlay(Observable observable, Object data) {
       _heartbeat.trackPlay();
   }
   

5. 再生の完了を追跡

   メディア再生完了（ユーザーがコンテンツを最後まで視聴）に関するイベントをメディアプレーヤーから識別し、trackComplete を呼び出します。

   public void onVideoComplete(Observable observable, Object data) {
       _heartbeat.trackComplete();
   }
   

6. セッションの終了を追跡

   メディア再生のアンロード／終了（ユーザーがメディアを閉じる、またはメディアが完了してアンロードされる）に関するイベントをメディアプレーヤーから識別し、trackSessionEnd を呼び出します。

   // Closes the media and/or the media completed and unloaded,
   // and call trackSessionEnd().
   public void onMainVideoUnload(Observable observable, Object data) {
       _heartbeat.trackSessionEnd();
   }
   

   重要

   trackSessionEnd は、メディアトラッキングセッションの終わりをマークします。セッションが最後まで適切に視聴された場合（ユーザーがコンテンツを最後まで視聴）は、trackComplete の前に trackSessionEnd を呼び出すようにしてください。trackSessionEnd の後は、他のすべての track* API 呼び出しは無視されます（新しいメディアトラッキングセッション用の trackSessionStart を除く）。

7. 考えられるすべての一時停止シナリオを追跡

   メディアの一時停止に関するイベントをメディアプレーヤーから識別し、trackPause を呼び出します。

   public void onVideoPause(Observable observable, Object data) {
       _heartbeat.trackPause();
   }
   

   一時停止のシナリオ

   ビデオプレーヤーが一時停止するあらゆるシナリオを識別して、trackPause が適切に呼び出されるようにします。以下のシナリオでは、アプリで trackPause() () を呼び出す必要があります。

   • アプリ内でユーザーが明示的に一時停止をクリックする。
   • プレーヤー自体が一時停止状態になる。
   • （モバイルアプリケーション）- ユーザーがアプリケーションをバックグラウンドに移行した場合でも、アプリケーションのセッションを開いたままにしておきたい。
   • （モバイルアプリケーション）- 何らかのシステムの割り込みが生じ、アプリケーションがバックグラウンドに移行する。例：ユーザーに電話がかかってきた場合や、別のアプリケーションのポップアップが表示された場合でも、アプリケーションのセッションを終了せず、ユーザーが中断した場所からメディアを再開できるようにしたい。

8. 一時停止からのメディア再生およびメディア再開に関するイベントをメディアプレーヤーから識別し、trackPlay を呼び出します。

   // trackPlay()
   public void onVideoPlay(Observable observable, Object data) {
       _heartbeat.trackPlay();
   }
   

   ヒント

   これは、手順 4 で使用したのと同じイベントソースである可能性があります。メディア再生が再開される際に、各 trackPause() API 呼び出しが後続の trackPlay() API 呼び出しと対になっていることを確認します。

コア再生の追跡に関する追加情報については、以下を参照してください。

• トラッキングのシナリオ：広告のない VOD 再生
• Android SDK に含まれている、追跡の完全な例を示すサンプルプレーヤー