تتبع الأداة

يتناول هذا المستند كيفية استخدام واجهة برمجة التطبيقات الجديدة للأداة لتتبع الأدوات في "إحصاءات Google". توفّر واجهة برمجة التطبيقات هذه نموذج بيانات محسّنًا وتتبُّع الأداء لجمع إحصاءات تقارير "إحصاءات Google" عن أدواتك.

  1. قبل البدء
  2. تتبُّع أداتك
  3. طرق التتبّع
  4. اعتبارات الاستخدام
  5. نصائح
 

قبل البدء

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

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

  1. للبدء، سجِّل الدخول إلى Google Analytics أو اشترِك للحصول على حساب في Google Analytics.
    • من المفترض أن تظهر للمستخدمين الجدد صفحة الاشتراك في حساب جديد.
    • على المستخدمين الحاليين الانتقال إلى صفحة إعدادات "إحصاءات Google" والنقر على إضافة ملف شخصي لموقع إلكتروني. (تأكّد من اختيار نطاق جديد).
  2. من أي من هاتين الصفحتين، أدخِل أي عنوان URL صالح للموقع الإلكتروني.
    3. وبما أنّ عنوان URL للموقع الإلكتروني هو فقط سلسلة يقرنها برنامج "إحصاءات Google" برقم تعريف نطاقك، يمكن أن يكون عنوان URL هذا أي سلسلة لعنوان URL صالحة للموقع الإلكتروني، سواء كانت ملفقة أم حقيقية. لن تحتاج إلى تثبيت رمز التتبّع على أيّ صفحات ويب على الإطلاق، ولن تحتاج إلى الدخول إلى أيّ صفحات من صفحات الموقع الإلكتروني.
  3. انقر على الزر للمتابعة إلى الشاشة التالية.
    4. عند ظهور مقتطف رمز التتبّع، انسخ رقم تعريف النطاق الفريد إلى لوحة البداية. يحتوي مقتطف الرمز الذي يتم إنشاؤه تلقائيًا على رقم تعريف النطاق هذا في شكل UA-123456-1.
  4. انقر على الزر إنهاء.
    5. من المفترض أن يظهر اسم عنوان URL لموقعك الإلكتروني في قائمة الملفات الشخصية. يمكنك أيضًا تغيير اسم الملف الشخصي إلى اسم أكثر وضوحًا من خلال النقر على رابط تعديل لهذا الملف الشخصي، ثم النقر على تعديل مرة أخرى.
  5. استخدم رقم تعريف النطاق الذي تم إنشاؤه في رمز تتبّع أداتك.
    6. تكون أرقام تعريف نطاقات "إحصاءات Google" على النحو التالي:
    UA-123456-1
 

تتبع أداتك

تتضمن عملية تتبع أداتك ثلاث إضافات إلى رمز الأداة:

  1. جارٍ تفعيل الميزة.
  2. جارٍ إنشاء كائن متتبع.
  3. تتبع أداتك باستخدام إحدى الطريقتين.

يعرض نموذج رمز الأداة التالي كل إضافة من إضافات الرموز هذه، ويتم شرحها في ما يلي. يمكنك استخدام نموذج الملف هذا لبدء تشغيل أداتك الخاصة.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Analytics Test">
     <!-- Sets the feature -->
     <Require feature="com.google.gadgets.analytics" /> 
     <Require feature="setprefs" /> 
  </ModulePrefs>
  <UserPref 
      name="counter"
      datatype="hidden"
      default_value="0" />
  <Content type="html"> 
  <![CDATA[ 
      <script>
      // Track this gadget using Google Analytics.

      // Creates a tracking object and uses reportPageview method to call gadget view
      var ga = new _IG_GA("UA-00000-1");
      ga.reportPageview('/view/counterGadget');

      // Suppose, for example, you have a gadget with two counter buttons.
      // You can track interactions with those counters via Analytics.

      // Increment value of "counter" user preference
      function incrementCounter() {
         var count = prefs.getInt("counter");

         prefs.set("counter", count + 1);

         // Tracks button click as an event
         ga.reportEvent("Counter Gadget", "Increment", "Button", 0);
      }

      // Reset value of "counter" userpref to 0
      function resetCounter(){
         prefs.set("counter", 0);

         // Tracks button click as an event
         ga.reportEvent("Counter Gadget", "Reset", "Button", 0);
      }
      </script>
      <form name="counter">
      <input type=button value="Reset" name="reset" onClick="resetCounter()">
      <input type=button value="Count" name="count" onClick="incrementCounter()">
      </form>
  ]]>
  </Content>
</Module>

1- تفعيل الميزة

أولاً، فعِّل الميزة من خلال استيراد مكتبة "إحصاءات Google" باستخدام مساحة اسم الميزة:

 <Require feature="com.google.gadgets.analytics" />

2. إنشاء كائن أداة تتبع

وتتقيّد واجهة برمجة التطبيقات للتتبُّع في "إحصاءات Google" بالنموذج نفسه الذي يعتمد على عناصر واجهة المستخدم في رمز التتبّع ga.js. لذا، قبل تتبع أداتك، أنشئ مثيلاً لكائن أداة التتبع:

var ga = new _IG_GA("UA-123456-1");

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

عليك استخدام رقم تعريف النطاق الكامل مع رقم نهاية النطاق، وإلا سيتعذّر تنفيذ استدعاء عنصر التتبّع.

3- تتبع أداتك

توفر واجهة برمجة التطبيقات للأدوات طريقتين يمكنك استخدامهما لتتبع التفاعل على أدواتك:

  • طريقة عنوان URL الافتراضي
    • ga.reportPageview(path);

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

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

    ga.reportPageview('/view/counterGadget');
ga.reportPageview('/click/increment');
ga.reportPageview('/click/reset');

  • طريقة تتبع الأحداث
    • ga.reportEvent(name, action, [[]label], [[]value]);

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

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

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

    باستخدام مثال العدّادات، يمكننا استخدام طريقة الحدث لتتبع وظائف الأداة التي يتم تشغيلها، ويمكننا تمرير نوع التحكم، وهو زر في كلتا الحالتين. 

    ga.reportEvent("Counter Gadget", "Increment", "Button");
ga.reportEvent("Counter Gadget", "Reset", "Button");

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

 

طرق التتبع

في الوقت الحالي، توفّر ميزة "إحصاءات Google" الطرق التالية. وتمت مناقشة استخدامها أعلاه.

  • reportPageview()
    • يجب إدخال سلسلة من أجل تعبئة تقارير المحتوى بشكل صحيح. وتكون هذه السلسلة عادةً في شكل مسار تحدِّده لأغراض إعداد التقارير. يتم إرسال القيمة التي تم تمريرها إلى هذه الطريقة في طلب GIF من خلال المتغيّر utmp. استخدم هذه الطريقة لتتبع عمليات تحميل الأدوات والتفاعلات مع الأدوات. 
    ga.reportPageview("/view/gadgetName");
    المَعلمات
    String  path المسار الذي يجب توفيره لعنوان URL الافتراضي لهذا العنصر.

  • reportEvent()
    • يتطلب ذلك اسم الأداة ومَعلمة الإجراء حتى يتم إدراج البيانات التي يتم تتبّعها بشكل صحيح في تقارير "تتبُّع الأحداث". أما المعلمات الأخرى، فهي اختيارية. يتم إرسال القيم التي يتم تمريرها بهذه الطريقة في طلب GIF الذي يعرض متغيّر utme.

    المَعلمات
    String  name  مطلوبة.سلسلة مستخدَمة في المستوى الأعلى من تقارير تتبُّع الأحداث على سبيل المثال، إذا كنت بصدد تتبع التفاعل على عدد من عناصر الأداة، فمن المرجح أن تستخدم اسم الأداة نفسها لهذه المعلمة، بحيث يتم تجميع كل تتبع التفاعل للأداة في القسم نفسه من تقارير Google Analytics.

    String  action  مطلوبة. سلسلة لتقسيم تفاعل الأداة بشكل أكبر في تقارير تتبع الأحداث. لمزيد من المعلومات، اطّلِع على مستندات أحداث التتبُّع.

    String  label  اختيارية. سلسلة يمكنك استخدامها كمقطع ثانوي لأداتك.

    Int  value  اختيارية. الرقم الذي يمكنك تقديمه كقيمة لتفاعل الأداة. يتم تجميع هذا الرقم لكل مرة يتم فيها استدعاء الطريقة.

 

اعتبارات الاستخدام

تشمل واجهة برمجة التطبيقات لأداة "إحصاءات Google" عددًا من اعتبارات الاستخدام:

  • الحاويات المتوافقة
    • يمكن استخدام العديد من أنواع الحاويات مع واجهة برمجة التطبيقات للأداة "إحصاءات Google"، بما في ذلك على سبيل المثال لا الحصر:
    • iGoogle
    • مشاركة مفتوحة
    • فتح وسائل التواصل الاجتماعي
    • أدوات
  • أنواع الأدوات غير المتوافقة
    • لا تتوافق واجهة برمجة التطبيقات للأدوات في "إحصاءات Google" مع أنواع الأدوات التالية:
    • الأدوات المضمّنة (type=html-inline)
    • Mapplets
    • أدوات نوع عنوان URL (type-url)
    • إعلانات الأدوات على Google AdSense
  • اعتبارات النطاق
    • عندما تطلب ميزة "إحصاءات Google" لأداتك، ستعيد أداتك التوجيه إلى <subdomain>.gmodules.com، حيث يكون <subdomain> نطاقًا فرعيًا فريدًا وعشوائيًا. وبالتالي، يتم عرض كل المحتوى في الأداة ضمن هذا النطاق الفرعي. مثال: 3nvma227-a.gmodules.com بالإضافة إلى ذلك، يتم ضبط جميع ملفات تعريف ارتباط التتبّع في "إحصاءات Google" على هذا النطاق الفرعي الفريد. ولهذا السبب، لا تتوافق أدوات الخريطة مع ميزة تتبُّع "إحصاءات Google"، ويجب أن تسمح تحديدًا بالوصول الخاص إلى محتوى الفلاش إلى ميزة التتبُّع (انظر أدناه).
  • الأدوات التي تستخدم محتوى Flash
    • على الأدوات التي تستخدم محتوى Flash أن تتيح بشكل خاص إمكانية الاتصال بين عنوان URL لـ Flash وعنوان URL للأدوات من خلال ضبط المعلَمة allowScriptAccess على "دائمًا". 
    _IG_EmbedFlash("example.swf", "wrapper", {allowScriptAccess: "always"});
 

نصائح

أفضل طريقة لاستخدام طريقة عنوان URL الافتراضي

إذا لم تتمكن من الدخول إلى طريقة تتبع الأحداث لأداتك، اتبع هذه الاقتراحات لتتبع أدواتك باستخدام طريقة عنوان URL الافتراضي:

  • قسِّم حِمل الأداة بشكل مميّز.
    • يمكنك استدعاء ga.reportPageview() عند تحميل الأداة لتقديم مسار يقسّم إحصاءات تحميل/عرض الأداة بشكل منفصل عن مقاييس التفاعل مع الأداة. سيؤدي ذلك إلى إبقاء بيانات تقارير المحتوى الخاصة بالأداة في "دليل" منفصل عن التفاعلات على الأداة، حتى تتمكن من مشاهدة إجمالي المشاهدات بشكل منفصل عن عدد التفاعلات على الأداة نفسها. على سبيل المثال، يمكن استخدام مقتطف الرمز التالي في أداتك لعرض جميع الإحصاءات المرتبطة بتحميل الأداة: 
      ga.reportPageview('/view/gadgetName');
  • تقسيم أنواع التفاعلات المختلفة عن بعضها البعض.
    • يمكنك استدعاء ga.reportPageview() باستخدام مسار يُقسّم تفاعلات المستخدم المختلفة إلى شرائح. بهذه الطريقة، يمكنك الحصول على تقارير منفصلة للمحتوى الخاص بروابط الأدوات أو أزرار الأدوات أو غير ذلك من الأدوات التي قد ترغب في تتبعها للحصول على بيانات التفاعل. مثلاً:
    • ga.reportPageview('/link/click');
    • ga.reportPageview('/link/submit');

استخدام طريقة تتبع الأحداث

إذا كان لديك حق الوصول إلى ميزة "تتبُّع الأحداث" في تقارير "إحصاءات Google"، يمكنك الاستفادة من نموذج البيانات المرن للغاية لتحقيق أقصى استفادة من تتبُّع العناصر. إليك بعض النصائح:

  • يمكنك تتبع عرض الأداة أو مرات ظهورها باستخدام ga.reportPageview()، وتتبع تفاعل الأداة باستخدام ga.reportEvent().
    • سيتم عرض طرق عرض الأداة في قسم "المحتوى" لبيانات الصفحة، وسيتم عرض التفاعلات مع الأدوات في قسم "الأحداث" ضمن "تقارير المحتوى".
  • استخدِم document.referrer كمَعلمة لمعرفة مكان وضع أداتك.
    • في الأداة، عادةً ما يكون document.referrer هو عنوان URL لصفحة الحاوية، لذا يمكنك تمريره كمَعلمة تصنيف في الطريقة ga.reportEvent():
    var containerPage = document.referrer;
ga.reportEvent("Counter Gadget", "Increment", containerPage, 0);

تحديد المشاكل وحلّها

يمكنك استخدام أدوات تابعة لجهة خارجية لتحليل سلسلة طلب GIF لأداتك من أجل التحقق من إرسال البيانات إلى تقارير Google Analytics بالطريقة التي تتوقعها. بعد استضافة الأداة وتشغيلها على النحو الصحيح في الصفحة الاختبارية، حلل سلسلة طلب GIF على النحو التالي:

  • طريقة مشاهدة الصفحة على الويب
    • ابحث عن المتغيّر utmp في مَعلمات طلب GIF. المعلومات المرتبطة بهذا المتغيّر هي ما سيتم إرساله إلى تقارير "إحصاءات Google" على أنّه "مسار" الأداة.
  • طريقة تتبع الأحداث
    • ابحث عن متغيّر utme في مَعلمات طلب GIF. يجب أن تكون هذه المعلومات على النحو التالي: 5(object*action*label)(value).

لمزيد من المعلومات عن تحديد مشاكل رمز التتبّع وحلّها، اطّلِع على دليل تحديد المشاكل وحلّها في "إحصاءات Google (GATC)".