Topics API デベロッパー ガイド

テストに Chrome フラグを使用する方法など、API の使用方法について学びます。

実装ステータス

デモを試す

1 人のユーザーとして Topics を試すことができる Topics API のデモが 2 つあります。

また、Topics Colab を実行して、Topics 分類モデルを試すこともできます。

JavaScript API を使用してトピックにアクセスし、観測されたとおりに記録する

Topics JavaScript API のメソッドは document.browsingTopics() のみです。これには次の 2 つの目的があります。

  • 現在のページ訪問を呼び出し元が観測したものとして記録するようブラウザに指示します。これにより、後で呼び出し元のユーザーのトピックを計算する際に、これを使用できます。
  • 呼び出し元によってモニタリングされたユーザーのトピックにアクセスします。

このメソッドは、最大 3 つのトピック（直近の 3 つのエポックのそれぞれに 1 つずつ）をランダムな順序で並べた配列に解決される Promise を返します。エポックとは期間で、Chrome の実装では 1 週間に設定されます。

document.browsingTopics() によって返される配列内の各トピック オブジェクトには、次のプロパティがあります。

  • configVersion: 現在の Topics API 構成を識別する文字列（例: chrome.2）
  • modelVersion: サイトのトピックを推測するために使用される機械学習分類器を識別する文字列（例: 4）
  • taxonomyVersion: ブラウザで使用されるトピックのセットを識別する文字列（例: 2）
  • topic: 分類内のトピックを識別する番号（例: 309）
  • version: configVersion、taxonomyVersion、modelVersion を連結する文字列（chrome.2:2:4 など）

このガイドで説明するパラメータ、および API の詳細（分類サイズ、1 週間に計算されるトピック数、呼び出しごとに返されるトピック数など）は、エコシステムからのフィードバックを取り入れて API のイテレーションを行うにつれて変更される可能性があります。

document.browsingTopics のサポートを検出する

API を使用する前に、それがブラウザでサポートされているかどうか、ドキュメントで使用可能かどうかを確認してください。

'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
 console.log('document.browsingTopics() is supported on this page') :
 console.log('document.browsingTopics() is not supported on this page');

JavaScript API を使用してトピックにアクセスする

以下は、現在のユーザーのトピックにアクセスするための API の基本的な使用例です。

try {
  // Get the array of top topics for this user.
  const topics = await document.browsingTopics();
  
  // Request an ad creative, providing topics information.
  const response = await fetch('https://ads.example/get-creative', {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
   },
   body: JSON.stringify(topics)
  })
  
  // Get the JSON from the response.
  const creative = await response.json();
  
  // Display ad.

} catch (error) {
  // Handle error.
}

状態を変更せずにトピックにアクセスする

document.browsingTopics() は、現在のユーザーの呼び出し元がモニタリングしたトピックを返します。このメソッドのデフォルトでは、呼び出し元が確認した現在のページ訪問もブラウザに記録されるため、後でトピックの計算に使用できます。Chrome 108 以降では、ページ訪問の記録をスキップするオプションの引数 {skipObservation:true} をこのメソッドに渡すことができます。

つまり、{skipObservation:true} は、メソッド呼び出しによって現在のページがトピックの計算に含まれないことを意味します。

ヘッダーを使用してトピックにアクセスし、モニタリング対象としてマークする

トピックにアクセスできます。また、リクエスト ヘッダーとレスポンス ヘッダーを使用して、ページ訪問をモニタリング対象としてマークすることもできます。ヘッダー アプローチを使用すると、JavaScript API を呼び出すよりもはるかにパフォーマンスが向上します。

トピックには、fetch() または XHR リクエストの Sec-Browsing-Topics ヘッダーからアクセスできます。

リクエストのレスポンスに Observe-Browsing-Topics: ?1 ヘッダーを設定すると、ブラウザは呼び出し元が確認した現在のページ訪問を記録し、後でトピックの計算に使用できます。

HTTP ヘッダーを使用したトピックへのアクセスと監視には、次の 2 つの方法があります。

  • fetch(): {browsingTopics: true} を fetch() リクエストのオプション パラメータに追加します。Topics ヘッダーのデモでは、これを簡略化した例を紹介しています。
  • iframe 属性: browsingtopics 属性を <iframe> 要素に追加するか、同等の JavaScript プロパティ iframe.browsingTopics = true を設定します。iframe ソースの登録可能なドメインは呼び出し元ドメインです。たとえば、<iframe src="https://example.com" browsingtopics></iframe> の場合、呼び出し元は example.com です。

ヘッダーに関するその他の注意事項:

  • リダイレクトが行われ、リダイレクト リクエストで送信されるトピックはリダイレクト URL に固有のものになります。
  • リクエスト ヘッダーは、対応するレスポンス ヘッダーがなければ呼び出し元の状態を変更しません。つまり、レスポンス ヘッダーがないと、ページ訪問は観測されたものとして記録されないため、ユーザーの次のエポックでのトピック計算には影響しません。
  • レスポンス ヘッダーは、対応するリクエストにトピック ヘッダーが含まれている場合のみ使用されます。
  • リクエストの URL には、呼び出し元ドメインとして記録された登録可能なドメインが含まれています。

API 実装をデバッグする

Topics API を有効にすると、パソコンの Chrome で chrome://topics-internals ページを利用できるようになります。ここには、現在のユーザーのトピック、ホスト名から推測されるトピック、API 実装に関する技術情報が表示されます。Google はデベロッパーからのフィードバックに基づいて、ページのデザインを繰り返し改善しています。フィードバックは bugs.chromium.org からお送りください。

お使いのブラウザ用に計算されたトピックを表示

chrome://topics-internals を表示することで、現在と過去のエポックにブラウザで観測されたトピックに関する情報を表示できます。

[Topics State] パネルが選択された chrome://topics-internals ページ。
chrome://topics-internals ページの [トピックの状態] パネルに、トピック ID、ランダムなトピックと実際のトピックの割り当て、分類とモデルのバージョンが表示されます。

このスクリーンショットでは、最近アクセスしたサイトに topics-demo-cats.glitch.me と cats-cats-cats-cats.glitch.me が含まれていることがわかります。これにより、Topics API は、現在のエポックの上位トピックの 2 つとして Pets と Cats を選択します。残りの 3 つのトピックはランダムに選択されました。これは、（トピックを監視するサイトで）5 つのトピックを提供するのに十分な閲覧履歴がないためです。

[観測されたコンテキスト ドメイン（ハッシュ化）] 列には、トピックが確認されたホスト名のハッシュ値が表示されます。

ホスト名から推定されるトピックを表示

また、1 つ以上のホスト名に対して Topics 分類モデルによって推定されたトピックを chrome://topics-internals で表示できます。

[分類器] パネルが選択された chrome://topics-internals ページ。
chrome://topics-internals ページの [分類] パネルには、選択したトピック、アクセスしたホスト、モデルのバージョンとパスが表示されます。

Topics API の現在の実装では、ホスト名のみからトピックが推測されます。URL の他の部分からは推測されません。

ホスト名のみ（プロトコルやパスなし）を使用して、chrome://topics-internals 分類器から推定されたトピックを表示します。chrome://topics-internals で [Host] フィールドに「/」を含めようとすると、エラーが表示されます。

Topics API の情報を表示する

分類のバージョンやエポック期間など、Topics API の実装と設定に関する情報は chrome://topics-internals で確認できます。これらの値は、API のデフォルト設定またはコマンドラインから正常に設定されたパラメータを反映しています。これにより、コマンドライン フラグが期待どおりに動作していることを確認できます。

この例では、time_period_per_epoch は 15 秒に設定されています（デフォルトは 7 日）。

[機能とパラメータ] パネルが選択された chrome://topics-internals ページ。
chrome://topics-internals [機能とパラメータ] パネルには、有効になっている機能、エポックあたりの時間、トピックの計算に使用するエポック数、分類バージョン、その他の設定が表示されます。

スクリーンショットに示されているパラメータは、コマンドラインから Chrome を実行するときに設定できるフラグに対応しています。たとえば、topics-fetch-demo.glitch.me のデモでは、次のフラグの使用が推奨されています。

--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

以下に、各パラメータ、デフォルト値、目的について説明します。

Chrome フラグ

BrowsingTopics
デフォルト値: 有効
Topics API を有効にするかどうか。

PrivacySandboxAdsAPIsOverride
デフォルト値: 有効
広告 API（Attribution Reporting、Protected Audience、Topics、Fenced Frames）を有効にします。

PrivacySandboxSettings4
デフォルト値: 無効
プライバシー サンドボックスの UI 設定の 4 番目のリリースを有効にします。

OverridePrivacySandboxSettingsLocalTesting
デフォルト値: 有効
有効にすると、ブラウザでプライバシー サンドボックス機能を有効にするために、基盤となる設定を有効にする必要がなくなります。

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
デフォルト値: 無効
有効にすると、ページがトピック計算の対象となるかどうかを判断する際に、IP アドレスが公開ルーティング可能かどうかのチェックがバイパスされます。

BrowsingTopics:number_of_epochs_to_expose
デフォルト値: 3
リクエスト元のコンテキストに渡すトピックの計算を開始するエポック数。ブラウザは、内部的に最大 N+1 エポックまで維持します。

BrowsingTopics:time_period_per_epoch
デフォルト値: 7d-0h-0m-0s
各エポックの期間。 デバッグでは、この時間をデフォルトの 7 日間ではなく 15 秒に設定すると便利です。

BrowsingTopics:number_of_top_topics_per_epoch
デフォルト値: 5
エポックごとに計算されるトピックの数。

BrowsingTopics:use_random_topic_probability_percent
デフォルト値: 5
エポック内の個々のトピックが、トピックの分類全体からランダムに返される確率。ランダム性は、エポックとサイトに固定されます。

BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
デフォルト値: 3
呼び出しコンテキストのトピックをフィルタするために使用される API 使用状況データ（トピックの観測数）のエポック数。

BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
デフォルト値: 1,000
上位トピックごとに保持する、コンテキスト別観測ドメインの最大数。これは、使用中のメモリの上限を設定することを目的としています。

BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
デフォルト値: 100000
API 使用コンテキストの各クエリでデータベースから取得できるエントリの最大数。このクエリは、トピックの計算時にエポックごとに 1 回実行されます。その目的は、ピーク時のメモリ使用量を制限することです。

BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
デフォルト値: 30
ページの読み込みごとに保存できる API 使用状況コンテキスト ドメインの最大数。

BrowsingTopics:config_version
デフォルト値: 1
Topics API 構成パラメータをエンコードします。各バージョン番号は、1 つの構成セットにのみマッピングする必要があります。通常、ローカルテストでは config_version を更新せずに構成パラメータを更新しても問題ありませんが、状況によってはブラウザが一貫性のない状態になり、number_of_top_topics_per_epoch の更新などでブラウザがクラッシュする可能性があります。

BrowsingTopics:taxonomy_version
デフォルト値: 1
API で使用される分類バージョン。

サイトをオプトアウトする

ページに Permissions-Policy: browsing-topics=() Permissions-Policy ヘッダーを含めると、サイトの特定のページに対するトピック計算をオプトアウトできます。これにより、そのページのすべてのユーザーについてトピックが計算されなくなります。それ以降のサイト上の他のページへのアクセスは影響を受けません。あるページで Topics API をブロックするポリシーを設定しても、他のページには影響しません。

また、Permissions-Policy ヘッダーを使用して Topics API へのサードパーティのアクセスを制御することで、ページのトピックにアクセスできるサードパーティを制御できます。ヘッダーのパラメータとして、self と、API へのアクセスを許可するドメインを使用します。たとえば、自身のオリジンと https://example.com を除くすべてのブラウジング コンテキストで Topics API の使用を完全に無効にするには、次の HTTP レスポンス ヘッダーを設定します。

Permissions-Policy: browsing-topics=(self "https://example.com")

次のステップ

補足説明

フィードバックを共有