在 Roku 上追蹤核心播放

上次更新: 2023-11-08
  • 建立對象:
  • User
    Admin
    Developer

本文件涵蓋 SDK 2.x 版中的追蹤。

重要

若您正在實作 SDK 1.x 版,您可以在此處下載 1.x 開發人員指南:下載 SDK

  1. 初始追蹤設定

    識別使用者何時觸發播放的意圖 (使用者點擊「播放」及/或開啟自動播放) 並建立 MediaObject 例項。

    MediaObject參考資料:

    變數名稱 說明 必填
    name 視訊名稱
    mediaid 視訊唯一識別碼
    length 視訊長度
    streamType 資料流類型 (請參閱下列 StreamType 常數)
    mediaType 媒體類型 (請參閱下列 MediaType 常數)

    StreamType常數:

    常數名稱 說明
    MEDIA_STREAM_TYPE_VOD 隨選視訊的資料流類型。
    MEDIA_STREAM_TYPE_LIVE LIVE 內容的資料流類型。
    MEDIA_STREAM_TYPE_LINEAR LINEAR 內容的資料流類型。
    MEDIA_STREAM_TYPE_AOD 隨選音效的資料流類型
    MEDIA_STREAM_TYPE_AUDIOBOOK 有聲書的資料流類型
    MEDIA_STREAM_TYPE_PODCAST 播客的資料流類型

    MediaType常數:

    常數名稱 說明
    MEDIA_STREAM_TYPE_AUDIO 音效資料流的媒體類型。
    MEDIA_STREAM_TYPE_VIDEO 視訊資料流的媒體類型。

    為含有 VOD 內容的視訊建立媒體資訊物件:

     mediaInfo = adb_media_init_mediainfo(
      "<MEDIA_NAME>",
      "<MEDIA_ID>",
      600,
      ADBMobile().MEDIA_STREAM_TYPE_VOD,
      ADBMobile().MEDIA_TYPE_VIDEO
    )
    

    mediaInfo = adb_media_init_mediainfo()
    mediaInfo.name = "<MEDIA_NAME>"
    mediaInfo.id = "<MEDIA_ID>"
    mediaInfo.length = 600
    mediaInfo.streamType = ADBMobile().MEDIA_STREAM_TYPE_VOD
    mediaInfo.mediaType = ADBMobile().MEDIA_TYPE_VIDEO
    

    為含有 AOD 內容的視訊建立媒體資訊物件:

    mediaInfo = adb_media_init_mediainfo(
     "<MEDIA_NAME>",
     "<MEDIA_ID>",
     600,
     ADBMobile().MEDIA_STREAM_TYPE_AOD,
     ADBMobile().MEDIA_TYPE_AUDIO
    )
    

    mediaInfo = adb_media_init_mediainfo()
    mediaInfo.name = "<MEDIA_NAME>"
    mediaInfo.id = "<MEDIA_ID>"
    mediaInfo.length = 600
    mediaInfo.streamType = ADBMobile().MEDIA_STREAM_TYPE_AOD
    mediaInfo.mediaType = ADBMobile().MEDIA_TYPE_AUDIO
    
  2. 附加中繼資料

    可選擇透過內容資料變數,將標準和/或自訂中繼資料物件附加到追蹤工作階段。

    • 標準中繼資料

在 Roku 上實作標準中繼資料

 <div class="extension note">
 <div>注意</div>
 <div>
 <p>將標準視訊中繼資料物件附加到媒體物件為選用。</p>
 </div>
 </div>
  • 自訂中繼資料

    為自訂變數建立變數物件,並為此視訊填入資料。例如:

    mediaContextData = {}
    mediaContextData["cmk1"] = "cmv1"
    mediaContextData["cmk2"] = "cmv2"
    
  1. 追蹤開始播放的意圖

    若要開始追蹤媒體工作階段,請呼叫媒體心率例項上的 trackSessionStart:

    ADBMobile().mediaTrackSessionStart(mediaInfo,mediaContextData)
    
    秘訣

    秒數值是您在步驟 2 建立的自訂視訊中繼資料物件名稱。

    重要

    trackSessionStart 會追蹤使用者的播放意圖,而非播放的開始。此 API 用來載入視訊資料/中繼資料,以及估計開始 QoS 量度所需的時間 (trackSessionStarttrackPlay 之間的時間)。

    注意

    若您未使用自訂視訊中繼資料,只要對 trackSessionStart 中的 data 引數傳送空白物件即可,如上方 iOS 範例中的備註行所示。

  2. 追蹤實際的播放開始

    識別來自視訊播放器的視訊播放開始 (在畫面上轉譯了視訊的第一個時間格) 事件,並呼叫 trackPlay

    ADBMobile().mediaTrackPlay()
    
  3. 更新播放點值

    當媒體播放點發生變更時,請呼叫 mediaUpdatePlayhead API。
    對於隨選影片 (VOD),此值是從媒體項目的開頭開始以秒為單位指定的。
    對於直播串流,如果播放器未提供內容持續時間的相關資訊,則此值可以指定為自當天 UTC 午夜開始的秒數。

    ADBMobile().mediaUpdatePlayhead(position)
    
    注意

    呼叫 mediaUpdatePlayhead API:

    • 使用進度標籤時,需要內容持續時間,並且播放點需要更新為從媒體專案開始的秒數,從0開始。
    • 使用Media SDK時,您必須呼叫 mediaUpdatePlayhead API至少每秒執行一次。
  4. 追蹤播放完成

    識別來自視訊播放器的視訊播放完成 (使用者已觀看內容至結尾) 事件,並呼叫 trackComplete

    ADBMobile().mediaTrackComplete()
    
  5. 追蹤工作階段結尾

    識別來自視訊播放器的視訊播放卸載/關閉 (使用者關閉視訊和/或視訊完成及卸載) 事件,並呼叫 trackSessionEnd

    ADBMobile().mediaTrackSessionEnd()
    
    重要

    trackSessionEnd 會標記視訊追蹤工作階段的結尾。如果成功觀看工作階段至完成 (使用者觀看了內容至結尾),請確定在 trackComplete 之前呼叫 trackSessionEnd。除了新視訊追蹤工作階段的 trackSessionStart 外,在 trackSessionEnd 之後會忽略任何其他 track* API 呼叫。

  6. 追蹤所有可能的暫停情況

    識別來自視訊播放器視訊暫停的事件,並呼叫 trackPause

    ADBMobile().mediaTrackPause()
    

    暫停情況

    識別視訊播放器將暫停的任何案例,並確定正確呼叫 trackPause。以下情形都要求應用程式呼叫 trackPause()

    • 使用者明確在應用程式中點擊暫停。
    • 播放器自行進入「暫停」狀態。
    • (行動應用程式) - 使用者讓應用程式進入背景,但您希望應用程式保持工作階段開啟。
    • (行動應用程式) - 發生任何類型的系統中斷,導致應用程式進入背景。例如,使用者接聽電話、或發生來自另一個應用程式的彈出視窗,但您希望應用程式維持工作階段進行中,讓使用者能夠從中斷點復原影片。
  7. 識別來自播放器的視訊播放和/或來自暫停的視訊恢復事件,並呼叫 trackPlay

    ADBMobile().mediaTrackPlay()
    
    秘訣

    這可能與在步驟 4 使用的事件來源相同。在視訊播放繼續時,使用後續的 trackPause() API 呼叫確保 trackPlay() API 呼叫成對。

此頁面上的