このページは 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 を開き、プライバシーサンドボックス API を有効にします。
（推奨）Topics API 固有のパラメータを使用して、Chromium フラグを指定してコマンドラインから Chrome を実行し、必要に応じて設定します。

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

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

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

Preview Topics API の仕組み

chrome://topics-internals ツールを使用すると、基盤となる Topics API の仕組みをローカルで見ることができます。

Topics API の仕組み（chrome://topics-internals）をご覧ください。 — chrome://topics-internals ツールの [Topics State] タブ

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

このツールを使って、以下を確認できます。

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

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

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

エポック（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:
- ターゲットウェブサイト（パブリッシャーのウェブサイト）に iframe を追加します。この iframe には、document.browsingTopics() を使用して Topics API を呼び出す JavaScript コードが含まれています。
ヘッダーオプション:
- 取得（推奨）または 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 を動的に作成する方法の一つとして、次の 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() リクエストに Sec-Browsing-Topics ヘッダーが含まれ、リクエスト URL のホスト名で観測されたトピックのリストが示されます。

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 を活用して関連性の高い広告を配信するには、いくつかの方法があります。その中には、トピックを使用してオーディエンスを構築する方法もあれば、トピックをとりわけシグナルの一つとして使用して、オーディエンスの新たな興味 / 関心を推測したり、入札ロジックを最適化したりするために機械学習モデルをトレーニングするための方法を提案するものもあります。

ビルドとデプロイ

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

いくつかのターゲットサイトにデプロイする

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

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

毎月の訪問数を少なくする（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() トピックを作成するのにかかる時間も、計算対象となるもう 1 つの指標です。

トラブルシューティング

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 を有効にする

Preview Topics API の仕組み

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

主な推奨事項

MVP のデプロイを計画する

Topics API を呼び出す

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

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

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

iframe を使用して実装する

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

Topics のバックエンドの実装

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

ビルドとデプロイ

いくつかのターゲット サイトにデプロイする

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

トラブルシューティング

主な推奨事項

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

実装をスケーリングする

フィードバックを共有

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

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

いくつかのターゲットサイトにデプロイする