Back-forward cache notRestoreReasons API

Temukan navigasi yang diblokir agar tidak menggunakan bfcache, dan alasannya.

Chris Mills

Barry Pollard

Properti notRestoredReasons, yang ditambahkan ke class PerformanceNavigationTiming, melaporkan informasi tentang apakah frame yang ada dalam dokumen diblokir untuk menggunakan bfcache pada navigasi, dan alasannya. Developer dapat menggunakan informasi ini untuk mengidentifikasi halaman yang perlu diupdate agar kompatibel dengan bfcache, sehingga meningkatkan performa situs.

Status saat ini

API notRestoredReasons telah dikirim dari Chrome 123 dan diluncurkan secara bertahap.

Konsep dan penggunaan

Browser modern menyediakan fitur pengoptimalan untuk navigasi histori yang disebut back/forward cache (bfcache). Hal ini memungkinkan pengalaman pemuatan instan saat pengguna kembali ke halaman yang telah mereka kunjungi. Halaman dapat diblokir agar tidak masuk ke bfcache atau dikeluarkan saat berada di bfcache karena berbagai alasan, beberapa di antaranya diperlukan oleh spesifikasi dan beberapa lainnya khusus untuk penerapan browser.

Sebelumnya, developer tidak dapat mengetahui alasan halaman mereka diblokir untuk menggunakan bfcache di lapangan, meskipun ada pengujian di alat dev Chrome. Untuk mengaktifkan pemantauan di lapangan, class PerformanceNavigationTiming telah diperluas untuk menyertakan properti notRestoredReasons. Metode ini menampilkan objek yang berisi informasi terkait pada frame teratas dan semua iframe yang ada dalam dokumen:

Alasan mengapa mereka diblokir untuk menggunakan bfcache.
Detail seperti frame id dan name, untuk membantu mengidentifikasi iframe dalam HTML.

Hal ini memungkinkan developer mengambil tindakan untuk membuat halaman tersebut kompatibel dengan bfcache, sehingga meningkatkan performa situs.

Contoh

Instance PerformanceNavigationTiming dapat diperoleh dari fitur seperti Performance.getEntriesByType() dan PerformanceObserver.

Misalnya, Anda dapat memanggil fungsi berikut untuk menampilkan semua objek PerformanceNavigationTiming yang ada di linimasa performa dan mencatat notRestoredReasons-nya:

function returnNRR() {
  const navEntries = performance.getEntriesByType("navigation");
  for (let i = 0; i < navEntries.length; i++) {
    console.log(`Navigation entry ${i}`);
    let navEntry = navEntries[i];
    console.log(navEntry.notRestoredReasons);
  }
}

Untuk navigasi histori, properti PerformanceNavigationTiming.notRestoredReasons menampilkan objek dengan struktur berikut, yang merepresentasikan status diblokir dari frame tingkat teratas:

{
  children: [],
  id: null,
  name: null,
  reasons: [
    {"reason", "unload-listener"}
  ],
  src: null,
  url: "https://www.example.com/page/"
}

Properti tersebut adalah sebagai berikut:

children: Array objek yang merepresentasikan status pemblokiran frame yang sama asalnya yang disematkan dalam frame level teratas. Setiap objek memiliki struktur yang sama dengan objek induk — dengan cara ini, sejumlah tingkat frame sematan dapat direpresentasikan di dalam objek secara rekursif. Jika frame tidak memiliki turunan, array akan kosong.
id: String yang merepresentasikan nilai atribut id frame (misalnya <iframe id="foo" src="...">). Jika frame tidak memiliki id, nilainya adalah null. Untuk halaman tingkat atas, nilainya adalah null.
name: String yang merepresentasikan nilai atribut name frame (misalnya <iframe name="bar" src="...">). Jika frame tidak memiliki name, nilainya akan berupa string kosong. Untuk halaman tingkat atas, nilainya adalah null.
reasons: Array string yang masing-masing mewakili alasan mengapa halaman yang dibuka diblokir agar tidak menggunakan bfcache. Ada banyak alasan berbeda mengapa pemblokiran dapat terjadi. Lihat bagian Alasan pemblokiran untuk mengetahui detail selengkapnya.
src: String yang merepresentasikan jalur ke sumber frame (misalnya <iframe src="b.html">). Jika frame tidak memiliki src, nilainya akan berupa string kosong. Untuk halaman tingkat atas, nilainya adalah null.
url: String yang merepresentasikan URL halaman/iframe yang dibuka.

Untuk objek PerformanceNavigationTiming yang tidak merepresentasikan navigasi histori, properti notRestoredReasons akan menampilkan null.

Perhatikan bahwa notRestoredReasons juga menampilkan null jika tidak ada alasan pemblokiran, sehingga null ini bukan indikator bahwa bfcache digunakan atau tidak. Untuk itu, Anda harus menggunakan properti event.persisted.

Melaporkan pemblokiran bfcache dalam frame origin yang sama

Jika halaman memiliki frame origin yang sama yang disematkan, nilai notRestoredReasons yang ditampilkan akan berisi objek di dalam properti children yang merepresentasikan status pemblokiran setiap frame yang disematkan.

Contoh:

{
  children: [
    {
      children: [],
      id: "iframe-id",
      name: "iframe-name",
      reasons: [],
      src: "./index.html",
      url: "https://www.example.com/"
    },
    {
      children: [],
      id: "iframe-id2",
      name: "iframe-name2",
      reasons: [
        {"reason": "unload-listener"}
      ],
      src: "./unload-examples.html",
      url: "https://www.example.com/unload-examples.html"
    },
  ],
  id: null,
  name: null,
  reasons: [],
  src: null,
  url:"https://www.example.com"
}

Melaporkan pemblokiran bfcache dalam frame lintas asal

Jika halaman memiliki frame lintas origin yang disematkan, kami membatasi jumlah informasi yang dibagikan tentang frame tersebut untuk menghindari kebocoran informasi lintas origin. Kami hanya menyertakan informasi yang sudah diketahui oleh halaman luar, dan apakah subpohon lintas origin memblokir bfcache atau tidak. Kami tidak menyertakan alasan pemblokiran atau informasi tentang tingkat yang lebih rendah dari subpohon (meskipun beberapa subtingkat memiliki origin yang sama).

Contoh:

{
  children: [
    {
      children: [],
      id: "iframe-id",
      name: "iframe-name",
      reasons: [],
      src: "./index.html",
      url: "https://www.example2.com/"
    }
  ],
  id: null,
  name: null,
  reasons: [
        {"reason": "masked"}
  ],
  src: null,
  url:"https://www.example.com"
}

Untuk semua iframe lintas origin, kami melaporkan null untuk nilai reasons frame, dan frame tingkat teratas akan menampilkan alasan "masked". Perhatikan bahwa "masked" juga dapat digunakan untuk alasan khusus agen pengguna sehingga tidak selalu menunjukkan masalah dalam iframe.

Lihat bagian Keamanan dan privasi dalam penjelasan untuk mengetahui detail selengkapnya tentang pertimbangan keamanan dan privasi.

Alasan pemblokiran

Seperti yang kami katakan sebelumnya, ada banyak alasan berbeda mengapa pemblokiran dapat terjadi:

Berikut adalah contoh beberapa alasan paling umum bfcache tidak dapat digunakan:

unload-listener: halaman mendaftarkan pengendali unload, yang mencegah penggunaan bfcache di browser tertentu. Lihat Menghentikan penggunaan peristiwa pelepasan untuk mengetahui informasi selengkapnya.
response-cache-control-no-store: Halaman menggunakan no-store sebagai nilai cache-control.
related-active-contents: Halaman dibuka dari halaman lain (baik menggunakan "tab duplikat") yang masih memiliki referensi ke halaman ini.

Masukan

Tim Chromium ingin mengetahui pengalaman Anda dengan API bfcache notRestoredReasons.

Beri tahu kami tentang desain API

Apakah ada sesuatu tentang API yang tidak berfungsi seperti yang Anda harapkan? Atau, apakah ada metode atau properti yang tidak ada dan perlu Anda terapkan untuk mewujudkan ide Anda? Ada pertanyaan atau komentar tentang model keamanan? Laporkan masalah spesifikasi di repo GitHub yang sesuai, atau tambahkan pendapat Anda ke masalah yang sudah ada.

Melaporkan masalah terkait penerapan

Apakah Anda menemukan bug pada penerapan Chromium? Atau apakah implementasinya berbeda dengan spesifikasi? Laporkan bug di issue tracker kami. Pastikan untuk menyertakan detail sebanyak mungkin, petunjuk sederhana untuk mereproduksi, dan tentukan komponen sebagai UI > Browser > Navigation > BFCache.

Menunjukkan dukungan untuk API

Apakah Anda berencana menggunakan bfcache notRestoredReasons API? Dukungan publik Anda membantu tim Chromium memprioritaskan fitur dan menunjukkan kepada vendor browser lain betapa pentingnya mendukung fitur tersebut.

Kirim tweet ke @ChromiumDev menggunakan hashtag #NotRestoredReasons dan beri tahu kami di mana dan bagaimana Anda menggunakannya.