مكونات إضافية للكتابة

والمكوّنات الإضافية هي نصوص برمجية تُحسِّن وظائف 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":

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

جارٍ تحميل المكوّنات الإضافية

يتم عادةً تحميل المكوّنات الإضافية من ملف JavaScript منفصل أو يتم تجميعها مع رمز التطبيق الرئيسي.

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

المكونات الإضافية للتتبع التلقائي

مكتبة التتبّع التلقائي هي مكتبة مفتوحة المصدر ومتاحة على GitHub، وتتضمّن العديد من مكوّنات analytics.js الإضافية التي تساعد في تتبّع تفاعلات المستخدمين الشائعة. ارجع إلى رمز مصدر التتبع التلقائي للحصول على فهم أفضل لكيفية عمل المكوّنات الإضافية.