Topics API を実装する

このページでは、Topics API の呼び出し元がトピックをモニタリングしてアクセスするための実装の詳細について説明します。ソリューションの実装を開始する前に、ブラウザが正しく設定されていることを確認してください。発信者がユーザーのトピックをどのように確認し、アクセスするかについて詳しくは、概要セクションをご覧ください。

トピックを観察してアクセスする

ユーザーのトピックを観察してアクセスする方法は、HTTP ヘッダーと JavaScript API の 2 つです。

HTTP ヘッダー

HTTP ヘッダーを使用することは、ユーザー トピックをモニタリングしてアクセスするうえで推奨される方法です。このアプローチは、JavaScript API を使用するよりもパフォーマンスが大幅に向上する可能性があります。HTTP ヘッダーの場合、リクエストの URL によって、呼び出し元ドメインとして記録される登録可能なドメインが提供されます。これは、ユーザーのトピックを観察したと見なされるドメインです。

リクエストを開始する

ヘッダーでトピックを使用する方法は 2 つあります。

• browsingTopics: true オプションを含む fetch() リクエストでリクエスト ヘッダーとレスポンス ヘッダーにアクセスする。
• browsingtopics 属性を含む iframe 要素のヘッダーにアクセスする。

fetch でリクエストを開始する

fetch を使用して、API 呼び出し元はオプション パラメータに {browsingTopics: true} を含むリクエストを行います。フェッチ リクエストの URL パラメータのオリジンは、トピックを観測したと見なされるオリジンです。

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

iframe でリクエストを開始する

browsingtopics 属性を <iframe> 要素に追加します。ブラウザは、iframe のリクエストに Sec-Browsing-Topics ヘッダーを含めます。この場合、iframe のオリジンが呼び出し元になります。

   <iframe src="https://adtech.example" browsingtopics></iframe>

リクエスト ヘッダーの値を解釈する

どちらのアプローチ（fetch と iframe）でも、ユーザーが確認したトピックは、サーバーで Sec-Browsing-Topics リクエスト ヘッダーから取得できます。Topics API は、fetch() リクエストまたは iframe リクエストのヘッダーにユーザー トピックを自動的に含めます。API が 1 つ以上のトピックを返した場合、トピックが確認されたオリジンへのフェッチ リクエストには、次のような Sec-Browsing-Topics ヘッダーが含まれます。

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

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

   ();p=P0000000000000000000000000000000

リダイレクトがフォローされ、リダイレクト リクエストで送信されたトピックはリダイレクト URL に固有のものになります。Sec-Browsing-Topics ヘッダー値はパディングされ、ヘッダーの長さに基づいて呼び出し元にスコープ設定されたトピックの数を攻撃者が学習するリスクが軽減されます。

サーバーサイドのレスポンスを処理する

リクエストのレスポンスに Observe-Browsing-Topics: ?1 ヘッダーが含まれている場合、ブラウザは、付随するリクエストのトピックを観察済みとしてマークし、ユーザーの次のエポックのトピックの計算に現在のページ訪問を含める必要があります。サーバーサイド コードのレスポンスに Observe-Browsing-Topics: ?1 ヘッダーを含めます。

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

観察されたトピックをパートナーと共有する

SSP はパブリッシャー側でのみ存在するため、DSP は広告主のサイトで検出したトピックをパートナー SSP と共有したい場合があります。広告主の最上位コンテキストからトピック ヘッダーを含む fetch() リクエストを SSP に送信することで、この処理を行うことができます。

const response = await fetch("partner-ssp.example", {
 browsingTopics: true
});

JavaScript でトピックを観察してアクセスする

Topics JavaScript API メソッド document.browsingTopics() は、ブラウザ環境内でユーザーの関心のあるトピックを検出して取得する手段を提供します。 - 検出を記録: 呼び出し元がユーザーによる現在のページの閲覧を検出したことをブラウザに通知します。このオブザベーションは、将来のエポックで呼び出し元のユーザーのトピックの計算に貢献します。- トピックへのアクセス: 呼び出し元がユーザーについて以前に確認したトピックを取得します。このメソッドは、最近の 3 つのエポックから 1 つずつ選ばれたトピックをランダムな順序の配列で返します。

Topics JavaScript API デモをフォークして、コードの出発点として使用することをおすすめします。

API の可用性

API を使用する前に、API がサポートされていて使用可能であることを確認してください。

 if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
    console.log('document.browsingTopics() is supported on this page');
 } else {
    console.log('document.browsingTopics() is not supported on this page');
 }

iframe を埋め込む

API が呼び出されるコンテキストは、ブラウザが呼び出し元に適したトピックを返すために使用されるため、呼び出しにはクロスオリジン iframe を使用する必要があります。HTML に <iframe> 要素を含めます。

<iframe src="https://example.com" browsingtopics></iframe>

JavaScript を使用して iframe を動的に作成することもできます。

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

iframe 内から 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() メソッドは、呼び出し元が観測した現在のページ訪問をブラウザに記録させ、後でトピックの計算に使用できるようにします。このメソッドには、ページ訪問の記録をスキップするための省略可能な引数 {skipObservation:true} を渡すことができます。

 // current page won't be included in the calculation of topics:
 const topics = await document.browsingTopics({skipObservation:true});

レスポンスを理解する

最大 3 つのトピックが返されます。過去 3 週間のそれぞれについて、トピックが観測されたかどうかに応じて 1 つまたは 0 個のトピックが返されます。現在のユーザーについて呼び出し元が確認したトピックのみが返されます。API が返す値の例を次に示します。

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]

• configVersion: ブラウザのトピック アルゴリズムの構成バージョンを識別する文字列。
• modelVersion: トピックの推定に使用される機械学習分類器を識別する文字列。
• taxonomyVersion: ブラウザで使用されているトピックのセットを識別する文字列。
• topic: 分類内のトピックを識別する数値。
• version: configVersion、taxonomyVersion、modelVersion を連結した文字列。このガイドで説明したパラメータや API の詳細（分類トピックの数、1 週間に推定されるトピックの数、1 回の呼び出しで返されるトピックの数など）は、エコシステムからのフィードバックに基づく API の調整に伴い変わる可能性があります。

想定されるレスポンスと、トピックを関連性の高い広告の追加シグナルとして使用する方法については、テストと公開のページをご覧ください。

次のステップ

テストと公開

Topics ベースのソリューションをデプロイ、テスト、スケーリングする方法を学びます。

ツール

Chrome で利用できるツールを使用して、Topics API の情報を確認したり、トピックの割り当て方法を把握したり、実装をデバッグしたりする方法を学びます。

関連情報

ウェブ上の Topics API について理解を深めるには、Google のリソースをご覧ください。

• トピックのデモ、コラボレーション、チュートリアル動画をご覧ください。
• デベロッパーが Topics API をテスト用にカスタマイズできる Chrome フラグのリストをご覧ください。
• ユーザーとデベロッパーが API を制御する方法を確認する。
• 技術的な解説とサポートについては、リソースをご確認ください。質問したり、フィードバックを提供したり、交流したりできます。