이 문서는 공유 저장소 및 비공개 집계 사용에 관한 빠른 시작 가이드입니다. 공유 저장소는 값을 저장하고 비공개 집계는 집계 가능한 보고서를 만들기 때문에 두 API를 모두 이해해야 합니다.
대상: 광고 기술 및 측정 제공업체
데모 사용해 보기
라이브 데모 사용해 보기 데모 안내의 단계에 따라 개인 정보 보호 샌드박스 API를 사용 설정합니다. Chrome DevTools를 열면 다양한 사용 사례의 결과를 시각화할 수 있습니다. 데모에서 제공되는 사용 사례:
- 비공개 집계
- Unique Reach 측정
- 인구통계 측정
- K+ 게재빈도 측정
- 일반적인 사용법
- 분리 프레임 내에서 마우스 오버 이벤트 측정
- 최상위 탐색
- 서드 파티가 작성할 수 있는 위치 제어
공유 스토리지 확인 방법
공유 저장소에 저장된 내용을 보려면 Chrome DevTools를 사용하세요. 저장된 데이터는 Application -> Shared Storage에서 찾을 수 있습니다.
비공개 집계 보고서 보기
전송된 집계 가능한 보고서를 보려면 chrome://private-aggregation-internals로 이동합니다. 디버그 모드가 사용 설정되면 보고서는 지연 없이 즉시 [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage로 전송되어 시간이 지연된 보고서와 함께 [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage로 전송됩니다.
디버깅을 사용 설정하려면 디버깅 섹션의 안내를 따르세요.
공유 저장소 API
크로스 사이트 추적을 방지하기 위해 브라우저는 로컬 저장소, 쿠키 등을 포함한 모든 형태의 저장소를 분할하기 시작했습니다. 그러나 파티션을 나누지 않은 스토리지가 필요한 사용 사례도 있습니다. Shared Storage API는 여러 최상위 사이트에서 개인 정보를 보호하는 읽기 액세스 권한을 보유한 무제한 쓰기 액세스를 제공합니다.
공유 저장소는 컨텍스트 출처 (sharedStorage의 호출자)로 제한됩니다.
공유 스토리지에는 출처당 용량 제한이 있으며 각 항목의 최대 문자 수로 제한됩니다. 이 한도에 도달하면 더 이상 입력이 저장되지 않습니다. 데이터 저장용량 한도는 공유 저장소 설명에 설명되어 있습니다.
공유 저장소 호출
광고 기술은 JavaScript 또는 응답 헤더를 사용하여 공유 저장소에 쓸 수 있습니다. 공유 저장소에서 읽기는 Worklet이라고 하는 격리된 JavaScript 환경 내에서만 이루어집니다.
자바스크립트 사용 광고 기술은 JavaScript Worklet 외부의 값 설정, 추가, 삭제와 같은 특정 공유 저장소 기능을 실행할 수 있습니다. 그러나 공유 저장소 읽기 및 비공개 집계 수행과 같은 함수는 JavaScript Worklet을 통해 완료해야 합니다. JavaScript Worklet 외부에서 사용할 수 있는 메서드는 제안된 API 노출 영역 - worklet 외부에서 확인할 수 있습니다.
작업 중에 Worklet에서 사용되는 메서드는 제안된 API 노출 영역 - Worklet 내에서 확인할 수 있습니다.
응답 헤더 사용
자바스크립트와 마찬가지로, 공유 저장소의 값 설정, 추가, 삭제와 같은 특정 함수만 응답 헤더를 사용하여 수행할 수 있습니다. 응답 헤더에서 공유 저장소를 사용하려면 요청 헤더에
Shared-Storage-Writable: ?1를 포함해야 합니다.클라이언트에서 요청을 시작하려면 선택한 방법에 따라 다음 코드를 실행합니다.
fetch()사용fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});iframe또는img태그 사용<iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>iframe또는img태그와 함께 IDL 속성 사용let iframe = document.getElementById("my-iframe"); iframe.sharedStorageWritable = true; iframe.src = "https://a.example/path/for/updates";
자세한 내용은 공유 저장소: 응답 헤더를 참고하세요.
공유 저장소에 쓰기
공유 저장소에 쓰려면 JavaScript Worklet 내부 또는 외부에서 sharedStorage.set()를 호출합니다. Worklet 외부에서 호출되면 데이터는 호출이 발생한 탐색 컨텍스트의 출처에 기록됩니다. Worklet 내에서 호출하면 데이터는 Worklet을 로드한 탐색 컨텍스트의 출처에 기록됩니다. 설정된 키의 만료일은 최종 업데이트로부터 30일입니다.
ignoreIfPresent 필드는 선택사항입니다. 이 키가 있고 true로 설정된 경우 키가 이미 있으면 업데이트되지 않습니다. 키가 업데이트되지 않은 경우에도 키 만료가 set() 호출로부터 30일로 갱신됩니다.
동일한 페이지 로드 중에 동일한 키로 공유 저장소에 여러 번 액세스하면 키 값을 덮어씁니다. 키가 이전 값을 유지해야 하는 경우 sharedStorage.append()를 사용하는 것이 좋습니다.
자바스크립트 사용
Worklet 외부:
window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true }); // Shared Storage: {'myKey': 'myValue1'} window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true }); // Shared Storage: {'myKey': 'myValue1'} window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false }); // Shared Storage: {'myKey': 'myValue2'}마찬가지로 Worklet 내에서 다음을 실행합니다.
sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });응답 헤더 사용
응답 헤더를 사용하여 공유 스토리지에 쓸 수도 있습니다. 이렇게 하려면 응답 헤더의
Shared-Storage-Write를 다음 명령어와 함께 사용합니다.Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_presentShared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0여러 항목을 쉼표로 구분하여
set,append,delete,clear를 결합할 수 있습니다.Shared-Storage-Write : set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
값 추가
추가 메서드를 사용하여 기존 키에 값을 추가할 수 있습니다. 키가 없는 경우 append()를 호출하면 키가 생성되고 값이 설정됩니다. 자바스크립트 또는 응답 헤더를 사용하면 됩니다.
자바스크립트 사용
기존 키의 값을 업데이트하려면 worklet 내부 또는 외부에서
sharedStorage.append()를 사용합니다.window.sharedStorage.append('myKey', 'myValue1'); // Shared Storage: {'myKey': 'myValue1'} window.sharedStorage.append('myKey', 'myValue2'); // Shared Storage: {'myKey': 'myValue1myValue2'} window.sharedStorage.append('anotherKey', 'hello'); // Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}Worklet 내에 추가하는 방법은 다음과 같습니다.
sharedStorage.append('myKey', 'myValue1');응답 헤더 사용
공유 저장소에서 값을 설정하는 것과 마찬가지로 응답 헤더의
Shared-Storage-Write를 사용하여 키-값 쌍을 전달할 수 있습니다.Shared-Storage-Write : append;key="myKey";value="myValue2"
공유 저장소에서 읽기
Worklet 내에서만 공유 스토리지에서 읽을 수 있습니다.
await sharedStorage.get('mykey');
Worklet 모듈이 로드된 탐색 컨텍스트의 출처는 공유 저장소를 읽을 사용자를 결정합니다.
공유 저장소에서 삭제 중
Worklet 내부 또는 외부에서 JavaScript를 사용하거나 응답 헤더와 delete()를 사용하여 공유 저장소에서 삭제를 실행할 수 있습니다.
한 번에 모든 키를 삭제하려면 둘 중 하나에서 clear()를 사용합니다.
자바스크립트 사용
Worklet 외부의 공유 스토리지에서 삭제하려면 다음 안내를 따르세요.
window.sharedStorage.delete('myKey');Worklet 내부의 공유 스토리지에서 삭제하려면 다음을 실행하세요.
sharedStorage.delete('myKey');Worklet 외부에서 모든 키를 한 번에 삭제하려면 다음 안내를 따르세요.
window.sharedStorage.clear();Worklet 내에서 모든 키를 한 번에 삭제하려면 다음 안내를 따르세요.
sharedStorage.clear();응답 헤더 사용
응답 헤더를 사용하여 값을 삭제하려면 응답 헤더에
Shared-Storage-Write를 사용하여 삭제할 키를 전달하면 됩니다.delete;key="myKey"응답 헤더를 사용하여 모든 키를 삭제하려면 다음 안내를 따르세요.
clear;
컨텍스트 전환
공유 저장소 데이터는 호출이 시작된 탐색 컨텍스트의 출처(예: https://example.adtech.com)에 기록됩니다.
<script> 태그를 사용하여 서드 파티 코드를 로드하면 코드는 임베딩의 탐색 컨텍스트에서 실행됩니다. 따라서 서드 파티 코드가 sharedStorage.set()를 호출하면 데이터는 임베딩의 공유 저장소에 작성됩니다. iframe 내에서 서드 파티 코드를 로드하면 코드가 새로운 탐색 컨텍스트를 수신하며 출처가 iframe의 출처입니다. 따라서 iframe에서 실행된 sharedStorage.set() 호출은 데이터를 iframe 출처의 공유 저장소에 저장합니다.
퍼스트 파티 맥락
퍼스트 파티 페이지에 sharedStorage.set() 또는 sharedStorage.delete()를 호출하는 서드 파티 자바스크립트 코드가 삽입된 경우 키-값 쌍은 퍼스트 파티 컨텍스트에 저장됩니다.
서드 파티 컨텍스트
키-값 쌍은 iframe을 만들고 iframe 내 JavaScript 코드에서 set() 또는 delete()를 호출하여 광고 기술 또는 서드 파티 컨텍스트에 저장할 수 있습니다.
비공개 집계 API
Shared Storage에 저장된 집계 가능한 데이터를 측정하려면 Private Aggregation API를 사용하면 됩니다.
보고서를 만들려면 버킷과 값을 사용하여 Worklet 내에서 contributeToHistogram()를 호출합니다. 버킷은 함수에 BigInt로 전달되어야 하는 부호 없는 128비트 정수로 표시됩니다. 값은 양의 정수입니다.
개인 정보 보호를 위해 버킷과 값이 포함된 보고서의 페이로드는 전송 중에 암호화되며 집계 서비스를 통해서만 복호화하고 집계할 수 있습니다.
또한 브라우저는 사이트가 출력 쿼리에 대해 제공할 수 있는 기여를 제한합니다. 특히 참여 예산은 모든 버킷에서 지정된 기간 동안 특정 브라우저에 대한 단일 사이트의 모든 보고서 합계를 제한합니다. 현재 예산을 초과하면 보고서가 생성되지 않습니다.
privateAggregation.contributeToHistogram({
bucket: BigInt(myBucket),
value: parseInt(myBucketValue)
});
공유 저장소 및 비공개 집계 실행
광고의 iframe에서 addModule()를 호출하여 Worklet 모듈을 로드합니다.
sharedStorageWorklet.js Worklet 파일에 등록된 메서드를 실행하려면 동일한 광고 iframe JavaScript에서 sharedStorage.run()를 호출합니다.
await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
data: { campaignId: '1234' },
});
Worklet 스크립트에서 비동기 run 메서드를 사용하여 클래스를 만들어야 합니다. register: 이 클래스를 광고의 iframe에서 실행합니다.
sharedStorageWorklet.js 내부:
class SharedStorageReportOperation {
async run(data) {
// Other code goes here.
bucket = getBucket(...);
value = getValue(...);
privateAggregation.contributeToHistogram({
bucket: bucket,
value: value
});
}
}
register('shared-storage-report',
SharedStorageReportOperation);
디버깅
디버깅을 사용 설정하려면 공유 저장소 및 비공개 집계가 사용되는 동일한 컨텍스트에서 enableDebugMode() JavaScript 메서드를 호출합니다. 이는 동일한 컨텍스트의 향후 보고서에도 적용됩니다.
privateAggregation.enableDebugMode();
보고서를 트리거한 컨텍스트와 연결하려면 JavaScript 호출에 전달되는 부호 없는 64비트 정수 디버그 키를 설정하면 됩니다. debugKey은 BigInt입니다.
privateAggregation.enableDebugMode({debugKey: 1234});
공유 저장소 디버깅
Shared Storage가 일반적인 오류 메시지를 반환합니다.
Promise is rejected without and explicit error message
호출을 try-catch 블록으로 래핑하여 공유 저장소를 디버그할 수 있습니다.
try {
privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
console.log(e);
}
비공개 집계 디버깅
보고서는 /.well-known/private-aggregation/report-shared-storage 및 /.well-known/private-aggregation/debug/report-shared-storage로 전송됩니다.
디버그 보고서는 다음 JSON과 유사한 페이로드를 수신합니다. 이 페이로드는 api 필드를 'shared-storage'로 정의합니다.
{
"aggregation_coordinator_identifier": "aws-cloud",
"aggregation_service_payloads": [ {
"debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
"key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
"payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
} ],
"debug_key": "1234",
"shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}
일반 텍스트 페이로드 디버그
debug_cleartext_payload는 Base64
CBOR로 인코딩됩니다. 디코더를 사용하거나 공유 저장소 디코더에 있는 자바스크립트 코드를 사용하여 버킷과 값을 확인할 수 있습니다.
다음 단계
다음 페이지에서는 Shared Storage 및 Private Aggregation API의 중요한 측면을 설명합니다.
- 공유 저장소 소개 (개발자 Chrome)
- 공유 저장소 사용 사례 (개발자 Chrome)
- 비공개 집계 소개 (개발자 Chrome)
- 공유 스토리지 설명 (GitHub)
- 비공개 집계 설명 (GitHub)
- 공유 스토리지 및 비공개 집계 데모
API에 익숙해지면 요청 본문에서 JSON으로 다음 엔드포인트에 POST 요청으로 전송되는 보고서 수집을 시작할 수 있습니다.
- 디버그 보고서 -
context-origin/.well-known/private-aggregation/debug/report-shared-storage - 보고서 -
context-origin/.well-known/private-aggregation/report-shared-storage
보고서가 수집되면 로컬 테스트 도구를 사용하여 테스트하거나 집계 서비스를 위한 신뢰할 수 있는 실행 환경을 설정하여 집계된 보고서를 가져올 수 있습니다.
의견 공유
GitHub에서 API 및 문서에 관한 의견을 공유할 수 있습니다.