Wtyczki do pisania

Wtyczki to skrypty, które zwiększają funkcjonalność tagu analytics.js, aby pomagać w rozwiązywaniu problemów i pomóc mierzyć interakcje użytkowników. Z tego przewodnika dowiesz się, jak tworzyć własne wtyczki do analytics.js. Więcej informacji o korzystaniu z wtyczek analytics.js we własnych implementacjach znajdziesz w artykule Używanie wtyczek.

Definiowanie wtyczki

Wtyczki są zdefiniowane w poleceniu provide, które należy wywoływać jako pierwszy argument, po którym następuje funkcja konstruktora wtyczki. Uruchomione polecenie provide rejestruje wtyczkę do użytku w kolejce poleceń ga().

Konstruktor wtyczki

Oto podstawowy przykład wtyczki analytics.js:

// Defines the plugin constructor.
function MyPlugin() {
  console.log('myplugin has been required...');
}

// Registers the plugin for use.
ga('provide', 'myplugin', MyPlugin);

Wtyczki muszą działać prawidłowo, nawet jeśli nazwa globalnego obiektu ga została zmieniona, więc jeśli piszesz wtyczkę do użytku zewnętrznego, musisz sprawdzić, czy zmienna GoogleAnalyticsObject nie ma ustawionego ciągu innego niż 'ga'. Funkcja providePlugin wykonuje tę czynność:

// 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);
  }
}

Konfiguruję instancje wtyczek

Gdy kolejka poleceń ga() wykonuje polecenie require, tworzy nowy obiekt, korzystając z operatora new w funkcji konstruktora wtyczki provide. Konstruktor przekazuje obiekt śledzenia jako pierwszy argument, a wszystkie opcje konfiguracji przekazywane do polecenia require jako drugi argument.

Rozważ następujące polecenie require dodane do tagu Google Analytics:

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

A kod 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);

Po uruchomieniu polecenia require w konsoli zostanie zarejestrowane to polecenie (nazwa domyślnego trackera to "t0"):

// localHitSender enabled for path: /log
// on tracker: t0

Definiowanie metod wtyczek

Wtyczki mogą udostępniać własne metody, które można wywoływać za pomocą składni kolejki ga:

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

gdzie trackerName jest opcjonalna, a methodName odpowiada nazwie funkcji w konstruktorze wtyczek. Jeśli wtyczka methodName nie istnieje lub wtyczka nie istnieje, wystąpi błąd.

Przykładowe wywołania metody wtyczek:

// 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);

Przykładowe definicje metod wtyczek:

// 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;
}:

Wczytuję wtyczki

Wtyczki są zwykle ładowane z osobnego pliku JavaScript lub dołączone do głównego kodu aplikacji.

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

Wtyczki nie muszą być zdefiniowane, zanim będą wymagane. Plik analytics.js jest wczytywany asynchronicznie, a wtyczki również często.

Jeśli kolejka poleceń otrzyma polecenie require dotyczące wtyczki, której jeszcze nie dostarczono, zatrzyma ona wykonywanie pozostałych elementów w kolejce, dopóki wtyczka nie będzie dostępna.

Ten kod pokazuje, jak polecenie ga('require', 'myplugin') nie jest wykonywane do momentu wyświetlenia polecenia ga('provide', 'myplugin', ...), czyli 3 sekundy później.

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);

Przykłady

Poniższa przykładowa wtyczka służy do rejestrowania niestandardowych wartości kampanii z adresu URL strony i przekazywania ich do narzędzia do śledzenia. Pokazuje ona, jak określić i zarejestrować skrypt wtyczki, określić parametry konfiguracji wtyczki oraz określić i wywołać metody wtyczki.

// 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);

Powyższy kod można umieścić na stronie HTML w ten sposób:

<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>

Wtyczki automatycznego śledzenia

Biblioteka autotrack jest oprogramowaniem typu open source, dostępna w GitHubie i zawiera kilka wtyczek analytics.js, które ułatwiają śledzenie częstych interakcji użytkowników. Więcej informacji o tym, jak działają wtyczki, znajdziesz w kodzie źródłowym autośledzenia.