تمت ترجمة هذه الصفحة بواسطة 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".

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

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

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