メソッド リファレンス - ウェブ トラッキング(analytics.js)

analytics.js ライブラリでは、2 つの主要オブジェクトを介して Google アナリティクスを操作します。それぞれのオブジェクトには、さまざまなメソッドが含まれています。

ga オブジェクト メソッド

デフォルトの analytics.js JavaScript スニペットをページに追加すると、ga という名前のグローバル オブジェクトが作成されます。ga オブジェクトを使用してトラッカー オブジェクトを作成し、そのトラッカー オブジェクトから Google アナリティクスのウェブ プロパティにデータを送信します。

create

新しいデフォルトのトラッカーを作成します。

ga('create', trackingId, opt_configObject);

パラメータ

  • String trackingId – トラッキング対象のサイトのウェブ プロパティ ID。
  • Object opt_configObject – 設定のフィールドと値のペアを含むオプションのオブジェクト。

デフォルトのトラッカーを作成する場合は以下のようになります。

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

カスタムの Cookie 名を使用してトラッカーを作成します。

ga('create', 'UA-XXXX-Y', 'auto', {'cookieName': '_ga2'});

同期構文を使用してトラッカーを作成します。

var tracker = ga.create('UA-XXXX-Y', 'auto');

ga('create', ...) で、trackingIdcookieDomainname フィールドのポジション引数とオブジェクト引数の両方を受け入れることができます。重要なのは順序で、たとえば以下の 2 つのスニペットは同一となります。

ga('create', 'UA-XXXX-Y', 'auto', 'T1000');
ga('create', {trackingId: 'UA-XXXX-Y', cookieDomain: 'auto', name: 'T1000'});

getByName

特定の名前を持つトラッカー オブジェクトが返されるか、特定の名前を持つトラッカー オブジェクトがない場合は null が返されます。

ga.getByName(name);

パラメータ

  • String name – 取得するトラッカーの名前。

戻り値

  • Tracker – トラッカー オブジェクト。

shoehorn という名前のトラッカー オブジェクトを返す場合は以下のようになります。

ga(function() {
  var tracker = ga.getByName('shoehorn');
});

getAll

現存するトラッカー オブジェクトをすべて含む配列を、作成時の順序で返します。

ga.getAll();

戻り値

  • Array<Tracker> - すべてのトラッカー オブジェクトの配列。

すべてのトラッカー オブジェクトを返し、その名前を通知する場合は以下のようになります。

ga(function() {
  var trackers = ga.getAll();

  for (var i=0; i < trackers.length; ++i) {
    var tracker = trackers[i];
    alert(tracker.get('name'));
  }
});

トラッカー オブジェクトのメソッド

create メソッドによってトラッカー オブジェクトを作成した後は、以下のメソッドを使用して Google アナリティクスを操作できます。

送信

トラッキング ビーコンを Google のコレクション サーバーに送信します。オプションのフィールド オブジェクトを利用すると、このヒットのフィールドの値のみを 1 つ以上、上書きすることができます。

ga('send', hitType, opt_fieldObject);

パラメータ

  • String hitType – 送信するヒットのタイプです。利用できる値は以下のとおりです。
  • Object opt_fieldObject - 1 つ以上のフィールドと値のペアを含むオブジェクト。このヒットのフィールドの値のみを上書きするために使用されます。ヒットの完了後、フォールドの値は元に戻ります。

pageview タイプのヒットを送信し、ページのタイトルを上書きする場合は以下のようになります。

ga('send', 'pageview', {'title': 'my new title'});

set

特定のフィールドに関連付けられている値を更新します。set メソッドは、単一のフィールドと値で呼び出すことができます。

ga('set', fieldName, value);

パラメータ

  • String fieldName - 設定するフィールドの名前。
  • String|Number|Object|Boolean value - 指定したフィールドに関連付ける新しい値。

set メソッドは、複数のフィールドと値のペアを含むオブジェクトで呼び出し、一括更新することもできます。

ga('set', fieldObject);

設定される値は、トラッカー オブジェクトの有効期間が過ぎるまで、以降のすべての send の呼び出しに対して維持されます。

パラメータ

  • Object fieldObject - 設定する 1 つ以上のフィールドと値のペアを含むオブジェクト。

以降のすべてのヒットの page フィールドを設定する場合は以下のようになります。

ga('set', 'page', '/my-new-page');

以降のすべてのヒットの pagetitle の両方を設定する場合は以下のようになります。

ga('set', {
  'page': '/my-new-page',
  'title': 'my new title'
});

get

特定のフィールドに関連付けられている値を返します。インスタンス化されたトラッカー オブジェクトで呼び出す必要があります。

var fieldValue = tracker.get(fieldName);

パラメータ

  • String fieldName - 取得するフィールドの名前。

戻り値

  • String|Number|Object - フィールドの値。

現在のトラッカーのページを取得する場合は以下のようになります。

ga(function(tracker) {
  var page = tracker.get('page');
});

この関数は analytics.js ライブラリの読み込み後に実行されます。関数が実行されると、tracker パラメータにデフォルトのトラッカーへの参照が設定されます(関数の呼び出し前にデフォルトのトラッカーが作成されていた場合)。このトラッカーの参照によって page の値が取得されます。

呼び出し構文

それぞれの ga メソッドを呼び出す方法は複数あります。

非同期(デフォルトのトラッカー)

anaytics.js JavaScript スニペットは、ブラウザによるライブラリの読み込みが停止しないよう、非同期的に読み込まれるようになっています。ライブラリの読み込み中にコードを同期化しなくても済むよう、最初のパラメータとしてメソッド名を渡すことで、ga オブジェクトを関数として使用することができます。

ga('create', 'UA-XXXX-Y', 'auto');
ga('send', 'pageview');

これはライブラリの読み込み完了直後に実行されます。create によって、t0 という名前でデフォルトのトラッキング オブジェクトが作成された後、send メソッドか、この構文で呼び出された他のメソッドが、デフォルトのトラッキング オブジェクトに対して実行されます。

このケースでは一般的な設定方法に合わせて、デフォルトのトラッカー オブジェクトが作成されています。

非同期(名前付きのトラッカー)

同一のページ上で複数のトラッカーを作成する場合、トラッカー同士を区別するには、各トラッカーに名前を付ける必要があります。

名前付きのトラッカー オブジェクトを作成するには、create メソッドのオプションの設定オブジェクト パラメータを使って name 設定フィールドを指定します。

ga('create', 'UA-XXXX-Y', 'auto', {'name': 'tracker2'});

そのうえでトラッカー名とピリオド(.)をメソッドの先頭に追加し、名前付きのトラッカーを対象にトラッカー メソッドを呼び出します。

ga('tracker2.send', 'pageview');

同期

anaytics.js ライブラリでは、同期的にメソッドを呼び出すこともできます。その場合は ga または tracker オブジェクトそれぞれを対象に、直接メソッドを呼び出します。

var tracker = ga.create('UA-XXXX-Y', 'auto');
tracker.send('pageview');

非同期型同期

場合によっては、一部のメソッドをライブラリの読み込み後に呼び出す必要があります。たとえば get メソッドは、ライブラリの読み込み、トラッカーの作成、フィールドの設定が完了した後にのみ機能します。これに対処するには、ライブラリの読み込み後にのみ実行される関数を ga オブジェクトに渡します。

ga(function(tracker) {
  var page = tracker.get('name');
});

ga オブジェクトに渡した関数によってパラメータが受け入れられ、実行後にデフォルトのトラッカーの値が割り当てられます。このトラッカー オブジェクトはその後、同期型の構文で使用できます。たとえば以下のような場合でも機能します。

ga('create', 'UA-XXXX-Y', 'auto');
ga(function(tracker) {
  tracker.send('pageview');
});

同様に、作成されたすべてのトラッカーを対象にページビューをトラッキングする場合は、以下のようになります。

ga(function() {
  var trackers = ga.getAll();
  for (var i=0; i<trackers.length; ++i) {
    var tracker = trackers[i];
    tracker.send('pageview');
  }
});

これは特に、サイト上で作成されるトラッカーの数が不明な状況で処理を拡張展開する場合に便利です。この構文を使用すると、トラッキング コードの読み込み後に、関数によってページ上のすべてのトラッカーを対象に多数のロジックを実行できます。