از گوگل آنالیتیکس استفاده کنید

این آموزش نحوه‌ی پیگیری میزان استفاده از افزونه‌ی خود را با استفاده از گوگل آنالیتیکس نشان می‌دهد. می‌توانید یک نمونه‌ی گوگل آنالیتیکسِ در حال کار را در گیت‌هاب پیدا کنید، جایی که google-analytics.js شامل تمام کدهای مربوط به گوگل آنالیتیکس است.

الزامات

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

همچنین باید یک حساب گوگل آنالیتیکس برای ردیابی افزونه خود تنظیم کنید. توجه داشته باشید که هنگام تنظیم حساب، می‌توانید از هر مقداری در فیلد URL وب‌سایت استفاده کنید، زیرا افزونه شما URL مخصوص به خود را نخواهد داشت.

از پروتکل اندازه‌گیری گوگل آنالیتیکس استفاده کنید

از زمان Manifest V3، افزونه‌های کروم اجازه اجرای کد میزبانی‌شده از راه دور را ندارند . این بدان معناست که شما باید از پروتکل اندازه‌گیری گوگل آنالیتیکس برای ردیابی رویدادهای افزونه استفاده کنید. پروتکل اندازه‌گیری به شما امکان می‌دهد رویدادها را مستقیماً با درخواست‌های HTTP به سرورهای گوگل آنالیتیکس ارسال کنید. یکی از مزایای این رویکرد این است که به شما امکان می‌دهد رویدادهای تحلیلی را از هر جایی در افزونه خود، از جمله سرویس ورکر خود، ارسال کنید.

اعتبارنامه‌های API را تنظیم کنید

برای ارسال رویدادها به گوگل آنالیتیکس، به یک api_secret و یک measurement_id نیاز دارید. برای کسب اطلاعات بیشتر در مورد مشخصات کلی پروتکل اندازه‌گیری ، مستندات پروتکل اندازه‌گیری را دنبال کنید.

مرحله ۱: ایجاد یک جریان داده وب

از آنجا که افزونه‌های کروم به عنوان محیط‌های وب ردیابی می‌شوند، باید یک جریان داده وب را در ویژگی گوگل آنالیتیکس خود تنظیم کنید:

1. به صفحه مدیریت گوگل آنالیتیکس بروید.
2. در ستون «ویژگی‌ها» ، روی «جمع‌آوری و اصلاح داده‌ها» کلیک کنید، سپس «جریان‌های داده» را انتخاب کنید.
3. روی افزودن جریان کلیک کنید، سپس روی وب کلیک کنید.
4. هر آدرس اینترنتی (URL) دلخواهی را در فیلد آدرس وب‌سایت وارد کنید (برای مثال، https://extension یا آدرس اینترنتی فروشگاه وب کروم افزونه شما).
5. یک نام برای استریم وارد کنید (برای مثال، My Chrome Extension ).
6. روی ایجاد جریان کلیک کنید.

پس از ایجاد، شناسه اندازه‌گیری شما (که به شکل G-XXXXXXXXXX است) در بالای صفحه جزئیات پخش نمایش داده می‌شود.

مرحله ۲: ایجاد یک راز API پروتکل اندازه‌گیری

برای تولید api_secret مورد نیاز برای پروتکل اندازه‌گیری، به تنظیمات جریان داده وب که اخیراً ایجاد کرده‌اید، بروید:

1. به بخش مدیریت > جمع‌آوری و اصلاح داده‌ها > جریان‌های داده بروید و جریان داده وب خود را انتخاب کنید.

2. در بخش رویدادها ، روی اسرار API پروتکل اندازه‌گیری کلیک کنید.

3. در صورت درخواست، شرایط پروتکل اندازه‌گیری را بخوانید و بپذیرید.

4. روی ایجاد کلیک کنید.

5. یک نام مستعار برای راز خود وارد کنید (برای مثال، Chrome Extension Secret ) و برای ایجاد راز، روی ایجاد کلیک کنید.

6. مقدار Secret تولید شده را کپی کنید.

یک client_id ایجاد کنید

مرحله دوم، ایجاد یک شناسه منحصر به فرد برای یک دستگاه/کاربر خاص، یعنی client_id ، است. این شناسه باید تا زمانی که افزونه روی مرورگر کاربر نصب شده است، ثابت بماند. این شناسه می‌تواند یک رشته دلخواه باشد، اما باید برای کلاینت منحصر به فرد باشد. client_id را در chrome.storage.local ذخیره کنید تا مطمئن شوید که تا زمانی که افزونه نصب شده است، ثابت می‌ماند.

استفاده از chrome.storage.local نیاز به مجوز storage در فایل مانیفست شما دارد:

مانیفست.json:

{
  …
  "permissions": ["storage"],
  …
}

سپس می‌توانید chrome.storage.local برای ذخیره client_id استفاده کنید:

function getRandomId() {
  const digits = '123456789'.split('');
  let result = '';

  for (let i = 0; i < 10; i++) {
    result += digits[Math.floor(Math.random() * 9)];
  }

  return result;
}

async function getOrCreateClientId() {
  const result = await chrome.storage.local.get('clientId');
  let clientId = result.clientId;
  if (!clientId) {
    // Generate a unique client ID, the actual value is not relevant. We use
    // the <number>.<number> format since this is typical for GA client IDs.
    const unixTimestampSeconds = Math.floor(new Date().getTime() / 1000);
    clientId = `${getRandomId()}.${unixTimestampSeconds}`;
    await chrome.storage.local.set({clientId});
  }
  return clientId;
}

ارسال یک رویداد تحلیلی

با استفاده از اعتبارنامه‌های API و client_id ، می‌توانید با استفاده از یک درخواست fetch یک رویداد را به Google Analytics ارسال کنید:

const GA_ENDPOINT = 'https://www.google-analytics.com/mp/collect';
const MEASUREMENT_ID = `G-...`;
const API_SECRET = `...`;

fetch(
  `${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: 'POST',
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          name: 'button_clicked',
          params: {
            id: 'my-button',
          },
        },
      ],
    }),
  }
);

این یک رویداد button_clicked ارسال می‌کند که در گزارش رویدادهای گوگل آنالیتیکس شما ظاهر می‌شود. اگر می‌خواهید رویدادهای خود را در گزارش لحظه‌ای گوگل آنالیتیکس مشاهده کنید، باید دو پارامتر اضافی ارائه دهید: session_id و engagement_time_msec .

از پارامترهای توصیه شده session_id و engagement_time_msec استفاده کنید

هر دو پارامتر session_id و engagement_time_msec هنگام استفاده از پروتکل اندازه‌گیری گوگل آنالیتیکس توصیه می‌شوند، زیرا برای نمایش فعالیت کاربر در گزارش‌های استاندارد مانند Realtime مورد نیاز هستند.

session_id دوره زمانی را توصیف می‌کند که در طی آن کاربر به طور مداوم با افزونه شما در تعامل است. به طور پیش‌فرض، یک جلسه پس از 30 دقیقه عدم فعالیت کاربر پایان می‌یابد. هیچ محدودیتی برای مدت زمان یک جلسه وجود ندارد.

در افزونه‌های کروم، برخلاف وب‌سایت‌های معمولی، مفهوم مشخصی از نشست کاربر وجود ندارد. از این رو، شما باید در افزونه خود تعریف کنید که نشست کاربر به چه معناست. برای مثال، هر تعامل جدید کاربر ممکن است یک نشست جدید باشد. در این صورت، می‌توانید با هر رویداد، مثلاً با استفاده از یک مهر زمانی، یک شناسه نشست جدید ایجاد کنید.

مثال زیر رویکردی را نشان می‌دهد که پس از 30 دقیقه عدم گزارش رویداد، یک نشست جدید را به پایان می‌رساند (این زمان می‌تواند برای تطابق بهتر با رفتار کاربر افزونه شما سفارشی‌سازی شود). این مثال از chrome.storage.session برای ذخیره نشست فعال در حین اجرای مرورگر استفاده می‌کند. همراه با نشست، آخرین باری که یک رویداد اجرا شده است را ذخیره می‌کنیم. به این ترتیب می‌توانیم تشخیص دهیم که آیا نشست فعال منقضی شده است یا خیر:

const SESSION_EXPIRATION_IN_MIN = 30;

async function getOrCreateSessionId() {
  // Store session in memory storage
  let {sessionData} = await chrome.storage.session.get('sessionData');
  // Check if session exists and is still valid
  const currentTimeInMs = Date.now();
  if (sessionData && sessionData.timestamp) {
    // Calculate how long ago the session was last updated
    const durationInMin = (currentTimeInMs - sessionData.timestamp) / 60000;
    // Check if last update lays past the session expiration threshold
    if (durationInMin > SESSION_EXPIRATION_IN_MIN) {
      // Delete old session id to start a new session
      sessionData = null;
    } else {
      // Update timestamp to keep session alive
      sessionData.timestamp = currentTimeInMs;
      await chrome.storage.session.set({sessionData});
    }
  }
  if (!sessionData) {
    // Create and store a new session
    sessionData = {
      session_id: currentTimeInMs.toString(),
      timestamp: currentTimeInMs.toString(),
    };
    await chrome.storage.session.set({sessionData});
  }
  return sessionData.session_id;
}

مثال زیر session_id و engagement_time_msec را به درخواست رویداد کلیک دکمه قبلی اضافه می‌کند. برای engagement_time_msec ، بهتر است زمان سپری شده از آخرین رویداد را ارائه دهید. با این حال، اگر این امکان پذیر نیست، می‌توانید مقدار پیش‌فرض 100 ms را ارائه دهید.

const GA_ENDPOINT = "https://www.google-analytics.com/mp/collect";
const MEASUREMENT_ID = `G-...`;
const API_SECRET = `...`;
const DEFAULT_ENGAGEMENT_TIME_IN_MSEC = 100;

fetch(
`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          name: "button_clicked",
          params: {
            session_id: await getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            id: "my-button",
          },
        },
      ],
    }),
  }
);

این رویداد به صورت زیر در گزارش Google Analytics Realtime نمایش داده خواهد شد.

مشاهده صفحات در صفحات پاپ‌آپ، پنل کناری و افزونه‌ها را پیگیری کنید

پروتکل اندازه‌گیری گوگل آنالیتیکس از یک رویداد ویژه page_view برای ردیابی بازدید صفحات پشتیبانی می‌کند. از این رویداد برای ردیابی کاربرانی که از کادرهای محاوره‌ای، صفحات منو، پنل‌های جانبی و صفحات افزونه در یک تب جدید بازدید می‌کنند، استفاده کنید. رویداد page_view همچنین به پارامترهای page_title و page_location نیاز دارد. مثال زیر یک رویداد page view را در رویداد load سند برای یک منوی افزونه اجرا می‌کند:

فایل popup.js:

window.addEventListener("load", async () => {
  fetch(`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          name: "page_view",
          params: {
            session_id: await getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            page_title: document.title,
            page_location: document.location.href
          },
        },
      ],
    }),
  });
});

اسکریپت popup.js باید در فایل html پاپ‌آپ شما وارد شود و قبل از اجرای هر اسکریپت دیگری اجرا شود:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Analytics Demo Popup</title>
    <script src="./popup.js" type="module"></script>
  </head>
  <body>
    <h1>Analytics Demo</h1>
  </body>
</html>

نمای بازشو مانند هر نمای صفحه دیگر در گزارش Google Analytics Realtime نمایش داده خواهد شد:

رویدادهای تحلیلی را در سرویس ورکرها پیگیری کنید

استفاده از پروتکل اندازه‌گیری گوگل آنالیتیکس، ردیابی رویدادهای تحلیلی در ورکرهای سرویس توسعه را ممکن می‌سازد. به عنوان مثال، با گوش دادن به unhandledrejection event در ورکرهای سرویس خود، می‌توانید هرگونه استثنائات ثبت نشده در ورکرهای سرویس خود را در گوگل آنالیتیکس ثبت کنید، که می‌تواند به اشکال‌زدایی مشکلاتی که کاربران ممکن است گزارش دهند، کمک زیادی کند.

سرویس-ورکر.js:

addEventListener("unhandledrejection", async (event) => {
  fetch(`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          // Note: 'error' is a reserved event name and cannot be used
          // see https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference?client_type=gtag#reserved_names
          name: "extension_error",
          params: {
            session_id: await getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            message: event.reason.message,
            stack: event.reason.stack,
          },
        },
      ],
    }),
  });
});

اکنون می‌توانید رویداد خطا را در گزارش‌های گوگل آنالیتیکس خود مشاهده کنید:

اشکال‌زدایی

گوگل آنالیتیکس دو ویژگی مفید برای اشکال‌زدایی رویدادهای تحلیلی در افزونه شما ارائه می‌دهد:

1. یک نقطه پایانی اشکال‌زدایی ویژه https://www.google-analytics.com**/debug**/mp/collect که هرگونه خطایی را در تعاریف رویداد شما گزارش می‌دهد.
2. گزارش لحظه‌ای گوگل آنالیتیکس که رویدادها را به محض ورود نمایش می‌دهد.