이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Topics API 개발자 가이드

테스트를 위해 Chrome 플래그를 사용하는 방법을 포함하여 API를 사용하는 방법을 알아보세요.

구현 상태

Topics API는 공개 토론 단계를 완료했으며 현재 사용자의 99%가 사용할 수 있으며 최대 100%까지 확장됩니다.
Topics API에 관한 의견을 제공하려면 Topics 설명에서 문제를 작성하거나 웹 광고 개선 비즈니스 그룹의 토론에 참여하세요. 설명에는 추가 정의가 필요한 미해결 질문이 여러 개 있습니다.
개인 정보 보호 샌드박스 타임라인은 Topics API 및 기타 개인 정보 보호 샌드박스 제안의 구현 타임라인을 제공합니다.
Topics API: 최신 업데이트에서는 Topics API와 구현의 변경사항 및 개선사항을 자세히 설명합니다.

데모 사용해 보기

단일 사용자로 Topics를 사용해 볼 수 있는 Topics API 데모가 두 가지 있습니다.

JavaScript API 데모: topics-demo.glitch.me.
헤더 데모: topics-fetch-demo.glitch.me

Topics Colab을 실행하여 Topics 분류 기준 모델을 사용해 볼 수도 있습니다.

JavaScript API를 사용하여 주제에 액세스하고 관찰한 대로 기록합니다.

Topics JavaScript API에는 document.browsingTopics()라는 한 가지 메서드가 있습니다. 여기에는 두 가지 목적이 있습니다.

나중에 발신자에 대한 주제를 계산하는 데 사용할 수 있도록 브라우저에 현재 페이지 방문이 발신자에 대해 관찰된 것으로 기록하도록 지시합니다.
호출자가 관찰한 사용자의 주제에 액세스합니다.

이 메서드는 가장 최근의 세 개의 에포크마다 하나씩, 최대 세 개의 주제의 배열로 무작위 순서로 확인되는 프로미스를 반환합니다. 에포크는 Chrome 구현에서 1주일로 설정된 기간입니다.

document.browsingTopics()에서 반환된 배열의 각 주제 객체에는 다음과 같은 속성이 있습니다.

configVersion: 현재 Topics API 구성을 식별하는 문자열입니다(예: chrome.2).
modelVersion: 사이트의 주제를 추론하는 데 사용되는 머신러닝 분류기를 식별하는 문자열입니다(예: 4).
taxonomyVersion: 브라우저에서 사용하는 주제 집합을 식별하는 문자열(예: 2)
topic: 분류의 주제를 식별하는 숫자(예: 309)
version: configVersion, taxonomyVersion, modelVersion를 연결하는 문자열(예: chrome.2:2:4)

이 가이드에 설명된 매개변수와 API의 세부정보 (예: 분류 크기, 매주 계산된 주제 수, 호출당 반환되는 주제 수)는 생태계 의견을 통합하고 API에서 반복함에 따라 변경될 수 있습니다.

document.browsingTopics 지원 감지

API를 사용하기 전에 브라우저에서 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}은 메서드 호출로 인해 현재 페이지가 주제 계산에 포함되지 않음을 의미합니다.

헤더를 사용하여 주제에 액세스하고 주제를 관찰한 것으로 표시

또한 요청 및 응답 헤더를 사용하여 주제에 액세스하고 페이지 방문을 관찰된 것으로 표시할 수 있습니다. 헤더 접근 방식을 사용하는 것이 JavaScript API를 호출하는 것보다 훨씬 더 효과적일 수 있습니다.

fetch() 또는 XHR 요청의 Sec-Browsing-Topics 헤더에서 주제에 액세스할 수 있습니다.

참고: XHR 요청에 Topics 헤더를 포함하는 것은 일시적으로만 가능하며 향후 지원이 중단될 예정입니다.

요청에 대한 응답에 Observe-Browsing-Topics: ?1 헤더를 설정하면 브라우저에서 호출자가 관찰한 대로 현재 페이지 방문을 기록하므로 나중에 주제 계산에 사용할 수 있습니다.

HTTP 헤더를 사용하여 다음 두 가지 방법으로 주제에 액세스하고 관찰할 수 있습니다.

fetch(): {browsingTopics: true}를 fetch() 요청의 옵션 매개변수에 추가합니다. Topics 헤더 데모에서 이에 관한 간단한 예를 확인할 수 있습니다.
iframe 속성: browsingtopics 속성을 <iframe> 요소에 추가하거나 상응하는 JavaScript 속성 iframe.browsingTopics = true를 설정합니다. iframe 소스의 등록 가능한 도메인은 호출자 도메인입니다. 예를 들어 <iframe src="https://example.com" browsingtopics></iframe>의 경우 호출자는 example.com입니다.

핵심사항: CSP 지시어는 광고 기술 스크립트의 fetch() 호출과 같이 페이지에 포함된 서드 파티 코드의 실행을 허용하지 않을 수 있습니다.

다음은 헤더에 관한 몇 가지 추가 참고사항입니다.

리디렉션이 이어지며 리디렉션 요청에서 전송되는 주제는 리디렉션 URL과 관련이 있습니다.
요청 헤더는 해당하는 응답 헤더가 없으면 호출자의 상태를 수정하지 않습니다. 즉, 응답 헤더가 없으면 페이지 방문이 관찰된 것으로 기록되지 않으므로 다음 에포크의 사용자 주제 계산에 영향을 미치지 않습니다.
응답 헤더는 해당 요청에 주제 헤더가 포함된 경우에만 적용됩니다.
요청의 URL은 호출자 도메인으로 기록된 등록 가능한 도메인을 제공합니다.

API 구현 디버그

Topics API를 사용 설정하면 데스크톱의 Chrome에서 chrome://topics-internals 페이지를 사용할 수 있습니다. 여기에는 현재 사용자의 주제, 호스트 이름으로 유추된 주제 및 API 구현에 대한 기술 정보가 표시됩니다. Google은 개발자 의견을 기반으로 페이지 디자인을 반복하고 개선하고 있습니다. bugs.chromium.org에 의견을 추가하세요.

브라우저에 맞게 계산된 주제 보기

사용자는 chrome://topics-internals를 보고 현재 및 이전 에포크 동안 브라우저에서 관찰된 주제에 관한 정보를 볼 수 있습니다.

주제 상태 패널이 선택된 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에서 하나 이상의 호스트 이름에 대해 Topics 분류 기준 모델에서 추론한 주제를 확인할 수도 있습니다.

분류 기준 패널이 선택된 chrome://topics-internals 페이지 — chrome://topics-internals 페이지의 Classifier 패널에는 선택한 주제, 방문한 호스트, 모델 버전 및 경로가 표시됩니다.

현재 Topics API 구현에서는 URL의 다른 부분에서가 아닌 호스트 이름에서만 주제를 추론합니다.

chrome://topics-internals 분류 기준에서 추론된 주제를 보려면 호스트 이름 (프로토콜 또는 경로 제외)만 사용하세요. 호스트 입력란에 '/'를 포함하려고 하면 chrome://topics-internals에서 오류를 표시합니다.

Topics API 정보 보기

분류 버전 및 에포크 기간과 같은 Topics API 구현 및 설정에 관한 정보는 chrome://topics-internals에서 확인할 수 있습니다. 이 값은 명령줄에서 성공적으로 설정된 API 또는 매개변수의 기본 설정을 반영합니다. 이렇게 하면 명령줄 플래그가 예상대로 작동하는지 확인하는 데 도움이 될 수 있습니다.

이 예에서 time_period_per_epoch는 15초로 설정되었습니다 (기본값은 7일).

기능 및 매개변수 패널이 선택된 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 설정의 네 번째 출시를 사용 설정합니다.
: 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; 기본값: 1000; 각 상위 주제에서 유지할 최대 관찰 컨텍스트 도메인 수입니다. 사용 중인 메모리를 제한하는 것이 목적입니다.
: BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch; 기본값: 100000; API 사용 컨텍스트의 각 쿼리에 대해 데이터베이스에서 검색할 수 있는 최대 항목 수입니다. 쿼리는 주제 계산 시간에 에포크당 한 번 발생합니다. 목적은 최대 메모리 사용량을 제한하는 것입니다.
: 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=() 권한-정책 헤더를 포함하여 사이트의 특정 페이지에 관한 주제 계산을 선택 해제하여 해당 페이지의 모든 사용자에 대해서만 주제 계산을 차단할 수 있습니다. 이후 사이트의 다른 페이지를 방문한 후에는 영향을 받지 않습니다. 한 페이지에서 Topics API를 차단하는 정책을 설정해도 다른 페이지에는 영향을 미치지 않습니다.

Permissions-Policy 헤더를 사용하여 Topics API에 대한 서드 파티 액세스를 제어하여 페이지의 주제에 액세스할 수 있는 서드 파티를 제어할 수도 있습니다. 헤더의 매개변수로 self와 API에 대한 액세스를 허용할 도메인을 사용합니다. 예를 들어 자체 출처 및 https://example.com를 제외한 모든 탐색 컨텍스트에서 Topics API 사용을 완전히 중지하려면 다음 HTTP 응답 헤더를 설정합니다.

Permissions-Policy: browsing-topics=(self "https://example.com")

다음 단계

주제의 정의 및 작동 방식에 대해 자세히 알아보세요.
데모 사용해 보기

자세히 알아보기

참여 및 의견 공유

GitHub: Topics API 설명서를 읽고 API 저장소에서 질문을 올리고 문제에 대한 토론을 팔로우합니다.
W3C: 웹 광고 개선 비즈니스 그룹에서 업계 사용 사례에 관해 토론하세요.
공지사항: 메일링 리스트 참여 또는 보기
개인 정보 보호 샌드박스 개발자 지원: 개인 정보 보호 샌드박스 개발자 지원 저장소에서 질문하고 토론에 참여하세요.
Chromium: Chromium 버그를 신고하여 현재 Chrome에서 테스트할 수 있는 구현에 관해 질문합니다.