テストに Chrome フラグを使用する方法など、API の使用方法について学びます。
実装ステータス
- Topics API は公開ディスカッション フェーズを完了し、現在 99% のユーザーが利用できます(最大 100%)。
- Topics API に関するフィードバックを提供するには、トピックの説明機能で問題を作成するか、ウェブ広告ビジネスの改善グループのディスカッションに参加してください。説明には未解決の質問が多くあり、さらに定義が必要です。
- プライバシー サンドボックスのタイムラインには、Topics API とその他のプライバシー サンドボックスの提案の実装タイムラインが記載されています。
- Topics API: 最新情報では、Topics API と実装に対する変更と機能強化について詳しく説明します。
デモを試す
1 人のユーザーとして Topics を試すことができる Topics API のデモが 2 つあります。
- JavaScript API のデモ: topics-demo.glitch.me
- ヘッダーのデモ: topics-fetch-demo.glitch.me
また、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 を使用する場合よりもパフォーマンスが大幅に向上します。API では、クロスオリジンの iframe を作成し、そこから document.browsingTopics()
呼び出しを行う必要があるためです。(呼び出しにはクロスオリジンの iframe を使用する必要があります。これは、API が呼び出されたコンテキストに基づいて、ブラウザが呼び出し元に適したトピックを返す必要があるためです)。Topics の解説では、Fetch をリクエスト ヘッダーとして使用してトピックを送信する方法はありますか?という詳しいディスカッションが行われています。.
トピックには、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-demo-cats.glitch.me
と cats-cats-cats-cats.glitch.me
が含まれていることがわかります。これにより、Topics API は、現在のエポックの上位トピックの 2 つとして Pets
と Cats
を選択します。残りの 3 つのトピックはランダムに選択されました。これは、(トピックを監視するサイトで)5 つのトピックを提供するのに十分な閲覧履歴がないためです。
[観測されたコンテキスト ドメイン(ハッシュ化)] 列には、トピックが確認されたホスト名のハッシュ値が表示されます。
ホスト名から推定されるトピックを表示
また、1 つ以上のホスト名に対して Topics 分類モデルによって推定されたトピックを 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-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")
次のステップ
- 詳しくは、トピックとその仕組みについての記事をご覧ください。
- デモをお試しください。
補足説明
フィードバックを共有
- GitHub: Topics API の説明を読み、API リポジトリで問題の投稿とディスカッションのフォローを行います。
- W3C: 「ウェブ広告ビジネスの改善」グループで、業界のユースケースについてご確認ください。
- お知らせ: メーリング リストへの参加や表示を行います。
- プライバシー サンドボックスのデベロッパー サポート: プライバシー サンドボックス デベロッパー サポート リポジトリで質問したり、ディスカッションに参加したりできます。
- Chromium: 現在 Chrome でテストできる実装について質問がある場合は、Chromium のバグを報告してください。