مقدمة عن ga.js (الإصدار القديم)

ga.js عبارة عن مكتبة JavaScript لقياس كيفية تفاعل المستخدمين مع موقعك. هذه مكتبة قديمة. إذا كنت تبدأ استخدام "إحصاءات Google"، يجب استخدام أحدث مكتبة تتبُّع، analytics.js.

التشغيل السريع لشفرة التتبع

مقتطف "إحصاءات Google" هو جزء صغير من رمز JavaScript تلصقه في صفحاتك. يتم تفعيل ميزة التتبُّع في "إحصاءات Google" من خلال إدراج ga.js في الصفحة. لاستخدام هذه السمة في صفحاتك، انسخ مقتطف الرمز أدناه، مع استبدال UA-XXXXX-X برقم تعريف موقعك الإلكتروني. ألصِق هذا المقتطف في صفحة نموذج موقعك الإلكتروني حتى يظهر قبل علامة الإغلاق </head>.

إذا كنت بحاجة إلى تنفيذ أكثر من تتبُّع الصفحة الأساسية، يمكنك الاطّلاع على مرجع التتبّع للاطّلاع على قائمة بالطرق المتاحة في واجهة برمجة التطبيقات ومراجعة دليل الاستخدام للحصول على تفاصيل حول استخدام البنية غير المتزامنة. للحصول على تعليمات مفصّلة حول إعداد التتبّع، راجِع مقالة مركز المساعدة حول إعداد التتبّع.

<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-XXXXX-X']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>

يمثل المقتطف أعلاه الحد الأدنى من الإعدادات اللازمة لتتبع الصفحة بشكل غير متزامن. تستخدِم هذه الميزة السمة _setAccount لضبط رقم تعريف الموقع الإلكتروني للصفحة، ثم تستدعي _trackPageview لإرسال بيانات التتبّع إلى خوادم "إحصاءات Google".

ملاحظة مهمة: إذا كنت بصدد تعديل صفحاتك من المقتطف التقليدي إلى أحدث إصدار غير متزامن، عليك إزالة مقتطف التتبّع الحالي أولاً. ولا ننصح باستخدام كلا المقتطفَين معًا في الصفحة نفسها. للحصول على تعليمات نقل البيانات، يُرجى الاطّلاع على نقل البيانات إلى الحالة غير المتزامنة.

كيف تعمل البنية غير المتزامنة

الكائن _gaq هو ما يجعل البنية غير المتزامنة ممكنة. تعمل هذه الواجهة كقائمة انتظار، وهي بنية بيانات أولية يتم الحصول عليها أولاً تجمع طلبات البيانات من واجهة برمجة التطبيقات حتى تصبح ga.js جاهزة لتنفيذها. لإضافة محتوى إلى قائمة المحتوى التالي، يمكنك استخدام الإجراء _gaq.push.

ولإرسال طلب بيانات من واجهة برمجة التطبيقات إلى قائمة الانتظار، يجب تحويله من بنية JavaScript التقليدية إلى مصفوفة أوامر. صفائف الأوامر هي ببساطة صفائف JavaScript تتوافق مع تنسيق معيّن. العنصر الأول في مصفوفة الأوامر هو اسم طريقة كائن أداة التتبُّع التي تريد استدعاءها. ويجب أن تكون سلسلة. أما باقي العناصر، فهي الوسيطات التي تريد تمريرها إلى طريقة كائن التتبع. ويمكن أن تكون هذه القيم أي قيمة JavaScript.

يستدعي الرمز التالي _trackPageview() باستخدام البنية التقليدية:

var pageTracker = _gat._getTracker('UA-XXXXX-X');
pageTracker._trackPageview();

يتطلب الرمز المكافئ في البنية غير المتزامنة طلبين إلى _gaq.push.

_gaq.push(['_setAccount', 'UA-XXXXX-X']);
_gaq.push(['_trackPageview']);

في البنية غير المتزامنة، يكون إنشاء كائن المتتبّع ضمنيًا، لكننا ما زلنا بحاجة إلى طريقة لضبط رقم تعريف موقع الويب لأداة التتبُّع. تمت إضافة طريقة _setAccount لتوفير هذه الإمكانية. جميع طرق عناصر التتبع الأخرى متماثلة في كلٍّ من التتبع غير المتزامن والتقليدي. فقط الصيغة هي المختلفة.

لمزيد من المعلومات عن البنية غير المتزامنة، اطّلِع على مرجع التتبّع لطريقة _gaq.push.

الرجوع إلى أعلى الصفحة

التتبّع باستخدام معالِجات أحداث HTML

يجب أيضًا استخدام بنية التتبّع غير المتزامنة من داخل معالِجات أحداث DOM. على سبيل المثال، ينشئ الزر التالي حدثًا عند النقر عليه.

<button onclick="_gaq.push(['_trackEvent', 'button3', 'clicked'])"></button>

حتى إذا تم النقر على هذا الزر قبل انتهاء المتصفّح من تحميل ga.js، سيتم تسجيل الحدث وتنفيذه في النهاية. عند استخدام التتبّع التقليدي، قد يطرح المتصفّح استثناء في هذه الحالة.

الرجوع إلى أعلى الصفحة

دفع الدوال إلى قائمة الانتظار

بالإضافة إلى صفائف الأوامر، يمكنك أيضًا دفع كائنات الدوال إلى قائمة الانتظار _gaq. يمكن أن تحتوي الدوال على أي JavaScript عشوائي، وتمامًا مثل صفائف الأوامر، يتم تنفيذها بالترتيب الذي يتم دفعها به في _gaq. ويُعدّ هذا الأسلوب مفيدًا لاستدعاء واجهات برمجة التطبيقات للتتبّع التي تعرض قيمًا. على سبيل المثال، ينشئ الرمز التالي عنوان URL للرابط ويضبط السمة href لرابط يؤدي إلى النتيجة.

_gaq.push(function() {
  var pageTracker = _gat._getTracker('UA-XXXXX-X');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

يستخدم المثال أعلاه _gat لإنشاء كائن متتبع، ولكن لا يمكن استخدامه لمتغير محلي لأنّه مخصّص لمتغير محلي. ومع أنّ هذا الإجراء مقبول، يمكنك استخدام الطريقة _gat._createTracker لإنشاء عنصر دائم يمكن الوصول إليه عالميًا. يوضح التعليمة البرمجية التالية كيفية عمل ذلك.

_gaq.push(function() {
  var pageTracker = _gat._createTracker('UA-XXXXX-X', 'myTracker');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

_gaq.push(['myTracker._trackPageview']);

ينشئ المثال أعلاه أداة تتبُّع غير متزامنة داخل الدالة، ثم يشير إليها لاحقًا بالاسم في صفيف الأوامر.

من الممكن أيضًا حالة الاستخدام المعاكسة. على سبيل المثال، إذا كنت بحاجة إلى استخدام كائن متتبّع غير متزامن تم إنشاؤه من خلال مصفوفة أوامر تم إرسالها سابقًا، استخدِم الطريقة _gat._getTrackerByName. يوضح الرمز التالي كيفية عمله.

_gaq.push(['myTracker._setAccount', 'UA-XXXXX-X']);

_gaq.push(function() {
  var pageTracker = _gat._getTrackerByName('myTracker');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

الرجوع إلى أعلى الصفحة

دفع واحد، وأوامر متعددة

بدلاً من كتابة الرمز _gaq.push(...) لكل مكالمة، يمكنك إرسال جميع الطلبات في وقت واحد. توضح التعليمة البرمجية التالية هذا الأسلوب.

_gaq.push(
  ['_setAccount', 'UA-XXXXX-X'],
  ['_setDomainName', 'example.com'],
  ['_setCustomVar', 1, 'Section', 'Life & Style', 3],
  ['_trackPageview']
);

وتُعدّ هذه الطريقة مناسبة لأنّ الطريقة _gaq.push تقلّد الطريقة Array.push، ما يسمح بإرسال عناصر متعدّدة باستخدام استدعاء واحد.

الرجوع إلى أعلى الصفحة

تقسيم المقتطف

إذا كنت تفضّل وضع مقتطف "إحصاءات Google" في أسفل الصفحة، يُرجى العلم بأنّه ليس عليك وضع المقتطف بأكمله في أسفل الصفحة. لا يزال بإمكانك الاحتفاظ بمعظم مزايا التحميل غير المتزامن من خلال تقسيم المقتطف إلى نصفين، وإبقاء النصف الأول في أعلى الصفحة ونقل الباقي إلى الأسفل. بما أنّ الجزء الأول من مقتطف التتبّع لا يؤثر كثيرًا في عرض الصفحة أو لا يؤثر إطلاقًا، يمكنك ترك هذا الجزء في الأعلى ووضع ذلك المقتطف الذي يُدخل ga.js في الجزء السفلي.

وقد تظهر الصفحة التي يتم تقسيم المقتطف غير المتزامن إلى نصفين بها على النحو التالي:

<html>

<head>
  <script type="text/javascript">
    var _gaq = _gaq || [];
    _gaq.push(['_setAccount', 'UA-XXXXX-X']);
    _gaq.push(['_trackPageview']);
  </script>
</head>

<body>
  <p>Page Content</p>

  <script src="some_random_script.js"></script>

  <p>Page Content</p>

  <script type="text/javascript">  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
  ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script> </body> </html>

ويجب أن يتم تضمين كلا الجزأين في علامات النص البرمجي الخاصة بهما، ولكن يجب نقل الأسطر الستة الأخيرة فقط من المقتطف الأصلي غير المتزامن إلى الأسفل. ويمكن أن تظل جميع الخطوط التي تنقل الطرق إلى _gaq في الأعلى.

الرجوع إلى أعلى الصفحة

تجنب المزالق الشائعة

عند استخدام البنية غير المتزامنة أو التقليدية، ضع في اعتبارك ما يلي:

  • أسماء الطرق حسّاسة لحالة الأحرف.
    في حال استخدام اسم طريقة بدون حالة الأحرف المناسبة، لن تنجح استدعاءات الطريقة. أمثلة:
    _gaq.push(['_trackpageview']);   // bad
    _gaq.push(['_trackPageview']);   // good
  • استخدِم أسماء الطُرق الصحيحة.
    إذا كان التتبّع لا يعمل بشكل صحيح، يُرجى التأكّد من استخدام الاسم الصحيح للطريقة. أمثلة:
    _gaq.push(['_setDomain', 'example.com']);       // bad
    _gaq.push(['_setDomainName', 'example.com']);   // good
    
  • يجب تمرير السلاسل فقط بين علامات اقتباس. يجب ترك جميع الأنواع الأخرى بدون علامتي اقتباس.
    يجب تمرير أي قيمة لا تكون سلسلة بدون علامات اقتباس، مثل القيم المنطقية أو القيم الحرفية للكائن أو الدوال أو الصفائف. ولا تستخدِم علامات الاقتباس إلا عند تمرير عنصر من أجل تفسيره كسلسلة. إذا كنت بصدد نقل البيانات من البنية التقليدية، يجب أن تظل أي مَعلمة دالة تم تمريرها بدون علامات اقتباس بدون علامات اقتباس في البنية غير المتزامنة. أمثلة:
    _gaq.push(['_setAllowLinker', 'false']);    // bad
    _gaq.push(['_setAllowLinker', false]);      // good
    
  • تأكَّد من أنّ السلاسل لا تحتوي على أي مسافة بيضاء بادئة أو لاحقة.
    أمثلة:
    _gaq.push(['_setAccount', ' UA-65432-1']);    // bad
    _gaq.push(['_setAccount', 'UA-65432-1']);     // good
    

الرجوع إلى أعلى الصفحة

إيقاف التتبّع

في بعض الحالات، قد يكون من الضروري إيقاف رمز تتبّع "إحصاءات Google" على صفحة ما بدون الحاجة إلى إزالة مقتطف الرمز. على سبيل المثال، يمكنك استخدام هذا الإجراء إذا كانت سياسة خصوصية موقعك الإلكتروني تتضمن قدرة الزائر على إيقاف تتبُّع "إحصاءات Google".

يتضمّن مقتطف التتبّع ga.js الآن موقع نافذة يعمل على إيقاف مقتطف التتبّع من إرسال البيانات إلى "إحصاءات Google"، وذلك عند ضبطه على true. عندما تحاول "إحصاءات Google" ضبط ملف تعريف ارتباط أو إرسال البيانات مرة أخرى إلى خوادم "إحصاءات Google"، ستتحقّق ممّا إذا تم ضبط هذا الموقع على true. وإذا كان كذلك، سيكون له التأثير نفسه كما لو كان الزائر قد تم تثبيت مكوّن المتصفح الإضافي لإيقاف التتبّع في "إحصاءات Google".

لإيقاف التتبّع، اضبط خاصية النافذة التالية على "صحيح":

window['ga-disable-UA-XXXXXX-Y'] = true;

عندما تتجاوب القيمة UA-XXXXXX-Y مع رقم تعريف الموقع الإلكتروني الذي تريد إيقاف التتبّع عليه.

يجب ضبط سمة النافذة هذه قبل استدعاء رمز التتبّع. ويجب ضبط هذا الموقع في كل صفحة تريد إيقاف تتبُّع "إحصاءات Google" فيها. إذا لم يتم ضبط السمة أو تم ضبطها على "خطأ"، سيعمل التتبُّع كالمعتاد.

لذلك، على سبيل المثال، إذا كان رمز تتبّع "إحصاءات Google" في إحدى الصفحات يتضمن ما يلي:

_gaq.push['_setAccount', 'UA-123456-1']

وكنت تريد إيقاف رمز التتبّع هذا من ضبط ملفات تعريف الارتباط أو إرسال البيانات مرّة أخرى إلى "إحصاءات Google"، عليك استخدام الرمز التالي قبل طلب رمز التتبّع:

window['ga-disable-UA-123456-1'] = true;

إذا كنت تستخدم أدوات تتبّع متعدّدة على صفحة بها أرقام تعريف متعدّدة للمواقع الإلكترونية، يجب ضبط المتغيّر window['ga-disable-UA-XXXXXX-Y'] المكافئ على true لكل موقع إلكتروني لإيقاف تتبُّع "إحصاءات Google" تمامًا على تلك الصفحة.

مثال

في ما يلي مثال بسيط على بعض الرموز التي يمكنك استخدامها لتوفير وظيفة إيقاف مشاركة البيانات للمستخدمين.

أولاً، أضِف رابط HTML جديدًا إلى موقعك الإلكتروني لتنفيذ منطق الإيقاف:

<a href="javascript:gaOptout()">Click here to opt-out of Google Analytics</a>

ثم أضِف مقتطف الرمز التالي قبل مقتطف رمز ga.js. احرص على استبدال القيمة gaProperty من UA-XXXX-Y بالسمة المستخدَمة على موقعك الإلكتروني. وهذه هي القيمة نفسها التي تمرِّرها إلى الأمر _setAccount.

<script>
// Set to the same value as the web property used on the site
var gaProperty = 'UA-XXXX-Y';

// Disable tracking if the opt-out cookie exists.
var disableStr = 'ga-disable-' + gaProperty;
if (document.cookie.indexOf(disableStr + '=true') > -1) {
  window[disableStr] = true;
}

// Opt-out function
function gaOptout() {
  document.cookie = disableStr + '=true; expires=Thu, 31 Dec 2099 23:59:59 UTC; path=/';
  window[disableStr] = true;
}
</script>

وعندما ينقر المستخدم على رابط HTML لإيقاف الميزة، سيتم تنفيذ دالة gaOptout المخصّصة. ستضبط هذه الميزة ملف تعريف ارتباط لفترة طويلة في المستقبل وستوقِف جمع بيانات analytics.js. عندما يعود المستخدم إلى هذا الموقع الإلكتروني، سيتحقق النص البرمجي أعلاه لمعرفة ما إذا تم تعيين ملف تعريف ارتباط الإيقاف. وفي حال حدوث ذلك، سيتم أيضًا إيقاف جمع البيانات analytics.js.

فرض طبقة المقابس الآمنة (HTTPS)

لفرض إرسال البيانات دائمًا باستخدام طبقة المقابس الآمنة (SSL)، حتى من الصفحات غير الآمنة (HTTP)، استخدِم الإجراء _gat._forceSSL كما في هذا المثال:

_gaq.push(['_setAccount', 'UA-12345-1']);
_gaq.push(['_gat._forceSSL']);       // Send all hits using SSL, even from insecure (HTTP) pages.
_gaq.push(['_trackPageview']);

الرجوع إلى أعلى الصفحة