Menulis Plugin

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.