Plugin adalah skrip yang meningkatkan fungsi analytics.js untuk membantu mengatasi masalah dan mengukur interaksi pengguna. Panduan ini menjelaskan proses penulisan plugin analytics.js Anda sendiri. Untuk informasi tentang cara menggunakan plugin analytics.js dalam penerapan Anda sendiri, lihat Menggunakan plugin.
Menentukan plugin
Plugin ditentukan melalui perintah provide
, yang harus dipanggil dengan nama plugin sebagai argumen pertama yang diikuti dengan fungsi konstruktor plugin. Saat dijalankan, perintah provide
akan mendaftarkan plugin yang akan digunakan dengan antrean perintah ga()
.
Konstruktor plugin
Berikut adalah contoh plugin analytics.js yang paling dasar:
// Defines the plugin constructor.
function MyPlugin() {
console.log('myplugin has been required...');
}
// Registers the plugin for use.
ga('provide', 'myplugin', MyPlugin);
Plugin harus berfungsi dengan benar bahkan jika objek ga
global telah diganti namanya. Jadi jika Anda menulis plugin untuk penggunaan pihak ketiga, Anda harus menyertakan centang untuk mengetahui apakah variabel GoogleAnalyticsObject
telah tetapkan ke string selain 'ga'
. Fungsi providePlugin
berikut melakukan hal ini:
// 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);
}
}
Mengonfigurasi Instance Plugin
Saat antrean perintah ga()
mengeksekusi perintah require
, instance objek baru akan dibuat menggunakan operator new
di fungsi konstruktor plugin provide
. Konstruktor meneruskan objek tracker sebagai argumen pertamanya, dan opsi konfigurasi apa pun yang diteruskan ke perintah require
sebagai argumen kedua.
Pertimbangkan perintah require
berikut yang ditambahkan ke tag Google Analytics:
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'localHitSender', {path: '/log', debug: true});
ga('send', 'pageview');
Dan kode 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);
Saat perintah require
dijalankan, hal berikut akan dicatat ke konsol (perhatikan bahwa nama pelacak default adalah "t0"):
// localHitSender enabled for path: /log
// on tracker: t0
Menentukan Metode Plugin
Plugin dapat mengekspos metodenya sendiri yang dapat dipanggil menggunakan sintaksis antrean perintah ga
:
ga('[trackerName.]pluginName:methodName', ...args);
dengan trackerName
bersifat opsional dan methodName
sesuai dengan nama fungsi di prototipe konstruktor plugin. Jika methodName
tidak ada di plugin atau plugin tidak ada, error akan terjadi.
Contoh panggilan metode plugin:
// 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);
Contoh definisi metode plugin:
// 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;
}:
Memuat plugin
Plugin biasanya dimuat dari file JavaScript terpisah atau dipaketkan bersama dengan kode aplikasi utama Anda.
<script async src="myplugin.js"></script>
Plugin tidak perlu ditentukan sebelum diperlukan. Karena analytics.js dimuat secara asinkron dan plugin juga sering dimuat secara asinkron, antrean perintah ga()
dibuat untuk menangani hal ini.
Jika antrean perintah menerima perintah require
untuk plugin yang belum diberikan, eksekusi sisa item dalam antrean akan dihentikan sampai plugin tersedia.
Kode berikut menunjukkan bagaimana perintah ga('require', 'myplugin')
tidak benar-benar dieksekusi sampai perintah ga('provide', 'myplugin', ...)
ditemukan, tiga detik kemudian.
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);
Contoh
Contoh plugin berikut didesain untuk mengambil nilai kampanye kustom dari URL halaman dan meneruskannya ke pelacak. Plugin ini menunjukkan cara menentukan dan mendaftarkan skrip plugin, meneruskan parameter konfigurasi plugin, serta menentukan dan memanggil metode plugin.
// 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);
Kode di atas dapat disertakan ke dalam halaman HTML sebagai berikut:
<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>
Plugin Autotrack
Library autotrack adalah open source, tersedia di GitHub, dan menyertakan beberapa plugin analytics.js yang membantu melacak interaksi pengguna umum. Lihat kode sumber autotrack untuk mendapatkan pemahaman yang lebih baik tentang cara kerja plugin.