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

Private Aggregation API 기본사항

Private Aggregation API의 주요 개념

이 문서의 대상

Private Aggregation API를 사용하면 크로스 사이트 데이터에 액세스할 수 있는 워크릿에서 집계된 데이터를 수집할 수 있습니다. 여기에 공유된 개념은 Shared Storage 및 Protected Audience API 내에서 보고 기능을 빌드하는 개발자에게 중요합니다.

개발자로서 크로스 사이트 측정을 위한 보고 시스템을 구축하는 경우
마케팅 담당자, 데이터 과학자 또는 기타 요약 보고서 사용자인 경우 이러한 메커니즘을 이해하면 최적화된 요약 보고서를 가져오기 위한 설계 결정을 내리는 데 도움이 됩니다.

핵심 용어

이 문서를 읽기 전에 핵심 용어와 개념을 숙지하는 것이 좋습니다. 각 용어는 여기에서 자세히 설명합니다.

집계 키 (버킷이라고도 함)는 미리 결정된 데이터 포인트 모음입니다. 예를 들어 브라우저에서 국가 이름을 보고하는 위치 데이터 버킷을 수집할 수 있습니다. 집계 키에는 두 개 이상의 측정기준 (예: 국가 및 콘텐츠 위젯 ID)이 포함될 수 있습니다.
집계 가능한 값은 집계 키로 수집된 개별 데이터 포인트입니다. 프랑스의 사용자가 내 콘텐츠를 본 횟수를 측정하려면 France이 집계 키의 측정기준이고 1의 viewCount이 집계 가능한 값입니다.
집계 가능한 보고서는 브라우저 내에서 생성되고 암호화됩니다. Private Aggregation API의 경우 단일 이벤트에 관한 데이터가 포함됩니다.
집계 서비스는 집계 가능한 보고서의 데이터를 처리하여 요약 보고서를 만듭니다.
요약 보고서는 집계 서비스의 최종 결과이며, 노이즈가 추가된 집계 사용자 데이터와 세부적인 전환 데이터를 포함합니다.
worklet은 특정 JavaScript 함수를 실행하고 요청자에게 정보를 다시 반환할 수 있는 인프라입니다. 워크릿 내에서는 JavaScript를 실행할 수 있지만 외부 페이지와 상호작용하거나 통신할 수는 없습니다.

Private Aggregation 워크플로

집계 키와 집계 가능한 값을 사용하여 Private Aggregation API를 호출하면 브라우저에서 집계 가능한 보고서를 생성합니다. 보고서는 보고서를 일괄 처리하는 서버로 전송됩니다. 배치된 보고서는 나중에 집계 서비스에서 처리되고 요약 보고서가 생성됩니다.

데이터는 클라이언트에서 수집기로, 수집기에서 집계 서비스로 흘러 요약 보고서를 생성합니다. — 클라이언트에서 수집기로의 데이터 흐름

Private Aggregation API를 호출하면 클라이언트 (브라우저)가 집계 가능한 보고서를 생성하여 수집되도록 서버에 전송합니다.
서버는 클라이언트에서 보고서를 수집하고 집계 서비스로 전송하기 위해 일괄 처리합니다.
보고서가 충분히 수집되면 신뢰할 수 있는 실행 환경에서 실행되는 집계 서비스로 일괄 처리하여 전송하여 요약 보고서를 생성합니다.

이 섹션에 설명된 워크플로는 Attribution Reporting API와 유사합니다. 하지만 기여 분석 보고는 서로 다른 시간에 발생하는 노출 이벤트와 전환 이벤트에서 수집된 데이터를 연결합니다. 비공개 집계는 단일 교차 사이트 이벤트를 측정합니다.

집계 키

집계 키(줄여서 '키')는 집계 가능한 값이 누적되는 버킷을 나타냅니다. 하나 이상의 측정기준을 키에 인코딩할 수 있습니다. 측정기준은 사용자 연령대 또는 광고 캠페인의 노출수와 같이 자세히 알아보고 싶은 측면을 나타냅니다.

예를 들어 여러 사이트에 삽입된 위젯이 있고 위젯을 본 사용자의 국가를 분석하고 싶을 수 있습니다. '내 위젯을 본 사용자 중 X 국가의 사용자는 몇 명인가요?'와 같은 질문에 답하고 싶습니다. 이 질문에 대한 보고서를 작성하려면 위젯 ID와 국가 ID라는 두 가지 측정기준을 인코딩하는 집계 키를 설정하면 됩니다.

Private Aggregation API에 제공되는 키는 여러 측정기준으로 구성된 BigInt입니다. 이 예에서 측정기준은 위젯 ID와 국가 ID입니다. 위젯 ID는 최대 4자리 숫자(예: 1234)이고 각 국가는 알파벳순으로 숫자에 매핑된다고 가정해 보겠습니다(예: 아프가니스탄은 1, 프랑스는 61, 짐바브웨는 195). 따라서 집계 가능한 키는 7자리 길이이며, 처음 4자리는 WidgetID용으로 예약되고 마지막 3자리는 CountryID용으로 예약됩니다.

키가 위젯 ID 3276을 본 프랑스 (국가 ID 061) 사용자의 수를 나타낸다고 가정해 보겠습니다. 집계 키는 3276061입니다.

집계 키
위젯 ID	국가 ID
3276	061

예: 측정기준에 여러 자리에 사용할 수 있는 키 공간이 있지만 값이 더 적은 경우 선행 0을 추가합니다. 예를 들어 국가 ID가 3자리를 허용하는 경우 알제리의 국가 ID는 003입니다.

집계 키는 SHA-256과 같은 해싱 메커니즘으로 생성할 수도 있습니다. 예를 들어 {"WidgetId":3276,"CountryID":67} 문자열을 해싱한 다음 42943797454801331377966796057547478208888578253058197330928948081739249096287n의 BigInt 값으로 변환할 수 있습니다. 해시 값이 128비트를 초과하는 경우 2^128−1의 허용되는 최대 버킷 값을 초과하지 않도록 잘라낼 수 있습니다.

공유 스토리지 워크릿 내에서 해시를 생성하는 데 도움이 되는 crypto 및 TextEncoder 모듈에 액세스할 수 있습니다. 해시 생성에 대해 자세히 알아보려면 MDN의 SubtleCrypto.digest()을 확인하세요.

다음 예에서는 해시된 값에서 버킷 키를 생성하는 방법을 설명합니다.

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

집계 가능한 값

집계 가능한 값은 여러 사용자에 걸쳐 키별로 합산되어 요약 보고서에 요약 값 형태로 집계된 통계를 생성합니다.

이제 앞에서 제시한 질문인 '내 위젯을 본 사용자 중 프랑스에서 온 사용자는 몇 명인가요?'로 돌아가 보겠습니다. 이 질문에 대한 답변은 '위젯 ID 3276을 본 사용자 중 약 4,881명이 프랑스에 거주합니다.'와 같은 형식으로 표시됩니다. 집계 가능한 값은 각 사용자에 대해 1이고, '4881 users'는 해당 집계 키의 모든 집계 가능한 값의 합계인 집계된 값입니다.

집계 키		집계 가능한 값
위젯 ID	국가 ID	조회수
3276	061	1

이 예에서는 위젯을 본 사용자마다 값을 1씩 증가시킵니다. 실제로 집계 가능한 값은 신호 대 노이즈 비율을 개선하기 위해 조정될 수 있습니다.

기여 예산

비공개 집계 API에 대한 각 호출을 기여라고 합니다. 사용자 개인 정보를 보호하기 위해 개인으로부터 수집할 수 있는 참여 수가 제한됩니다.

모든 집계 키에서 집계 가능한 값을 모두 합산하면 합계가 기여 예산보다 작아야 합니다. 예산은 워클릿 출처별, 일별로 범위가 지정되며 Protected Audience API 및 Shared Storage 워클릿에 대해 별도로 적용됩니다. 하루에 대해 지난 24시간의 롤링 윈도우가 사용됩니다. 새 집계 가능 보고서로 인해 예산이 초과되는 경우 보고서가 생성되지 않습니다.

기여 예산은 매개변수 L₁로 표시되며, 일일 10분당 2¹⁶ (65,536)으로 설정되고 백스톱은 2²⁰(1,048,576)입니다. 이러한 매개변수에 대해 자세히 알아보려면 설명을 참고하세요.

기여 예산의 값은 임의로 지정되지만 노이즈는 이 값에 따라 조정됩니다. 이 예산을 사용하여 요약 값의 신호 대 노이즈 비율을 최대화할 수 있습니다(노이즈 및 스케일링 섹션에서 자세히 설명).

기여 예산에 대해 자세히 알아보려면 설명을 참고하세요. 자세한 내용은 기여 예산을 참고하세요.

보고서당 기여 한도

호출자에 따라 기여 한도가 다를 수 있으며, 공유 저장소의 경우 이러한 한도는 재정의할 수 있는 기본값입니다. 현재 Shared Storage API 호출자에 대해 생성된 보고서는 보고서당 20개의 기여로 제한됩니다. 반면 Protected Audience API 호출자는 보고서당 100개의 기여로 제한됩니다. 이러한 한도는 삽입할 수 있는 참여 수와 페이로드 크기의 균형을 맞추기 위해 선택되었습니다.

공유 저장소의 경우 단일 run() 또는 selectURL() 작업 내에서 이루어진 기여는 하나의 보고서로 일괄 처리됩니다. Protected Audience의 경우 입찰 내에서 단일 출처가 제공한 기여는 일괄 처리됩니다.

패딩이 있는 기여

패딩 기능으로 기여가 추가로 수정됩니다. 페이딩은 집계 가능한 보고서에 삽입된 실제 기여 수에 관한 정보를 보호합니다. 패딩은 고정 길이에 도달하기 위해 null 기여 (즉, 값이 0)로 페이로드를 보강합니다.

집계 가능한 보고서

사용자가 Private Aggregation API를 호출하면 브라우저에서 집계 서비스가 나중에 처리하여 요약 보고서를 생성할 수 있는 집계 가능한 보고서를 생성합니다. 집계 가능한 보고서는 JSON 형식이며 암호화된 기여 목록을 포함합니다. 각 기여는 {aggregation key, aggregatable value} 쌍입니다. 집계 가능한 보고서는 최대 1시간의 무작위 지연과 함께 전송됩니다.

기여도는 암호화되어 있으며 집계 서비스 외부에서는 읽을 수 없습니다. 집계 서비스는 보고서를 복호화하고 요약 보고서를 생성합니다. 브라우저의 암호화 키와 집계 서비스의 복호화 키는 키 관리 서비스 역할을 하는 코디네이터에 의해 발급됩니다. 코디네이터는 호출자가 복호화 키를 수신할 수 있는지 확인하기 위해 서비스 이미지의 바이너리 해시 목록을 유지합니다.

디버그 모드가 사용 설정된 집계 가능한 보고서의 예:

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

집계 가능한 보고서는 chrome://private-aggregation-internals 페이지에서 검사할 수 있습니다.

테스트 목적으로 '선택한 보고서 보내기' 버튼을 사용하여 보고서를 서버로 즉시 보낼 수 있습니다.

집계 가능한 보고서 수집 및 일괄 처리

브라우저는 나열된 잘 알려진 경로를 사용하여 Private Aggregation API 호출이 포함된 워크릿의 출처에 집계 가능한 보고서를 전송합니다.

공유 스토리지: /.well-known/private-aggregation/report-shared-storage
Protected Audience의 경우: /.well-known/private-aggregation/report-protected-audience

이러한 엔드포인트에서는 클라이언트에서 전송된 집계 가능한 보고서를 수신하는 수집기 역할을 하는 서버를 운영해야 합니다.

그러면 서버는 보고서를 일괄 처리하고 일괄 처리된 보고서를 집계 서비스에 전송해야 합니다. 집계 가능한 보고서의 암호화되지 않은 페이로드(예: shared_info 필드)에서 제공되는 정보를 기반으로 배치를 만듭니다. 배치당 100개 이상의 보고서를 포함하는 것이 이상적입니다.

일별 또는 주별로 일괄 처리할 수 있습니다. 이 전략은 유연하며, 더 많은 볼륨이 예상되는 특정 이벤트(예: 더 많은 노출이 예상되는 날짜)에 대해 일괄 처리 전략을 변경할 수 있습니다. 배치에는 동일한 API 버전, 보고 출처, 보고 일정 시간의 보고서가 포함되어야 합니다.

필터 ID

Private Aggregation API 및 Aggregation Service를 사용하면 더 큰 쿼리에서 결과를 처리하는 대신 필터링 ID를 사용하여 광고 캠페인별과 같은 더 세부적인 수준에서 측정을 처리할 수 있습니다.

비공개 집계 및 집계 서비스 필터링 ID입니다. — Private Aggregation 및 집계 서비스 필터링 ID.

오늘부터 이 기능을 사용하려면 현재 구현에 적용할 수 있는 대략적인 단계는 다음과 같습니다.

Shared Storage 단계

흐름에서 Shared Storage API를 사용하는 경우:

새 공유 저장소 모듈을 선언하고 실행할 위치를 정의합니다. 다음 예에서는 모듈 파일의 이름을 filtering-worklet.js로 지정하고 filtering-example에 등록했습니다.
```
(async function runFilteringIdsExample () {
await window.sharedStorage.worklet.addModule('filtering-worklet.js');
await window.sharedStorage.run('filtering-example', {
  keepAlive: true,
  privateAggregationConfig: {
    contextId: 'example-id',
    filteringIdMaxBytes: 8 // optional
  }
}});
})();
```
filteringIdMaxBytes은 보고서별로 구성할 수 있으며 설정되지 않은 경우 기본값은 1입니다. 이 기본값은 페이로드 크기를 불필요하게 늘려 스토리지 및 처리 비용을 늘리는 것을 방지하기 위한 것입니다. 자세한 내용은 유연한 기여 설명을 참고하세요.

filtering-worklet.js에서 공유 스토리지 워클릿 내의 privateAggregation.contributeToHistogram(...)에 기여를 전달할 때 필터링 ID를 지정할 수 있습니다.

// Within  filtering-worklet.js
class FilterOperation {
  async run() {
    let contributions = [{
      bucket: 1234n,
      value: 56,
      filteringId: 3n // defaults to 0n if not assigned, type bigint
    }];

    for (const c of contributions) {
      privateAggregation.contributeToHistogram(c);
    }
    …
}
});

register('filtering-example', FilterOperation);

집계 가능한 보고서는 엔드포인트 /.well-known/private-aggregation/report-shared-storage를 정의한 위치로 전송됩니다. ID 필터링 가이드로 계속 이동하여 집계 서비스 작업 매개변수에 필요한 변경사항을 알아보세요.

일괄 처리가 완료되고 배포된 집계 서비스로 전송되면 필터링된 결과가 최종 요약 보고서에 반영됩니다.

Protected Audience 단계

흐름에서 Protected Audience API를 사용하는 경우:

현재 Protected Audience 구현 내에서 다음을 설정하여 Private Aggregation에 연결할 수 있습니다. 공유 스토리지와 달리 필터링 ID의 최대 크기는 아직 구성할 수 없습니다. 기본적으로 필터링 ID 최대 크기는 1바이트이며 0n으로 설정됩니다. 이러한 값은 Protected Audience 보고 함수 (예: reportResult() 또는 generateBid())에 설정됩니다.
```
const contribution = {
  ...
  filteringId: 0n
};

privateAggregation.contributeToHistogram(contribution);
```
집계 가능한 보고서는 엔드포인트 /.well-known/private-aggregation/report-protected-audience를 정의한 위치로 전송됩니다. 일괄 처리가 완료되고 배포된 집계 서비스로 전송되면 필터링된 결과가 최종 요약 보고서에 반영됩니다. Attribution Reporting API 및 Private Aggregation API에 관한 다음 설명서와 초기 제안서가 제공됩니다.

집계 서비스의 ID 필터링 가이드를 계속 읽거나 Attribution Reporting API 섹션으로 이동하여 자세한 내용을 확인하세요.

Aggregation Service

서비스는 TEE에서 실행되고 집계 가능한 보고서를 복호화하고 노이즈를 추가하여 최종 요약 보고서를 생성합니다. — 서비스는 TEE에서 실행되고, 집계 가능한 보고서를 복호화하고, 노이즈를 추가하여 최종 요약 보고서를 생성합니다.

집계 서비스는 수집기에서 암호화된 집계 가능 보고서를 수신하고 요약 보고서를 생성합니다. 수집기에서 집계 가능한 보고서를 일괄 처리하는 방법에 관한 추가 전략은 일괄 처리 가이드를 참고하세요.

이 서비스는 신뢰할 수 있는 실행 환경 (TEE)에서 실행되며, 이는 데이터 무결성, 데이터 기밀성, 코드 무결성을 보장합니다. 코디네이터가 TEE와 함께 사용되는 방식을 자세히 알아보려면 역할과 목적을 자세히 읽어보세요.

요약 보고서

요약 보고서를 사용하면 노이즈가 추가된 수집 데이터를 확인할 수 있습니다. 특정 키 집합에 대한 요약 보고서를 요청할 수 있습니다.

요약 보고서에는 JSON 딕셔너리 스타일의 키-값 쌍 집합이 포함됩니다. 각 쌍에는 다음이 포함됩니다.

bucket: 집계 키(이진수 문자열)입니다. 사용된 집계 키가 '123'이면 버킷은 '1111011'입니다.
value: 노이즈가 추가된 모든 집계 가능한 보고서에서 합산된 특정 측정 목표의 요약 값입니다.

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

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

노이즈 및 스케일링

사용자 개인 정보를 보호하기 위해 집계 서비스는 요약 보고서가 요청될 때마다 각 요약 값에 한 번씩 노이즈를 추가합니다. 노이즈 값은 라플라스 확률 분포에서 무작위로 추출됩니다. 노이즈가 추가되는 방식을 직접 제어할 수는 없지만 측정 데이터에 미치는 노이즈의 영향을 줄일 수는 있습니다.

노이즈 분포는 집계 가능한 모든 값의 합계와 관계없이 동일합니다. 따라서 집계 가능한 값이 높을수록 노이즈가 미치는 영향이 적을 가능성이 높습니다.

예를 들어 노이즈 분포의 표준 편차가 100이고 0을 중심으로 한다고 가정해 보겠습니다. 수집된 집계 가능 보고서 값 (또는 '집계 가능 값')이 200인 경우 노이즈의 표준 편차는 집계된 값의 50% 가 됩니다. 하지만 집계 가능한 값이 20,000이면 노이즈의 표준 편차는 집계된 값의 0.5% 에 불과합니다. 따라서 집계 가능한 값 20,000은 신호 대 노이즈 비율이 훨씬 높습니다.

따라서 집계 가능한 값에 배율을 곱하면 노이즈를 줄일 수 있습니다. 소수 자릿수 계수는 집계 가능한 특정 값을 얼마나 조정할지 나타냅니다.

노이즈는 집계된 값과 관계없이 일정합니다. — 집계된 값과 관계없는 노이즈 상수입니다.

더 큰 스케일링 계수를 선택하여 값을 스케일링하면 상대적 노이즈가 줄어듭니다. 하지만 이렇게 하면 모든 버킷의 모든 기여도 합계가 기여도 예산 한도에 더 빨리 도달하게 됩니다. 더 작은 확장 요소 상수를 선택하여 값을 축소하면 상대적 노이즈가 증가하지만 예산 한도에 도달할 위험이 줄어듭니다.

집계 가능한 값을 기여도 예산으로 조정합니다. — 집계 가능한 값을 기여 예산으로 조정합니다.

적절한 확장 요소를 계산하려면 기여 예산을 모든 키의 집계 가능한 값의 최대 합계로 나눕니다.

자세한 내용은 기여 예산 문서를 참고하세요.

참여 및 의견 공유

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

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

Private Aggregation API 기본사항 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이 문서의 대상

핵심 용어

Private Aggregation 워크플로

집계 키

집계 가능한 값

기여 예산

보고서당 기여 한도

패딩이 있는 기여

집계 가능한 보고서

집계 가능한 보고서 수집 및 일괄 처리

필터 ID

Shared Storage 단계

Protected Audience 단계

Aggregation Service

요약 보고서

노이즈 및 스케일링

참여 및 의견 공유

Private Aggregation API 기본사항