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

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

تعريف مكوّن إضافي

يتم تحديد المكونات الإضافية من خلال الأمر provide الذي يجب استدعاؤه باسم المكوّن الإضافي كوسيطة أولية متبوعة بوظيفة منشئ المكوِّن الإضافي's. عند تشغيل الأمر 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);

ملاحظة مهمة: على الرغم من عدم أهمية ترتيب الأمرَين require وprovide، إلا أنه لا يمكن طلبهما قبل تشغيل مقتطف التتبّع JavaScript لأنّهما يشيران إلى دالة قائمة الأوامر ga العامة.

أمثلة

تم تصميم مثال المكوِّن الإضافي التالي لالتقاط قيم الحملة المخصّصة من عنوان 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 مفتوحة المصدر، متاحة على GitHub، وتضم العديد من مكوّنات analytics.js الإضافية التي تساعد في تتبّع تفاعلات المستخدم الشائعة. يمكنك الرجوع إلى رمز مصدر التتبع التلقائي لفهم كيفية عمل المكونات الإضافية بشكل أفضل.

• eventTracker
• mediaQueryTracker
• outboundFormTracker
• outboundLinkTracker
• socialTracker
• urlChangeTracker