مرجع قائمة انتظار ga

تقدّم قائمة أوامر الأوامر ga() واجهة لتنفيذ كل ما تحتاج إليه تقريبًا باستخدام مكتبة analytics.js.

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

لإبقاء مقتطف التتبُّع صغيرًا قدر الإمكان، يتم تحميل قائمة انتظار الأوامر ga() بشكل زائد لقبول الوسيطات بتنسيقات مختلفة. يوضّح هذا المستند بالتفصيل الطرق المختلفة التي يمكن من خلالها استدعاء دالة قائمة انتظار الأوامر ga().

توقيع الدالة
ga(command, [...fields], [fieldsObject])

سيؤدي استدعاء دالة قائمة انتظار الأوامر ga() من خلال توقيع الدالة التالي إلى إرسال الأوامر إلى قائمة الانتظار التي ستتم جدولتها للتنفيذ بعد تحميل المكتبة.

ga(readyCallback)

يؤدي استدعاء دالة قائمة انتظار الأوامر ga() من خلال تمريرها إلى جدولة الدالة التي تم تمريرها للتنفيذ في المرحلة التالية من قائمة الانتظار.

بما أنه لا يتم تنفيذ الأوامر إلا بعد تحميل مكتبة analytics.js بالكامل، فالسبب الأكثر شيوعًا لتمرير قائمة انتظار الأوامر هو الدالة كاستدعاء عندما يتم تحميل مكتبة analytics.js وجاهزة.

إضافة طلبات إلى قائمة المحتوى التالي

سيؤدي استدعاء دالة قائمة انتظار الأوامر ga() من خلال توقيع الدالة التالي إلى إرسال الأوامر إلى قائمة الانتظار التي ستتم جدولتها للتنفيذ بعد تحميل المكتبة.

الاستخدام

ga(command, [...fields], [fieldsObject])

المَعلمات

الاسم النوع مطلوب الوصف
command string نعم

تمثّل هذه الخاصية معرّفًا يمثل الأمر المطلوب إضافته إلى قائمة الانتظار. يتألّف المعرّف من ثلاثة أجزاء (الجزء الأول اختياري):

[trackerName.][pluginName:]methodName
trackerName اسم أداة التتبّع لاستدعاء الأمر المُجدوَل. وفي حال عدم تحديد اسم أداة التتبُّع، يتم استدعاء الأمر في أداة التتبُّع التلقائية.
pluginName اسم المكوّن الإضافي analytics.js المطلوب. إذا تم تحديد pluginName، يجب أن تكون methodName طريقة يوفّرها المكوّن الإضافي.
methodName اسم الطريقة التي ستتم جدولتها للتنفيذ. عند عدم تحديد اسم مكوّن إضافي، يجب أن تكون هذه الطريقة إحدى طرق الأوامر المُدرجة أدناه.
...fields * لا معلمة إضافية اختيارية واحدة أو أكثر لتحديد الحقول الشائعة بسرعة. يختلف عدد الحقول المحددة المسموح بها بناءً على طريقة الأمر التي يتم طلبها.
fieldsObject Object لا

كائن لتحديد أي قيم متبقية لم يتم تحديدها في أي من معلَمات fields.

إذا تم ضبط حقل في كل من معلَمة fields وfieldsObject، سيتم استخدام القيمة في fieldsObject.

اطّلِع على مرجع الحقل للحصول على مستندات الحقول الفردية.

أمثلة

يمكنك الاطّلاع على قسم طرق الأوامر أدناه للحصول على أمثلة على أوامر فردية.

معاودة الاتصال جاهزة

يؤدي استدعاء دالة قائمة انتظار الأوامر ga() من خلال تمريرها إلى جدولة الدالة التي تم تمريرها للتنفيذ في المرحلة التالية من قائمة الانتظار.

بما أنه لا يتم تنفيذ الأوامر إلا بعد تحميل مكتبة analytics.js بالكامل، فالسبب الأكثر شيوعًا لتمرير قائمة انتظار الأوامر هو الدالة كاستدعاء عندما يتم تحميل مكتبة analytics.js وجاهزة.

الاستخدام

ga(readyCallback)

المَعلمات

الاسم النوع مطلوب الوصف
readyCallback Function نعم

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

ملاحظة: عند استدعاء دالة رد الاتصال، تتوفّر جميع طرق العناصر ga للاستخدام.

أمثلة

// Queues a tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto');

// Once the tracker has been created, log the
// client ID to the console.
ga(function(tracker) {
  console.log(tracker.get('clientId'));
});
// Queues a named tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto', 'myTracker');

// When there is no default tracker, the first
// argument of the ready callback is `undefined`.
ga(function(tracker) {
  console.log(tracker); // Logs `undefined`.
});

تفاصيل طريقة الطلب

في ما يلي قائمة بجميع الطرق التي يمكن تمريرها إلى قائمة انتظار الأوامر ga() (باستثناء طرق المكوّنات الإضافية).

create

إنشاء مثيل أداة تتبُّع جديد بالحقول المحدّدة.

الاستخدام

ga('create', [trackingId], [cookieDomain], [name], [fieldsObject]);

المَعلمات

اطّلِع على مرجع الحقل للحصول على مستندات الحقول الفردية.

المرتجعات

undefined

أمثلة

// Creates a default tracker for the Property UA-XXXXX-Y
// and uses automatic cookie domain configuration.
ga('create', 'UA-XXXXX-Y', 'auto');
// Creates a tracker with the name "myTracker" for the Property
// UA-XXXXX-Y, sets the cookieDomain to "example.com", and specifies
// a transport mechanism of "beacon".
ga('create', 'UA-XXXXX-Y', 'example.com', 'myTracker', {
  transport: 'beacon'
});

send

إرسال نتيجة إلى "إحصاءات Google".

الاستخدام

ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);

تمثّل الحقول التي تم إرسالها القيم المحدّدة في المَعلمتَين ...fields وfieldsObject، وقد تم دمجها مع الحقول المخزّنة حاليًا في أداة التتبّع.

المَعلمات

تختلف الحقول التي يمكن تحديدها بواسطة المعلمات ...fields بناءً على نوع النتيجة. يسرد الجدول التالي الحقول التي تتوافق مع كل نوع نتيجة. لا تقبل أنواع النتائج غير المدرَجة معلَمات ...fields، بل تقبل fieldsObject فقط.

نوع النتيجة ...fields
pageview page
event eventCategory، eventAction، eventLabel، eventValue
social socialNetwork، socialAction، socialTarget
timing timingCategory، timingVar، timingValue، timingLabel

اطّلِع على مرجع الحقل للحصول على مستندات الحقول الفردية.

المرتجعات

undefined

أمثلة

// Sends a pageview hit.
ga('send', 'pageview');
// Sends an event hit for the tracker named "myTracker" with the
// following category, action, and label, and sets the nonInteraction
// field value to true.
ga('send', 'event', 'link', 'click', 'http://example.com', {
  nonInteraction: true
});

set

تضبط هذه السمة حقلاً واحدًا وزوجًا من القيم أو مجموعة من أزواج الحقول/القيمة في عنصر أداة تتبُّع.

الاستخدام

// Sets a single field and value.
ga('[trackerName.]set', fieldName, fieldValue);
// Sets a group of field/value pairs.
ga('[trackerName.]set', fieldsObject);

المَعلمات

اطّلِع على مرجع الحقل للحصول على مستندات الحقول الفردية.

المرتجعات

undefined

أمثلة

// Sets the page field to "/about.html".
ga('set', 'page', '/about.html');
// Sets the page field to "/about.html" and the title to "About".
ga('set', {
  page: '/about.html',
  title: 'About'
});

require

يتطلب المكوّن الإضافي analytics.js.

الاستخدام

ga('[trackerName.]require', pluginName, [pluginOptions]);

المَعلمات

الاسم النوع مطلوب الوصف
pluginName string نعم اسم المكوِّن الإضافي المطلوب. ملاحظة: إذا لم يكن المكوّن الإضافي رسميًا رسميًا في analytics.js، يجبتقديمه في مكان آخر على الصفحة.
pluginOptions Object لا كائن إعداد سيتم تمريره إلى أداة إنشاء المكوّنات الإضافية عند إنشاء مثيل.

المرتجعات

undefined

مثال

// Requires the Enhanced Ecommerce plugin.
ga('require', 'ec');
// Requires the Advertising Features plugin
// named "myTracker" and override its default cookie name.
ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

provide

توفّر المكوّن الإضافي analytics.js وطرق استخدامه مع قائمة أوامر ga().

ga('provide', pluginName, pluginConstuctor);

المَعلمات

الاسم النوع مطلوب الوصف
pluginName string نعم يعرض هذا الحقل اسم المكوِّن الإضافي الذي يتم تقديمه. يجب أن يكون الاسم المستخدَم هو الاسم نفسه المستخدَم في أي من مكالمات طلب.
pluginConstuctor Function نعم توفّر دالة المُنشئ جميع منطق وأساليب المكوِّنات الإضافية. سيتم استدعاء أداة الإنشاء هذه بكائن pluginsOptions المحدَّد في الطريقة required.

مثال

// Defines a plugin constructor
function MyPlugin(tracker, options) {
  // ...
}

// Provides the plugin for use with the ga() command queue.
ga('provide', 'myplugin', MyPlugin);

remove

إزالة عنصر أداة التتبُّع

الاستخدام

ga('[trackerName.]remove');

أمثلة

// Remove the default tracker.
ga('remove');
// Remove the  tracker named "myTracker".
ga('myTracker.remove');