Wtyczki do pisania

Wtyczki to skrypty, które rozszerzają funkcje tagu analytics.js, aby pomagać w rozwiązywaniu problemów i pomiarach interakcji użytkowników. W tym przewodniku opisujemy proces tworzenia własnych wtyczek analytics.js. Aby dowiedzieć się, jak używać wtyczek analytics.js we własnych implementacjach, przeczytaj artykuł Korzystanie z wtyczek.

Definiowanie wtyczki

Wtyczki są definiowane za pomocą polecenia provide, które musi zostać wywołane z nazwą wtyczki jako pierwszym argumentem, po której następuje funkcja konstruktora wtyczki. Po uruchomieniu polecenia provide wtyczka zostanie zarejestrowana w kolejce poleceń ga(), której należy użyć.

Konstruktor wtyczek

Oto najbardziej 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 w przypadku zmiany nazwy globalnego obiektu ga. Jeśli więc tworzysz wtyczkę do użytku zewnętrznego, sprawdź, czy zmienna GoogleAnalyticsObject została ustawiona na ciąg znaków inny niż 'ga'. Robi to ta funkcja 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);
  }
}

Konfigurowanie instancji wtyczek

Gdy kolejka poleceń ga() wykonuje polecenie require, tworzy instancję nowego obiektu przy użyciu operatora new w funkcji konstruktora wtyczki provide. Konstruktor przekazuje obiekt skryptu śledzenia jako pierwszy argument, a wszelkie opcje konfiguracyjne przekazywane do polecenia require jako drugi argument.

Zastanów się nad dodaniem do tagu Google Analytics tego polecenia require:

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

Oraz 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 zostaną zarejestrowane te dane (zwróć uwagę, że nazwa domyślnego trackera to „t0”):

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

Definiowanie metod wtyczek

Wtyczki mogą ujawniać własne metody, które można wywołać przy użyciu składni kolejki poleceń ga:

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

gdzie trackerName jest opcjonalny, a methodName odpowiada nazwie funkcji w prototypze konstruktora wtyczki. Jeśli wtyczka methodName nie istnieje lub nie istnieje, pojawi się błąd.

Przykładowe wywołania metody wtyczki:

// 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 wczytywane z osobnego pliku JavaScript lub połączone z głównym kodem aplikacji.

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

Nie trzeba definiować wtyczek, zanim są wymagane. Ponieważ plik analytics.js jest ładowany asynchronicznie, a wtyczki często również są ładowane asynchronicznie, kolejka poleceń ga() jest stworzona do obsługi tej operacji.

Jeśli kolejka poleceń otrzyma polecenie require dotyczące wtyczki, które nie zostało jeszcze udostępnione, wstrzyma wykonanie pozostałych elementów w kolejce, dopóki wtyczka nie będzie dostępna.

Poniższy kod pokazuje, jak polecenie ga('require', 'myplugin') nie jest wykonywane, dopóki nie zostanie napotkane polecenie ga('provide', 'myplugin', ...) – 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

Ta przykładowa wtyczka służy do przechwytywania niestandardowych wartości kampanii z adresu URL strony i przekazywania ich do tagu śledzenia. Pokazuje ona, jak zdefiniować i zarejestrować skrypt wtyczki, przekazać parametry konfiguracji wtyczki oraz zdefiniować 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 następujący 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>

Automatyczne śledzenie wtyczek

Biblioteka autotrack to oprogramowanie open source, dostępne na GitHubie. Zawiera ona kilka wtyczek analytics.js, które pomagają śledzić typowe interakcje użytkowników. Aby lepiej zrozumieć, jak działają wtyczki, zapoznaj się z kodem źródłowym automatycznego śledzenia.