タスク

このガイドでは、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 のフィールド リファレンスで定義されたフィールドへのアクセスを実現します。

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

実装

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

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

タスクをオーバーライドするには、タスクの値を 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');