Private Aggregation API 개요

Protected Audience의 데이터와 공유 저장소의 교차 사이트 데이터를 사용하여 집계 데이터 보고서를 생성합니다.

웹이 의존하는 중요한 기능을 제공하기 위해 비공개 집계는 이 API는 교차 사이트 데이터를 집계하고 보고하기 위해 보호해야 합니다

구현 상태

제안 내용 상태
공유 저장소의 보고서 확인을 통해 잘못된 Private Aggregation API 보고서 방지
설명		 Chrome에서 사용 가능
서드 파티 쿠키 자격요건에 따라 비공개 집계 디버그 모드 사용 가능 여부
GitHub 문제		 Chrome M119에서 사용 가능
신고 지연 줄이기
설명		 Chrome M119에서 사용 가능
Google Cloud용 Private Aggregation API 및 집계 서비스 지원
설명 자료		 Chrome M121에서 사용 가능
집계 가능한 보고서 페이로드의 패딩
설명		 Chrome M119에서 사용 가능
입찰보고서 구매자 보고에 비공개 집계 디버그 모드 사용 가능
설명 자료		 Chrome M123에서 사용 가능
ID 필터링 지원
설명		 Chrome M128에서 사용 가능
클라이언트 측 참여 병합
설명 자료		 Chrome M129에서 사용 가능

Private Aggregation API란 무엇인가요?

Private Aggregation API를 사용하면 개발자가 합산 데이터 보고서를 생성할 수 있습니다. Protected Audience API의 데이터와 활용 공유 저장소의 크로스 사이트 데이터

이 API의 기본 함수는 contributeToHistogram()입니다. 히스토그램 작업을 통해 데이터를 집계하고 사용자가 정의하는 각 버킷 (API에서는 집계 키로 알려짐)의 사용자 전체에 적용됩니다. 히스토그램 호출은 값을 누적하고 노이즈가 있는 집계 결과를 요약 보고서 형식으로 표시됩니다 예를 들어, 보고서에는 제3자 스크립트에서 버그를 발견했거나 사용자가 콘텐츠를 본 사이트 이 작업은 다른 API의 worklet 내에서 수행됩니다.

예를 들어 이전에 공유 스토리지에 인구통계 및 지역 데이터를 기록한 경우 Private Aggregation API를 사용하여 크로스 사이트에서 내 콘텐츠를 본 뉴욕시의 사용자 수를 대략적으로 알려주는 히스토그램을 구성할 수 있습니다. 이 측정을 집계하려면 지역 측정기준을 집계 키로 인코딩하고 집계 가능한 값에서 사용자를 집계하면 됩니다.

주요 개념

집계 키와 집계 가능한 값을 사용하여 Private Aggregation API를 호출하면 브라우저에서 집계 가능한 보고서를 생성합니다.

집계 가능한 보고서는 수집 및 일괄 처리를 위해 서버로 전송됩니다. 일괄 보고서는 나중에 집계 서비스에서 처리되고 요약 보고서가 생성됩니다.

Private Aggregation API와 관련된 주요 개념에 대한 자세한 내용은 Private Aggregation API 기초 문서를 참조하세요.

기여도 보고서와의 차이점

Private Aggregation API는 Attribution Reporting API와 많은 유사점을 공유합니다. Attribution Reporting은 전환을 측정하도록 설계된 독립형 API인 반면 Private Aggregation은 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회 이상 본 사용자의 수를 측정할 수 있습니다.

비공개 집계는 '콘텐츠 ID 581을 3회 이상 본 사용자는 약 89명입니다'와 같은 답변을 제공할 수 있습니다. 카운터는 다른 사이트의 공유 저장공간에서 증가될 수 있으며 Worklet 내에서 읽을 수 있습니다. 개수가 K에 도달하면 비공개 집계를 통해 보고서를 제출할 수 있습니다.

멀티 터치 기여 분석

이 가이드는 광고 기술이 공유 스토리지 + 비공개 집계 내에서 MTA를 구현하는 방법을 이해할 수 있도록 개발자 사이트에 게시되어야 합니다.

Protected Audience API 사용 시

Protected Audience API는 재타겟팅과 맞춤 잠재고객 사용 사례를 지원하며 비공개 집계를 사용하면 구매자 및 판매자 워크릿의 이벤트를 보고할 수 있습니다. 이 API는 입찰 입찰가 분포를 측정하는 등의 작업에 사용할 수 있습니다.

Protected Audience API Worklet에서 contributeToHistogram()를 사용하여 직접 데이터를 집계하고 Protected Audience API의 특별한 확장 프로그램인 contributeToHistogramOnEvent()를 사용하여 트리거를 기반으로 데이터를 보고할 수 있습니다.

사용 가능한 함수

다음 함수는 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 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 sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

위의 코드 예시는 교차 사이트 iframe 콘텐츠가 로드될 때마다 비공개 집계를 호출합니다. iframe 코드가 Worklet을 로드하고 Worklet은 콘텐츠 ID를 집계 키 (버킷)로 변환하여 Private Aggregation API를 호출합니다.

contributeToHistogramOnEvent()

Protected Audience API 워크렛 내에서만 Google은 특정 이벤트가 발생하는 경우에만 보고서를 전송하기 위한 트리거 기반 메커니즘을 제공합니다. 또한 이 함수를 사용하면 입찰의 해당 시점에 아직 사용할 수 없는 신호에 버킷과 값이 종속될 수도 있습니다.

privateAggregation.contributeToHistogramOnEvent(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를 사용하여 보고서가 공유 저장공간 작업에서 전송되었는지 확인할 수 있습니다.

자세한 내용은 보고서 인증 설명을 참고하세요.

참여 및 의견 공유

Private Aggregation API는 현재 논의 중이며 향후 변경될 수 있습니다. 이 API를 사용해 보고 의견이 있으면 언제든지 알려 주세요.