バックフォワード キャッシュの 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 にツイートし、どこでどのように使用しているかをお知らせください。

関連情報