Eklenti Yazma

Eklentiler, sorunları çözmek ve kullanıcı etkileşimini ölçmeye yardımcı olmak için analytics.js'nin işlevlerini geliştiren komut dosyalarıdır. Bu rehberde, kendi analytics.js eklentilerinizi yazma süreci açıklanmaktadır. Analytics.js eklentilerini kendi uygulamalarınızda nasıl kullanacağınızla ilgili bilgi edinmek için Eklentileri kullanma başlıklı makaleyi inceleyin.

Eklenti tanımlama

Eklentiler, provide komutuyla tanımlanır. İlk bağımsız değişken olarak eklentinin adı ve ardından eklentinin oluşturucu işlevi çağırılmalıdır. provide komutu çalıştırıldığında, kullanılacak eklentiyi ga() komut kuyruğuyla kaydeder.

Eklenti oluşturucu

Aşağıda, bir analytics.js eklentisinin en temel örneği verilmiştir:

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

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

Eklentiler, genel ga nesnesinin yeniden adlandırıldığı durumlarda da düzgün şekilde çalışmalıdır. Bu nedenle, üçüncü taraf kullanımı için bir eklenti yazıyorsanız, GoogleAnalyticsObject değişkeninin 'ga' dışında bir dize olarak ayarlanmış olup olmadığını kontrol etmeniz gerekir. Bunu aşağıdaki providePlugin işlevi yapar:

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

Eklenti Örneklerini Yapılandırma

ga() komut sırası require komutu çalıştırdığında, provide eklentisi oluşturucu işlevindeki new operatörünü kullanarak yeni bir nesneyi somutlaştırır. Oluşturucu, izleyiciyi ilk bağımsız değişkeni olarak iletir ve tüm yapılandırma seçenekleri ikinci bağımsız değişken olarak require komutuna iletilir.

Google Analytics etiketine aşağıdaki require komutunu ekleyin:

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

localHitSender kodu ise:

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 komutu çalıştırıldığında aşağıdaki bilgiler konsola kaydedilir (varsayılan izleyicinin adının "t0" olduğuna dikkat edin):

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

Eklenti Yöntemlerini Tanımlama

Eklentiler, ga komut sırası söz dizimi kullanılarak çağrılan kendi yöntemlerini gösterebilir:

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

burada trackerName isteğe bağlıdır ve methodName, eklenti oluşturucular prototipindeki bir işlevin adına karşılık gelir. Eklentide methodName yoksa veya eklenti yoksa bir hata oluşur.

Örnek eklenti yöntemi çağrıları:

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

Örnek eklenti yöntemi tanımları:

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

Eklentiler yükleniyor

Eklentiler genellikle ayrı bir JavaScript dosyasından yüklenir veya ana uygulama kodunuzla birlikte verilir.

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

Eklentilerin gerekli olması için tanımlanması gerekmez. analytics.js eşzamansız olarak ve eklentiler de genellikle eşzamansız olarak yüklendiğinden, bu işlemi gerçekleştirmek için ga() komut sırası oluşturulur.

Komut sırası, henüz sağlanmamış bir eklenti için require komutu alırsa eklenti kullanıma sunulana kadar sıradaki diğer öğelerin çalıştırılmasını durdurur.

Aşağıdaki kod, üç saniye sonra ga('provide', 'myplugin', ...) komutuyla karşılaşana kadar ga('require', 'myplugin') komutunun nasıl çalıştırılmadığını gösterir.

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

Örnekler

Aşağıdaki örnek eklenti, bir sayfanın URL'sinden özel kampanya değerleri yakalamak ve bunları izleyiciye iletmek için tasarlanmıştır. Bu eklenti, eklenti komut dosyasının nasıl tanımlanıp kaydedileceğini, eklenti yapılandırma parametrelerini nasıl iletileceğini ve eklenti yöntemlerinin nasıl tanımlanıp çağrılacağını gösterir.

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

Yukarıdaki kod, HTML sayfasına aşağıdaki şekilde eklenebilir:

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

Eklentileri otomatik izle

Autotrack kitaplığı açık kaynaklıdır, GitHub'da mevcuttur ve yaygın kullanıcı etkileşimlerini izlemeye yardımcı olan birkaç analytics.js eklentisi içerir. Eklentilerin işleyiş şeklini daha iyi anlamak için otomatik izleme kaynak koduna bakın.