Calculer la durée totale d'utilisation au premier plan

Ce guide explique comment calculer avec précision la durée totale pendant laquelle un utilisateur consulte activement une page. Les métriques traditionnelles, comme le temps passé sur la page, incluent souvent à tort le temps passé avec la page en arrière-plan. En utilisant l'API VisibilityStateEntry, vous ne pouvez mesurer que le "temps au premier plan", ce qui fournit une meilleure métrique de l'engagement utilisateur.

Implémenter le calcul du temps d'utilisation au premier plan

L'API PerformanceTimeline expose les changements d'état de visibilité en tant qu'entrées de performances. Plutôt que de réagir aux événements visibilitychange et d'accumuler manuellement du temps tout au long d'une session, vous pouvez interroger l'historique complet de visibilité à tout moment.

OBLIGATOIRE : Vous devez interroger les entrées de performances visibility-state pour calculer la durée réelle au premier plan.

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

Créations de remplacement et navigateurs compatibles

L'API VisibilityStateEntry est un ajout récent à la chronologie des performances et n'est peut-être pas compatible avec tous les navigateurs.

Étant donné que performance.getEntriesByType('visibility-state') renvoie un tableau vide dans les navigateurs non compatibles, la détection des fonctionnalités est intégrée au flux de calcul. Vous devez toujours vérifier si des entrées sont renvoyées avant de continuer.

Si l'API n'est pas compatible, la solution de remplacement recommandée consiste à renvoyer performance.now(). Il s'agit de la durée totale écoulée depuis la navigation, qui sert de limite supérieure raisonnable pour le temps d'engagement lorsque l'historique de l'état de visibilité n'est pas 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();
}