Topics API デベロッパー ガイド

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

実装ステータス

デモを試す

1 人のユーザーとして Topics をお試しいただける Topics API のデモが 2 つあります。

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

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

Topics JavaScript API には、document.browsingTopics() というメソッドが 1 つあります。これには次の 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} は、メソッド呼び出しでは現在のページがトピックの計算に含まれないことを意味します。

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

request と response ヘッダー。

この API ではクロスオリジン iframe を作成し、そこから document.browsingTopics() 呼び出しを行う必要があるため、ヘッダーを使用する方法は JavaScript API を使用する場合よりもパフォーマンスが大幅に向上します。（この呼び出しにはクロスオリジン iframe を使用する必要があります。これは、ブラウザが呼び出し元に適したトピックを返すように、API が呼び出されたコンテキストが使用されるためです）。Topics の解説では、Fetch as a request ヘッダーを使用してトピックを送信する方法を検討する必要があります。.

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

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

Topics は、HTTP ヘッダーを使用してアクセス、監視する方法は 2 つあります。

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

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

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

API 実装をデバッグする

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

ご利用のブラウザに合わせて計算されたトピックを表示します

ユーザーは、chrome://topics-internals を表示することで、現在および過去のエポック中にブラウザで確認されたトピックに関する情報を表示できます。

<ph type="x-smartling-placeholder">
</ph> [Topics State] パネルが選択されている chrome://topics-internals ページ。
chrome://topics-internals ページの [トピックの状態] パネルには、トピック ID、ランダムおよび実際のトピック割り当て、分類とモデルのバージョンが表示されます。

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

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

ホスト名から推測されたトピックを表示

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

<ph type="x-smartling-placeholder">
</ph> [分類器] パネルが選択されている chrome://topics-internals ページ。
chrome://topics-internals ページの [分類器] パネルには、選択したトピック、訪問したホスト、モデルのバージョンとパスが表示されます。

Topics API の現在の実装では、ホスト名からのみトピックを推測します。URL の他の部分からのものはありません。

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

Topics API の情報を表示する

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

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

<ph type="x-smartling-placeholder">
</ph> [Features and Parameters] パネルが選択されている 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
各クエリでデータベースから取得できるエントリの最大数 を参照してください。このクエリは、トピックの計算でエポックごとに 1 回実行されます あります。これは、ピーク時のメモリ使用量を制限することを目的としています。

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

BrowsingTopics:config_version
デフォルト値: 1
Topics API 構成パラメータをエンコードします。各バージョン番号は マッピングされます。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")

次のステップ

補足説明

フィードバックを共有