Private Aggregation API 개요

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

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

구현 상태

Private Aggregation API란 무엇인가요?

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

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

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

주요 개념

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

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

비공개 집계 API 기본사항 문서를 참고하여 비공개 집계 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는 '약 317명의 순 사용자가 콘텐츠 ID 861을 확인했습니다'와 같은 답변을 제공할 수 있습니다.

사용자가 콘텐츠를 이미 보았는지 여부를 나타내기 위해 Shared Storage에 플래그를 설정할 수 있습니다. 플래그가 없는 첫 방문 시 비공개 집계가 호출된 후 플래그가 설정됩니다. 크로스 사이트 방문을 포함한 사용자의 후속 방문 시 Shared Storage를 확인하고 플래그가 설정된 경우 Private Aggregation에 보고서를 제출하지 않아도 됩니다. 이러한 측정을 구현하는 방법을 자세히 알아보려면 도달범위 백서를 확인하세요.

인구통계 측정

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

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

K+ 게재빈도 측정

미리 선택한 K 값에 대해 특정 브라우저에서 콘텐츠 또는 광고를 K번 이상 본 사용자 수를 측정할 수 있습니다.

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

멀티 터치 기여 분석

마케팅 기여 분석은 광고주가 마케팅 전략과 후속 광고 상호작용이 매출 또는 전환에 미치는 기여도를 파악하는 데 사용하는 방법입니다.

Protected Audience API 사용 시

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

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

사용 가능한 함수

다음 함수는 Shared Storage 및 Protected Audience API 워크릿에서 사용할 수 있는 privateAggregation 객체에서 사용할 수 있습니다.

contributeToHistogram()

집계 키가 bucket이고 집계 가능한 값이 value인 privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })를 호출할 수 있습니다. bucket 매개변수의 경우 BigInt이 필요합니다. value 매개변수에는 정수 Number가 필요합니다.

다음은 도달범위 측정을 위해 공유 스토리지에서 호출되는 방법의 예입니다.

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를 사용하면 됩니다. 격리된 프레임의 이벤트로 트리거된 보고서를 제출하려면 맞춤 이벤트 유형을 정의하세요. 격리된 프레임에서 이벤트를 트리거하려면 격리된 프레임 광고 보고 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()

서드 파티 쿠키가 아직 제공되는 동안 디버그 모드를 사용 설정하여 더 쉽게 디버깅하고 테스트할 수 있는 임시 메커니즘이 제공됩니다. 디버그 보고서는 쿠키 기반 측정과 Private Aggregation 측정을 비교하는 데 유용하며 API 통합을 빠르게 검증할 수도 있습니다.

worklet에서 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 호출을 통해 생성되는지 확인하여 악의적인 행위자가 보고서를 조작하기 어렵게 합니다.
• 보고서 재생 방지: 이전 보고서의 재사용 시도를 감지하고 거부하여 각 보고서가 집계 결과에 한 번만 반영되도록 합니다.

공유 스토리지

집계 가능한 보고서를 전송할 수 있는 작업을 실행하기 위해 Shared Storage를 사용하는 경우 워크릿 외부에서 예측할 수 없는 ID를 설정할 수 있습니다.

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

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

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

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

Private Aggregation API는 최대 1시간의 무작위 지연으로 집계 가능한 보고서를 전송합니다. 하지만 보고서를 확인하기 위해 컨텍스트 ID를 설정하면 이 지연 시간이 줄어듭니다. 이 경우 공유 스토리지 작업이 시작된 후 고정된 더 작은 지연 시간인 5초가 있습니다.

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

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

컨텍스트 ID 확인

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

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

참여 및 의견 공유

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

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