Protected Audience의 데이터 및 공유 저장소의 크로스 사이트 데이터를 사용하여 집계 데이터 보고서를 생성합니다.
Private Aggregation API는 웹에서 사용하는 중요한 기능을 제공하기 위해 개인 정보를 보호하는 방식으로 교차 사이트 데이터를 집계하고 보고할 수 있도록 개발되었습니다.
구현 상태
| 제안 내용 | 상태 |
|---|---|
| Shared Storage에 대한 보고서 확인을 사용하여 잘못된 Private Aggregation API 신고를 방지하세요. Explainer |
Chrome에서 사용 가능 |
| 비공개 집계 디버그 모드의 사용 가능 여부는 3PC 자격요건에 따라 다릅니다. GitHub 문제 |
Chrome M119에서 사용 가능 |
| 보고서 지연 줄이기 설명서 |
Chrome M119에서 사용 가능 |
| Private Aggregation API 및 Google Cloud용 집계 서비스 지원 Explainer |
Chrome M121에서 사용 가능 |
| 집계 가능한 보고서 페이로드의 패딩 Explainer |
Chrome M119에서 사용 가능 |
| 입찰 보고서 구매자 보고에 비공개 집계 디버그 모드를 사용할 수 있습니다. 설명자 |
Chrome M123에서 출시 예정 |
| 필터링 ID 지원 Explainer |
2024년 2분기에 Chrome에서 최초 출시될 예정입니다. |
Private Aggregation API란 무엇인가요?
개발자는 Private Aggregation API를 사용하여 Protected Audience API의 데이터와 공유 저장소의 크로스 사이트 데이터로 집계 데이터 보고서를 생성할 수 있습니다.
이 API는 현재 sendHistogramReport() 작업 하나만 제공하지만 향후 더 많은 작업이 지원될 수 있습니다. 히스토그램 작업을 사용하면 정의한 각 버킷 (API에서는 집계 키로 알려짐)에서 사용자 전체의 데이터를 집계할 수 있습니다.
히스토그램 호출은 값을 누적하고 노이즈가 적용된 집계 결과를 요약 보고서 형태로 반환합니다. 예를 들어 보고서에는 각 사용자가 내 콘텐츠를 본 사이트 수가 표시되거나 서드 파티 스크립트에서 버그가 발견될 수 있습니다. 이 작업은 다른 API의 worklet 내에서 수행됩니다.
예를 들어 이전에 공유 스토리지에 인구통계 및 지역 데이터를 기록한 경우 Private Aggregation API를 사용하여 크로스 사이트에서 내 콘텐츠를 본 뉴욕시의 사용자 수를 대략적으로 알려주는 히스토그램을 구성할 수 있습니다. 이 측정을 집계하려면 지역 측정기준을 집계 키로 인코딩하고 집계 가능한 값에서 사용자를 집계하면 됩니다.
주요 개념
집계 키와 집계 가능한 값으로 Private Aggregation API를 호출하면 브라우저에서 집계 가능한 보고서를 생성합니다.
집계 가능한 보고서는 수집 및 일괄 처리를 위해 서버로 전송됩니다. 일괄 보고서는 나중에 집계 서비스에서 처리되고 요약 보고서가 생성됩니다.
Private Aggregation API와 관련된 주요 개념에 대한 자세한 내용은 Private Aggregation API 기초 문서를 참조하세요.
기여도 보고서와의 차이점
Private Aggregation API는 Attribution Reporting API와 많은 유사점이 있습니다. Attribution Reporting은 전환을 측정하기 위한 독립형 API인 반면, 비공개 집계는 Protected Audience API 및 Shared Storage와 같은 API와 함께 크로스 사이트 측정을 위해 빌드됩니다. 두 API 모두 집계 가능한 보고서를 생성하며, 이 보고서는 집계 서비스 백엔드에서 사용되어 요약 보고서를 생성합니다.
기여도 보고서는 서로 다른 시점에 발생하는 노출 이벤트와 전환 이벤트에서 수집된 데이터를 연결합니다. 비공개 집계는 단일 크로스 사이트 이벤트를 측정합니다.
이 API 테스트
Private Aggregation API를 로컬에서 테스트하려면 chrome://settings/adPrivacy에서 모든 광고 개인 정보 보호 API를 사용 설정합니다.
실험 및 참여에서 테스트에 관해 자세히 알아보세요.
데모 사용
공유 저장소용 Private Aggregation API의 데모는 goo.gle/shared-storage-demo에서 액세스할 수 있으며 코드는 GitHub에서 제공됩니다. 데모는 클라이언트 측 작업을 구현하고 집계 가능한 보고서를 생성하여 서버로 전송합니다.
Protected Audience API용 Private Aggregation API의 데모는 향후 게시될 예정입니다.
사용 사례
비공개 집계는 교차 사이트 측정을 위한 범용 API로, 공유 저장소 및 Protected Audience API 워크릿에서 사용할 수 있습니다. 첫 번째 단계는 수집할 정보를 구체적으로 결정하는 것입니다. 이러한 데이터 포인트는 집계 키의 기반입니다.
공유 저장공간 포함
공유 저장소를 사용하면 안전한 환경에서 교차 사이트 데이터를 읽고 쓸 수 있어 유출을 방지할 수 있으며, Private Aggregation API를 사용하면 공유 저장소에 저장된 크로스 사이트 데이터를 측정할 수 있습니다.
순 사용자 도달범위 측정
해당 콘텐츠를 본 순 사용자 수를 측정하고 싶을 수 있습니다. Private Aggregation API는 '약 317명의 순 사용자가 Content ID 861을 확인했습니다.'와 같은 답변을 제공할 수 있습니다.
공유 저장소에서 사용자가 이미 콘텐츠를 봤는지 여부를 나타내는 플래그를 설정할 수 있습니다. 플래그가 없는 첫 번째 방문에서 비공개 집계가 호출되고 플래그가 설정됩니다. 교차 사이트 방문을 포함하여 사용자의 후속 방문에서 공유 스토리지를 확인하고 플래그가 설정된 경우 비공개 집계에 보고서 제출을 건너뛸 수 있습니다.
인구통계 측정
여러 사이트에서 내 콘텐츠를 본 사용자의 인구통계를 측정하고 싶을 수 있습니다.
비공개 집계를 사용하면 '독일 만 18~45세의 순 사용자 약 317명이 독일에 있습니다.'와 같은 답변을 얻을 수 있습니다. 공유 스토리지를 사용하여 서드 파티 컨텍스트에서 인구통계 데이터에 액세스합니다. 나중에 집계 키에 연령대 및 국가 측정기준을 인코딩하여 비공개 집계를 사용하여 보고서를 생성할 수 있습니다.
K+ 게재빈도 측정
미리 선택한 K 값으로 특정 브라우저에서 콘텐츠나 광고를 K회 이상 본 사용자의 수를 측정할 수 있습니다.
비공개 집계에서는 '약 89명의 사용자가 Content ID 581을 최소 3회 이상 본 적이 있습니다.'와 같은 답변을 제공할 수 있습니다. 카운터는 다른 사이트의 공유 저장공간에서 증가될 수 있으며 Worklet 내에서 읽을 수 있습니다. 개수가 K에 도달하면 비공개 집계를 통해 보고서를 제출할 수 있습니다.
Protected Audience API 사용 시
Protected Audience API는 재타겟팅과 맞춤 잠재고객 사용 사례를 지원하며 비공개 집계를 사용하면 구매자 및 판매자 워크릿의 이벤트를 보고할 수 있습니다. 이 API는 입찰 입찰가 분포를 측정하는 등의 작업에 사용할 수 있습니다.
Protected Audience API Worklet에서 sendHistogramReport()를 사용하여 직접 데이터를 집계하고 Protected Audience API의 특별한 확장 프로그램인 reportContributionForEvent()를 사용하여 트리거를 기반으로 데이터를 보고할 수 있습니다.
사용 가능한 함수
다음 함수는 Shared Storage 및 Protected Audience API 워크릿에서 사용 가능한 privateAggregation 객체에서 사용할 수 있습니다.
contributeToHistogram()
privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })를 호출할 수 있습니다. 여기서 집계 키는 bucket이고 집계 가능한 값은 value입니다. bucket 매개변수의 경우 BigInt이 필요합니다. value 매개변수의 경우 정수가 필요합니다.
다음은 도달범위 측정을 위해 공유 저장공간에서 호출되는 방식의 예입니다.
iframe.js
// Cross-site iframe code
async function measureReach() {
// Register worklet
await window.sharedStorage.worklet.addModule('worklet.js');
// Run reach measurement operation
await window.sharedStorage.run('reach-measurement', {
data: { contentId: '1234' }
});
}
measureReach();
worklet.js
// Shared storage worklet code
function convertContentIdToBucket(campaignId){
// Generate aggregation key
}
// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;
class ReachMeasurementOperation {
async run(data) {
const key = 'has-reported-content';
// Read the flag from Shared Storage
const hasReportedContent = await this.sharedStorage.get(key) === 'true';
// Do not send report if the flag is set
if (hasReportedContent) {
return;
}
// Send histogram report
// Set the aggregation key in `bucket`
// Bucket examples: 54153254n or BigInt(54153254)
// Set the scaled aggregatable value in `value`
privateAggregation.contributeToHistogram({
bucket: convertContentIdToBucket(data.contentId),
value: 1 * SCALE_FACTOR
});
// Set the flag in Shared Storage
await this.sharedStorage.set(key, true);
}
}
register('reach-measurement', ReachMeasurementOperation);
위의 코드 예에서는 교차 사이트 iframe 콘텐츠가 로드될 때마다 비공개 집계를 호출합니다. iframe 코드가 Worklet을 로드하고 Worklet은 콘텐츠 ID를 집계 키 (버킷)로 변환하여 Private Aggregation API를 호출합니다.
contributeToHistogramOnEvent()
Protected Audience API 워크렛 내에서만 Google은 특정 이벤트가 발생하는 경우에만 보고서를 전송하기 위한 트리거 기반 메커니즘을 제공합니다. 또한 이 함수를 사용하면 입찰의 해당 시점에 아직 사용할 수 없는 신호에 버킷과 값이 종속될 수도 있습니다.
privateAggregation.reportContributionForEvent(eventType, contribution) 메서드는 트리거 이벤트를 지정하는 eventType와 이벤트가 트리거될 때 제출할 contribution를 사용��니다. 트리거 이벤트는 입찰 낙찰 또는 실패 이벤트 등 입찰 종료 후 입찰 자체에서 발생하거나 광고를 렌더링한 분리 프레임에서 발생할 수 있습니다.
입찰 이벤트 보고서를 전송하려면 reserved.win, reserved.loss, reserved.always의 두 가지 예약된 키워드를 사용하세요. 분리 프레임에서 이벤트에 의해 트리거된 보고서를 제출하려면 맞춤 이벤트 유형을 정의합니다. 분리 프레임에서 이벤트를 트리거하려면 Fenced Frames Ads Reporting API에서 사용할 수 있는 fence.reportEvent() 메서드를 사용합니다.
다음 예에서는 입찰 낙찰 이벤트가 트리거될 때 노출 보고서를 전송하고, 광고를 렌더링한 분리 프레임에서 click 이벤트가 트리거되면 클릭 보고서를 전송합니다. 이 두 값은 클릭률을 계산하는 데 사용할 수 있습니다.
function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
// …
privateAggregation.contributeToHistogramOnEvent("reserved.win", {
bucket: getImpressionReportBucket(),
value: 1
});
privateAggregation.contributeToHistogramOnEvent("click", {
bucket: getClickReportBuckets(), // 128-bit integer as BigInt
value: 1
});
자세한 내용은 확장된 비공개 집계 보고 설명을 참고하세요.
enableDebugMode()
서드 파티 쿠키도 계속 사용할 수 있지만, 디버그 모드를 사용 설정하여 디버깅과 테스트를 더 쉽게 할 수 있는 임시 메커니즘을 제공할 예정입니다. 디버그 보고서는 쿠키 기반 측정값과 비공개 집계 측정값을 비교하는 데 유용하며 API 통합을 빠르게 검증할 수도 있게 해줍니다.
Worklet에서 privateAggregation.enableDebugMode()를 호출하면 디버그 모드가 사용 설정되므로 집계 가능한 보고서에 암호화되지 않은 (일반 텍스트) 페이로드가 포함됩니다. 그런 다음 집계 서비스 로컬 테스트 도구를 사용하여 이러한 페이로드를 처리할 수 있습니다.
디버그 모드는 서드 파티 쿠키에 액세스할 수 있는 호출자만 사용할 수 있습니다. 호출자가 서드 파티 쿠키에 액세스할 수 없는 경우 enableDebugMode()는 자동으로 실패합니다. 즉, 서드 파티 쿠키가 지원 중단되면 디버그 모드를 더 이상 사용할 수 없습니다.
privateAggregation.enableDebugMode({ <debugKey: debugKey> })를 호출하여 디버그 키를 설정할 수도 있습니다. 여기서 BigInt를 디버그 키로 사용할 수 있습니다. 디버그 키는 쿠키 기반 측정의 데이터와 비공개 집계 측정의 데이터를 연결하는 데 사용할 수 있습니다.
컨텍스트당 한 번만 호출할 수 있습니다. 이후의 모든 호출은 예외를 ���생시킵니다.
// Enables debug mode
privateAggregation.enableDebugMode();
// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });
신고 확인
공유 저장소의 경우 공유 저장소 작업 호출에 컨텍스트 ID를 추가하여 수신한 집계 가능한 보고서가 합법적인지 확인할 수 있습니다. 전송된 보고서에 ID가 첨부되며, 나중에 이 ID를 사용하여 보고서가 공유 저장공간 작업에서 전송되었는지 확인할 수 있습니다.
이 기능은 Chrome M114 이상에서 테스트할 수 있습니다. Protected Audience API의 보고서 확인은 아직 테스트할 수 없습니다.
자세한 내용은 보고서 인증 설명을 참고하세요.
참여 및 의견 공유
Private Aggregation API는 현재 논의 중이며 향후 변경될 수 있습니다. 이 API를 사용해 보고 의견이 있으면 언제든지 알려 주세요.
- GitHub: 설명서를 읽고 질문을 올리고 토론에 참여합니다.
- 개발자 지원: 개인 정보 보호 샌드박스 개발자 지원 저장소에서 질문하고 토론에 참여하세요.
- Shared Storage API 그룹 및 Protected Audience API 그룹에 가입하여 비공개 집계와 관련된 최신 공지사항을 확인하세요.