概述： Data Collection API v2

簡介

Analytics（分析）資料會由 Brightcove Player，包括本機提供的 Player SDK。 如果你是 不 使用 Brightcove Player 交付 Video Cloud 視頻，您需要檢測 player 您正在用來將數據發送到數據收集器。

Data Collection API v2是當前標準。 v1版本已棄用。 如果您有v1的實現，請參見 與v1相比的變化 以下部分。

除了本概述和 API參考，也看到這個 示例實施.

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

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

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

尺寸

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

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

影片ID（ 789）和帳戶ID（ 123），並且從請求本身收集的任何設備和位置信息都是與 video_view 事件。 Analytics（分析）系統會記錄 video_view 發出此請求並具有這些尺寸的事件。

事件和域參數

event 參數描述發生了哪個事件。 的 domain 參數提供事件的名稱空間。 的 event, domain和 session 是必填參數（ domain 總是 videocloud).

附加參數

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

回應類型

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

最少的數據

至少，您應該發送一個 session id和 video_view 會話中播放的每個視頻的事件。 的 video_view 應該發送 後 所有片頭廣告均已完成。

session

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

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

性能數據最少（播放率和 Engage計分）

活動

• video_impression
• video_view
• video_engagement

屬性（所有事件）

• account
• video

附加屬性（video_engagement 僅活動）

VOD

• range
• video_duration

Live

• video_seconds_viewed

HTTP標頭

• User-Agent -設備報告必需

最佳實踐

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

1. 為您的數據構建腳本 player.
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

意向/含義

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

例

http://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

意向/含義

當遇到致命錯誤並破壞播放體驗時發送。

例

http://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 是。

例

http://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 收到。

例

http://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

意向/含義

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

例

http://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
  &time=1377191644796

ad_mode_begin

意向/含義

當播放平台將控制權移交給廣告代理時發送。

例

http://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

意向/含義

當播放平台將控制權移交給廣告代理時發送。

例

http://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

意向/含義

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

例

http://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
  &domain=videocloud
  &account=1749339200

video_view

意向/含義

視頻已開始播放（加載後自動播放，或者由於用戶交互）。

例

http://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

意向/含義

用戶觀看了視頻時間軸的幾秒鐘範圍。 此事件是跟踪視頻參與度的心跳，並且在播放期間可能會發送多次，具體取決於用戶交互和視頻的長度。 布萊頓灣 player 如果不中斷播放，則儀器每10秒發送一次此事件。 Analytics（分析）系統會丟棄描述超過20秒範圍的事件。

例

http://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

所有事件的參數

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

用戶參數

• 如果 player/ client應用程序想要跟踪唯一的查看器，因此它應該向用戶發送唯一的ID作為用戶參數到收集器。
• 如果 user 未提供或為空，我們使用後備方法 Source IP address + the User-Agent String 作為唯一標識符。
• 用戶參數的值從不存儲在日誌/數據庫中，僅存儲哈希（使用SHA-256）。
• 收集器未設置任何cookie。

唯一用戶

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

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

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

• 使用標準語法創建 Brightcove Player 插件名稱定義為 uniqueUserForAnalyticsPlugin。 該插件還接受 options 對象，其中包含傳遞給插件的數據。
• myPlayer 變量分配了對 player。 同樣，還創建了兩個其他變量。
• userPath 為變量分配了通過傳遞給插件的路徑 options 目的。
• uniqueViewer 變量分配給解析的版本 userPath，因此僅將用戶ID數字分配給該變量。
• 用戶屬性已添加到Google 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中，使用 插件 部分將插件加載到 player， 如圖所示。

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

  {
  "path": "http://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 or unknown 如果請求包含無法識別的替代值。

目標和源參數

destination 和 source 參數提供了引發事件的URI（ destination）以及將用戶發送到那裡的URI（ source).

source 參數用於確定流量來源信息。 如果 source 如果未指定，則Analytics（分析）系統會將事件視為由直接流量發起。

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

在網絡播放期間，正在播放視頻的頁面地址欄中的URL是 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
  
  

Google Analytics（分析）系統將按以下方式進行處理：

如果URI包含 權威，API響應將使用該權限作為 destination_domain 以及提供為 destination_path。 如果URI不包含授權，則API將不會記錄 destination_domain。 “ destination_path 將被記錄為URI中的路徑。 一個 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 player 如果播放沒有中斷，則檢測儀器每10秒發送一次此事件。） 目前，描述超過20秒範圍的事件已被Google Analytics（分析）系統丟棄，因此有必要更頻繁地發送這些事件。

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

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

雖然兩個版本都跟踪觀看秒數，但其中包含的版本 video_duration 和 range 還包含計算其他參與數據所需的信息，並且 首選方式 發送 video_engagement 事件數據發送到Google Analytics（分析）系統。 對於實時流，或在播放期間視頻時間軸不斷變化或不可靠的情況下， video_seconds_viewed 將是唯一可用的數據。 對於VOD，除非 duration 無法使用 video_engagement 事件應包括 video_duration 和 range.

如果所有三個參數（ video_duration, range 和 video_seconds_viewed）與 video_engagement 事件，Google Analytics（分析）系統將根據 video_duration+ range 參數。

V2變更

本節概述了使用v1的用戶從Data Collector的v2到v1的變化。

追踪器的基本網址

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

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

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

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

V2的新事件

catalog_request：在發出對videocloud目錄api的請求時發送-請注意，此事件僅供內部使用，不會在Analytics（分析）模塊中或通過 Analytics API.

• catalog_url：與關聯的目標網址 catalog_request 事件-請注意，此事件僅供內部使用，不會在Google Analytics（分析）模塊中或通過 Analytics API..

catalog_response：在對先前的回复時發送 catalog_request 已收到-請注意，此事件僅供內部使用，不會在Google Analytics（分析）模塊中或通過 Analytics API.

• catalog_url：與關聯的目標網址 catalog_request 引發此響應的事件-請注意，此事件僅供內部使用，不會在Google Analytics（分析）模塊中或通過 Analytics API..
• response_time_ms：之間的時間（以毫秒為單位） catalog_request 事件與 catalog_response 事件-請注意，此事件僅供內部使用，不會在Google Analytics（分析）模塊中或通過 Analytics API..

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

ad_mode_begin：[替換 ad_start]當播放平台將控制權移交給廣告代理時發送。

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

錯誤：在遇到嚴重錯誤會破壞播放體驗時發送。

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

V2的更新事件

video_view：包括新的延遲測量

• load_time_ms：為視頻啟動數據加載和可播放視頻之間的時間（以毫秒為單位）。
• start_time_ms：從開始播放到正在渲染的視頻的第一幀之間的時間（以毫秒為單位）。 根據體驗的不同，該值可能會有所不同，例如，如果未配置前貼片廣告，則此度量標準是介於“ play_request”和“ video_view 事件。 如果有預貼廣告，則 ad_mode_begin 和 ad_mode_complete 不應該包含在內。

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

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