يوضّح هذا الدليل بالتفصيل كيفية احتساب إجمالي الوقت الذي يقضيه المستخدم في عرض صفحة معيّنة بدقة. غالبًا ما تتضمّن المقاييس التقليدية، مثل الوقت المستغرَق في الصفحة، الوقت الذي يقضيه المستخدم في الصفحة في الخلفية بشكل غير صحيح. باستخدام واجهة برمجة التطبيقات VisibilityStateEntry، يمكنك قياس "وقت الظهور على الشاشة" فقط، ما يوفّر مقياسًا أفضل لتفاعل المستخدمين.
تنفيذ عملية احتساب وقت التشغيل في المقدّمة
تعرض واجهة برمجة التطبيقات PerformanceTimeline تغييرات حالة الظهور كإدخالات للأداء. بدلاً من التفاعل مع أحداث 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 إضافة حديثة إلى Performance Timeline، وقد لا تكون متوافقة مع بعض المتصفّحات.
بما أنّ performance.getEntriesByType('visibility-state') تعرض مصفوفة فارغة في المتصفّحات غير المتوافقة، يتم تضمين ميزة رصد الميزات في مسار الاحتساب. يجب دائمًا التحقّق مما إذا تم عرض الإدخالات قبل المتابعة.
إذا لم تكن واجهة برمجة التطبيقات متوافقة، ننصحك بالرجوع إلى 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();
}