이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Private Aggregation API 개요

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

웹에서 사용하는 중요한 기능을 제공하기 위해 Private Aggregation API는 개인 정보를 보호하는 방식으로 크로스 사이트 데이터를 집계하고 보고하기 위해 만들어졌습니다.

구현 상태

제안 내용	상태
공유 저장소의 보고서 확인으로 잘못된 Private Aggregation API 보고서 방지 설명	Chrome에서 사용 가능
3PC 자격요건에 따라 비공개 집계 디버그 모드 사용 가능 여부 달라짐 GitHub 문제	Chrome M119에서 사용 가능
신고 지연 줄이기 설명	Chrome M119에서 사용 가능
공유 저장소의 비공개 집계 참여 시간 제한 설명	M119에서 사용 가능
Google Cloud용 Private Aggregation API 및 집계 서비스 지원 설명	Chrome M121에서 사용 가능
집계 가능한 보고서 페이로드의 패딩 설명	Chrome M119에서 사용 가능
auctionReportBuyers 보고에 사용할 수 있는 비공개 집계 디버그 모드 설명	Chrome M123에서 사용 가능
ID 필터링 지원 설명	Chrome M128에서 사용 가능
클라이언트 측 참여 병합 설명	Chrome M129에서 사용 가능

Private Aggregation API란 무엇인가요?

Private Aggregation API를 사용하면 개발자가 Protected Audience API의 데이터와 Shared Storage의 크로스 사이트 데이터를 사용하여 집계 데이터 보고서를 생성할 수 있습니다.

이 API의 기본 함수는 contributeToHistogram()라고 합니다. 히스토그램 작업을 사용하면 정의한 각 버킷 (API에서는 집계 키라고 함)의 사용자를 대상으로 데이터를 집계할 수 있습니다. 히스토그램 호출은 값을 누적하고 요약 보고서 형식으로 노이즈가 있는 집계된 결과를 반환합니다. 예를 들어 보고서에는 각 사용자가 콘텐츠를 본 사이트 수가 표시되거나 서드 파티 스크립트에서 버그가 발견될 수 있습니다. 이 작업은 다른 API의 워크렛 내에서 실행됩니다.

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

주요 개념

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

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

Private Aggregation API와 관련된 주요 개념에 대해 자세히 알아보려면 Private Aggregation API 기본사항 문서를 참고하세요.

Attribution Reporting과의 차이점

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를 사용 설정하세요.

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

데모 사용

공유 저장소용 비공개 집계 API의 데모는 goo.gle/shared-storage-demo에서 액세스할 수 있으며 코드는 GitHub에서 확인할 수 있습니다. 이 데모는 클라이언트 측 작업을 구현하고 집계 가능한 보고서를 생성하여 서버로 전송합니다.

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

사용 사례

Private Aggregation은 교차 사이트 측정을 위한 범용 API이며 Shared Storage 및 Protected Audience API 워크렛에서 사용할 수 있습니다. 첫 번째 단계는 수집할 정보를 구체적으로 결정하는 것입니다. 이러한 데이터 포인트는 집계 키의 기반이 됩니다.

공유 저장소 포함

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

순 사용자 도달범위 측정

콘텐츠를 본 순 사용자 수를 측정할 수 있습니다. Private Aggregation API는 'Content ID 861을 본 순 사용자 수가 약 317명입니다'와 같은 답변을 제공할 수 있습니다.

공유 저장소에서 사용자가 콘텐츠를 이미 시청했는지 여부를 나타내는 플래그를 설정할 수 있습니다. 플래그가 없는 첫 방문에서 비공개 집계를 호출한 후 플래그가 설정됩니다. 교차 사이트 방문을 포함하여 사용자가 이후에 방문할 때 공유 저장소를 확인하고, 플래그가 설정된 경우 비공개 집계에 보고서를 제출하는 작업을 건너뛸 수 있습니다. 이러한 측정을 구현하는 방법에 대해 자세히 알아보려면 도달범위 백서를 확인하세요.

인구통계 측정

여러 사이트에서 내 콘텐츠를 본 사용자의 인구통계를 측정할 수 있습니다.

비공개 집계는 '독일에서 18~45세의 순 사용자 수가 약 317명입니다.'와 같은 답변을 제공할 수 있습니다. 공유 저장소를 사용하여 서드 파티 컨텍스트의 인구통계 데이터에 액세스합니다. 나중에 집계 키에 연령대 및 국가 측정기준을 인코딩하여 비공개 집계로 보고서를 생성할 수 있습니다.

K+ 게재빈도 측정

사전 선택된 K 값을 사용하여 특정 브라우저에서 콘텐츠 또는 광고를 K번 이상 본 사용자 수를 측정할 수 있습니다.

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

멀티 터치 기여 분석

이 안내는 광고 기술이 공유 저장소 + 비공개 집계 내에서 MTA를 구현하는 방법을 이해할 수 있도록 개발자 사이트에 게시됩니다.

Protected Audience API 사용 시

Protected Audience API를 사용하면 리타겟팅 및 맞춤 잠재고객 사용 사례를 지원할 수 있으며, Private Aggregation을 사용하면 구매자 및 판매자 워크렛의 이벤트를 보고할 수 있습니다. 이 API는 입찰가 분포를 측정하는 등의 작업에 사용할 수 있습니다.

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

사용 가능한 함수

다음 함수는 공유 저장소 및 Protected Audience API 워크렛에서 사용할 수 있는 privateAggregation 객체에서 사용할 수 있습니다.

contributeToHistogram()

집계 키가 bucket이고 집계 가능한 값이 value인 privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <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';

    // Don't 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 코드는 워크렛을 로드하고 워크렛은 콘텐츠 ID를 집계 키 (버킷)로 변환하여 Private Aggregation API를 호출합니다.

contributeToHistogramOnEvent()

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

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 통합을 빠르게 검증할 수도 있습니다.

워크렛에서 privateAggregation.enableDebugMode()를 호출하면 집계 가능한 보고서에 암호화되지 않은 (명시 텍스트) 페이로드가 포함되는 디버그 모드가 사용 설정됩니다. 그런 다음 집계 서비스 로컬 테스트 도구로 이러한 페이로드를 처리할 수 있습니다.

디버그 모드는 서드 파티 쿠키에 액세스할 수 있는 호출자만 사용할 수 있습니다. 호출자가 서드 파티 쿠키에 액세스할 수 없는 경우 enableDebugMode()가 자동으로 실패합니다.

BigInt를 디버그 키로 사용할 수 있는 경우 privateAggregation.enableDebugMode({ <debugKey: debugKey> })를 호출하여 디버그 키를 설정할 수도 있습니다. 디버그 키는 쿠키 기반 측정의 데이터와 비공개 집계 측정의 데이터를 연결하는 데 사용할 수 있습니다.

이는 컨텍스트당 한 번만 호출할 수 있습니다. 이후 호출 시 예외가 발생합니다.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

보고서 확인

Private Aggregation API는 사용자 개인 정보를 보호하면서 크로스 사이트 측정을 지원합니다. 하지만 악의적인 행위자가 이러한 측정의 정확성을 조작하려고 시도할 수 있습니다. 이를 방지하려면 컨텍스트 ID를 사용하여 신고의 진위를 확인할 수 있습니다.

컨텍스트 ID를 설정하면 최종 집계 결과에 기여할 때 데이터의 정확성을 보장하는 데 도움이 됩니다. 이를 위해 다음을 실행합니다.

잘못되거나 허위인 신고 방지: 합법적이고 진정한 API 호출을 통해 보고서가 생성되도록 하여 악의적인 행위자가 보고서를 조작하기 어렵게 합니다.
보고서 재생 방지: 이전 보고서를 재사용하려는 시도를 감지하고 거부하여 각 보고서가 집계 결과에 한 번만 기여하도록 합니다.

공유 저장소

공유 저장소를 사용하여 집계 가능한 보고서를 보낼 수 있는 작업을 실행하는 경우 워크렛 외부에 예측할 수 없는 ID를 설정할 수 있습니다.

이 ID는 워크렛에서 생성된 보고서에 삽입됩니다. privateAggregationConfig 키 아래의 옵션 객체 내에서 run() 또는 selectURL() 공유 저장소 메서드를 호출할 때 지정할 수 있습니다.

예를 들면 다음과 같습니다.

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

이 ID를 설정하면 이를 사용하여 공유 저장소 작업에서 보고서가 전송되었는지 확인할 수 있습니다. 정보 유출을 방지하기 위해 공유 저장소 작업당 contributeToHistogram() 호출 수와 관계없이 정확히 하나의 보고서가 전송됩니다 (참여가 없더라도).

Private Aggregation API는 집계 가능한 보고서를 최대 1시간의 무작위 지연으로 전송하지만, 보고서를 확인하도록 컨텍스트 ID를 설정하면 이 지연이 줄어듭니다. 이 경우 공유 저장소 작업 시작부터 5초의 고정된 더 짧은 지연이 발생합니다.

신고 확인 워크플로 예시

워크플로 예시 (위 다이어그램 참고):

공유 저장소 작업은 컨텍스트 ID를 지정하는 비공개 집계 구성으로 실행되고 집계 가능한 보고서가 생성됩니다.
컨텍스트 ID는 생성된 집계 가능한 보고서에 삽입되어 서버로 전송됩니다.
서버는 생성된 집계 가능한 보고서를 수집합니다.
서버의 프로세스는 각 집계 가능한 보고서의 컨텍스트 ID를 저장된 컨텍스트 ID와 비교하여 유효성을 확인한 후 보고서를 일괄 처리하여 집계 서비스로 전송합니다.

컨텍스트 ID 확인

수집기 서버로 수신되는 보고서는 집계 서비스로 전송되기 전에 여러 가지 방법으로 확인할 수 있습니다. 잘못된 컨텍스트 ID가 포함된 보고서는 컨텍스트 ID가 다음과 같은 경우 거부될 수 있습니다.

알 수 없음: 시스템에서 생성하지 않은 컨텍스트 ID와 함께 보고서가 수신되면 보고서를 삭제할 수 있습니다. 이렇게 하면 알 수 없는 행위자나 악의적인 행위자가 집계 파이프라인에 데이터를 삽입하는 것을 방지할 수 있습니다.
중복: 컨텍스트 ID가 동일한 신고가 두 번 이상 접수되면 삭제할 신고를 선택해야 합니다.
스팸 감지에서 신고됨:
- 신고를 처리하는 동안 사용자의 의심스러운 활동(예: 사용자 활동의 갑작스러운 변화)을 감지하면 신고를 삭제할 수 있습니다.
- 보고서를 컨텍스트 ID 및 관련 신호(예: 사용자 에이전트, 추천 소스 등)와 함께 저장할 수 있습니다. 나중에 사용자 행동을 분석하고 새로운 스팸 지표를 식별할 때 연결된 컨텍스트 ID 및 신호를 기반으로 저장된 보고서를 재평가할 수 있습니다. 이렇게 하면 처음에 신고되지 않았더라도 의심스러운 활동을 보여주는 사용자의 신고를 삭제할 수 있습니다.

참여 및 의견 공유

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

GitHub: 설명서를 읽고 질문을 하고 토론에 참여하세요.
개발자 지원: 개인 정보 보호 샌드박스 개발자 지원 저장소에서 질문을 게시하고 토론에 참여하세요.
Shared Storage API 그룹 및 Protected Audience API 그룹에 참여하여 Private Aggregation과 관련된 최신 공지사항을 확인하세요.