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

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

Chris Mills
Barry Pollard

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

現在のステータス

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

コンセプトと使用方法

最新のブラウザには、バックフォワード キャッシュ（bfcache）と呼ばれる履歴ナビゲーションの最適化機能が用意されています。これにより、ユーザーがすでにアクセスしたページに戻ったときに、瞬時に読み込まれるようになります。ページが bfcache に入るのをブロックされたり、bfcache に入っている間に追い出されたりする理由はさまざまです。仕様で定められているものもあれば、ブラウザの実装に固有のものもあります。

以前は、フィールドでページが bfcache の使用をブロックされた理由をデベロッパーが確認する方法はありませんでしたが、Chrome デベロッパー ツールでテストを行うことはできました。フィールドでモニタリングを有効にするため、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 が使用されません。詳しくは、unload イベントの非推奨化をご覧ください。
  • response-cache-control-no-store: ページは no-store を cache-control 値として使用します。
  • related-active-contents: このページは、このページへの参照が残っている別のページから（「タブを複製」を使用して）開かれました。

フィードバック

Chromium チームは、bfcache notRestoredReasons API の使用感についてご意見をお待ちしています。

API 設計について教えてください

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

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

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

API のサポートを表示する

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

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

関連情報