پلاگین های نوشتن

پلاگین ها اسکریپت هایی هستند که عملکرد analytics.js را برای کمک به حل مشکلات و کمک به اندازه گیری تعامل کاربر افزایش می دهند. این راهنما روند نوشتن افزونه های analytics.js خود را شرح می دهد. برای کسب اطلاعات در مورد نحوه استفاده از افزونه های analytics.js در پیاده سازی های خود، به استفاده از افزونه ها مراجعه کنید.

تعریف پلاگین

پلاگین ها از طریق دستور provide تعریف می شوند که باید با نام افزونه به عنوان اولین آرگومان و سپس تابع سازنده افزونه فراخوانی شود. هنگامی که دستور provide اجرا می شود، افزونه را برای استفاده در صف فرمان ga() ثبت می کند.

سازنده پلاگین

زیر ابتدایی ترین مثال از افزونه analytics.js است:

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

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

افزونه‌ها باید به درستی عمل کنند حتی در مواردی که شیء جهانی ga تغییر نام داده است، بنابراین اگر در حال نوشتن یک افزونه برای استفاده شخص ثالث هستید، باید یک بررسی برای مشاهده اینکه آیا متغیر GoogleAnalyticsObject روی رشته‌ای غیر از آن تنظیم شده است قرار دهید. 'ga' . تابع providePlugin زیر این کار را انجام می دهد:

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

پیکربندی نمونه های پلاگین

هنگامی که صف فرمان ga() یک فرمان require اجرا می کند، یک شی جدید را با استفاده از عملگر new در تابع سازنده افزونه provide . سازنده، شی ردیاب را به عنوان اولین آرگومان ارسال می کند، و هر گزینه پیکربندی را به عنوان آرگومان دوم به دستور require ارسال می کند.

دستور require زیر را در نظر بگیرید که به تگ Google Analytics اضافه شده است:

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

و کد 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);

هنگامی که دستور require اجرا می شود، موارد زیر در کنسول ثبت می شود (توجه داشته باشید که نام ردیاب پیش فرض "t0" است):

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

تعریف روش های پلاگین

پلاگین‌ها می‌توانند روش‌های خود را که می‌توانند با استفاده از دستور صف دستور ga فراخوانی کنند، نشان دهند:

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

جایی که trackerName اختیاری است و methodName با نام یک تابع در نمونه اولیه سازنده پلاگین مطابقت دارد. اگر methodName در افزونه وجود نداشته باشد یا افزونه وجود نداشته باشد، خطایی رخ می دهد.

نمونه فراخوانی متد افزونه:

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

نمونه تعاریف روش پلاگین:

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

در حال بارگیری افزونه ها

پلاگین ها معمولاً از یک فایل جاوا اسکریپت جداگانه بارگیری می شوند یا همراه با کد برنامه اصلی شما همراه می شوند.

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

پلاگین ها لزوماً نیازی به تعریف قبل از نیاز ندارند. از آنجایی که analytics.js به صورت ناهمزمان بارگذاری می شود و پلاگین ها نیز اغلب به صورت ناهمزمان بارگذاری می شوند، صف فرمان ga() برای رسیدگی به این موضوع ساخته شده است.

اگر صف فرمان برای افزونه‌ای که هنوز ارائه نشده است، دستور require دریافت کند، اجرای موارد باقی‌مانده در صف را تا زمانی که افزونه در دسترس نباشد، متوقف می‌کند.

کد زیر نشان می دهد که چگونه دستور ga('require', 'myplugin') تا زمانی که سه ثانیه بعد با دستور ga('provide', 'myplugin', ...) مواجه نشود، واقعاً اجرا نمی شود.

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

مثال ها

افزونه مثال زیر برای گرفتن مقادیر کمپین سفارشی از URL صفحه و ارسال آنها به ردیاب طراحی شده است. این افزونه نحوه تعریف و ثبت اسکریپت افزونه، پاس کردن پارامترهای پیکربندی افزونه و تعریف و فراخوانی متدهای افزونه را نشان می دهد.

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

کد بالا را می توان به صورت زیر در یک صفحه HTML قرار داد:

<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

کتابخانه autotrack منبع باز است، در GitHub موجود است و شامل چندین پلاگین analytics.js است که به ردیابی تعاملات رایج کاربر کمک می کند. برای درک بهتر نحوه کار افزونه ها به کد منبع خودکار ردیابی مراجعه کنید.