プラグイン - ウェブ トラッキング(analytics.js)

このガイドでは、高度な機能であるプラグインについて説明します。プラグインでは、カスタム トラッキング ライブラリを非同期的に読み込まれるスクリプトにまとめて、analytics.js のコマンドキューと直接やり取りできます。

概要

上級ユーザーの多くは、複雑なサイトのトラッキングを管理したり、analytics.js で提供されていない拡張機能を実現したりするために、何百ものカスタム コードを作成しています。通常このようなカスタム ライブラリは、サイト全域で参照される別の JavaScript ファイルから読み込まれます。こうしたスクリプトをすばやく読み込んで、ウェブサイトの読み込みや表示を邪魔しないようにするには、スクリプトを非同期的に読み込むことをおすすめします。

<script async src="myplugin.js"></script>

しかし analytics.js も非同期的に読み込まれるため、analytics.js のコマンド キューを使用してカスタム トラッキング スクリプトの実行を調整するのが難しい場合もあります。こうした場合に analytics.js プラグイン システムを使用することで、requireprovide のシンプルなコマンドで問題を解決することができます。

require

require コマンドはプラグインの名前を引数として、そのプラグインの読み込みと実行が終わるまで、後続のコマンドの実行をブロックします。

ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'myplugin');
ga('send', 'pageview');

上記の例で、'myplugin' の読み込みが終わっていなければ、このプラグインが利用できるようになるまで analytics.js のコマンド キューが一時停止し、'send' コマンドや、そのページの後続のコマンドがブロックされます。

provide

analytics.js でカスタム プラグインを登録するには、provide コマンドを使用します。provide コマンドは 2 つの引数を取ります。1 つはプラグインの名前、もう 1 つはプラグインの新しいインスタンスを作るコンストラクタ関数です。

function MyPlugin(tracker) {
  alert('Loaded plugin on tracker ' + tracker.get('name'));
}
ga('provide', 'myplugin', MyPlugin);

この例の myplugin.js には、読み込みの際にポップアップでアラート ボックスを表示するシンプルなプラグイン関数が含まれています。この関数は ga('require', 'myplugin'); が呼び出されるたびに起動します。

実装

ここまでは analytics.js プラグイン システムの概要について説明しました。次に、プラグイン スクリプトの作成、プラグイン インスタンスの設定、プラグイン メソッドの定義について説明します。

プラグイン スクリプトの作成

個々のプラグイン スクリプトには、他のカスタム コードに加えて、1 つ以上のプラグイン コンストラクタ関数と、プラグインを登録する provide コマンドへの呼び出しを含める必要があります。analytics.js スニペットが ga グローバル オブジェクトでカスタムな識別子を使うように設定されている場合でも、プラグインのスクリプトは適切に機能させる必要があるため、単純に ga('provide', ..) コマンドを呼び出すことはできません。代わりに、個々のプラグインのスクリプトに以下に示す providePlugin 関数のコピーを追加して、プラグインの登録に使用します。

myplugin.js

// Provides a plugin name and constructor function to analytics.js. This
// function works even if the site has customized the ga global identifier.
function providePlugin(pluginName, pluginConstructor) {
  var ga = window[window['GoogleAnalyticsObject'] || 'ga'];
  if (ga) ga('provide', pluginName, pluginConstructor);
}

// Plugin constructor.
function MyPlugin(tracker) {
  alert('Loaded myplugin on tracker ' + tracker.get('name'));
}

// Register the plugin.
providePlugin('myplugin', MyPlugin);

プラグイン インスタンスの設定

require コマンドでは、読み込むプラグインの名前を指定できるほか、プラグインのインスタンスを初期化するための設定オブジェクトも渡すことができます。

ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'localHitSender', {path: '/log', debug: true});
ga('send', 'pageview');

設定オブジェクトは 2 番目のパラメータとしてプラグイン コンストラクタに渡されます。

function LocalHitSender(tracker, config) {
  this.url = config.url;
  this.debug = config.debug;
  if (this.debug) {
    alert('Enabled local hit sender for: ' + this.url);
  }
}
providePlugin('localHitSender', LocalHitSender);

プラグイン メソッドの定義

プラグインでは、次のような ga コマンドのキュー構文で呼び出し可能な独自のメソッドをエクスポーズできます。

ga('[targetName.][pluginName:]methodName', ...);

この例では、targetName はトラッカーの名前です。targetName を指定しなかった場合、デフォルトの名前として「t0」が使用されます。また、pluginName はプラグインの名前で、methodName はプラグイン インスタンスでのメソッドの名前です。プラグインに methodName が存在しない場合や、プラグインが存在しない場合は、エラーが発生します。

プラグイン メソッドの呼び出しは、次の例のようになります。

// Execute the 'doStuff' method using the 'myplugin' plugin.
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'myplugin');
ga('myplugin:doStuff');

// Execute the 'setEnabled' method of the 'hitCopy' plugin on tracker 't3'.
ga('create', 'UA-XXXXX-Y', 'auto', {name: 't3'});
ga('t3.require', 'hitcopy');
ga('t3.hitcopy:setEnabled', false);

プラグイン メソッドの定義は次の例のようになります。

// myplugin constructor.
var MyPlugin = function(tracker) {
};

// myplugin:doStuff method definition.
MyPlugin.prototype.doStuff = function() {
  alert('doStuff method called!');
};

// hitcopy plugin.
var HitCopy = function(tracker) {
};

// hitcopy:setEnabled method definition.
HitCopy.prototype.setEnabled = function(isEnabled) {
  this.isEnabled = isEnabled;
}:

次の例のプラグインは、ページの URL からカスタム キャンペーンの値を取得して、トラッカーに渡すためのものです。このプラグインは、プラグイン スクリプトを定義登録を行い、プラグインの設定パラメータを渡し、プラグイン メソッドを定義して呼び出す方法を示しています。

campaign-loader.js

function providePlugin(pluginName, pluginConstructor) {
  var ga = window[window['GoogleAnalyticsObject'] || 'ga'];
  if (ga) ga('provide', pluginName, pluginConstructor);
}

/**
 * Constructor for the campaignLoader plugin.
 */
var CampaignLoader = function(tracker, config) {
  this.tracker = tracker;
  this.nameParam = config.nameParam || 'name';
  this.sourceParam = config.sourceParam || 'source';
  this.mediumParam = config.mediumParam || 'medium';
  this.isDebug = config.debug;
};

/**
 * Loads campaign fields from the URL and updates the tracker.
 */
CampaignLoader.prototype.loadCampaignFields = function() {
  this.debugMessage('Loading custom campaign parameters');

  var nameValue = getUrlParam(this.nameParam);
  if (nameValue) {
    this.tracker.set('campaignName', nameValue);
    this.debugMessage('Loaded campaign name: ' + nameValue);
  }

  var sourceValue = getUrlParam(this.sourceParam);
  if (sourceValue) {
    this.tracker.set('campaignSource', sourceValue);
    this.debugMessage('Loaded campaign source: ' + sourceValue);
  }

  var mediumValue = getUrlParam(this.mediumParam);
  if (mediumValue) {
    this.tracker.set('campaignMedium', mediumValue);
    this.debugMessage('Loaded campaign medium: ' + mediumValue);
  }
};

/**
 * Enables / disables debug output.
 */
CampaignLoader.prototype.setDebug = function(enabled) {
  this.isDebug = enabled;
};

/**
 * Displays a debug message in the console, if debugging is enabled.
 */
CampaignLoader.prototype.debugMessage = function(message) {
  if (!this.isDebug) return;
  if (console) console.debug(message);
};

/**
 * Utility function to extract a URL parameter value.
 */
function getUrlParam(param) {
  var match = document.location.search.match('(?:\\?|&)' + param + '=([^&#]*)');
  return (match && match.length == 2) ? decodeURIComponent(match[1]) : '';
}

// Register the plugin.
providePlugin('campaignLoader', CampaignLoader);

index.html


<!DOCTYPE html>
<html>
  <head>

    <!-- Google Analytics Snippet-->
    <script>
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
    m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

    ga('create', 'UA-XXXXX-Y', 'auto');
    ga('require', 'campaignLoader', {
      debug: true,
      nameParam: 'cname',
      sourceParam: 'csrc',
      mediumParam: 'cmed'
    });
    ga('campaignLoader:loadCampaignFields');

    ga('send', 'pageview');
    </script>

    <!-- Plugin Script (must be sourced after the analytics.js snippet) -->
    <script async src="campaign-loader.js"></script>

  </head>

    ...