タスク

このガイドでは、analytics.js による Measurement Protocol リクエストの検証、構成、送信をカスタマイズする高度な機能、「タスク」について説明します。

概要

analytics.js では send コマンドが呼び出されるたびに一連のタスクを実行し、ユーザーのブラウザからの Measurement Protocol リクエストを検証、作成して、Google アナリティクスに送信します。次の表で、それぞれのタスクを実行順に説明します。

タスク名 説明
customTask デフォルト状態では何もしないタスクです。オーバーライドにより動作をカスタマイズすることができます。
previewTask Safari の「Top Sites」サムネイルを表示するだけのページの場合に、そのリクエストを中止します。
checkProtocolTask ページのプロトコルが http でも https でもない場合に、リクエストを中止します。
validationTask 必須フィールドがない場合や無効な場合に、リクエストを中止します。
checkStorageTask トラッカーで Cookie を使用するものの、ユーザーのブラウザで Cookie が無効にされている場合に、リクエストを中止します。
historyImportTask ユニバーサル アナリティクスにサイトを移行する際に、ユーザーの履歴を保持するために、ga.js や urchin.js の Cookie から情報をインポートします。
samplerTask トラッカーの sampleRate の設定に基づいて、ユーザーをサンプリングします。
buildHitTask Measurement Protocol リクエストの文字列を作成し、hitPayload フィールドに保存します。
sendHitTask hitPayload フィールドに保存された Measurement Protocol リクエストを Google アナリティクス サーバーに送ります。
timingTask トラッカーの siteSpeedSampleRate の設定に基づいて、サイトの速度 timing ヒットを自動的に生成します。
displayFeaturesTask ディスプレイ広告機能が有効になっており、広告向け機能の Cookie（_gat）で設定されたタイムアウト時間内に以前のヒットが送信されていない場合は、追加のヒットを送信します。

こうしたタスクはすべて JavaScript 関数として実装され、引数として 1 つのモデル パラメータを取ります。このモデルは単純なオブジェクトで、analytics.js のフィールド リファレンスで定義されたフィールドへのアクセスを実現します。

タスクにアクセスしたり、タスクを置き換えたりするには、標準的なトラッカーの get と set メソッドを使用します。こうしたメソッドを使えば、独自のカスタム関数でタスクを置き換えることができます。また、カスタム関数をチェーンでつないで既存のタスクの前または後に実行し、既存の機能を拡張することもできます。

実装

このセクションでは、既存のタスクに新しい機能を追加する方法と、タスクに組み込まれた関数を独自のカスタムコードに置き換える方法、タスクの関数を無効にする方法を説明します。

タスクをオーバーライドする

タスクをオーバーライドするには、set コマンドでタスクの値を別の処理を行う関数に変更します。一般に、タスクのオーバーライドは、analytics.js の実装をテストする際に機能をスタブ化するときなどに必要となります。

次のコードでは、sendHitTask をオーバーライドして、ヒットのペイロードをコンソールにログ出力する関数に置き換えています。

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'sendHitTask', function(model) {
  console.log(model.get('hitPayload'));
});

タスクに機能を追加する

新しい機能を追加するには、カスタムタスク関数をチェーンでつないで、既存のタスクの前または後に実行します。下の例では、sendHitTask がカスタムタスク関数に置き換えられています。このカスタムタスク関数では、最初に元の sendHitTask 関数を呼び出して通常のリクエスト ビーコンを google-analytics.com/collection に送信してから、カスタムコードを実行して Measurement Protocol リクエストのコピーをローカル サーバーに送ります。

ga('create', 'UA-XXXXX-Y', 'auto');

ga(function(tracker) {

  // Grab a reference to the default sendHitTask function.
  var originalSendHitTask = tracker.get('sendHitTask');

  // Modifies sendHitTask to send a copy of the request to a local server after
  // sending the normal request to www.google-analytics.com/collect.
  tracker.set('sendHitTask', function(model) {
    originalSendHitTask(model);
    var xhr = new XMLHttpRequest();
    xhr.open('POST', '/localhits', true);
    xhr.send(model.get('hitPayload'));
  });
});

ga('send', 'pageview');

タスクの処理を中止する

タスクの途中で例外をスローすると、後続のタスクの処理を中止できます。例外のスローを sendHitTask の前に実行すると、その Measurement Protocol リクエストを Google アナリティクスに送らない機能を実現できます。下の例では、ユーザーのブラウザに「testing」という名前で値「true」を持つ Cookie がある場合に、必ずリクエストを中止しています。

ga('create', 'UA-XXXXX-Y', 'auto');

ga(function(tracker) {
  var originalBuildHitTask = tracker.get('buildHitTask');
  tracker.set('buildHitTask', function(model) {
    if (document.cookie.match(/testing=true/)) {
      throw 'Aborted tracking for test user.';
    }
    originalBuildHitTask(model);
  });
});

ga('send', 'pageview');

タスクを無効にする

タスクに組み込まれた関数を無効にするには、関数を null に置き換えます。

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'checkProtocolTask', null); // Disables file protocol checking.
ga('send', 'pageview');