Calcula el tiempo total en primer plano

En esta guía, se detalla cómo calcular con precisión el tiempo total que un usuario pasa viendo una página de forma activa. Las métricas tradicionales, como el tiempo en la página, suelen incluir de forma incorrecta el tiempo que se pasa con la página en segundo plano. Si usas la API de VisibilityStateEntry, puedes medir solo el "tiempo en primer plano", lo que proporciona una mejor métrica de la participación de los usuarios.

Implementa el cálculo del tiempo en primer plano

La API de PerformanceTimeline expone los cambios de estado de visibilidad como entradas de rendimiento. En lugar de reaccionar a los eventos de visibilitychange y acumular tiempo de forma manual durante una sesión, puedes consultar todo el historial de visibilidad en cualquier momento.

OBLIGATORIO: Debes consultar las entradas de rendimiento de visibility-state para calcular el tiempo real en primer plano.

/**
 * 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;
}

Resguardos y compatibilidad con navegadores

La API de VisibilityStateEntry es una incorporación moderna a la línea de tiempo de rendimiento y es posible que no sea compatible con todos los navegadores.

Debido a que performance.getEntriesByType('visibility-state') devuelve un array vacío en los navegadores no compatibles, la detección de funciones se integra en el flujo de cálculo. Siempre debes verificar si se devuelven entradas antes de continuar.

Si la API no es compatible, la alternativa recomendada es devolver performance.now(). Esto representa el tiempo total desde la navegación, lo que sirve como un límite superior razonable para el tiempo de participación cuando el historial de estado de visibilidad no está disponible.

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();
}