Eklentiler Yazma

Eklentiler, sorunları çözmeye ve kullanıcı etkileşimini ölçmeye yardımcı olmak için analytics.js'nin işlevselliğini geliştiren komut dosyalarıdır. Bu kılavuzda, kendi analytics.js eklentilerinizi yazma süreci açıklanmaktadır. Kendi uygulamalarınızda analytics.js eklentilerini nasıl kullanacağınız hakkında bilgi edinmek için Eklentileri kullanma başlıklı makaleyi inceleyin.

Eklenti tanımlama

Eklentiler, provide komutu aracılığıyla tanımlanır. Bu komut, eklentinin adıyla ilk bağımsız değişken olarak ve ardından eklentinin oluşturucu işleviyle çağrılmalıdır. provide komutu çalıştırıldığında, kullanılacak eklentiyi ga() komut sırasına 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);

Genel ga nesnesinin yeniden adlandırıldığı durumlarda bile eklentilerin düzgün çalışması gerekir. Bu nedenle, üçüncü taraf kullanımı için bir eklenti yazıyorsanız, GoogleAnalyticsObject değişkeninin 'ga' dışında bir dizeye ayarlanıp ayarlanmadığını kontrol eden bir kontrol eklemeniz gerekir. Aşağıdaki providePlugin işlevi bunu 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ı bir require komutu yürüttüğünde, provide eklentisinin oluşturucu işlevinde new operatörünü kullanarak yeni bir nesne somutlaştırır. Oluşturucu, izleyici nesnesine ilk bağımsız değişken, yapılandırma seçenekleri ise ikinci bağımsız değişken olarak require komutuna geçirilir.

Google Analytics etiketine aşağıdaki require komutunun eklendiğini düşünün:

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

localHitSender kodu:

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ğıdakiler 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ılabilecek kendi yöntemlerini gösterebilir:

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

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

Eklenti yöntemi çağrılarına örnek:

// 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 paketlenir.

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

Eklentiler zorunlu olmadan önce tanımlanmak zorunda değildir. analytics.js eşzamansız olarak yüklendiğinden ve eklentiler de genellikle eşzamansız olarak yüklendiğinden, ga() komut sırası bunu işleyecek şekilde oluşturulur.

Komut sırası, henüz sağlanmamış bir eklenti için require komutu alırsa, eklenti kullanılabilir olana kadar sıradaki diğer öğelerin yürütülmesi durdurulur.

Aşağıdaki kod, üç saniye sonra ga('provide', 'myplugin', ...) komutuyla karşılaşılıncaya kadar ga('require', 'myplugin') komutunun nasıl yürütülmediğini 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, özel kampanya değerlerini bir sayfanın URL'sinden yakalamak ve izleyiciye iletmek için tasarlanmıştır. Bu eklentide, eklenti komut dosyasının nasıl tanımlanıp kaydedileceği, eklenti yapılandırma parametrelerinin nasıl geçirileceği ve eklenti yöntemlerini tanımlayıp çağıracağınız gösterilmektedir.

// 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, bir HTML sayfasına aşağıdaki gibi 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>

Autotrack eklentileri

GitHub'dan erişilebilen autotrack kitaplığı açık kaynaktır ve yaygın kullanıcı etkileşimlerini izlemeye yardımcı olan çeşitli analytics.js eklentileri içerir. Eklentilerin nasıl çalıştığını daha iyi anlamak için otomatik izleme kaynak koduna bakın.