محاسبه کل زمان پیش‌زمینه

این راهنما نحوه محاسبه دقیق کل زمانی را که کاربر به‌طور فعال برای مشاهده صفحه صرف می‌کند شرح می‌دهد. سنجه‌های سنتی مانند زمان صرف‌شده در صفحه اغلب به‌اشتباه شامل زمانی می‌شوند که صفحه در پس‌زمینه باز بوده است. بااستفاده از VisibilityStateEntry API، می‌توانید فقط «زمان پیش‌زمینه» را اندازه‌گیری کنید که سنجه بهتری برای مشارکت کاربر ارائه می‌دهد.

درحال پیاده‌سازی محاسبه زمان پیش‌زمینه

PerformanceTimeline API تغییرات وضعیت رؤیت‌پذیری را به‌عنوان ورودی‌های عملکرد نشان می‌دهد. به‌جای واکنش نشان دادن به رویدادهای visibilitychange و جمع‌آوری دستی زمان درطول جلسه، می‌توانید در هر زمانی کل سابقه نمایان بودن را پُرسمان کنید.

اجباری: برای محاسبه زمان واقعی پیش‌زمینه، باید ورودی‌های عملکرد visibility-state را پُرسمان کنید.

/**
 * Calculates total time the page was in the visible state.
 *
 * @returns {number} Total foreground time in milliseconds.
 */
function getTotalForegroundTime() {
  // MANDATORY: Query the visibility-state entries from the performance timeline.
  const entries = performance.getEntriesByType('visibility-state');

  // Fallback: If the browser does not support VisibilityStateEntry,
  // the API will gracefully return an empty array.
  if (entries.length === 0) {
    // Return total time since navigation start as a fallback.
    return performance.now();
  }

  let totalForegroundTime = 0;

  for (let i = 0; i < entries.length; i++) {
    // Only calculate duration for periods where the state was 'visible'
    if (entries[i].name === 'visible') {
      const start = entries[i].startTime;

      // The end time is the start time of the next state change,
      // or the current time if this is the final entry.
      const end = i + 1 < entries.length
          ? entries[i + 1].startTime
          : performance.now();

      totalForegroundTime += (end - start);
    }
  }

  return totalForegroundTime;
}

پشتیبانی مرورگر و بازگشت‌ها

VisibilityStateEntry API یک افزودنی مدرن به «خط زمان عملکرد» است و ممکن است در همه مرورگرها پشتیبانی نشود.

چون performance.getEntriesByType('visibility-state') در مرورگرهای پشتیبانی‌نشده آرایه خالی برمی‌گرداند، تشخیص ویژگی در جریان محاسبه تعبیه شده است. همیشه باید قبل‌از ادامه دادن بررسی کنید که آیا ورودی‌ها برگردانده شده‌اند یا نه.

اگر API پشتیبانی نمی‌شود، بازگشت به performance.now() به‌عنوان جایگزین توصیه می‌شود. این نشان‌دهنده کل زمان از زمان ناوبری است که به‌عنوان حد بالای معقولی برای زمان تعامل در زمانی که سابقه وضعیت رؤیت‌پذیری دردسترس نیست عمل می‌کند.

const entries = performance.getEntriesByType('visibility-state');

// If the array is empty, the API is likely unsupported.
if (entries.length === 0) {
  // Fallback: Return total time since page load.
  return performance.now();
}