概述：資料收集 API 第 2 版

簡介

分析資料會由布萊特灣玩家自動傳送，包括原生玩家 SDK 所提供的資料。如果你是不是使用 Brightcove Player 傳送 Video Cloud 視頻時，您需要對用於將數據發送到 Data Collector 的播放器進行檢測。

數據收集API v2是當前標準。v1 版本已棄用。如果您有 v1 實現，請參閱v1 的變化下面的部分。

除了這個概述和API參考 , 也看到這個示例實現 .

Analytics Data Collection API是實時分析事件的終結點。事件數據通過HTTP請求提交的一系列參數發送到Brightcove，例如：

  https://metrics.brightcove.com/v2/tracker?event=video_view&domain=videocloud&account=123&video=789
  
  

這些參數描述了一個事實關於事件發生時系統的狀態。上面的例子描述了一個事實video_view視頻發生事件789帳戶123（或者：用戶開始觀看帳戶123的視頻789 .看以下了解當前跟踪的分析事件的描述）。

尺寸

維度是事件發生時有關係統狀態的定性事實。例如，如果請求是：

  https://metrics.brightcove.com/tracker/v2/?event=video_view
  &session=581136_2018-07-03T18:34:46.214Z
  &domain=videocloud&account=123
  &video=789
  
  

視頻 ID ( 789 ) 和帳戶 ID ( 123 ), 並且從請求本身收集到的任何設備和位置信息都是與請求相關的維度video_view事件。分析系統將記錄video_view發出此請求時發生的事件具有這些維度。

事件和域參數

這event參數描述發生了哪個事件。這domain參數為事件提供命名空間。這event , domain， 和session是必需的參數（的值domain總是videocloud ).

附加參數

事件中必須包含某些參數，以便Analytics（分析）系統可以成功分析它們

回應類型

對分析數據收集API請求的響應包括HTTP響應代碼和人類可讀的消息。

VOD 和現場活動

現場活動

必須滿足以下條件才能讓 Data Collection API 將事件分類為 Live ：

• 請求 不能 有 video_duration 參數。
• 請求必須有帳戶參數。
• 請求必須有視頻參數。
• 事件類型必須是以下之一：
  • play_request
  • video_impression
  • video_view
  • video_engagement
  • alive_ss_ad_start
• 該帳戶必須由 Brightcove Support 啟用以進行實時視頻流。

VOD

• 你必須包括video_duration有要求僅適用於 VOD。永遠不要為直播流發送 video_duration .
• 任何包含video_duration參數將被分類為點播 .

最少的數據

至少，你應該發送一個session編號和video_view會話期間播放的每個視頻的事件。這video_view應該發送後任何前置廣告都已完成。

session

這是會話標識符。這session本質上是其中包含播放器的頁面或應用程序視圖的一個視圖，只要它持續。該值在會話期間應保持不變，並且為所有事件發送 .它應盡可能接近全局唯一標識符（GUID）。如果存在衝突，如果無法解開這兩個會話，則可能會將其視為無效會話而被丟棄。

在JavaScript中有多種創建GUID的方案。一個例子是這個 GitHub 存儲庫 .請注意，Brightcove不支持第三方腳本。

性能數據最少（播放率和參與度得分）

活動

• video_impression
• play_request
• video_view
• video_engagement

屬性（所有事件）

• account
• video

附加屬性 ( video_engagement僅限活動）

VOD

• range
• video_duration

生活

• video_seconds_viewed

HTTP頭

• User-Agent -設備報告必需

最佳實務

為確保將正確的數據發送到收集器，應在一般部署之前測試數據收集腳本。我們推薦：

1. 為您的播放器構建數據收集腳本。
2. 在受控環境中測試至少一天。
3. 通過分析模塊或Analytics API以確保所收集的內容符合您的期望。

發送請求-避免CORS問題

垃圾數據

通常，發送到收集器的數據將由Analytics（分析）系統記錄為真值。如果事件包含不適當或不正確的信息，則Analytics（分析）系統將錯誤地解釋數據。

例如，如果您不小心將時間戳記作為視頻ID發送，則分析數據將以影響整體匯總的方式發生偏差。

URI 編碼

您發送到 Data Collection API 的任何可能包含空格或特殊字符的字符串必須經過 URI 編碼為了請求成功。如果您通過 JavaScript 提交請求，您可以使用encodeURI()方法對請求字符串進行編碼。例如：

  urlStr += "&video=" + currentVideo.id + "&video_name=" + encodeURI(currentVideo.video_name);
  
  

活動

下面列出的事件由Google Analytics（分析）系統處理。

player_load

意圖 ／ 意義

玩家會話已由最終用戶發起。這標誌著分析會話的開始，應在任何其他事件之前發送。

範例

https://metrics.brightcove.com/tracker
  ?event=player_load
  &session=581136_2018-07-03T18:34:46.214Z
  &destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
  &source=http%3A-%2F%2Fwww.google.com
  %2Furl%3Fsa%3D-t%26rct%3Dj%26q%3D%26esrc%3Ds%26source
  %253A-%252F%252Fsupport.brightcove.com%252F%26ei%3D
  OdxWZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200
  &time=1377191644796

error

意圖 ／ 意義

遇到干擾播放體驗的嚴重錯誤時傳送。

範例

https://metrics.brightcove.com/tracker
  ?event=error
  &error_code=MEDIA_ERR_SRC_NOT_SUPPORTED
  &session=581136_2018-07-03T18:34:46.214Z
  &destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
  &source=http%3A-%2F%2Fwww.google.com
  %3Dhttp%253A-%252F%252Fsupport.brightcove.com
  %26usgWZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200
  &time=1377191644796

catalog_request

意圖 ／ 意義

發出對Video Cloud Playback API的請求時發送。

範例

https://metrics.brightcove.com/tracker
  ?event=catalog_request
  &session=581136_2018-07-03T18:34:46.214Z
  &catalog_url=https%3A%2F%2Fedge.api.brightcove.com%2Fplayback
  &destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
  &source=http%3A-%2F%2Fwww.google.com
  %3Dhttp%253A-%252F%252Fsupport.brightcove.com
  WZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
  &domain=videocloud&account=1749339200
  &time=1377191644796

catalog_response

意圖 ／ 意義

當對先前的響應時發送catalog_request收到。

範例

https://metrics.brightcove.com/tracker
  ?event=catalog_response
  &session=581136_2018-07-03T18:34:46.
  &catalog_url=https%3A%2F%2Fedge.api.brightcove.com%2Fp2F23823423800
  &response_time_ms=243
  &destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
  &source=http%3A-%2F%2Fwww.google.com
  53A-%252F%252Fsupport.brightcove.com%252F%2Tzn-oCgCQ
  AFQjCNJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200
  &time=1377191644796

play_request

意圖 ／ 意義

當播放是由用戶明確點擊播放按鈕啟動，或者當平台在自動播放場景中觸發播放時自動發送。請注意，多個play_request如果觀看者暫停並繼續觀看視頻，則可能會在單個觀看會話期間發送事件。

範例

https://metrics.brightcove.com/tracker
  ?event=play_request
  &session=581136_2018-07-03T18:34:46.214Z
  &destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
  &source=http%3A-%2F%2Fwww.google.com
  %3Dhttp%253A-%252F%252Fsupport.brightcove.com%252F%2
  dJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200
  &video_duration=189
  &time=1377191644796

ad_mode_begin

意圖 ／ 意義

在播放平台將控制權移交給廣告代理程式時傳送。

範例

https://metrics.brightcove.com/tracker
  ?event=ad_mode_begin
  &session=581136_2018-07-03T18:34:46.214Z
  &destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
  &source=http%3A-%2F%2Fwww.google.com
  %3Dhttp%253A-%252F%252Fsupport.brightcove.com%252
  %26usg%3DAFQjCNEtLod%3Dbv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200
  &time=1377191644796

ad_mode_complete

意圖 ／ 意義

在播放平台將控制權移交給廣告代理程式時傳送。

範例

https://metrics.brightcove.com/tracker
  ?event=ad_mode_complete
  &session=581136_2018-07-03T18:34:46.214Z
  &destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
  &source=http%3A-%2F%2Fwww.google.com
  %3Dhttp%253A-%252F%252Fsupport.brightcove.com%252F%2
  WZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200
  &time=1377191644796

video_impression

意圖 ／ 意義

添加到播放器的視頻的元數據已完成加載，並且播放器已準備好通過自動播放或用戶交互來觸發觀看事件。

範例

https://metrics.brightcove.com/tracker
  ?event=video_impression
  &session=581136_2018-07-03T18:34:46.214Z
  &destination=http%3A%2F%2Fwww.current-times.com%2F
  &time=1377191644801
  &source=http%3A%2F%2Fwww.google.com
  %252-F%26ei%3DoEYWUtCgEIXq9ATznoCgCQ
  %26usg%3DAFQjCNEtLod-Odx6bvm%3Dbv.5115-6542%2Cd.dmg
  &video=2621468623001
  &video_name=Democratic-Rivals%20Target%20Bill
  &video_duration=189
  &domain=videocloud
  &account=1749339200

video_view

意圖 ／ 意義

視頻已開始播放（加載後自動播放，或者由於用戶交互）。注意只有一個video_view即使觀看者停止並重新啟動或重播視頻，也會在觀看會話期間記錄事件。

範例

https://metrics.brightcove.com/tracker
  ?event=video_view
  &session=581136_2018-07-03T18:34:46.214Z
  &destination=http%3A%2F%2Fwww.current-times.com%2F
  &video=2621468623001
  &video_name=Debate-2
  &video_duration=189
  &time=1377191666432
  &source=http%3A%2F%2Fwww.google.com%2Furl%
  %252F%26ei%3DoEYWUtCgEIXq9ATznoCgCQ%26us-g
  %3DAFQjCNEtv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200

video_engagement

意圖 ／ 意義

使用者觀看影片時間軸的秒範圍。此事件是追蹤視訊參與的活動訊號，可能會在播放期間傳送多次，視使用者互動和視訊的長度而定。如果播放不中斷，Brightcove播放器儀器將每10秒發送一次此事件。Analytics（分析）系統會丟棄描述超過20秒範圍的事件。

範例

https://metrics.brightcove.com/tracker
  ?event=video_engagement
  &session=581136_2018-07-03T18:34:46.214Z
  &destination=http%3A%2F%2Fwww.current-times.com%2F
  &video=2621468623001
  &video_name=Debate-2
  &video_duration=189
  &time=1377191676589
  &range=0..9
  &source=http%3A%2F%2Fwww.google.com
  %2Furl%3Fsa%3Dt-%26rct%3Dj%26q%3D%26esrc%3Ds
  %26source%3Dweb%26cd%3D1%26ved%3D0CDYQFjAA
  %26url%3Dhttp%253A%252F%252Fwww.current-times.com
  %252F%26ei%3DoEYWUtC-gEIXq9ATznoCgCQ
  %26usg%3DAFQjCNEtLodOdxWZSGdJpL7WJ.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200

所有事件的參數

這些事件的參數應包括事件發生時與系統當前狀態相關的任何信息，並應盡可能具體。本節詳細介紹可以與所有事件一起發送的參數，而以下各節顯示特定事件的參數。

用戶參數

• 如果播放器/客戶端應用程序要跟踪唯一的查看器，則應將用戶的唯一ID作為用戶參數發送給收集器。
• 如果user未提供或為空白，我們使用回退方法使用Source IP address + the User-Agent String作為唯一標識符。
• 用戶參數的值從不存儲在日誌/數據庫中，僅存儲散列（使用SHA-256）。
• 收集器未設置任何cookie。

唯一用戶

您可以使用Brightcove Player的插件功能將唯一的視頻查看器數據添加到報告的分析中。為此，您將向settings分析功能的對象。

當然，如何捕獲唯一用戶 ID 因應用程序而異，但例如，此代碼假定捕獲包含唯一用戶數據的登錄 URL，例如 https://exampledomain.com/users/912389123 。這個唯一的URL被傳遞給插件。

以下插件的代碼執行以下任務：

• 使用標準語法創建 Brightcove Player 插件，插件名稱定義為uniqueUserForAnalyticsPlugin .該插件還接受options對象，其中包含傳遞給插件的數據。
• 這myPlayer變量被分配給玩家的引用。同樣，還創建了兩個其他變量。
• 這userPath變量被分配通過傳遞給插件的路徑options目的。
• 這uniqueViewer變量被分配了解析後的版本userPath，因此只有用戶 ID 數字被分配給變量。
• 將用戶屬性添加到 Analytics 插件的settings目的。

  videojs.registerPlugin('uniqueUserForAnalyticsPlugin', function(options) {
  var myPlayer = this,
  userPath = '',
  uniqueViewer = '';
  //Assign uniqueViewer a value according to your app and business rules
  //In this example, parsing the path passed to the plugin in the options object
  userPath = options.path;
  uniqueViewer = userPath.substring( userPath.lastIndexOf('/') + 1 );
  //Assign a user variable to Analytic's settings object
  myPlayer.bcAnalytics.client.user(USER) = uniqueViewer;
  });
  
  

需要更改此代碼以適合您的應用程序邏輯，然後將其保存到Internet可訪問的URL。

在 Studio 中，使用插件部分在播放器中加載插件，如圖所示。

您可以將包含用戶數據的字符串傳遞給插件，而不是後面的JSON。當然，將需要相應地更新插件代碼以提取唯一的用戶ID。

  {
  "path": "https://exampledomain.com/users/912389123"
  }
  
  

有關插件開發的更多信息，請參閱一步步：插件開發文檔。

device_type , device_os , device_os_version , device_manufacturer， 和browser_type參數

默認情況下，Analytics系統將嘗試從User-Agent標頭中檢測設備類型和操作系統信息。如果兩個都device_type和device_os被發送時，來自 User-Agent 標頭的信息將被忽略，有利於device_type和device_os .在大多數情況下，您無需發送設備，操作系統和瀏覽器信息 -僅當User-Agent不可靠或不可用時，才應使用此替代。

分析系統將記錄other如果請求包含無法識別的設備參數覆蓋值。

地理數據參數

默認情況下，Google Analytics（分析）系統將嘗試從遠程IP地址檢測地理信息。可以通過傳遞來覆蓋此行為country , country_name , region , region_name , city和dma參數。在大多數情況下，不需要這些參數 -僅當遠程IP地址不可靠或不可用時才應使用此替代。

分析系統將記錄ZZ或者unknown如果請求包含無法識別的覆蓋值。

目標和源參數

這destination和source參數提供發起事件的 URI ( destination ) 和將用戶發送到那裡的 URI ( source ).

這source參數用於判斷流量來源信息。如果source未指定，Analytics 系統會將事件視為由直接流量發起。

這destination參數將用於確定交通目的地信息——即觀看視頻的位置。如果 URI 不包含權限，則 API 不會記錄權限destination_domain .這destination_path將被記錄為 URI 中的路徑。

網頁播放時，視頻播放頁面地址欄中的網址為destination , 和source是推薦人（top.document.referrer ).

例如，當在Brightcove支持網站上搜索“實時流媒體有線廣播”並觀看結果中顯示的視頻時：

  https://support.brightcove.com/en/video-cloud/search/live%20streaming%20wirecast
  
  

  https://support.brightcove.com/en/video-cloud/training-videos/live-streaming-wirecast
  
  

如果沒有 URL（例如在本機播放的情況下），則兩者destination和source應該是有效的 URI，分別標識視頻的播放位置和用戶如何到達那裡。

假設destination是一個有效的 URI :

  <scheme name> : <hierarchical part> [ ? <query> ] [ # <fragment> ]
  ex. https://www.example.com/foo/bar/baz
  --------------/----------/
  |             |
  authority        path
  ---/    -------------------------/
  |                |
  scheme       hierarchical part
  
  

分析系統將按如下方式處理：

如果 URI 包含一個權威，API 響應將使用該權限作為destination_domain以及作為destination_path .如果 URI 不包含權限，則 API 不會記錄權限destination_domain .這destination_path將被記錄為 URI 中的路徑。A destination沒有分層部分（例如只是一個方案）被認為是無效的，就像沒有方案的任何值一樣。

特定事件的參數

錯誤事件參數

應發送以下參數error事件。

catalog_request事件參數

應發送以下參數catalog_request事件。

catalog_response事件參數

應發送以下參數catalog_response事件。

video_impression事件參數

應發送以下參數video_impression事件。

video_view事件參數

應發送以下參數video_view事件。

video_engagement事件參數

應發送以下參數video_engagement事件。

這video_engagement事件是一種在播放視頻時跟踪視頻參與度的方法，並且可能會在播放期間發送多次。（如果播放不中斷，則Flash / HTML5播放器工具每10秒發送一次此事件。）目前，描述超過20秒範圍的事件已被Google Analytics（分析）系統丟棄，因此有必要更頻繁地發送這些事件。

有兩種形式video_engagement事件可以接受（為簡潔起見省略了其他參數）：

  event=video_engagement&video=123&video_duration=75&range=0..9
  
  

雖然這兩個版本都跟踪瀏覽秒數，但包含的版本video_duration和range還包含計算額外參與數據所需的信息，並且是首選方式發送video_engagement事件數據到分析系統。對於直播，或者視頻時間軸在播放過程中不斷變化或不可靠的情況，video_seconds_viewed將是唯一可用的數據。對於 VOD，除非duration不可用，則video_engagement事件應包括video_duration和range .

如果所有三個參數（video_duration , range和video_seconds_viewed ) 與一個一起發送video_engagement事件，Analytics 系統將從video_duration + range參數。

V2變更

本節為使用v1的用戶提供了從Data Collector的v1到v2的更改的摘要。

追踪器的基本網址

  http(s)://metrics.brightcove.com/v2
  
  

所有事件支持的其他字段：

device_os_version：設備正在使用的操作系統的版本。如果未指定，則將通過分析跟踪請求的用戶代理字符串來計算。

platform_version：用於指示正在使用指定平台的新版本發送事件。

V2的新事件

catalog_request：發出對videocloud目錄api的請求時發送-請注意，此事件僅供內部使用，並且不會在Analytics模塊中或通過Analytics API公開。

• 目錄網址：與catalog_request事件 - 請注意，此事件供內部使用，不會在分析模塊中或通過分析 API 公開。

catalog_response：當對先前的響應時發送catalog_request已收到 - 請注意，此事件供內部使用，不會在分析模塊中或通過分析 API 公開。

• 目錄網址：與catalog_request啟動此響應的事件 - 請注意，此事件供內部使用，不會在分析模塊中或通過分析 API 公開。
• response_time_ms：之間的時間，以毫秒為單位catalog_request事件和catalog_response事件 - 請注意，此事件供內部使用，不會在分析模塊中或通過分析 API 公開。

play_request：當播放是由用戶明確點擊播放按鈕啟動，或者當平台在自動播放場景中觸發播放時自動發送。

廣告模式開始：[取代ad_start ] 當播放平台將控制權交給廣告代理時發送。

ad_mode_complete：[取代ad_end ]當控制權從廣告代理交還給播放平台時發送。

錯誤：遇到干擾播放體驗的嚴重錯誤時傳送。

• 錯誤代碼：與事件關聯的特定於平台的錯誤代碼。

V2的更新事件

video_view：包括新的延遲測量

• load_time_ms：為視頻發起數據加載和開始播放視頻之間的時間（以毫秒為單位）。
• start_time_ms：開始播放與正在呈現之視訊的第一個影格之間的時間 (以毫秒為單位)。這可能會因體驗而異，例如，如果沒有配置前置廣告，則此測量值是“play_request”和“play_request”之間的時間video_view事件。如果有前置廣告，則間隔時間ad_mode_begin和ad_mode_complete不應該包括在內。

video_engagement：包括附加的演繹選擇，比特率測量和緩衝信息。視頻參與度也進行了微妙的更改，即使在參與度期間沒有觀看，也應定期發送視頻。此更改是為了啟用跟踪重新緩衝的延遲和計數，這些延遲和計數會導致用戶等待播放。

• 範圍：現在，範圍參數是可選的，可以將參與事件排除在範圍之外，以表明在該事件所覆蓋的時間段內沒有觀看活動。 （例如，當只有重新緩衝活動時）
• rendition_url：最近選取的轉譯的網址。例如，對於HLS流，這將是最近選擇的變體的url。
• rendition_indicated_bps：最近選擇的再現的指示比特率，以每秒比特數為單位。
• rendition_mime_type：最近選擇的演繹的啞劇類型。
• rendition_height：視訊轉譯的編碼高度 (以像素為單位)
• rendition_width：視訊轉譯的編碼寬度 (以像素為單位)
• rebuffering_seconds：用戶在參與期間由於未請求的延遲而等待視頻播放所花費的秒數。
• rebuffering_count：在指定的參與時間段內，由於重新緩衝而停止播放的次數。
• forward_buffer_seconds：當前位於前向緩衝區中的視頻的秒數。
• 測量的_bps：最近下載的段中包含的位數與下載該段所花費的時間之比，以每秒位數為單位。
• player_width玩家在交戰範圍末端的當前像素寬度。
• player_height玩家在交戰範圍末端的當前像素高度。
• drop_frames：在此參與期間視頻播放中掉落的幀數