Calcola il tempo totale in primo piano

Questa guida spiega in dettaglio come calcolare con precisione il tempo totale trascorso da un utente a visualizzare attivamente una pagina. Le metriche tradizionali, come il tempo sulla pagina, spesso includono erroneamente il tempo trascorso con la pagina in background. Utilizzando l'API VisibilityStateEntry, puoi misurare solo il "tempo in primo piano", fornendo una metrica migliore del coinvolgimento degli utenti.

Implementazione del calcolo del tempo in primo piano

L'API PerformanceTimeline espone le modifiche dello stato di visibilità come voci di rendimento. Anziché reagire agli eventi visibilitychange e accumulare manualmente il tempo nel corso di una sessione, puoi eseguire query sull'intera cronologia di visibilità in qualsiasi momento.

OBBLIGATORIO: devi eseguire una query sulle voci di rendimento visibility-state per calcolare il tempo effettivo in primo piano.

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

Alternative e supporto dei browser

L'API VisibilityStateEntry è un'aggiunta moderna alla cronologia delle prestazioni e potrebbe non essere supportata in tutti i browser.

Poiché performance.getEntriesByType('visibility-state') restituisce un array vuoto nei browser non supportati, il rilevamento delle funzionalità è integrato nel flusso di calcolo. Prima di procedere, devi sempre verificare se vengono restituite voci.

Se l'API non è supportata, il fallback consigliato è restituire performance.now(). Rappresenta il tempo totale trascorso dalla navigazione, che funge da limite superiore ragionevole per il tempo di coinvolgimento quando la cronologia dello stato di visibilità non è disponibile.

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