Private Aggregation API 개요

Protected Audience의 데이터와 Shared Storage의 크로스 사이트 데이터를 사용하여 집계 데이터 보고서를 생성합니다.

웹에서 사용하는 중요한 기능을 제공하기 위해 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 내에서 수행됩니다.

예를 들어 이전에 Shared Storage에 인구통계 및 지역 데이터를 기록한 경우 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://flags/#privacy-sandbox-ads-apis에서 개인 정보 보호 샌드박스 광고 API 실험 플래그를 사용 설정하여 로컬에서 테스트할 수 있습니다.

이 API를 사용하려면 개인 정보 보호 샌드박스 Ads API 실험을 사용 설정하세요.
이 API를 사용하려면 개인 정보 보호 샌드박스 광고 API 실험을 사용 설정합니다.

실험 및 참여에서 테스트에 관해 자세히 알아보세요.

데모 사용

Shared Storage용 Private Aggregation API의 데모는 goo.gle/shared-storage-demo에서 액세스할 수 있으며 코드는 GitHub에서 제공됩니다. 데모는 클라이언트 측 작업을 구현하고 서버로 전송되는 집계 가능한 보고서를 생성합니다.

Protected Audience API용 Private Aggregation API 데모는 향후 게시될 예정입니다.

사용 사례

비공개 집계는 교차 사이트 측정을 위한 범용 API이며 공유 저장소 및 Protected Audience API Worklet에서 사용할 수 있습니다. 첫 번째 단계는 수집할 정보를 구체적으로 결정하는 것입니다. 이러한 데이터 포인트는 집계 키의 기반이 됩니다.

공유 저장장치 포함

Shared Storage를 사용하면 안전한 환경에서 크로스 사이트 데이터를 읽고 써서 유출을 방지하고, Private Aggregation API를 사용하면 Shared Storage에 저장된 크로스 사이트 데이터를 측정할 수 있습니다.

순 사용자 도달범위 측정

콘텐츠를 본 순 사용자 수를 측정할 수 있습니다. 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 Worklet에서 사용 가능한 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()

Google은 Protected Audience API Worklet 내에서만 특정 이벤트가 발생하는 경우에만 보고서를 전송하기 위한 트리거 기반 메커니즘을 제공합니다. 또한 이 함수를 사용하면 버킷 및 값이 입찰 시점에서는 아직 제공되지 않는 신호에 따라 달라질 수 있습니다.

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()

서드 파티 쿠키도 계속 사용할 수 있지만, Google에서는 디버그 모드를 사용 설정하여 디버깅과 테스트를 더 쉽게 할 수 있는 임시 메커니즘을 제공할 예정입니다. 디버그 보고서는 쿠키 기반 측정값을 비공개 집계 측정값과 비교할 때 유용하며 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를 사용해 보시고 의견이 있으면 알려주세요.