概要： Data Collection API v2

概要

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

追加パラメータ

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

応答タイプ

分析データ収集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

意図/意味

ユーザーが明示的に再生ボタンをクリックするか、プラットフォームが自動再生シナリオで再生をトリガーするときに自動的に再生が開始されたときに送信されます。

例

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秒ごとに送信します。 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).

たとえば、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 イベント。

video_engagementイベントパラメータ

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

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

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

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

どちらのバージョンも表示秒数を追跡していますが、 video_duration と range 追加のエンゲージメントデータを計算するために必要な情報も含まれています 好ましい方法 送信する video_engagement Analyticsシステムへのイベントデータ。 ライブストリームの場合、または再生中にビデオのタイムラインが絶えず変化している場合、または信頼性が低い場合は、 video_seconds_viewed 利用可能な唯一のデータになります。 VODの場合は、 duration 利用できない、 video_engagement イベントに含める必要があります video_duration と range.

3つのパラメータ（ video_duration, range と video_seconds_viewed）と一緒に送信されます video_engagement アナリティクスのシステムでは、 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 含まれてはいけません。

video_engagement：追加の演奏選択、ビットレート測定、およびバッファリング情報が含まれます。 ビデオエンゲージメントへの微妙な変更は、エンゲージメント期間中に視聴が発生しなくても定期的に送信する必要があるという点でも行われました。 この変更は、ユーザが再生を待つ原因となる遅延およびカウントの再バッファリングを追跡することを可能にすることである。

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