Document: browsingTopics() メソッド

Experimental:これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。

非標準: この機能は標準化されていません。非標準の機能はブラウザーの対応が限られ、将来的に変更または削除される可能性があるため、本番環境での使用は推奨されません。ただし、標準の選択肢が存在しない特定のケースでは、有効な代替手段となる場合があります。

警告:この機能は現在2つのブラウザーベンダーによって反対されています。反対の詳細については下記の標準の位置づけの節を参照してください。

メモ:アプリケーションでこの機能を使用するには、登録プロセスが要求されます。

browsingTopics() はDocument インターフェイスのメソッドで、ユーザーのトップトピックを表すオブジェクトの配列で履行されるプロミスを返します。これらのトピックは、その後のフェッチリクエストで広告技術プラットフォームに返すことができます。既定では、このメソッドは呼び出し側が監視する現在のページ訪問をブラウザーに記録するので、ページのホスト名を後でトピックの計算に使用することができます。

詳しくはトピック API の使用を参照してください。

メモ:browsingTopics() は他のトピック API を有効にする機能のように HTTP ヘッダーに頼ってトピックを送信したり、トピックを監視対象としてマークしたりすることはしませんが、パフォーマンスは少し落ちます。HTTP ヘッダーを使用する機能を使用し、ヘッダーを変更できない場合にのみbrowsingTopics() で代替することをお勧めします。

構文

browsingTopics()browsingTopics(options)

引数

options省略可

以下のプロパティを持つオプションオブジェクトです。

skipObservation: 論理値。true に設定すると、browsingTopics() を呼び出したときにブラウザーがトピックを監視しないようになります。既定ではfalse で、トピックを監視します。

返値

最大 3 つのオブジェクトの配列で履行されたPromise で、現在のユーザーが選択した直近 3 世代のトピックを表します。各オブジェクトは以下のプロパティを格納します。

configVersion: 文字列で、トピックを計算するために使用するアルゴリズム（モデル部分以外）を識別します。
modelVersion: 文字列で、（ウェブページのホスト名などの）文字列をトピック ID に分類するために使用するモデルを表します。
taxonomyVersion: 文字列で、使用するタクソノミーのバージョンを表します。
topic: 数値で、ブラウザーがタクソノミーからトピックを検索するために使用することができる、トピックの ID を表します（興味のタクソノミーの例を参照）。
version: configVersion、modelVersion，taxonomyVersion のそれぞれにコロン (:) を挟んだものです。

正確なプロパティ値は、ブラウザー実装によって異なる場合があります。Chrome のオブジェクト例は以下のようになります：

{  configVersion: "chrome.1",  modelVersion: "1",  taxonomyVersion: "1",  topic: 43,  version: "chrome.1:1:1"}

例外

NotAllowedErrorDOMException

以下の場合に発生します。

トピック APIの使用がbrowsing-topics権限ポリシーによって不許可になっていた場合。
呼び出されたウェブサイトに、成功したプライバシーサンドボックスの登録プロセスにに含まれるトピック API がない場合。

例

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