概述：資料收集 API 第 2 版

簡介

分析資料會由布萊特灣玩家自動傳送，包括原生玩家 SDK 所提供的資料。如果您沒有使用 Brightcove 播放器來傳遞視訊雲端影片，則需要測試您用來將資料傳送給資料收集器的播放器。

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

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

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

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

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

活動

• video_impression
• 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

意圖 ／ 意義

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

範例

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

意圖 ／ 意義

當播放是由用戶明確點擊播放按鈕啟動，或者當平台在自動播放場景中觸發播放時自動發送。注意多個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

意圖 ／ 意義

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

範例

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

意圖 ／ 意義

視頻已開始播放（加載後自動播放，或者由於用戶交互）。請注意，只有一個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

意圖 ／ 意義

使用者觀看影片時間軸的秒範圍。此事件是追蹤視訊參與的活動訊號，可能會在播放期間傳送多次，視使用者互動和視訊的長度而定。如果播放不中斷，Brightcove播放器儀器將每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

所有事件的參數

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

用戶參數

• 如果播放器/客戶端應用程序要跟踪唯一的查看器，則應將用戶的唯一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變量分配給玩家的參考。同樣，還創建了兩個其他變量。
• 的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中，使用外掛程式部分將插件加載到播放器中，如圖所示。

您可以將包含用戶數據的字符串傳遞給插件，而不是後面的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要么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播放器工具每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的v1到v2的更改的摘要。

追踪器的基本網址

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

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

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

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

V2的新事件

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

• 目錄網址：與該網址相關聯的目標網址catalog_request事件-請注意，此事件僅供內部使用，不會在Google Analytics（分析）模塊或Google Analytics（分析）API中公開。

catalog_response：對先前的回應發送catalog_request收到-請注意，此事件僅供內部使用，並且不會在Analytics模塊中或通過Analytics API公開。

• 目錄網址：與該網址相關聯的目標網址catalog_request引發此響應的事件-請注意，此事件僅供內部使用，不會在Analytics模塊中或通過Analytics API公開。
• response_time_ms：兩次之間的時間（以毫秒為單位）catalog_request事件與catalog_response事件-請注意，此事件僅供內部使用，不會在Google Analytics（分析）模塊或Google 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：包括附加的演繹選擇，比特率測量和緩衝信息。視頻參與度也進行了微妙的更改，即使在參與度期間沒有觀看，也應定期發送視頻。此更改是為了啟用跟踪重新緩衝的延遲和計數，這些延遲和計數會導致用戶等待播放。

• 範圍：現在，範圍參數是可選的，可以將參與事件排除在範圍之外，以表明在該事件所覆蓋的時間段內沒有觀看活動。 （例如，當只有重新緩衝活動時）
• 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：在此參與期間視頻播放中掉落的幀數