このページは Cloud Translation API によって翻訳されました。

Topics API 統合ガイド

Topics API を使用して特定の広告テクノロジーのユースケースに対応する方法について説明します。

始める前に

最初のステップは、Topics API とサービスについてよく理解することです。

デベロッパードキュメントを確認します。
1. まず概要に目を通し、Topics API とその機能を理解しましょう。
2. Topics デモのチュートリアル（動画）
3. Topics ヘッダーと JavaScript API のデモをお試しください。
4. デモをフォークし（どちらもコードへのリンクを提供します）、自分のサイトから実行します。
5. 詳細については、API の説明をご覧ください。
Topics API の実装ステータスとタイムラインを確認します。
Cookie のない未来における広告の関連性のサポートにおける API の役割を理解する。
API のステータス変更について通知を受け取るには、デベロッパー向けメーリングリストに参加してください。また、Topics の最新情報もあわせてご確認ください。
Topics API に関する最新情報をご確認ください。
GitHub の問題または W3C の通話を通じて会話に参加します。
不明な用語については、プライバシーサンドボックスの用語集をご覧ください。
Chrome フラグなど Chrome のコンセプトについて詳しくは、goo.gle/cc の短い動画や記事をご覧ください。

ローカルでのビルドとテスト

このセクションでは、個人デベロッパーとして Topics API を試す方法について説明します。

ローカルでのテストとデプロイ（推定所要時間: 約 2 日）
1. コマンドラインから機能フラグを使用して、ローカルブラウザで API を有効にします。ヘッダーと JavaScript API のデモをテストして、Topics の動作を確認します（チュートリアル動画）。
2. Topics Colab を実行し、Topics ML モデルを使用したトピック推論をテストします。

ブラウザで Topics を有効にする

ローカルテスト用に独自の Chrome インスタンスで Topics API を有効にするには、次の 2 つの方法があります。

chrome://flags/#privacy-sandbox-ads-apis を開き、Privacy Sandbox API を有効にします。
（推奨）必要に応じて、Chromium フラグを使用してコマンドラインから Chrome を実行します。Topics API 固有のパラメータを使用して設定します。

chrome://flags/#privacy-sandbox-ads-apis でプライバシーサンドボックスの API を有効にします。 — プライバシーサンドボックス API を有効にする。

コマンドラインから Chrome を実行すると、Topics 機能をきめ細かく管理できます。たとえば、Topics のエポック（API がユーザーの興味 / 関心を計算するために使用する期間）を設定して、ニーズに応じて API の動作を構成できます。

chrome://flags/#privacy-sandbox-ads-apis が有効になっている場合は、コマンドラインのエポック設定がオーバーライドされ、デフォルト値（現時点では 1 週間）に戻ります。

Topics API の仕組みをプレビューする

chrome://topics-internals ツールを使用すると、Topics API の仕組みをローカルで可視化できます。

chrome://topics-internals で Topics API の内部をご覧ください。 — chrome://topics-internals ツールの [トピックの状態] タブ。

Topics API Internals ツールを使用して、アクセスしたサイトに基づいて分類器をローカルでテストします。

このツールを使用すると、以下を確認できます。

Topics State: 現在のユーザーに関して観測されたトピックを表示します。
分類器: ホスト名から推定されるトピックをプレビューします。
機能とパラメータ: API のパラメータ値を表示して、機能フラグが意図したとおりに動作していることを確認します。

Internals ツールを使用してトピックをデバッグする方法を学習する。

API がトピックを返す仕組み

Chrome でエポック数（1 週間）の上位 5 つのトピックを作成するのに十分な数のトピックが観察されていない場合、Topics API はランダムなトピックを追加して上位 5 つのトピックを完成させます。[Real or Random] という見出しが付いた「Topics Internals」列は、その特定のトピックが実際の観察に基づくものか、上位 5 つを完成させるための追加のランダムな「パディング」に基づくものかを示します。このメカニズムについて詳しくは、説明をご覧ください。

エポックごとに選ばれるトピックは、その期間にユーザーが最も関心を持っている 5 つのトピックからランダムに抽出されます。エポック中に十分な数のトピックが確認されなかった場合は、追加のトピックがランダムに選択され、合計 5 つになります。ランダムに選択されたこれらのトピックはフィルタの対象となります。

プライバシーをさらに強化し、すべてのトピックを表現できるようにするために、エポックで選択されるトピックが、観測されたトピックから選択されるのではなく、すべてのトピックからランダムに選択される確率は 5% です。観測されたトピックが少なすぎる場合と同様に、これらの無作為に選択されたトピックはフィルタの対象になりません。

トピックが選択される仕組みについて詳しくは、トピックの分類をご覧ください。

主な推奨事項

フラグを使用して新しいプロセスを開始する前に、すべての Chrome プロセスを終了（および停止）してください。
ローカル環境でテストする場合は、chrome://flags/#privacy-sandbox-ads-apis を無効にする必要があります。これは、コマンドラインの設定がオーバーライドされ、デフォルト値に戻されるためです。
デバッグページを使用して、Topics のローカルでの動作を把握します。
不明な点がある場合は、GitHub の事象の解説をご確認ください。
API が期待どおりに機能しない場合は、トラブルシューティングのヒントをお試しください。

MVP のデプロイを計画する

Topics API を使用すると、ユーザーがアクセスしたサイトを追跡したり、ナビゲーション履歴を公開したりすることなく、ユーザーに関して観測された関心のあるトピックにアクセスできます。

Topics API の呼び出し元は、document.browsingTopics() JavaScript メソッドを呼び出すか、HTTP リクエストヘッダーを使用してトピックを監視してアクセスするエンティティです。この例では、ユーザーのコードと、その呼び出し元の eTLD+1 が呼び出し元です。Topics API を呼び出すと、ユーザーがウェブサイトにアクセスしたときに、関心のあるトピックをモニタリングするようにユーザーのブラウザに指示します。このアクセスは次のエポックのトピック計算で考慮されます。

Topics API は、呼び出しコンテキストの呼び出し元または eTLD+1 ごとに結果をフィルタリングするように設計されています。つまり、iframe の生成元（JavaScript API を使用している場合）または取得リクエストの URL（ヘッダーを使用している場合）が呼び出し元と見なされ、その呼び出し元に応じてトピックが計算されます。

次の図は、この方法を示しています。

API を使用するサイトにユーザーがアクセスするときに Topics API が実行するステップ。 — API がトピックを監視してアクセスする方法。

次の図:

ユーザーが Chrome を開き、広告テクノロジーの iframe（ソース: iframe.adtech.example）またはフェッチ呼び出しを渡すヘッダーを含む複数のウェブサイト（customerA.example、customerB.example.br など）にアクセスします。
- Chrome では、このユーザーの興味 / 関心のあるトピックが記録されます。
Topics API で関心のあるトピックが観測された状態で 7 日間移動した後、同じデバイスの同じユーザーがターゲットウェブサイト（publisher-e.example）にアクセスします。Topics API はトピックのリストを返します。この例では、ユーザーの前週のモニタリングから計算された 1 つのトピックが返されます。
- ステップ 1 で adtech.example が確認したサイトを訪問したユーザーのブラウザのみが、ステップ 2 でトピックの結果を返します（このモニタリングフィルタリングと呼びます。以前に見たことのないユーザーのトピックは表示されません）。
このリスト（現時点では 1 つのトピックのみ）を使用して、バックエンド API（ads.adtech.example/topics-backend）を呼び出して、コンテキストデータセットの一部としてトピックデータを使用できます。
ユースケースに応じて、過去数週間にユーザーが確認した関心のあるトピックにアクセスすることで、このユーザーのパーソナライズされたエクスペリエンスを創出できます。

Topics API を呼び出す

ユーザーのトピックを監視してアクセスする方法は 2 つあります。誰かと話す必要がある場合などに

iframe 内からの JavaScript API:
- ターゲットウェブサイト（パブリッシャーのウェブサイト）に、document.browsingTopics() を使用して Topics API を呼び出す JavaScript コードを含む iframe を追加します。
ヘッダーオプション:
- 取得（推奨）または XHR（推奨されません。また、完了したオリジントライアル中のみ使用可能でした）:
  - トピックには、広告テクノロジーバックエンドへのリクエストの Sec-Browsing-Topics ヘッダーからアクセスできます。これは最もパフォーマンスの高いオプションです（特定の 1 人のユーザーのトピックをモニタリングするためのレイテンシが低い）。
- browsingtopics 属性を持つ iframe タグを使用する場合:
  - browsingtopics 属性を使用して iframe を追加すると、Chrome は iframe のリクエストの Sec-Browsing-Topics ヘッダーにトピック（iframe の eTLD+1 で観測）を含めます。

JavaScript と iframe を使用して実装する

Topics の JavaScript API デモまたはヘッダーのデモをフォークし、そのいずれかをコードの出発点として使用することをおすすめします。

HTML に <iframe> 要素を含めるか、JavaScript を使用して iframe を動的に追加します。iframe を動的に作成する 1 つの方法は、次の JavaScript を使用することです。

const iframe = document.createElement('iframe');
iframe.setAttribute('src', 'https://...');
document.body.appendChild(iframe);

機能検出を通じて、Topics 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');

その iframe 内から Topics API を呼び出します。

const topics = await document.browsingTopics();

このユーザーが過去 3 週間に確認したトピックのリストを受け取ります。このリストは空にすることも、過去 3 週間までのトピックを 1 つ、2 つ、または 3 つ含めることもできます。

API から返される内容の例を次に示します。

[{'configVersion': String, 
  'modelVersion': String, 
  'taxonomyVersion': String, 
  'topic': Number, 
  'version': String}]

configVersion: 現在の構成を識別する文字列。
modelVersion: トピックの推定に使用される機械学習分類器を識別する文字列。
taxonomyVersion: ブラウザで現在使用されているトピックのセットを識別する文字列。
topic: 分類内でトピックを識別する番号。
version: configVersion と modelVersion を組み合わせた文字列。

この実装に関する詳細をご確認ください。

HTTP ヘッダーを使用して実装する

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

トピックの設定と取得を行うリクエストヘッダーとレスポンスヘッダー。 — iframe と `fetch()` のヘッダー

リクエストヘッダーで指定されたトピックをモニタリング対象としてマークするには、リクエストのレスポンスに Observe-Browsing-Topics: ?1 ヘッダーを設定します。ブラウザはこれらのトピックを使用して、ユーザーが関心を持つトピックを計算します。

API が 1 つ以上のトピックを返す場合、そのトピックが確認された eTLD+1 へのフェッチリクエストには、次のような Sec-Browsing-Topics ヘッダーが含まれます。

(325);v=chrome.1:1:1, ();p=P000000000

API からトピックが返されない場合、ヘッダーは次のようになります。

();p=P0000000000000000000000000000000

Sec-Browsing-Topics ヘッダー値はパディングされます。これにより、ヘッダーの長さに基づいて呼び出し元をスコープとするトピック数を攻撃者が学習するリスクを軽減できます。

`fetch()` を使用して実装する

ニュースメディアのページで、取得リクエストのコードを追加します。必ず {browsingTopics: true} を含めます。

fetch('<topics_caller_eTLD+1>', {browsingTopics: true})
    .then((response) => {
        // Process the response
 })

API をサポートしているブラウザでは、fetch() リクエストに、リクエスト URL のホスト名で観測されたトピックをリストする Sec-Browsing-Topics ヘッダーが含まれます。

iframe を使用して実装する

fetch() リクエストと同様に、iframe で browsingtopics 属性を使用すると Sec-Browsing-Topics ヘッダーが送信されます。

<iframe src="<topics_caller_eTLD+1>" browsingtopics></iframe>

この場合、フェッチ呼び出しと同様に、が呼び出し元になります。

サーバーサイド（すべてのケースで同一）

Sec-Browsing-Topics リクエストヘッダーのトピックをブラウザによって「観測」とマークすると同時に、ユーザーの次回のエポックトップトピック計算に現在のページ訪問を含めるには、サーバーのレスポンスに Observe-Browsing-Topics: ?1 を含める必要があります。

setHeader() を使用した JavaScript の例を次に示します。

res.setHeader('Observe-Browsing-Topics', '?1');

Topics バックエンドの実装

Topics のバックエンドの追加は任意です。どちらを選択するかは、デバイス上の（ブラウザで）計算されたトピックをどこでどのように使用するかによって異なります。

// Use the language/framework/stack of your preference
function processTopicsBackendAPI(topics, user, domain, caller) {
  // Validate inputs
  // If the list is not empty, continue
  // Use topics as an additional contextual signal
}

トピックをコンテキストデータとして使用する

トピックのデータは、URL やキーワード、タグなどの他のシグナルと並行して、オーディエンスに関する追加のシグナルとして考慮できます。

サードパーティ Cookie のない環境で広告の関連性を最大限に高めるで説明したように、Topics を活用して関連性の高い広告を配信するには、複数の方法があります。たとえば、トピックを使用してオーディエンスを構築する場合や、Topics をシグナルの 1 つとして使用して機械学習モデルをトレーニングし、オーディエンスの新たな興味 / 関心を推測したり入札ロジックを最適化したりする提案もあります。

ビルドとデプロイ

まだスケーリングしていない本番環境のユーザーを観察してトピックを収集します（推定所要時間: 約 1 週間）。
1. 選択肢を理解する（iframe と JavaScript または HTTP ヘッダー）
2. iframe のドメインを定義します。
3. デモアプリをコード参照として使用して JavaScript コードをビルドするか、ヘッダーオプションを実装します。
4. 制御された環境（一部の本番環境サイト）に Topics をデプロイします。
5. いくつかのターゲットサイトに Topics の実装を追加します（現時点では 5 つまで）。
6. 機能のテストと検証。
[省略可] Topics データをコンテキストシグナル（URL、タグなど）として使用する（推定所要時間: 約 3 日）。
1. トピックのリストを受け取ったら、他のコンテキストシグナルとともにバックエンドに送信できます。

一部のターゲットサイトにデプロイ

コードが完成したので、最初のテストのためにそのコードをいくつかのターゲットサイトに追加し、API がこの制御された環境で安定して動作することを確認します。

次のようなウェブサイトをターゲットに設定することをおすすめします。

1 か月の訪問回数が少ない（1 か月あたり約 100 万人未満）: まず、少数の利用者を対象に API をデプロイすることから始めます。
お客様が所有し管理: 必要に応じて、複雑な承認を行うことなく、すぐに実装を無効にできます。
ビジネスクリティカルではない: この実装はユーザーエクスペリエンスを阻害する可能性があるため、リスクの低いターゲットサイトから開始します。
サイトの数が 5 つ以下: 今のところ、それほど多くのトラフィックや露出は必要ないでしょう。
さまざまなテーマを用意する: カテゴリごとに異なるウェブサイトを選びます（例: スポーツに関するウェブサイト、ニュースに関するウェブサイト、フードとドリンク関連のウェブサイトなど）。Chrome の内部トピックツールを使用して、ドメインと、Topics 機械学習分類器によるドメイン分類方法を検証できます。詳しくは、Topics API デベロッパーガイドのデバッグをご覧ください。

機能をテストして確認する

この限られた環境で Topics API を呼び出すと、次のようになります。

このサイトと呼び出し元について過去 7 日間にこのデバイスが初めて呼び出された場合は、トピック [] の空の配列。
このユーザーの興味や関心を表す 0 ～ 3 個のトピックのリスト。
7 日間のモニタリングが完了すると、次の通知が届きます。
- その週のナビゲーション履歴から計算された、ユーザーの興味や関心を表す 1 つのトピック。
  - 重要な点として、Topics API がその週の上位 5 つのトピックを計算するのに十分なトピックがユーザーによって確認されなかった場合、Topics は合計 5 つのトピックを算出するために必要な数だけランダムなトピックを追加します。API の詳細を確認する。
4 週間のモニタリング後に呼び出す場合、3 つのうち 1 つを置き換える新しいトピックエントリ。
- これは、Topics API が今後数週間は安定し、ユーザーの興味 / 関心があまりにも多く公開されないためです。GitHub で詳細を確認する。
ユーザーのトピックが 3 週間を超えて確認されていない場合、Topics API は空の配列 [] を再度返します。

ユーザーエクスペリエンスのパフォーマンスと指標を測定します。

クロスオリジンの iframe 内での Topics API への JavaScript 呼び出しの実行時間は、今後のパフォーマンス分析で使用するために測定する必要があります。バックエンドでテレメトリーデータを適切に収集して保存してください。
- トピックを受信してから iframe と postMessage() のトピックを作成するのにかかる時間も、計算対象となる指標の一つです。

トラブルシューティング

Topics API を呼び出しても null が返されます。どうすればよいですか？: ユーザーのモニタリングから 1 週間以内に Topics API を呼び出す場合、これは想定された動作です。

主な推奨事項

フロントエンドのコードをテストして、JavaScript が期待どおりに動作することを確認します。
バックエンドをテストしてトピックの結果を受け取る。
1. データ型とバックエンド API パラメータが正しく設定されていることを確認してください。
2. バックエンドが適切なスケーリングを行うように設定されていることを確認してください。
これまでの経験から、より関連性の高いトピックの検索結果を得るには、少なくとも 3 週間は待つ必要があります。
すべてのユーザーが Topics を利用できるわけではありません。
1. ユーザーは Topics API を明示的に無効にできます。
2. パブリッシャーのページで権限ポリシーを管理できます。Topics API デベロッパーガイドのオプトアウトをご覧ください。
3. 詳しくは、chromestatus.com をご覧ください。
この環境に指標とオブザーバビリティを追加します。これらは最初の結果を分析するために必要です。指標の例:
1. 通話のレイテンシ
2. トピック呼び出しの HTTP エラー
最初の 3 週間は、実装に対する変更は最小限にとどめてください。

本番環境へのスケーリング

以下に、本番環境にスケーリングする方法の概要を示します。以下で手順を説明します。

実装をスケーリングする（本番環境）これについては以下で説明します。
1. 複数のパブリッシャーのウェブサイトに iframe を追加する。
トピックデータを処理して使用します（推定所要時間: 約 4 週間）。
1. トピックデータを他のデータとともに追加のシグナルとして組み込みます。
2. リアルタイムビッダーのテストを行うパートナーを選定します。
3. 他のデータに付加的なシグナルとして、トピックを使用してユーティリティテストを実行します。

実装を拡大する

この時点で、制御された環境で一部のサイトからトピック・データが収集され、ソリューション全体に対する高い信頼度が得られるはずです。

今度は、同じコードをより多くのターゲットウェブサイトにデプロイして、実装を拡大しましょう。これにより、より多くのユーザーをモニタリングし、より多くのトピックデータを収集し、オーディエンスに対する理解を深めることができます。

次のことをおすすめします。

特にトラフィック量が多い場合は、サイト全体に段階的に導入します。
予想されるトラフィックに応じて、トピックデータの負荷テストを実行します。
1. バックエンドで大量の通話を処理できることを確認する。
2. 分析用の指標収集とログを設定する。
Topics API をデプロイしたらすぐに指標を確認し、エンドユーザーに重大な問題がないか確認します。定期的に指標を確認してください。
中断や予期しない動作が発生した場合は、デプロイメントをロールバックしてログを分析して、問題を把握して修正します。

フィードバックを共有

GitHub: Topics API の説明を読み、API リポジトリで問題の投稿とディスカッションのフォローを行います。
W3C: 「ウェブ広告ビジネスの改善」グループで、業界のユースケースについてご確認ください。
お知らせ: メーリングリストへの参加や表示を行います。
プライバシーサンドボックスのデベロッパーサポート: プライバシーサンドボックスデベロッパーサポートリポジトリで質問したり、ディスカッションに参加したりできます。
Chromium: 現在 Chrome でテストできる実装について質問がある場合は、Chromium のバグを報告してください。

Topics API 統合ガイド

始める前に

ローカルでのビルドとテスト

ブラウザで Topics を有効にする

Topics API の仕組みをプレビューする

API がトピックを返す仕組み

主な推奨事項

MVP のデプロイを計画する

Topics API を呼び出す

JavaScript と iframe を使用して実装する

HTTP ヘッダーを使用して実装する

fetch() を使用して実装する

iframe を使用して実装する

サーバーサイド（すべてのケースで同一）

Topics バックエンドの実装

トピックをコンテキスト データとして使用する

ビルドとデプロイ

一部のターゲット サイトにデプロイ

機能をテストして確認する

トラブルシューティング

主な推奨事項

本番環境へのスケーリング

実装を拡大する

フィードバックを共有

`fetch()` を使用して実装する

トピックをコンテキストデータとして使用する

一部のターゲットサイトにデプロイ