웹의 Topics API 지원 리소스

웹의 주제 관련 디버깅, 문제 해결, 지원 리소스에 관한 권장사항을 확인하세요.

문제 해결

헤더 Sec-Browsing-Topics를 설정하여 document.browsingTopics() 호출 또는 fetch() 요청을 실행했지만 응답으로 빈 배열을 수신하는 경우 로컬 개발 환경과 프로덕션 시스템 모두에서 문제의 근본 원인을 파악하기 위해 취할 수 있는 여러 디버깅 단계가 있습니다.

로컬에서 디버그

로컬에서 테스트하는 경우 필요한 매개변수를 사용하여 Chrome을 실행해야 합니다.

  • 등록을 우회하려면 chrome://flags/#privacy-sandbox-enrollment-overrides 플래그를 사용 설정하고 Topics를 호출하는 사이트의 URL을 추가합니다.

  • 기능 플래그를 사용하여 테스트할 Topics API를 구성합니다. 이러한 플래그를 사용하면 주제를 편안하게 테스트할 수 있도록 에포크 기간, 인기 주제 수 등의 매개변수를 수정할 수 있습니다. 다음과 같은 권장 기능 플래그를 사용할 수 있습니다.

    --enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

  • 플래그를 사용하여 Chrome을 실행하기 전에 다른 모든 Chrome 인스턴스와 프로세스를 닫았는지 확인하세요.

  • 다음 사항을 확인하세요.

    • Chrome 101 이상을 사용 중입니다.
    • 스크립트에서 Topics API를 호출하여 주제를 관찰했습니다. 테스트할 때는 스크립트가 삽입된 사이트를 방문하여 사용자 행동을 시뮬레이션할 수 있습니다. 실제 예는 데모를 참고하세요.
    • 광고 차단 프로그램 또는 유사한 앱이나 확장 프로그램이 실행되고 있지 않습니다.
    • 시크릿 모드가 아닙니다.
    • chrome://settings/trackingProtection에서 Block all third-party cookies 옵션은 사용 중지됩니다.

실시간 구현 디버그

사용자를 관찰한 지 1주일 이내에 실시간 애플리케이션에서 Topics API를 호출하는 경우 애플리케이션에서 아직 사용자의 주제를 관찰하지 못했을 수 있으므로 빈 결과가 표시될 수 있습니다. 권장사항에 따라 솔루션을 디버그할 수 있습니다.

  • 사이트가 개인 정보 보호 샌드박스에 등록되어 있는지 확인합니다.
  • 프런트엔드 코드를 테스트하여 JavaScript가 예상대로 작동하는지 확인합니다.
  • 백엔드를 테스트하여 주제 결과를 수신합니다.
    • 데이터 유형과 백엔드 API 매개변수가 올바르게 구성되었는지 확인하세요.
    • 백엔드가 적절하게 확장되도록 구성되어 있는지 확인합니다.
  • Google의 경험에 비추어 볼 때, 관련성 높은 주제 결과를 얻으려면 최소 3주가 소요됩니다.
  • 일부 사용자에게는 주제가 사용 설정되지 않습니다.
    • 사용자는 Topics API를 명시적으로 사용 중지할 수 있습니다.
    • 게시자 페이지에서 권한 정책을 관리하고 사이트의 선택 해제할 수 있습니다.
  • 이 환경에 측정항목과 관측 가능성을 추가합니다. 첫 번째 결과를 분석하려면 이러한 항목이 필요합니다. 측정항목의 예는 다음과 같습니다.
    • 호출 지연 시간입니다.
    • 주제 호출 시 HTTP 오류
  • 처음 3주 동안은 구현 변경사항을 최소화하세요.

리소스