Workbox-google-analytics

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

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

يعمل Google Analytics على حل هذه المشكلة لمستخدمي "إحصاءات Google" من خلال الاستفادة من قدرة "عامل الخدمة" على اكتشاف الطلبات التي تعذّر تنفيذها.

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

تتولى "إحصاءات Google" من Google Workspace تنفيذ هذا الإجراء بالضبط. وتضيف أيضًا معالِجات الجلب لتخزين النصوص البرمجية analytics.js وgtag.js مؤقتًا، كي يمكن أيضًا تشغيلها بلا إنترنت. أخيرًا، عند إعادة محاولة إرسال الطلبات التي تعذّر تنفيذها، تضبط "إحصاءات Google" على Workbox أيضًا (أو تعدِّل) العنصر qt في حمولة الطلب للتأكّد من أنّ الطوابع الزمنية في "إحصاءات Google" تعكس وقت تفاعل المستخدم الأصلي.

تفعيل "إحصاءات Google" ضمن Workbox

لتفعيل "إحصاءات Google" ضمن Workbox، يمكنك استدعاء طريقة initialize():

import * as googleAnalytics from 'workbox-google-analytics';

googleAnalytics.initialize();

هذا هو الرمز الوحيد المطلوب لوضع الطلبات الفاشلة في قائمة انتظار وإعادة المحاولة إلى "إحصاءات Google"، وهي أبسط طريقة لتشغيل "إحصاءات Google" بلا إنترنت.

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

لمعالجة هذه المشكلة، يمكنك استخدام أحد خيارات الضبط الموضّحة أدناه لتعديل البيانات التي يتم إرسالها في الطلب الذي تمت إعادة المحاولة أو إضافة تعليقات توضيحية إليه.

تعديل البيانات التي يتم إرسالها

إذا أردت أن تتمكّن من التفريق بين الطلبات التي تمت إعادة محاولة إجرائها والطلبات التي لم تتم إعادة محاولة إجرائها، يمكنك تحديد إما parameterOverrides أو hitFilter خيارات الضبط.

وتتيح لك هذه الخيارات إمكانية تعديل مَعلمات Measurement Protocol التي يتمّ إرسالها في الطلب الذي تتمّ إعادة المحاولة. يجب استخدام الخيار parameterOverrides عندما تريد ضبط القيمة نفسها لمَعلمة معينة لكل طلب تتم إعادة محاولة إجرائه. ويجب استخدام الخيار hitFilter في الحالات التي يجب فيها احتساب قيمة معلَمة معيّنة في وقت التشغيل أو اشتقاقها من قيمة معلَمة أخرى.

توضّح الأمثلة أدناه كيفية استخدام كلا الخيارين.

أمثلة

استخدام سمة مخصصة لتتبُّع التفاعلات على الإنترنت مقارنةً بالتفاعلات بلا إنترنت

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

لتتبُّع الطلبات التي تمت إعادة تشغيلها من قِبل مشغّل الخدمات باستخدام سمة مخصّصة في "إحصاءات Google" ضمن Workbox، اتّبِع الخطوات التالية:

1. أنشئ بُعدًا مخصّصًا جديدًا في "إحصاءات Google". أدخِل اسمًا مثل "حالة الشبكة" واضبط نطاقه على "النتيجة" (لأن أي تفاعل يمكن أن يكون في وضع عدم الاتصال بالإنترنت).

2. دوِّن الفهرس المعيّن للبُعد الذي تم إنشاؤه حديثًا واضبطه كاسم المعلَمة لخيار الإعداد parameterOverrides في رمز "إحصاءات Google" ضمن Workbox.

   على سبيل المثال، إذا كانت هذه هي السمة المخصّصة الأولى، سيكون فهرسها 1، واسم المَعلمة cd1 (إذا كان الفهرس 8، سيكون cd8):

   import * as googleAnalytics from 'workbox-google-analytics';
   
   googleAnalytics.initialize({
     parameterOverrides: {
       cd1: 'offline',
     },
   });
   

3. (اختياري) بما أنّه لا يتم تطبيق القيم في parameterOverrides إلا على طلبات إعادة المحاولة ("بلا إنترنت")، يمكنك أيضًا ضبط قيمة تلقائية من النوع "online" لجميع الطلبات الأخرى. في حين أن هذا ليس ضروريًا تمامًا، إلا أنه سيجعل قراءة تقاريرك أسهل.
   
   على سبيل المثال، إذا استخدمت مقتطف تتبُّع analytics.js التلقائي لتثبيت "إحصاءات Google"، يمكنك إضافة السطر ga('set', 'dimension1', 'online') لاستخدام القيمة التلقائية 'online' للسمة المخصّصة "حالة الشبكة" لجميع الطلبات التي لم يعيد مشغّل الخدمات تشغيلها.

   <script>
     (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
     (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
     m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
     })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
   
     ga('create', 'UA-XXXXX-Y', 'auto');
   
     // Set default value of custom dimension 1 to 'online'
     ga('set', 'dimension1', 'online');
   
     ga('send', 'pageview');
   </script>
   

استخدام مقياس مخصَّص لتتبُّع طلبات الوقت المُستغرَقة في قائمة الانتظار

إذا أردت معرفة مقدار الوقت المنقضي بين وقت حدوث تفاعل بلا اتصال بالإنترنت واستعادة إمكانية الاتصال بالإنترنت وتمّت إعادة محاولة تقديم الطلب بنجاح، يمكنك تتبُّع ذلك باستخدام مقياس مخصّص وخيار الإعداد hitFilter:

1. إنشاء مقياس مخصّص جديد في "إحصاءات Google" أدخِل اسمًا مثل "وقت قائمة المحتوى التالي بلا إنترنت"، واضبط نطاقه على "ضرب"، وضبط نوع تنسيقه على "الوقت" (بالثواني).

2. استخدِم الخيار hitFilter للحصول على قيمة المَعلمة qt واقسمها على 1000 (لتحويلها إلى ثوانٍ). بعد ذلك، اضبط هذه القيمة كمعلمة باستخدام فهرس المقياس الذي تم إنشاؤه حديثًا. إذا كان هذا هو المقياس المخصّص الأول لك، سيكون اسم المَعلمة 'cm1':

   import * as googleAnalytics from 'workbox-google-analytics';
   
   googleAnalytics.initialize({
     hitFilter: (params) => {
       const queueTimeInSeconds = Math.round(params.get('qt') / 1000);
       params.set('cm1', queueTimeInSeconds);
     },
   });
   

"إحصاءات Google" - إطار عمل الاختبار

بما أنّ "إحصاءات Google" ضمن Workbox تستخدم ميزة "مزامنة الخلفية" لإعادة تشغيل الأحداث، قد يكون من الصعب اختبارها. يمكنك الاطّلاع على مزيد من المعلومات على الرابط Testing Workbox Background Sync (اختبار المزامنة في الخلفية لإطار العمل).

workbox-google-analytics.initialize(
  options?: GoogleAnalyticsInitializeOptions,
)