ردیابی گجت

این سند نحوه استفاده از API ابزار جدید برای ردیابی ابزار Analytics را شرح می‌دهد. این API یک مدل داده بهبود یافته و ردیابی عملکرد را برای جمع‌آوری آمار گزارش‌های Analytics برای اسبابک‌های شما ارائه می‌دهد.

  1. قبل از اینکه شروع کنی
  2. ردیابی ابزارک شما
  3. روش های ردیابی
  4. ملاحظات استفاده
  5. نکات
 

قبل از اینکه شروع کنی

در گوگل آنالیتیکس، هر دامنه وب سایت یا زیر دامنه منحصر به فردی که به حساب خود اضافه می کنید در یک نمای (نمایه) جداگانه ردیابی می شود و یک شناسه دامنه جداگانه به آن اختصاص می یابد. از آنجایی که هر ابزار در زیر دامنه خود در سایت میزبان gmodules.com کار می کند، می خواهید هر ابزاری را که ایجاد می کنید در نمای (نمایه) خودش و با یک شناسه دامنه منحصر به فرد ردیابی کنید.

ساده ترین راه برای انجام این کار این است که به Google Analytics اجازه دهید یک شناسه منحصر به فرد برای شما ایجاد کند.

  1. برای شروع، وارد Google Analytics شوید یا برای یک حساب Google Analytics ثبت نام کنید.
    • کاربران جدید باید صفحه ثبت نام حساب جدید را ببینند.
    • کاربران موجود باید به صفحه تنظیمات تجزیه و تحلیل رفته و روی افزودن نمای وب سایت (نمایه) کلیک کنند. (حتما دامنه جدید را انتخاب کنید.)
  2. از هر یک از این صفحات، آدرس وب سایت معتبری را وارد کنید.
    3. از آنجایی که URL وب سایت تنها رشته ای است که نرم افزار Google Analytics آن را با شناسه دامنه شما جفت می کند، این URL می تواند هر رشته URL معتبر وب سایت باشد، چه ساختگی یا واقعی. به هیچ وجه قرار نیست کد رهگیری را روی هیچ صفحه وب نصب کنید و نیازی به دسترسی به هیچ صفحه وب سایتی نخواهید داشت.
  3. روی دکمه کلیک کنید تا به صفحه بعدی بروید.
    4. وقتی قطعه کد رهگیری ظاهر شد، شناسه دامنه منحصر به فرد را در یک صفحه اسکرچ کپی کنید. قطعه کد تولید شده به صورت خودکار حاوی این شناسه دامنه به شکل UA-123456-1 است.
  4. روی دکمه Finish کلیک کنید.
    5. شما باید نام URL وب سایت خود را در لیست view (پروفایل) ببینید. همچنین می‌توانید با کلیک کردن روی پیوند ویرایش برای آن نما (نمایه)، و سپس روی ویرایش مجدد، نام نما (نمایه) را به چیزی معنادارتر تغییر دهید.
  5. از شناسه دامنه تولید شده در کد رهگیری ابزار خود استفاده کنید.
    6. شناسه دامنه تجزیه و تحلیل به شکل زیر است:
    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. فعال کردن ویژگی

ابتدا، با وارد کردن کتابخانه Analytics با استفاده از فضای نام ویژگی، ویژگی را فعال کنید:

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

2. ایجاد یک شی ردیاب

API ردیابی Analytics به همان مدل شی گرا کد رهگیری ga.js پایبند است. بنابراین، قبل از ردیابی ابزار خود، یک شی ردیاب را نمونه برداری کنید:

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

اینجاست که با دنبال کردن مراحل بالا، شناسه دامنه تولید شده را وارد می‌کنید.

شما باید از شناسه دامنه کامل با یک عدد انتهایی استفاده کنید. در غیر این صورت تماس شی ردیابی ناموفق خواهد بود.

3. ردیابی ابزار شما

ابزار API دو روش ارائه می دهد که می توانید از آنها برای ردیابی تعامل در ابزارهای خود استفاده کنید:

  • روش URL مجازی
    • ga.reportPageview(path);

    این روش آمار گجت‌ها را به‌عنوان نمایش‌های صفحه ویژه ردیابی می‌کند و همان روشی است که در نسخه قبلی API ابزار Analytics استفاده می‌شد. با استفاده از این روش، می‌توانید هر کد ردیابی ابزار از قبل موجود را بدون تأثیر بر طرح‌بندی گزارش‌های Analytics موجود خود به‌روزرسانی کنید. همانطور که داده های گزارش صفحات وب را مشاهده می کنید، داده های گزارش را روی اسبابک های خود مشاهده می کنید.

    وقتی از روش URL مجازی برای ردیابی تعامل ابزارک استفاده می‌کنید، هر تماس به‌عنوان درخواست صفحه برای رشته‌ای که به‌عنوان پارامتر به روش ارائه می‌دهید، ثبت می‌شود. می‌توانید از این رفتار برای عبور در یک مسیر URL ساخته‌شده استفاده کنید، بنابراین می‌توانید گزارش‌های ابزارک‌ها را در رابط Google Analytics دقیقاً مانند گزارش‌های صفحه وب‌سایت مشاهده کنید. برای مثال، می‌توانید از مسیرهای جداگانه برای ردیابی نماهای ابزار و تعاملات ابزارک استفاده کنید:

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

  • روش ردیابی رویداد
    • ga.reportEvent(name, action, [[]label], [[]value]);

    این روش فقط در API ابزار جدید Analytics موجود است. با استفاده از این روش، می توانید بازدیدهای صفحه (مثلاً رندر ابزار) را به طور جداگانه از تعاملات کاربر در ابزار خود ردیابی کنید.

    توجه : در حال حاضر، ردیابی رویداد در نسخه بتا بسته است. اگر به ردیابی رویداد دسترسی ندارید از روش URL مجازی استفاده کنید.

    روش رویداد مدل متفاوتی را در اختیار شما قرار می دهد تا با ردیابی ابزارک از آن استفاده کنید. ابتدا تماس‌های رویداد جدا از تماس‌های نمایش صفحه محاسبه می‌شوند و داده‌های حاصل در قسمت جداگانه‌ای از گزارش‌های محتوای Google Analytics نمایش داده می‌شوند. بنابراین، می‌توانید نمای یک ابزارک را به‌طور مجزا از تعاملات کاربر بر روی این ابزار، بدون نیاز به تعامل کاربر، ردیابی کنید که اعداد کلی برای بازدیدهای ابزارک را افزایش دهد. ثانیا، این روش از مدل ردیابی رویداد استفاده می کند که ساختار آن به طور خاص برای تجزیه و تحلیل تعامل کاربر بر روی ابزارها طراحی شده است. در این مدل، هر دو برچسب و مقدار پارامترهای اختیاری هستند.

    با استفاده از مثال شمارنده، می‌توانیم از روش رویداد برای ردیابی عملکردهای ابزاری استفاده کنیم، و می‌توانیم نوع کنترل را که در هر دو حالت یک دکمه است، عبور دهیم.

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

    این یک مثال بسیار ساده است، اما مدل ردیابی رویداد یک ساختار بسیار انعطاف‌پذیر است که می‌توانید آن را اصلاح کنید تا از نیازهای ردیابی منحصربه‌فرد ابزار خود بهره ببرید. برای اطلاعات بیشتر، به مستندات ردیابی رویدادها مراجعه کنید.

 

روش های ردیابی

در حال حاضر، ویژگی Analytics روش های زیر را ارائه می دهد. استفاده از آنها در بالا مورد بحث قرار گرفته است.

  • ReportPageview()
    • به منظور پر کردن صحیح گزارش های محتوا، به یک رشته نیاز دارد. به طور معمول این رشته به شکل مسیری است که شما برای اهداف گزارش خود تعریف می کنید. مقدار ارسال شده به این متد در درخواست GIF از طریق متغیر utmp ارسال می شود. از این روش برای ردیابی بارهای ابزارک و تعاملات ابزارک استفاده کنید. پارامترهای 
    ga.reportPageview("/view/gadgetName");

    path String مسیر برای ارائه URL مجازی این عنصر.

  • ReportEvent()
    • برای درج صحیح داده‌های ردیابی‌شده در گزارش‌های ردیابی رویداد، به نام ابزارک و پارامتر اقدام نیاز دارد. سایر پارامترها اختیاری هستند. مقادیر ارسال شده از طریق این روش در نمای درخواست GIF متغیر utme ارسال می شود.

    مولفه های
    name String الزامی است . رشته ای که در سطح بالای گزارش های ردیابی رویداد استفاده می شود. برای مثال، اگر تعامل را در تعدادی از عناصر ابزار ردیابی می‌کردید، احتمالاً از نام خود ابزار برای این پارامتر استفاده می‌کردید، به طوری که تمام ردیابی تعامل برای این ابزار در همان بخش گزارش‌های Google Analytics جمع‌آوری می‌شود.

    action String مورد نیاز است . رشته ای برای بخش بندی بیشتر تعامل ابزارک در گزارش های ردیابی رویداد. برای اطلاعات بیشتر، به مستندات ردیابی رویدادها مراجعه کنید.

    label String اختیاری رشته ای که می توانید به عنوان بخش ثانویه برای ابزار خود استفاده کنید.

    value Int اختیاری است . عددی که می‌توانید به‌عنوان مقداری برای تعامل ابزارک ارائه کنید. این عدد برای هر بار فراخوانی روش جمع می شود.

 

ملاحظات استفاده

API ابزار Google Analytics چندین ملاحظات استفاده دارد:

  • کانتینرهای پشتیبانی شده
    • بسیاری از انواع کانتینرها با API ابزار Google Analytics پشتیبانی می‌شوند، از جمله، اما نه محدود به:
    • iGoogle
    • سندیکا را باز کنید
    • اجتماعی را باز کنید
    • ابزارک ها
  • انواع اسبابک پشتیبانی نشده
    • API ابزار Google Analytics از انواع ابزارک زیر پشتیبانی نمی‌کند :
    • اسبابک های درون خطی (type=html-inline)
    • Mapplets
    • اسبابک‌های نوع URL (type-url)
    • تبلیغات ابزارک در Google AdSense
  • ملاحظات دامنه
    • هنگامی که به ویژگی Analytics برای ابزار خود نیاز دارید، ابزار شما به <subdomain>.gmodules.com هدایت می شود، جایی که <subdomain> یک زیر دامنه تصادفی منحصر به فرد است. از این رو، تمام محتوای ابزار در زیر دامنه آن نمایش داده می شود. مثال: 3nvma227-a.gmodules.com . علاوه بر این، تمام کوکی‌های ردیابی Google Analytics روی این زیر دامنه منحصربه‌فرد تنظیم شده‌اند. به همین دلیل، نقشه‌های نقشه توسط ویژگی ردیابی Analytics پشتیبانی نمی‌شوند و شما باید به طور خاص به محتوای فلش اجازه دسترسی ویژه به ویژگی ردیابی را بدهید (به زیر مراجعه کنید).
  • ابزارک هایی که از محتوای فلش استفاده می کنند
    • ابزارک هایی که از محتوای 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 Analytics دسترسی دارید، می‌توانید از مدل داده بسیار انعطاف‌پذیر برای استفاده حداکثری از ردیابی اشیاء خود استفاده کنید. در اینجا چند نکته وجود دارد:

  • با استفاده از 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 Analytics ارسال می شود.
  • روش ردیابی رویداد
    • به دنبال متغیر utme در پارامترهای درخواست GIF بگردید. این اطلاعات باید به شکل 5(object*action*label)(value) باشد.

برای اطلاعات بیشتر در مورد عیب یابی کد رهگیری، به راهنمای عیب یابی GATC مراجعه کنید.