バックフォワード キャッシュの notRestoredReasons API

bfcache の使用がブロックされたナビゲーションとその理由を確認します。

Chris Mills
Barry Pollard

PerformanceNavigationTiming クラスに追加された notRestoredReasons プロパティは、ドキュメント内のフレームがナビゲーション時に bfcache の使用をブロックされたかどうかと、その理由に関する情報を報告します。デベロッパーは、この情報を使用して、bfcache と互換性を持たせるために更新が必要なページを特定し、サイトのパフォーマンスを改善できます。

現在のステータス

notRestoredReasons API は Chrome 123 からリリースされ、段階的にロールアウトされています。

コンセプトと使用方法

最新のブラウザには、履歴ナビゲーションを最適化するための機能として、バックフォワード キャッシュ（bfcache）が用意されています。これにより、ユーザーがすでにアクセスしたページに戻ったときに、即時読み込みが可能です。ページは、さまざまな理由で bfcache へのアクセスがブロックされたり、bfcache 内から強制排除されたりすることがあります。その理由には、仕様で義務付けられているものや、ブラウザの実装に固有のものがあります。

これまで、Chrome デベロッパー ツールのテストはあったものの、デベロッパーがフィールドでページが bfcache の使用をブロックされた理由を確認する方法はありませんでした。現場でのモニタリングを有効にするため、PerformanceNavigationTiming クラスが拡張され、notRestoredReasons プロパティが追加されました。これにより、最上位のフレームとドキュメント内のすべての iframe に関する関連情報が含まれるオブジェクトが返されます。

  • bfcache の使用がブロックされた理由。

  • フレーム id や name などの詳細情報。HTML 内の iframe の特定に役立ちます。

    これにより、デベロッパーはこれらのページを bfcache と互換性のあるものにするための対策を講じ、サイトのパフォーマンスを改善できます。

例

PerformanceNavigationTiming インスタンスは、Performance.getEntriesByType() や PerformanceObserver などの特徴から取得できます。

たとえば、次の関数を呼び出して、パフォーマンス タイムラインに存在するすべての PerformanceNavigationTiming オブジェクトを返して、その notRestoredReasons をログに記録できます。

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

履歴ナビゲーションの場合、PerformanceNavigationTiming.notRestoredReasons プロパティは、最上位フレームのブロック状態を表す次の構造のオブジェクトを返します。

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

プロパティは次のとおりです。

children
トップレベル フレームに埋め込まれた同一オリジンのフレームのブロック状態を表すオブジェクトの配列。各オブジェクトは親オブジェクトと同じ構造を持ちます。これにより、任意の数のレベルの埋め込みフレームをオブジェクト内で再帰的に表現できます。フレームに子がない場合、配列は空になります。
id
フレームの id 属性値を表す文字列（<iframe id="foo" src="..."> など）。フレームに id がない場合、値は null になります。トップレベル ページの場合は null です。
name
フレームの name 属性値を表す文字列（<iframe name="bar" src="..."> など）。フレームに name がない場合、値は空の文字列になります。トップレベル ページの場合は null です。
reasons
各ページが bfcache の使用をブロックされた理由を表す文字列の配列。ブロックが発生する理由はさまざまです。詳しくは、ブロックの理由のセクションをご覧ください。
src
フレームのソースへのパスを表す文字列（例: <iframe src="b.html">）。フレームに src がない場合、値は空の文字列になります。トップレベル ページの場合は null です。
url
ナビゲートされたページまたは iframe の URL を表す文字列。

履歴ナビゲーションを表さない PerformanceNavigationTiming オブジェクトの場合、notRestoredReasons プロパティは null を返します。

notRestoredReasons は、ブロック理由がない場合にも null を返します。したがって、null が返された場合、bfcache が使用されたかどうかを示すものではありません。そのためには、event.persisted プロパティを使用する必要があります。

同一オリジンのフレームでの bfcache ブロックを報告

ページに同じオリジンのフレームが埋め込まれている場合、返される notRestoredReasons 値には、埋め込まれた各フレームのブロック状態を表す children プロパティ内のオブジェクトが含まれます。

次に例を示します。

{
  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"
}

クロスオリジン フレームでの bfcache のブロックを報告

ページにクロスオリジン フレームが埋め込まれている場合、クロスオリジン情報の漏洩を防ぐため、そのフレームに関する共有される情報の量を制限しています。外側のページがすでに知っている情報と、クロスオリジン サブツリーが bfcache をブロックしたかどうかのみが含まれます。ブロックの理由や、サブツリーの下位レベルに関する情報は含まれません（一部のサブレベルが同じオリジンの場合でも同様です）。

次に例を示します。

{
  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"
}

すべてのクロスオリジン iframe について、フレームの reasons 値に null が報告され、最上位のフレームには理由として "masked" が表示されます。"masked" はユーザー エージェント固有の理由で使用される場合もあるため、iframe の問題を示しているとは限りません。

セキュリティとプライバシーの留意事項について詳しくは、説明のセキュリティとプライバシーのセクションをご覧ください。

ブロックの理由

前述のとおり、ブロックが発生する理由はさまざまです。

bfcache を使用できない最も一般的な理由の例を次に示します。

  • unload-listener: ページが unload ハンドラを登録し、特定のブラウザで bfcache の使用を防ぎます。詳しくは、アンロード イベントの非推奨をご覧ください。
  • response-cache-control-no-store: このページでは、cache-control 値として no-store を使用しています。
  • related-active-contents: このページは、別のページ（「タブを複製」を使用）から開かれ、そのページにはこのページへの参照がまだ残っています。

フィードバック

Chromium チームは、bfcache notRestoredReasons API の使用感について、皆様のご意見をお聞かせいただきたいと考えています。

API 設計について

API が想定どおりに動作しない点はありますか？または、アイデアを実装するために必要なメソッドやプロパティが不足している場合はどうすればよいですか？セキュリティ モデルに関するご質問やご意見がございましたら、対応する GitHub リポジトリで仕様に関する問題を報告するか、既存の問題にコメントを追加します。

実装に関する問題を報告する

Chromium の実装にバグが見つかりましたか？それとも、実装が仕様と異なるのでしょうか？Issue Tracker でバグを報告してください。できるだけ詳細に、再現手順を簡単に説明してください。コンポーネントは UI > Browser > Navigation > BFCache として指定してください。Glitch は、簡単な再現手順をすばやく共有するのに適しています。

API のサポートを表示する

bfcache notRestoredReasons API を使用する予定はありますか？公開サポートは、Chromium チームが機能を優先付けするうえで役立ち、他のブラウザ ベンダーに、その機能のサポートがどれほど重要であるかを示します。

ハッシュタグ #NotRestoredReasons を使用して @ChromiumDev にツイートを送信し、どこでどのように使用しているかをお知らせください。

関連情報