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.