기여도 보고 제안서는 API 메커니즘 변경사항부터 새로운 기능에 이르기까지 커뮤니티 의견을 반영하기 위해 여러 변경사항을 거쳤습니다.
변경 로그
- 2022년 2월 7일: 헤더 트리거 리디렉션 섹션이 추가되었습니다.
- 2022년 1월 27일: 도움말 첫 게시됨
이 게시물의 대상은 누구인가요?
다음은 나를 위한 게시물입니다.
- API를 이미 이해하고 있는 경우(예: WICG 저장소의 토론을 관찰하거나 참여했으며 2022년 1월에 제안서에 적용된 일괄 변경사항을 이해하려는 경우)
- 데모 또는 프로덕션의 실험에서 Attribution Reporting API를 사용하는 경우
이 API를 처음 사용하거나 아직 사용해 보지 않았다면 API 소개로 바로 이동하세요.
사전 마이그레이션
Chrome에 이러한 변경사항이 구현된 후: 데모에서 또는 프로덕션의 실험 (오리진 트라이얼)에서 Attribution Reporting API의 이벤트 수준 보고서를 사용하는 경우 API의 코드를 수정해야 API가 계속 작동합니다. 새로운 기능을 사용해 볼 수도 있습니다.
이 도움말에는 집계 가능한 보고서의 변경사항도 나와 있습니다. 그러나 이 문서의 작성 시점에는 집계 가능한 보고서에 대한 브라우저 구현이 아직 없으므로 변경사항이 구현되어도 별도의 조치나 이전이 필요하지 않습니다.
이름 변경
요약 보고서 및 집계 가능한 보고서
종합 보고서로 설명되었던 내용을 이제 요약 보고서라고 합니다.
요약 보고서는 이전에 기여 또는 히스토그램 기여라고 했던 여러 집계 가능한 보고서의 집계 최종 출력입니다.
API 메커니즘 변경사항
헤더 기반 소스 등록 (이벤트 수준 보고서)
변경되는 사항과 이유는 무엇인가요?
사용자가 광고를 보거나 클릭하면 사용자 기기의 로컬 브라우저가 기여 분석 보고와 관련된 매개변수 (예: attributionsourceeventid, attributiondestination, attributionexpiry, 기타 매개변수)와 함께 이 이벤트를 기록합니다. 이러한 매개변수의 값은 광고 기술을 통해 설정됩니다.
이러한 매개변수를 설정하는 방식이 변경됩니다.
이전 제안서에서는 매개변수를 앵커 태그에 HTML 속성으로 또는 JS 기반 호출의 인수로 클라이언트 측에 포함해야 했습니다. 클릭 또는 조회 시에 매개변수를 알아야 했습니다.
새 제안서에서는 이러한 매개변수의 값이 광고 기술 서버에 대신 정의됩니다.
여기에는 특히 보안 측면에서 여러 가지 장점이 있습니다. 헤더 메커니즘을 통해 보고 출처(일반적으로 광고 기술)에 기여 분석 소스가 범위에 등록되는지 직접 제어할 수 있습니다. 이 변경사항으로 인해 보고 출처의 선택 없이는 실제 브라우저가 소스를 등록하지 않으므로 이는 사기 우려를 부분적으로 완화합니다.
소스 등록은 어떻게 작동하나요?
- 이제 특정 광고의 경우 광고 기술은 특정 클라이언트 측 속성
attributionsrc를 정의해야 합니다. 이 속성의 값은 브라우저가 요청을 전송할 URL입니다. 이 요청에는 새 HTTP 헤더Attribution-Reporting-Source-Info가 포함되며 이 헤더의 값navigation또는event,는 소스가 각각 클릭인지 아니면 조회인지를 지정합니다. - 이 요청을 수신하면 클릭/조회 추적 서버는 원하는 기여 분석 매개변수가 포함된 HTTP 헤더
Attribution-Reporting-Register-Source로 응답해야 합니다. 이제 이 헤더를 반환하는 출처가 보고 출처 (이전의
attributionreportto로 정의됨)입니다.HTTP 응답 헤더
Attribution-Reporting-Register-Source:{ "source_event_id": "267630968326743374", "destination": "https://toasters.example", "expiry": "604800000" }
기술 설명에서 자세히 알아보기
공개 토론 참여
헤더 기반 기여 분석 트리거 (이벤트 수준 보고서)
변경되는 사항과 이유는 무엇인가요?
클릭 또는 조회 등록과 마찬가지로 새 제안서는 기여 분석 트리거를 헤더 기반 접근 방식으로 변경합니다(광고 기술이 브라우저에 전환을 기록하도록 지시할 때).
이 메커니즘은 헤더 기반 소스 등록과 일치하며 이전에 사용된 리디렉션 메커니즘보다 훨씬 일반적입니다.
또한 새 제안서에서는 전환 페이지에 attributionsrc 속성이 필요합니다.
근거는 권한의 문제입니다. 이전 제안서에서 트리거 측 사이트(일반적으로 광고주 사이트)는 Permissions-Policy 헤더를 통해 기능을 일반적으로 제어했지만, 요소가 궁극적으로 기여 분석을 트리거하는 당사자에게 요청을 전송할 수 있는지에 관한 세부적인 요소 수준 제어는 하지 않았습니다. attributionsrc는 이를 변경합니다. 광고주는 이 필수 마커를 통해 기여 분석을 트리거할 수 있는 요소를 모니터링하고 관리할 수 있습니다.
소스 측(일반적으로 게시자 사이트)에는 Permissions-Policy를 통한 페이지 전체 컨트롤과 attributionsrc를 통한 요소 전체 컨트롤이 있습니다.
기여 분석 트리거는 어떻게 작동하나요?
픽셀 요청을 수신하고 전환으로 분류해야 한다고 결정하면 광고 기술은 새 HTTP
헤더 Attribution-Reporting-Register-Event-Trigger로 응답해야 합니다.
이 헤더의 값은 트리거 이벤트를 JSON 객체로 처리하는 방법을 지정합니다. 이는 이전 제안서에서 쿼리 매개변수로 정의된 것과 동일한 정보입니다.
HTTP 응답 헤더 Attribution-Reporting-Register-Event-Trigger:
[{
trigger_data: (unsigned 3-bit integer),
trigger_priority: (signed 64-bit integer),
deduplication_key: (signed 64-bit integer)
}]
리디렉션 (선택사항)
선택적으로 광고 기술 서버는 Attribution-Reporting-Register-Event-Trigger를 포함하는 응답을 리디렉션 응답으로 만들 수 있습니다.
이를 통해 제3자가 전환 이벤트를 관찰하고 브라우저가 전환 이벤트에 기여도를 부여하도록 지시할 수 있습니다.
리디렉션은 선택사항이며, 광고 기술과 서드 파티 모두 페이지에 픽셀이 있는 경우에는 필요하지 않습니다.
자세한 내용은 제3자 보고를 참조하세요.
기술 설명에서 자세히 알아보기
공개 토론 참여
Worklet 없음 (집계 가능한 보고서)
변경되는 사항과 이유는 무엇인가요?
집계 가능한 보고서에 관한 이전 제안에서 이러한 보고서를 생성하는 Worklet(자바스크립트 기반 메커니즘)을 호출하려면 JavaScript 액세스가 필요했습니다.
새 제안서에서는 Worklet이 필요하지 않습니다. 대신 광고 기술은 브라우저에서 집계 가능한 보고서를 생성하는 데 사용해야 하는 규칙을 HTTP 헤더를 통해 선언적으로 정의합니다.
새 제안서에는 다음과 같은 몇 가지 이점이 있습니다.
- 브라우저 구현: 새 디자인은 Worklet 디자인과 달리 브라우저에 새로운 실행 환경이 필요하지 않기 때문에 훨씬 간단합니다.
- 개발자 환경: 새 디자인에서는 워크릿과 달리 일반적으로 사용되고 개발자가 널리 알려진 헤더를 사용합니다. 또한 소스 등록을 위한 API 노출 영역과 밀접하게 일치하므로 API를 더 쉽게 알아보고 사용할 수 있습니다.
- 채택: 새로운 설계를 통해 더 많은 기존 측정 시스템에서 집계 가능한 보고서를 사용할 수 있습니다. 많은 측정 솔루션이 HTTP 전용이며 JavaScript 액세스가 필요하지 않은 이미지 요청(픽셀 요청)에 의존합니다. 하지만 Worklet 접근 방식에는 JavaScript 액세스가 필요했기 때문에 일부 기존 측정 시스템에서 이전하기가 어려웠을 수 있습니다.
- 견고성: 새로운 디자인은
keepalive시맨틱스와 통합하기가 더 쉬우므로(예: 사용자가 페이지를 떠날 때 클릭 또는 조회가 등록되는 경우) 데이터 손실을 완화하는 데 도움이 됩니다.
Worklet 없는 메커니즘은 어떻게 작동하나요?
이 선언적 메커니즘은 이벤트 수준의 소스 등록 및 기여 분석 트리거 헤더와 마찬가지로 HTTP 헤더를 기반으로 합니다. 이에 관한 자세한 내용은 다음 섹션에서 설명합니다.
공개 토론 참여
헤더 기반 소스 등록 (집계 가능한 보고서)
집계 가능한 보고서의 소스를 등록하기 위한 새로운 메커니즘이 제안되었습니다. 이 메커니즘은 이벤트 수준 소스 등록과 동일합니다.
헤더 이름만 다릅니다(Attribution-Reporting-Register-Aggregatable-Source).
기술 설명에서 자세히 알아보기
헤더 기반 기여 분석 트리거 (집계 가능한 보고서)
집계 가능한 보고서의 소스를 등록하기 위한 새로운 메커니즘이 제안되었습니다. 이 메커니즘은 이벤트 수준 기여 분석 트리거와 동일합니다.
헤더 이름만 다릅니다(Attribution-Reporting-Register-Aggregatable-Trigger-Data).
기술 설명에서 자세히 알아보기
새로운 기능
서드 파티 보고 (이벤트 수준 보고서 및 집계 가능한 보고서)
변경되는 사항과 이유는 무엇인가요?
새로운 제안의 두 가지 측면은 제3자 보고 사용 사례를 더 효과적으로 지원하는 데 도움이 됩니다.
- 원하는 경우 광고 기술은 네트워크 요청을 다른 광고 기술 서버로 리디렉션하여 다른 광고 기술이 자체 소스 및 트리거 등록을 실행할 수 있도록 합니다. 이는 현재 서드 파티를 구성하는 일반적인 방법입니다. 이렇게 하면 기존 서드 파티 보고 시스템에서 특히 API를 더 쉽게 채택할 수 있습니다.
- 보고 출처(일반적으로 광고 기술)는 대부분의 개인 정보 보호 제한을 더 이상 공유하지 않습니다. 이는 여러 광고 기술이 동일한 게시자 또는 광고주와 작동하는 사용 사례를 지원합니다.
제3자 보고는 어떻게 작동하나요?
새 제안서에서는 응답 기반 소스 등록 및 트리거가 HTTP 헤더를 사용합니다. 광고 기술은 이러한 요청에 HTTP 리디렉션을 활용할 수 있습니다.
게시자 사이트의 클릭/조회 요청 (소스 등록)이 이후에 여러 당사자로 리디렉션되는 경우
각 당사자는 이 조회 또는 클릭 (소스 이벤트)을 등록할 수 있습니다.
마찬가지로 광고 기술은 이탈자 사이트에서 보낸 특정 기여 분석 요청을 리디렉션하여 여러 다른 당사자가 전환을 등록 (기여 분석 트리거)하도록 허용할 수 있습니다.
각 당사자가 별도의 보고서에 액세스하고 별도의 데이터로 보고서를 구성할 수 있습니다.
리디렉션 없이 여러 트리거 등록
전환 측에 여러 픽셀 요소 (트리거당 1개)를 추가하여 리디렉션을 사용하지 않고 여러 기여 분석 트리거를 등록할 수도 있습니다.
공개 토론 참여
조회 완료 측정 (이벤트 수준 보고서 및 집계 가능한 보고서)
변경되는 사항과 이유는 무엇인가요?
새 제안서에서는 조회 후 측정과 클릭연결 측정이 통합된 방식으로 작동합니다.
- 클릭과 함께 보기를 기록하도록 브라우저에 지시한 보기별 속성인
registerattributionsrc는 더 이상 제안서에 포함되지 않습니다. - 이제 클릭 및 조회 전반에 걸쳐 개인 정보 보호 메커니즘이 통합되었습니다. 이와 관련된 내용은 노이즈 및 투명도를 참고하세요.
이 변경사항은 새로운 헤더 기반 등록 메커니즘과 일치하도록 제안되었습니다. 또한 클릭연결 및 조회 후 측정을 모두 지원하려는 경우 개발자 환경이 간소화됩니다.
조회 후 측정은 어떻게 작동하나요?
조회 후 측정과 클릭연결 측정은 모두 헤더 기반 등록을 사용합니다.
기술 설명에서 자세히 알아보기
공개 토론 참여
디버깅 / 성능 분석 (이벤트 수준 보고서 및 집계 가능한 보고서)
변경되는 사항과 이유는 무엇인가요?
개발자가 버그를 감지하고 기여도 보고의 실적을 기존 쿠키 기반 측정 솔루션과 비교할 수 있도록 디버깅 메커니즘이 제안서에 추가되었습니다.
디버깅은 어떻게 작동하나요?
소스 및 트리거 등록은 모두 새로운 매개변수 debug_key, 즉 부호 없는 64비트 정수 (큰 숫자)를 허용합니다.
보고서가 소스 및 트리거 디버그 키로 생성되고 소스 및 트리거 등록 시간에 Samesite=None ar_debug=1 쿠키가 보고 출처의 쿠키 jar에 있는 경우 디버그 보고서 (JSON)가 .well-known/attribution-reporting/debug 엔드포인트로 전송됩니다.
{
"source_debug_key": 1234567890987,
"trigger_debug_key": 4567654345028
}
이벤트 수준 보고서와 집계 가능한 보고서도 이 두 가지 새로운 매개변수를 포함하므로 두 매개변수가 올바른 디버그 보고서와 연결될 수 있습니다.
기술 설명에서 자세히 알아보기
공개 토론 참여
필터링 기능 (이벤트 수준 보고서 및 집계 가능한 보고서)
변경되는 사항과 이유는 무엇인가요?
오늘날의 광고 생태계에서 중요한 사용 사례를 지원하므로 다양한 사용 사례가 이제 이벤트 수준 보고서와 집계 가능한 보고서에서 모두 지원됩니다.
- 전환 필터링: 소스 측 정보를 기준으로 전환을 필터링합니다. 예를 들어 광고 클릭 및 조회에 대해 다른 트리거 데이터 (전환 데이터)를 선택합니다.
- 기여 분석 불일치: 기여 분석이 잘못된 전환을 필터링합니다. 이는 특정 유형의 전환 필터링입니다. 예를 들어 API의 etld+1 대상 범위로 인해 잘못된 광고 클릭/조회와 일치하는 전환을 필터링합니다.
필터링 기능은 어떻게 작동하나요? (이벤트 수준 보고서의 경우)
소스 측 JSON 객체의 선택사항 source_data 필드는 전환 시 브라우저에서 필터링 로직을 적용하는 데 사용할 항목을 정의할 수 있습니다.
{
source_event_id: "267630968326743374",
destination: "https://toasters.example",
expiry: "604800000"
source_data: {
conversion_subdomain: ["electronics.megastore"
"electronics2.megastore"],
product: "198764",
// Note that "source_type" will be automatically generated as one of {"navigation", "event"}
}
}
이제 트리거 등록에서 선택적 헤더 Attribution-Reporting-Filters를 허용합니다.
HTTP 응답 헤더 Attribution-Reporting-Filters:
{
"conversion_subdomain": "electronics.megastore",
"directory": "/store/electronics"
}
또는 Attribution-Reporting-Register-Event-Trigger 헤더를 filters 필드로 확장하여 source_data을 기반으로 trigger_data를 설정하는 선택적 필터링을 실행할 수 있습니다.
필터 JSON의 키가 source_data의 키와 일치할 경우, 교차점이 비어 있으면 트리거가
완전히 무시됩니다.
기술 설명에서 자세히 알아보기
공개 토론 참여
개인 정보 보호 기능 변경사항
노이즈 및 투명성 (이벤트 수준 보고서 및 집계 가능한 보고서)
변경되는 사항과 이유는 무엇인가요?
새 제안서에서는 보고서의 개인 정보 보호 메커니즘 중 하나가 개선되었습니다. 보고서에는 무작위 응답이 적용됩니다.
즉, 일부 실제 전환이 올바르게 보고되며, 특정 비율의 경우 일부 실제 전환이 억제되거나 일부 가짜 전환이 추가됩니다.
이 새로운 기법에는 몇 가지 이점이 있습니다.
- 클릭 및 조회에 대한 개인 정보 보호 메커니즘을 통합합니다.
- 트리거 데이터 (전환 데이터)와 트리거 소스 링크 노이즈를 분리하는 메커니즘보다 추론이 더 간단합니다.
- 적절한 노이즈 설정으로 개인 정보 보호 프레임워크를 설정하여 어느 당사자도 API를 통해 개별 사용자가 특정 광고로 전환했는지 확실히 알 수 없도록 합니다.
이 새로운 메커니즘은 트리거 데이터(전환 데이터)의 5% 가 임의의 값으로 대체된 이전의 메커니즘을 대체합니다.
또한 무작위 응답 확률 값이 보고서 본문(randomized_trigger_rate 필드)에 추가되었습니다. 이 필드는 소스가 무작위 응답을 받을 확률 (0~1)을 지정합니다.
여기에는 두 가지 주요 이점이 있습니다.
- 보고서를 수신하는 당사자(일반적으로 광고 기술)에게 기본 브라우저 동작을 transparent하게 만듭니다.
- 이는 향후 여러 브라우저에서 API가 지원되는 미래에 유용합니다. 브라우저마다 개인 정보 보호 목표에 따라 서로 다른 수준의 노이즈를 적용할 수 있으며, 보고서를 처리하는 당사자가 이를 파악해야 합니다.
노이즈는 어떻게 작동하나요?
새 제안서에서는 소스가 등록될 때 (즉, 광고 클릭 또는 조회가 기록될 때) 브라우저가 전환에 대한 기여도를 정확하게 부여하고 광고 클릭/조회에 관한 보고서를 전송할지 또는 허위 출력을 생성할지 임의로 결정합니다.
가짜 출력은 다음과 같습니다.
- 보고 없음: 사용자의 전환 여부와 관계없이
- 하나 또는 여러 개의 허위 보고서: 사용자의 전환 여부와 관계없습니다.
허위 보고서에서 트리거 데이터 (전환 데이터)는 무작위이며, 클릭의 경우 임의의 3비트 값 (0~7 사이의 숫자)과 임의의 1비트 값 (0 또는 1)입니다.
실제 신고와 마찬가지로 가짜 신고는 사용자가 전환한 직후 전송되지 않습니다. 무작위 보고 기간이 끝날 때 전송됩니다.
클릭에 대한 보고 기간은 3가지 (클릭 후 2일, 7일 또는 30일)가 있습니다. 각 허위 보고서는 보고 기간 중 하나에 무작위로 할당됩니다.
이와 별도로, 이전 제안서에서 이미 언급한 것처럼 특정 기간 내에서 보고서의 순서는 무작위입니다.
기술 설명에서 자세히 알아보기
공개 토론 참여
보고 제한사항 (이벤트 수준 보고서 및 집계 가능한 보고서)
변경되는 사항과 이유는 무엇인가요?
새 제안서는 두 사이트 간의 이벤트를 측정할 수 있는 당사자 수를 명시적으로 제한합니다.
- {publisher, advertiser}별로 소스를 등록할 수 있는 고유한 보고 출처 (일반적으로 광고 기술)의 최대 개수는 30일당 100개로 제한됩니다. 이 카운터는 광고 클릭 또는 조회 (소스 이벤트)마다 증가하며, 기여에 기여하지 않은 경우에도 증가합니다.
- {publisher, advertiser}별로 보고서를 전송할 수 있는 고유한 보고 출처 (일반적으로 광고 기술)의 최대 개수는 30일당 10개로 제한되는 것이 좋습니다. 이 카운터는 기여 전환이 발생할 때마다 증가합니다.
이러한 한도는 행위자의 전환 측정 능력을 제한하지 않을 정도로 높고 일부 형태의 API 악용을 완화하는 데 도움이 될 만큼 낮게 설정됩니다.
보고 쿨다운 / 비율 제한
변경되는 사항과 이유는 무엇인가요?
보고 쿨다운은 지정된 기간 동안 사용자에 대해 이 API를 통해 전송되는 총 정보의 양을 제한하는 개인 정보 보호 메커니즘입니다.
새 제안서에서는 {소스 사이트, 대상, 보고 출처}(일반적으로 {publisher, advertiser, adtech})당 100개의 보고서를 30일 동안 예약할 수 있습니다.
이 한도를 초과하면 브라우저가 {소스 사이트, 대상, 보고 출처} (일반적으로 {게시자, 광고주, 광고 기술})와 일치하는 보고서의 예약을 중지합니다. 이때 해당 {소스 사이트, 대상, 보고 출처}의 30일 이동 보고서 수가 100개 미만이 될 때까지 계속됩니다.
기술 설명에서 자세히 알아보기
도착 페이지 설정 (이벤트 수준 보고서만 해당)
변경되는 사항과 이유는 무엇인가요?
대상 한도 설정은 범위에 보고 출처 (일반적으로 광고 기술)를 포함하도록 수정됩니다. {publisher, adtech}당 100개의 고유한 대기 중인 대상 (일반적으로 광고주 사이트 또는 전환이 발생할 것으로 예상되는 사이트)이 허용됩니다.
이는 방문 기록 재구성을 제한하는 개인 정보 보호 기능입니다.
기술 설명에서 자세히 알아보기
모든 리소스
- 기여도 보고를 참고하세요.
- API에 대해 알아야 할 사항 읽어보기