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

공유 저장소 및 비공개 집계 구현 빠른 시작

이 문서는 공유 저장소 및 비공개 집계를 사용하는 방법을 안내하는 빠른 시작 가이드입니다. 공유 저장소는 값을 저장하고 Private Aggregation은 집계 가능한 보고서를 만들므로 두 API를 모두 이해해야 합니다.

대상: 광고 기술 및 측정 제공업체

Shared Storage API

크로스 사이트 추적을 방지하기 위해 브라우저는 로컬 저장소, 쿠키 등을 비롯한 모든 형태의 저장소를 파티셔닝하기 시작했습니다. 하지만 파티션되지 않은 스토리지가 필요한 사용 사례도 있습니다. Shared Storage API는 개인 정보를 보호하는 읽기 액세스 권한으로 여러 최상위 사이트에서 무제한 쓰기 액세스를 제공합니다.

공유 저장소는 컨텍스트 출처 (sharedStorage의 호출자)로 제한됩니다.

공유 저장소에는 출처당 용량 제한이 있으며 각 항목은 최대 문자 수로 제한됩니다. 한도에 도달하면 더 이상 입력이 저장되지 않습니다. 데이터 스토리지 한도는 공유 저장용량 설명에 설명되어 있습니다.

공유 저장소 호출

광고 기술은 JavaScript 또는 응답 헤더를 사용하여 공유 저장소에 쓸 수 있습니다. 공유 저장소에서 읽기는 워크렛이라는 격리된 JavaScript 환경 내에서만 발생합니다.

JavaScript 사용 광고 기술은 JavaScript 워크렛 외부에서 값 설정, 추가, 삭제와 같은 특정 공유 스토리지 기능을 실행할 수 있습니다. 그러나 공유 저장소 읽기, 비공개 집계 실행과 같은 함수는 JavaScript 워크렛을 통해 완료해야 합니다. JavaScript Worklet 외부에서 사용할 수 있는 메서드는 제안된 API 노출 영역 - Worklet 외부에서 찾을 수 있습니다.

작업 중에 워크렛에서 사용되는 메서드는 제안된 API 노출 영역 - 워크렛에서 확인할 수 있습니다.
응답 헤더 사용

JavaScript와 마찬가지로 공유 저장소에서 값을 설정, 추가, 삭제하는 등의 특정 함수만 응답 헤더를 사용하여 실행할 수 있습니다. 응답 헤더에서 공유 저장소를 사용하려면 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 워크렛 안팎에서 sharedStorage.set()를 호출합니다. Worklet 외부에서 호출되면 호출이 실행된 브라우징 컨텍스트의 출처에 데이터가 작성됩니다. Worklet 내에서 호출되면 Worklet을 로드한 브라우징 컨텍스트의 출처에 데이터가 작성됩니다. 설정된 키의 만료일은 마지막 업데이트 후 30일입니다.

ignoreIfPresent 필드는 선택사항입니다. 키가 존재하고 true로 설정된 경우 키가 이미 있으면 업데이트되지 않습니다. 키가 업데이트되지 않더라도 set() 호출 후 30일로 키 만료가 갱신됩니다.

동일한 페이지 로드에서 동일한 키로 공유 저장소에 여러 번 액세스하면 키의 값이 덮어쓰기됩니다. 키가 이전 값을 유지해야 하는 경우 sharedStorage.append()를 사용하는 것이 좋습니다.

JavaScript 사용

워크렛 외부:

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'}

마찬가지로 워크렛 내부에서 다음과 같이 실행됩니다.

sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });

응답 헤더 사용

응답 헤더를 사용하여 공유 저장공간에 쓸 수도 있습니다. 이렇게 하려면 응답 헤더에서 다음 명령어와 함께 Shared-Storage-Write를 사용하세요.
```
Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
```
```
Shared-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 메서드를 사용하여 기존 키에 값을 추가할 수 있습니다. 키가 없는 경우 append()를 호출하면 키가 생성되고 값이 설정됩니다. JavaScript 또는 응답 헤더를 사용하여 이 작업을 실행할 수 있습니다.

JavaScript 사용

기존 키 값을 업데이트하려면 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'}

워크렛 내부에 추가하려면 다음을 실행합니다.

sharedStorage.append('myKey', 'myValue1');

응답 헤더 사용

공유 저장소에 값을 설정하는 것과 마찬가지로 응답 헤더의 Shared-Storage-Write를 사용하여 키-값 쌍을 전달할 수 있습니다.
```
Shared-Storage-Write : append;key="myKey";value="myValue2"
```

공유 저장소에서 읽기

공유 저장소는 워크렛 내에서만 읽을 수 있습니다.

await sharedStorage.get('mykey');

워크렛 모듈이 로드된 탐색 컨텍스트의 출처에 따라 누가 공유 저장소를 읽는지 결정됩니다.

공유 저장공간에서 삭제 중

워크렛 안팎에서 JavaScript를 사용하거나 delete()와 함께 응답 헤더를 사용하여 공유 저장소에서 삭제를 실행할 수 있습니다. 한 번에 모든 키를 삭제하려면 둘 중 하나에서 clear()를 사용합니다.

JavaScript 사용

워크렛 외부에서 공유 저장소를 삭제하려면 다음 단계를 따르세요.
```
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()를 호출하는 서드 파티 JavaScript 코드가 삽입된 경우 키-값 쌍이 퍼스트 파티 컨텍스트에 저장됩니다.

서드 파티 JavaScript가 삽입된 퍼스트 파티 페이지에 저장된 데이터입니다.

서드 파티 컨텍스트

키-값 쌍은 iframe을 만들고 iframe 내에서 JavaScript 코드에서 set() 또는 delete()를 호출하여 광고 기술 또는 서드 파티 컨텍스트에 저장할 수 있습니다.

Private Aggregation API

공유 저장소에 저장된 집계 가능한 데이터를 측정하려면 PrivateAggregation API를 사용하면 됩니다.

보고서를 만들려면 버킷과 값이 있는 워크렛 내에서 contributeToHistogram()를 호출합니다. 버킷은 부호 없는 128비트 정수로 표시되며 함수에 BigInt로 전달해야 합니다. 값은 양의 정수입니다.

개인 정보를 보호하기 위해 버킷과 값이 포함된 보고서의 페이로드는 전송 중에 암호화되며 집계 서비스를 사용하여만 복호화하고 집계할 수 있습니다.

또한 브라우저는 사이트가 출력 쿼리에 제공할 수 있는 기여도를 제한합니다. 특히 참여도 예산은 모든 버킷에서 특정 시간대에 특정 브라우저의 단일 사이트에서 발생한 모든 보고서의 합계를 제한합니다. 현재 예산을 초과하면 보고서가 생성되지 않습니다.

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

공유 저장소 및 비공개 집계 실행

공유 저장소의 데이터에 액세스하려면 워크렛을 만들어야 합니다. 이렇게 하려면 워크렛의 URL을 사용하여 createWorklet()를 호출합니다. 기본적으로 createWorklet()와 함께 공유 저장소를 사용하는 경우 데이터 파티션 출처는 워크렛 스크립트 자체의 출처가 아닌 호출 브라우징 컨텍스트의 출처가 됩니다.

기본 동작을 변경하려면 createWorklet를 호출할 때 dataOrigin 속성을 설정합니다.

dataOrigin: "context-origin": (기본값) 데이터가 호출 브라우징 컨텍스트의 출처의 공유 저장소에 저장됩니다.
dataOrigin: "script-origin": 데이터가 워크렛 스크립트 출처의 공유 저장소에 저장됩니다. 이 모드를 사용하려면 선택해야 합니다.

sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

선택하려면 "script-origin"를 사용할 때 스크립트 엔드포인트가 Shared-Storage-Cross-Origin-Worklet-Allowed 헤더로 응답해야 합니다. 교차 출처 요청에는 CORS를 사용 설정해야 합니다.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

교차 출처 iframe 사용

공유 저장소 워크렛을 호출하려면 iframe이 필요합니다.

광고의 iframe에서 addModule()를 호출하여 워크렛 모듈을 로드합니다. sharedStorageWorklet.js 워크렛 파일에 등록된 메서드를 실행하려면 동일한 광고 iframe JavaScript에서 sharedStorage.run()를 호출합니다.

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.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,
      value
    });
  }
}
register('shared-storage-report', SharedStorageReportOperation);

교차 출처 요청 사용

공유 저장소 및 비공개 집계를 사용하면 교차 출처 iframe 없이 교차 출처 워크릿을 만들 수 있습니다.

퍼스트 파티 페이지는 교차 출처 JavaScript 엔드포인트에 대한 createWorklet() 호출을 호출할 수도 있습니다. 워크렛을 만들 때 워크렛의 데이터 파티션 출처를 스크립트 출처로 설정해야 합니다.

async function crossOriginCall() {
  const privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.example/js/worklet.js',
    { dataOrigin: 'script-origin' }
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

교차 출처 JavaScript 엔드포인트는 Shared-Storage-Cross-Origin-Worklet-Allowed 헤더로 응답해야 하며 요청에 CORS가 사용 설정되어 있음을 확인합니다.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

createWorklet()를 사용하여 만든 워크렛에는 selectURL 및 run()가 있습니다. addModule()에서는 이 기능을 사용할 수 없습니다.

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}

다음 단계

다음 페이지에서는 Shared Storage API 및 Private Aggregation API의 중요한 측면을 설명합니다.

API에 익숙해지면 보고서 수집을 시작할 수 있습니다. 이 보고서는 다음 엔드포인트에 POST 요청으로 요청 본문에서 JSON으로 전송됩니다.

디버그 보고서 - context-origin/.well-known/private-aggregation/debug/report-shared-storage
보고서 - context-origin/.well-known/private-aggregation/report-shared-storage

보고서가 수집되면 로컬 테스트 도구를 사용하여 테스트하거나 집계 서비스를 위한 신뢰할 수 있는 실행 환경을 설정하여 집계 보고서를 가져올 수 있습니다.

의견 공유하기

GitHub의 API 및 문서에 관한 의견을 공유할 수 있습니다.