概要： Data Collection API v2

賃貸システムの概要

アナリティクスデータは自動的に Brightcove Playerネイティブが提供するものを含む Player SDK。 あなたがいる場合 Studio上ではサポートされていません。 使用して Brightcove Player デにliver 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).

追加パラメータ

アナリティクスシステムがイベントを正常に分析できるように、特定のパラメータをイベントに含める必要があります

応答タイプ

分析への応答 data collection API リクエストには、HTTP応答コードと人間が読めるメッセージが含まれます。

最小データ

最低でも、 session IDと video_view セッション中に再生されたすべてのビデオのイベント。 ザ video_view 送信する必要があります After プレロール広告はすべて完了します。

session

これがセッション識別子です。 ザ session 本質的には、 player それが続く限り、その中で。 値はセッションの期間中一定である必要があり、 すべてのイベントに送信されます。 これは、グローバル一意識別子（GUID）に可能な限り近いものでなければなりません。 衝突が発生した場合、2つのセッションを解体できない場合、2つのセッションが無効として破棄される可能性があります。

JavaScriptでGUIDを作成するためのさまざまなスキームがあります。 1つの例は このGitHubリポジトリ。 サードパーティのスクリプトはブライトコーブでサポートされていないことに注意してください。

パフォーマンスのための最小限のデータ（再生率と 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. 制御された環境で少なくとも1日はテストしてください。
3. アナリティクスモジュールを使用してアナリティクスデータを確認するか、 Analytics API 収集されたものがあなたの期待と一致するようにします。

要求を送信する - CORSの問題を回避する

ジャンクデータ

一般に、コレクタに送信されるデータは、Analyticsシステムによって真実として記録されます。 イベントに不適切または間違った情報が含まれていると、アナリティクスシステムはデータを正しく解釈しません。

たとえば、誤ってタイムスタンプをビデオIDとして送信した場合、分析データは全体的な要約に影響するように歪んでしまいます。

URIエンコーディング

あなたに送る文字列 Data Collection API スペースや特殊文字を含む可能性があります URIでエンコードする必要があります 要求が成功するために。 JavaScriptを使用してリクエストを送信する場合は、 encodeURI() リクエスト文字列をエンコードします。 例えば：

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

イベント

以下のイベントは、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

意図/意味

ユーザーが再生ボタンを明示的にクリックして再生が開始されたときに送信されるか、プラットフォームが自動再生シナリオで再生をトリガーしたときに自動的に送信されます。 複数のことに注意してください play_request 視聴者がビデオを一時停止および再開した場合、XNUMX回の視聴セッション中にイベントが送信されることがあります。

例

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

意図/意味

ビデオの再生が開始されました（ロード後の自動再生、またはユーザーの操作による）。 XNUMXつだけに注意してください 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

意図/意味

ユーザーは、ビデオのタイムラインの秒の範囲を視聴しました。 このイベントは、ビデオを追跡するためのハートビートです engageユーザーの操作やビデオの長さによっては、再生中に何度も送信される可能性があります。 ザ・ Brightcove player 計測は、再生が中断されない場合、このイベントを10秒ごとに送信します。 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 一意の識別子として使用します。
• userパラメータの値は決してログ/データベースに格納されず、ハッシュ（SHA-256を使用）のみが格納されます。
• コレクターはクッキーを設定しません。

ユニークユーザー

あなたが使用することができます Brightcove Playerのプラグイン機能を使用して、報告されたアナリティクスに一意のビデオビューアデータを追加します。 これを行うには、 settings 分析機能の対象です。

もちろん、ユニークなユーザーIDの取得方法はアプリケーションによって異なりますが、このコードでは、ログインURLがキャプチャされていることを前提としています。 http://exampledomain.com/users/912389123。 この一意のURLはプラグインに渡されます。

以下のプラグインのコードは以下のタスクを実行します：

• 標準構文を使用して Brightcove Player プラグイン名が次のように定義されたプラグイン uniqueUserForAnalyticsPlugin。 プラグインはまた、 options オブジェクトには、プラグインに渡されるデータが含まれます。
• 　 myPlayer 変数には、 player。 同様に、他のXNUMXつの変数が作成されます。
• 　 userPath 変数には、プラグインに渡されたパスが割り当てられます。 options オブジェクト。
• 　 uniqueViewer 変数には、解析されたバージョンの userPath、変数にはユーザーIDの数字だけが割り当てられます。
• アナリティクスプラグインのユーザープロパティが追加されました 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;
  });
  
  

このコードは、アプリケーションのロジックに合わせて変更し、インターネットでアクセス可能なURLに保存する必要があります。

スタジオからは、 プラグイン プラグインをロードするセクション player、図のように。

後続するJSONではなく、ユーザーデータを含む文字列をプラグインに渡します。 もちろん、一意のユーザーIDを抽出するために、プラグインコードを更新する必要があります。

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

プラグイン開発の詳細については、 ステップバイステップ：プラグイン開発 の資料をご参照ください。

device_type, device_os, device_os_version, device_manufacturer＆ browser_type パラメータ

デフォルトでは、AnalyticsシステムはUser-AgentヘッダーからデバイスタイプとOS情報を検出しようとします。 もし どちらも device_type および device_os User-Agentヘッダーからの情報は無視されます device_type および device_os. ほとんどの場合、デバイス、OS、およびブラウザ情報を送信する必要はありません - このオーバーライドは、User-Agentが信頼できない場合、または使用できない場合にのみ使用する必要があります。

Analyticsシステムが記録します other 要求にデバイスパラメータオーバーライドの認識されない値が含まれている場合

地理データ

デフォルトでは、アナリティクスシステムはリモートIPアドレスから地理情報を検出しようとします。 この動作は、渡すことでオーバーライドできます。 country, country_name, region, region_name, city および dma パラメーター。 ほとんどの場合、これらのパラメータは必須ではありません - このオーバーライドは、リモートIPアドレスが信頼できない場合、または使用できない場合にのみ使用する必要があります。

Analyticsシステムが記録します ZZ or unknown 要求に、上書きのための認識されない値が含まれている場合。

宛先とソースのパラメータ

　 destination および source パラメータは、イベントを発生させたURIを提供します（ destination）とそこにユーザーを送ったURI（ source).

　 source パラメータは、トラフィックソース情報を決定するために使用されます。 もし source が指定されていない場合、アナリティクスシステムはイベントを直接トラフィックによって開始されたものとして扱います。

　 destination パラメータは、トラフィックの宛先情報、つまりビデオが監視されている場所を特定するために使用されます。 URIに権限が含まれていない場合、APIは destination_domainとして指定することができます。 destination_path URIのパスとして記録されます。

ウェブ再生中、動画が再生されているページのアドレスバーにあるURLは destination、 そしてその source リファラー（ top.document.referrer).

たとえば、「live 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でなければなりません。

コーヒーの粉の形状を球体と捉えたとしたら、XNUMXミクロン以上の粒子ひとつに対して、XNUMXミクロン以下の粒子はどれくらい存在するでしょうか？ destination 　 有効なURI:

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

Analyticsシステムでは次のように処理されます。

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 イベント。

ビデオ_engageメントイベントパラメータ

次のパラメータは、 video_engagement イベント。

　 video_engagement イベントはビデオを追跡する手段です engageビデオの再生中にメントし、再生中に何度も送信される可能性があります。 （フラッシュ/ HTML5 player 計測は、再生が中断されない場合、このイベントを10秒ごとに送信します。） 現在、20秒以上の範囲を記述するイベントは、アナリティクスシステムによって破棄されるため、これらのイベントをより頻繁に送信する必要があります。

次の2つの形式があります。 video_engagement イベントが発生する可能性があります（簡潔にするため、他のパラメータは省略しています）。

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

どちらのバージョンも表示秒数を追跡していますが、 video_duration および range 追加の計算に必要な情報も含まれています engageメントデータ、および 好ましい方法 送信する video_engagement 分析システムへのイベントデータ。 にとって live ストリーム、または再生中にビデオのタイムラインが継続的に変更される場合、またはその他の方法で信頼できない場合、 video_seconds_viewed 利用可能な唯一のデータになります。 VODの場合は、 duration 利用できない、 video_engagement イベントに含める必要があります video_duration および range.

3つのパラメータ（ video_duration, range および video_seconds_viewed）と一緒に送信されます video_engagement イベント、分析システムは計算します engageからのメントメトリック video_duration+ range パラメーター。

V2の変更点

このセクションでは、v1を使用しているユーザーのデータコレクタのv2からv1への変更の概要を示します。

トラッカーのベースURL

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

すべてのイベントでサポートされる追加フィールド：

device_os_version：デバイスで使用されているOSのバージョン。 指定されていない場合は、トラッキング要求のユーザーエージェント文字列を解析して計算されます。

platform_version：指定されたプラットフォームの新しいリリースがイベントの送信に使用されていることを示すために使用されます。

V2の新しいイベント

catalog_request：videocloud catalog apiへのリクエストが行われたときに送信されます - このイベントは内部使用のためであり、Analyticsモジュール内で、または経由で公開されていないことに注意してください。 Analytics API.

• catalog_url：関連するリンク先URL catalog_request event - このイベントは内部使用のためのものであり、Analyticsモジュールまたはその外部からは公開されません。 Analytics API..

catalog_response：以前の catalog_request 受信 - このイベントは社内での使用を目的としており、Analyticsモジュール内または Analytics API.

• catalog_url：関連するリンク先URL catalog_request このレスポンスを開始したイベント - このイベントは内部使用のためのものであり、Analyticsモジュール内または Analytics API..
• response_time_ms：時間間隔（ミリ秒） catalog_request イベントと catalog_response event - このイベントは内部使用のためのものであり、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 含まれてはいけません。

ビデオ_engagemento：追加のレンディション選択、ビットレート測定、およびバッファリング情報が含まれます。 ビデオへの微妙な変更 engageまた、視聴中に視聴がなかった場合でも定期的に送信するように注意しました。 engage期間。 この変更は、ユーザーが再生を待機する原因となる再バッファリングの遅延とカウントを追跡できるようにするためのものです。

• 範囲：範囲パラメータはオプションになりました。範囲は省略できます。 engageイベントの対象期間中、視聴活動がなかったことを示すイベント。 （たとえば、再バッファリングアクティビティのみがある場合）
• rendition_url：最も最近選択された演奏へのURL。 たとえば、HLSストリームの場合、これは最近選択されたバリアントへのURLになります。
• rendition_indicated_bps：最も最近選択された演奏のビットレート（ビット/秒）。
• rendition_mime_type：最も最近選択されたレンディションのMIMEタイプ。
• rendition_height：ビデオレンディションのエンコードされた高さ（ピクセル単位）
• レンディション幅：ビデオレンディションの符号化された幅（ピクセル単位）
• rebuffering_seconds：要求されていない遅延のためにユーザーがビデオの再生を待機するのに費やした秒数 engage期間。
• rebuffering_count：表示中に再バッファリングが原因で再生が停止した回数 engage期間。
• forward_buffer_seconds：現在フォワードバッファに存在するビデオの秒数。
• measured_bps：最後にダウンロードしたセグメントに含まれるビット数とそのセグメントをダウンロードする時間の割合（ビット/秒）。
• player_幅 現在のピクセル幅 player 最後の engageメント範囲。
• player_高さ の現在のピクセルの高さ player 最後の engageメント範囲。
• 落ちたフレーム：この間にビデオ再生からドロップされたフレーム数 engage期間