مرجع قائمة انتظار أوامر 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 نعم اسم المكون الإضافي المقدَّم. يجب أن يكون الاسم المستخدَم هو الاسم نفسه المستخدَم في أي من طلبات البيانات require.
pluginConstuctor Function نعم توفر دالة الدالة الإنشائية جميع منطق وأساليب المكوّن الإضافي. سيتم استدعاء دالة الإنشاء هذه مع الكائن pluginsOptions المحدد في طريقة require.

مثال

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