Viết trình bổ trợ

Trình bổ trợ là các tập lệnh giúp nâng cao chức năng của analytics.js để giúp giải quyết vấn đề và hỗ trợ đo lường hoạt động tương tác của người dùng. Hướng dẫn này mô tả quy trình viết các trình bổ trợ analytics.js của riêng bạn. Để biết thông tin về cách sử dụng plugin analytics.js trong quá trình triển khai của riêng bạn, hãy xem Sử dụng plugin.

Xác định trình bổ trợ

Trình bổ trợ được xác định thông qua lệnh provide. Lệnh này phải được gọi bằng tên trình bổ trợ làm đối số đầu tiên, theo sau là hàm khởi tạo của trình bổ trợ. Khi chạy lệnh provide, lệnh này sẽ đăng ký trình bổ trợ sẽ được sử dụng với hàng đợi lệnh ga().

Hàm khởi tạo của trình bổ trợ

Sau đây là ví dụ cơ bản nhất về trình bổ trợ analytics.js:

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

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

Trình bổ trợ cần phải hoạt động chính xác ngay cả trong trường hợp đối tượng ga chung đã được đổi tên. Vì vậy, nếu đang viết một trình bổ trợ để sử dụng cho bên thứ ba, bạn nên kiểm tra để xem biến GoogleAnalyticsObject đã được đặt thành một chuỗi không phải là 'ga' hay chưa. Hàm providePlugin sau đây thực hiện việc này:

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

Định cấu hình các phiên bản trình bổ trợ

Khi hàng đợi lệnh ga() thực thi lệnh require, lệnh này sẽ tạo thực thể cho đối tượng mới bằng cách sử dụng toán tử new trên hàm khởi tạo của trình bổ trợ provide. Hàm khởi tạo được chuyển đối tượng trình theo dõi làm đối số đầu tiên và mọi tuỳ chọn cấu hình được truyền đến lệnh require làm đối số thứ hai.

Hãy xem xét lệnh require sau đây được thêm vào thẻ Google Analytics:

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

Và mã 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);

Khi chạy lệnh require, nội dung sau đây sẽ được ghi vào bảng điều khiển (lưu ý rằng tên của trình theo dõi mặc định là "t0"):

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

Xác định phương thức trình bổ trợ

Các trình bổ trợ có thể hiển thị các phương thức riêng có thể được gọi bằng cú pháp hàng đợi lệnh ga:

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

trong đó trackerName là không bắt buộc và methodName tương ứng với tên của một hàm trên nguyên mẫu của hàm khởi tạo trình bổ trợ. Lỗi sẽ xảy ra nếu methodName không tồn tại trên trình bổ trợ hoặc trình bổ trợ không tồn tại.

Ví dụ về lệnh gọi phương thức trình bổ trợ:

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

Ví dụ về định nghĩa phương thức trình bổ trợ:

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

Đang tải trình bổ trợ

Trình bổ trợ thường được tải từ một tệp JavaScript riêng hoặc đi kèm với mã xử lý ứng dụng chính.

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

Bạn không nhất thiết phải xác định trình bổ trợ trước khi yêu cầu. Vì analytics.js được tải không đồng bộ và các trình bổ trợ cũng thường tải không đồng bộ, nên hàng đợi lệnh ga() được tạo để xử lý việc này.

Nếu hàng đợi lệnh nhận được lệnh require cho một trình bổ trợ chưa được cung cấp, thì lệnh này sẽ tạm dừng việc thực thi các mục còn lại trong hàng đợi cho đến khi có trình bổ trợ này.

Đoạn mã sau đây cho thấy cách lệnh ga('require', 'myplugin') không thực sự được thực thi cho đến khi gặp lệnh ga('provide', 'myplugin', ...), 3 giây sau đó.

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

Ví dụ

Trình bổ trợ mẫu sau được thiết kế để thu thập các giá trị tuỳ chỉnh của chiến dịch từ URL của một trang và chuyển các giá trị đó đến trình theo dõi. Trình bổ trợ này minh hoạ cách xác định và đăng ký tập lệnh trình bổ trợ, truyền tham số cấu hình trình bổ trợ, cũng như xác định và gọi các phương thức trình bổ trợ.

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

Bạn có thể đưa mã trên vào trong trang HTML như sau:

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

Trình bổ trợ tự động theo dõi

Thư viện autotrack là nguồn mở, có sẵn trên GitHub và bao gồm một số trình bổ trợ analytics.js hỗ trợ theo dõi các hoạt động tương tác phổ biến của người dùng. Tham khảo mã nguồn tự động theo dõi để hiểu rõ hơn về cách hoạt động của trình bổ trợ.