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

Private Aggregation API 기본사항

Private Aggregation API의 주요 개념

이 문서의 사용 대상

Private Aggregation API는 크로스 사이트 데이터에 액세스할 수 있는 Worklet에서 집계 데이터 수집을 지원합니다. 여기에서 설명하는 개념은 Shared Storage 및 Protected Audience API 내에서 보고 기능을 빌드하는 개발자에게 중요합니다.

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

핵심 용어

이 문서를 읽기 전에 주요 용어와 개념을 알면 도움이 됩니다. 각 용어는 여기에 자세히 설명되어 있습니다.

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

비공개 집계 워크플로

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

데이터는 클라이언트에서 수집기로 이동한 다음 집계 서비스로 이동하여 요약 보고서를 생성합니다.

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

이 섹션에서 설명하는 워크플로는 Attribution Reporting API와 유사합니다. 그러나 Attribution Reporting은 서로 다른 시간에 발생하는 노출 이벤트에서 수집된 데이터와 전환 이벤트를 연결합니다. 비공개 집계는 단일 크로스 사이트 이벤트를 측정합니다.

집계 키

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

예를 들어 여러 사이트에 삽입된 위젯이 있고 내 위젯을 본 사용자의 국가를 분석하려고 할 수 있습니다. '내 위젯을 본 사용자 중 몇 명이 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를 초과하지 않도록 자를 수 있습니다.

공유 저장소 Worklet 내에서 해시를 생성하는 데 도움이 되는 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

집계 가능한 값

집계 가능한 값은 많은 사용자에 대해 키별로 합산되어 요약 보고서의 요약 값 형식으로 집계된 통계를 생성합니다.

이제 이전에 제기했던 예시 질문으로 돌아갑니다. '내 위젯을 본 사용자 중 프랑스 출신은 몇 명입니까?' 이 질문에 대한 답변은 '내 Widget ID 3276을 확인한 사용자 약 4,881명은 프랑스 사용자입니다.'와 같이 표시됩니다. 집계 가능한 값은 각 사용자에 대해 1이고 '4881 사용자'는 해당 집계 키의 모든 집계 가능한 값의 합계인 집계 값입니다.

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

이 예에서는 위젯을 보는 각 사용자에 대해 값을 1씩 증분합니다. 실제로는 집계 가능한 값을 확장하여 신호 대 잡음 비율을 개선할 수 있습니다.

후원 예산

각 Private Aggregation API 호출을 참여라고 합니다. 사용자 개인 정보 보호를 위해 개인으로부터 수집할 수 있는 기여의 수는 제한되어 있습니다.

모든 집계 키에서 모든 집계 가능한 값을 합산할 때 합계가 기여 예산보다 작아야 합니다. 예산 범위는 Worklet 출처, 하루 단위로 지정되며 Protected Audience API 및 공유 저장소 Worklet에 대해 별개입니다. 하루에는 약 24시간의 순환 기간이 사용됩니다. 집계 가능한 새 보고서로 인해 예산이 초과되는 경우에는 보고서가 생성되지 않습니다.

참여 예산은 매개변수 L₁로 표시되며, 하루 10분당 2¹⁶ (65,536)으로 설정되고 백스톱은 2²⁰으로 설정됩니다.

(1,048,576) 이러한 매개변수에 대한 자세한 내용은 설명서를 참고하세요.

기여 예산의 값은 임의적이지만 노이즈가 여기에 조정됩니다. 이 예산을 사용하여 요약 값의 신호 대 잡음 비율을 최대화할 수 있습니다(자세한 내용은 노이즈 및 조정 섹션에서 설명).

후원 예산에 대한 자세한 내용은 설명서를 참고하세요. 자세한 내용은 참여 예산을 참고하세요.

집계 가능한 보고서

사용자가 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 페이지에서 검사할 수 있습니다.

테스트 목적으로 'Send Selected Reports' 버튼을 사용하여 보고서를 서버로 즉시 보낼 수 있습니다.

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

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

공유 저장소: /.well-known/private-aggregation/report-shared-storage
Protected Audience: /.well-known/private-aggregation/report-protected-audience

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

그런 다음 서버는 보고서를 일괄 처리하고 일괄 처리 서비스를 집계 서비스로 전송합니다. shared_info 필드와 같이 집계 가능한 보고서의 암호화되지 않은 페이로드에서 사용할 수 있는 정보를 기반으로 배치를 만듭니다. 배치에 배치당 100개 이상의 보고서를 포함하는 것이 이상적입니다.

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

집계 서비스

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

집계 서비스는 수집기로부터 암호화된 집계 가능한 보고서를 수신하여 요약 보고서를 생성합니다.

보고서 페이로드를 복호화하기 위해 집계 서비스는 조정자에서 복호화 키를 가져옵니다. 이 서비스는 데이터 무결성, 데이터 기밀성, 코드 무결성을 어느 정도 보장하는 신뢰할 수 있는 실행 환경 (TEE)에서 실행됩니다. 서비스를 소유하고 운영하지만 TEE 내에서 처리 중인 데이터를 볼 수는 없습니다.

요약 보고서

요약 보고서에서는 노이즈를 추가하여 수집한 데이터를 확인할 수 있습니다. 지정된 키 세트에 관한 요약 보고서를 요청할 수 있습니다.

요약 보고서에는 JSON 사전 스타일의 키-값 쌍 조합이 포함되어 있습니다. 각 쌍에는 다음이 포함됩니다.

bucket: 2진수 문자열인 집계 키 사용되는 집계 키가 '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 그룹에 가입하세요.