از Google Analytics 4 استفاده کنید

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

الزامات

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

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

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

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

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

اولین قدم این است که api_secret و measurement_id بدست آورید. مستندات پروتکل اندازه گیری را برای نحوه دریافت آن ها برای حساب آنالیتیکس خود دنبال کنید.

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

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

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

manifest.json:

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

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

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
    clientId = self.crypto.randomUUID();
    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 را ارسال می کند که در گزارش رویدادهای Google Analytics شما ظاهر می شود. اگر می‌خواهید رویدادهای خود را در گزارش هم‌زمان Google Analytics ببینید، باید دو پارامتر دیگر را ارائه کنید: session_id و engagement_time_msec .

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

هر دو session_id و engagement_time_msec پارامترهای پیشنهادی هنگام استفاده از پروتکل اندازه‌گیری Google Analytics هستند، زیرا برای نمایش فعالیت کاربر در گزارش‌های استاندارد مانند 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 this.getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            id: "my-button",
          },
        },
      ],
    }),
  }
);

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

ردیابی بازدیدهای صفحه در صفحات بازشو، پانل جانبی و صفحات افزونه

پروتکل اندازه گیری Google Analytics از یک رویداد page_view ویژه برای ردیابی بازدیدهای صفحه پشتیبانی می کند. از این برای ردیابی کاربرانی که از صفحات بازشو، پانل کناری یا یک صفحه افزونه در یک برگه جدید بازدید می کنند، استفاده کنید. رویداد page_view همچنین به پارامترهای page_title و page_location نیاز دارد. مثال زیر یک رویداد نمایش صفحه را در رویداد 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 در سرویس‌کار خود، می‌توانید هرگونه استثنای غیرقابل شناسایی در سرویس‌کارگر خود را به Google Analytics وارد کنید، که می‌تواند به اشکال‌زدایی مشکلاتی که کاربران شما ممکن است گزارش کنند بسیار کمک کند.

service-worker.js:

addEventListener("unhandledrejection", async (event) => {
  `${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: 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 this.getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            message: error.message,
            stack: error.stack,
          },
        },
      ],
    }),
  }
});

اکنون می توانید رویداد خطا را در گزارش های Google Analytics خود مشاهده کنید:

اشکال زدایی

Google Analytics دو ویژگی مفید برای اشکال زدایی رویدادهای تجزیه و تحلیل در برنامه افزودنی شما ارائه می دهد:

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