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

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

Chris Mills
Barry Pollard

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

現在のステータス

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

コンセプトと使用方法

最新のブラウザには、バックフォワード キャッシュ（bfcache）と呼ばれる、履歴ナビゲーションの最適化機能が備わっています。これにより、ユーザーが以前にアクセスしたページに戻ったときに、すぐに読み込むことができます。ページが bfcache に保存されないようブロックされたり、bfcache 内にある間に強制排除されたりする理由には、仕様で必要な理由もあれば、ブラウザの実装に固有の理由もあります。

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

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

  • HTML で iframe を識別しやすくする、フレーム id や name などの詳細情報。

    これにより、デベロッパーはそれらのページに 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 にツイートし、どこでどのように使用しているかをお知らせください。

関連情報