Плагины позволяют добавить в библиотеку analytics.js дополнительные функции, помогающие в решении проблем и отслеживании действий пользователей. Из этой статьи вы узнаете, как создавать плагины analytics.js. О том, как их использовать, читайте здесь.
Определение параметров плагина
Параметры плагина задаются с помощью команды provide. В качестве первого аргумента указывается название плагина, а затем – функция-конструктор. При вызове команды provide плагин регистрируется для использования в очереди команд ga().
Конструктор плагина
Вот пример простейшего плагина для analytics.js:
// Defines the plugin constructor.
function MyPlugin() {
console.log('myplugin has been required...');
}
// Registers the plugin for use.
ga('provide', 'myplugin', MyPlugin);
Плагины должны работать корректно, даже если глобальный объект ga был переименован. Поэтому при написании плагина для внешнего использования не забудьте добавить в него функцию, проверяющую, отличается ли значение переменной GoogleAnalyticsObject от стандартного – 'ga'. Вот пример функции providePlugin, где это реализовано:
// 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 (typeof ga == 'function') {
ga('provide', pluginName, pluginConstructor);
}
}
Настройка экземпляров плагина
Когда в очереди ga() выполняется команда require, создается новый экземпляр объекта с помощью оператора new функции-конструктора плагина, зарегистрированного с помощью команды provide. В качестве первого аргумента конструктору передается объект отслеживания, а в качестве второго – параметры конфигурации, если они были переданы с помощью команды require.
Рассмотрим следующий пример команды require, добавленной в тег Google Аналитики:
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'localHitSender', {path: '/log', debug: true});
ga('send', 'pageview');
Код функции localHitSender:
function LocalHitSender(tracker, config) {
this.path = config.path;
this.debug = config.debug;
if (this.debug) {
console.log('localHitSender enabled for path: ' + this.path);
console.log('on tracker: ' + tracker.get('name'));
}
}
providePlugin('localHitSender', LocalHitSender);
При выполнении команды require в консоли появится указанная ниже запись. Обратите внимание, что название объекта отслеживания по умолчанию – t0.
// localHitSender enabled for path: /log
// on tracker: t0
Определение методов плагина
В плагинах реализуются методы, которые можно вызывать с помощью очереди команд ga:
ga('[trackerName.]pluginName:methodName', ...args);
trackerName – необязательное поле, а 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;
}:
Загрузка плагинов
Плагины обычно загружаются из отдельного файла JavaScript или файла, связанного с кодом основного приложения.
<script async src="myplugin.js"></script>
Плагины необязательно определять до требования. Библиотека analytics.js и плагины загружаются асинхронно, поэтому очередь команд ga() реализована так, чтобы такие ситуации обрабатывались корректно.
Если очередь команд получает команду require для плагина, который ещё не определен, выполнение оставшихся элементов в очереди приостанавливается до тех пор, пока плагин не становится доступен.
Ниже приведен пример кода, где команда ga('require', 'myplugin') не выполняется до запуска команды ga('provide', 'myplugin', ...) через три секунды.
ga('require', 'myplugin');
function MyPlugin() {
console.log('myplugin has been required...');
}
// Waits 3 second after running the `require`
// command before running the `provide` command.
setTimeout(function() {
ga('provide', 'myplugin', MyPlugin);
}, 3000);
Примеры
Следующий плагин извлекает значения пользовательской кампании из URL страницы и передает их трекеру. Этот пример демонстрирует, как создать и зарегистрировать скрипт плагина, передать параметры конфигурации, определить и вызвать методы плагина.
// campaign-loader.js
function providePlugin(pluginName, pluginConstructor) {
var ga = window[window['GoogleAnalyticsObject'] || 'ga'];
if (typeof ga == 'function') {
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);
Приведенный выше код можно добавить в HTML-страницу следующим образом:
<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>
<!--Note: plugin scripts must be included after the tracking snippet. -->
<script async src="campaign-loader.js"></script>
Плагины из библиотеки autotrack
autotrack – это библиотека с открытым исходным кодом, доступная на Github. Среди прочего в ней есть несколько плагинов analytics.js, с помощью которых можно отслеживать стандартные действия пользователей. Изучите исходный код autotrack, чтобы узнать, как работают плагины.