تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

مقدمة عن 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 الآن خاصية نافذة عند ضبطها على true، يوقف مقتطف التتبّع من إرسال البيانات إلى "إحصاءات Google". عندما تحاول "إحصاءات Google" ضبط ملف تعريف ارتباط أو إرسال البيانات مرة أخرى إلى خوادم "إحصاءات Google"، ستتحقّق مما إذا كان قد تم ضبط هذا الموقع على true. وإذا كان الأمر كذلك، سيكون لها التأثير نفسه كما لو كان الزائر قد تم تثبيت المكوّن الإضافي للمتصفح لإيقاف "إحصاءات Google".

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

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)

لفرض إرسال البيانات دائمًا باستخدام طبقة المقابس الآمنة على "إحصاءات Google"، حتى من الصفحات غير الآمنة (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']);

الرجوع إلى الأعلى