Ten dokument to krótki przewodnik po użyciu współdzielonego miejsca na dane i prywatnej agregacji. Musisz rozumieć oba interfejsy API, ponieważ Shared Storage przechowuje wartości, a Private Aggregation tworzy raporty podlegające agregacji.
Grupa odbiorców: dostawcy technologii reklamowych i dostawcy usług pomiarowych.
Interfejs Shared Storage API
Aby zapobiegać śledzeniu w wielu witrynach, przeglądarki zaczęły dzielić wszystkie formy pamięci, w tym pamięć lokalną, pliki cookie itp. Istnieją jednak przypadki, w których wymagane jest niepartycjonowane miejsce na dane. Interfejs Shared Storage API zapewnia nieograniczony dostęp do zapisu w różnych witrynach najwyższego poziomu z zachowaniem prywatności i dostępem do odczytu.
Pamięć współdzielona jest ograniczona do pochodzenia kontekstu (wywołującego sharedStorage
).
W przypadku współdzielonego miejsca na dane obowiązuje limit pojemności na źródło, a każdy wpis jest ograniczony do maksymalnej liczby znaków. Po osiągnięciu limitu nie są przechowywane żadne dodatkowe dane wejściowe. Limity miejsca na dane są opisane w artykule na temat współdzielonego miejsca na dane.
Wywoływanie pamięci współdzielonej
Technologia reklamowa może zapisywać dane w Shared Storage za pomocą JavaScripta lub nagłówków odpowiedzi. Odczyt z Shared Storage odbywa się tylko w odizolowanym środowisku JavaScriptu zwanym workletem.
Za pomocą JavaScriptu technologie reklamowe mogą wykonywać określone funkcje wspólnego magazynu, np. ustawiać, dołączać i usuwać wartości poza elementem roboczym JavaScriptu. Jednak funkcje takie jak odczytywanie współdzielonej pamięci i wykonywanie prywatnej agregacji muszą być realizowane za pomocą modułu JavaScript. Metody, których można używać poza modułem JavaScript worklet, można znaleźć w sekcji Proposed API Surface - Outside the worklet (Proponowana interfejs API – poza modułem worklet).
Metody używane w worklecie podczas operacji można znaleźć w sekcji Proponowana interfejsu API – w worklecie.
Używanie nagłówków odpowiedzi
Podobnie jak w przypadku JavaScript, za pomocą nagłówków odpowiedzi można wykonywać tylko określone funkcje, takie jak ustawianie, dołączanie i usuwanie wartości w Shared Storage. Aby korzystać z Shared Storage w nagłówku odpowiedzi, musisz podać wartość
Shared-Storage-Writable: ?1
w nagłówku żądania.Aby zainicjować żądanie z klienta, uruchom ten kod w zależności od wybranej metody:
Jak korzystać z aplikacji
fetch()
fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
Używanie tagu
iframe
lubimg
<iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
Używanie atrybutu IDL z tagiem
iframe
lubimg
let iframe = document.getElementById("my-iframe"); iframe.sharedStorageWritable = true; iframe.src = "https://a.example/path/for/updates";
Więcej informacji znajdziesz w artykule Udostępniona pamięć: nagłówki odpowiedzi.
Zapisywanie danych w pamięci współdzielonej
Aby zapisać dane w Shared Storage, wywołaj funkcję sharedStorage.set()
wewnątrz lub na zewnątrz workleta JavaScript. Jeśli wywołanie pochodzi z zewnątrz workletu, dane są zapisywane w źródle kontekstu przeglądania, z którego zostało wykonane wywołanie. Jeśli wywołanie pochodzi z poziomu workletu, dane są zapisywane w źródle kontekstu przeglądania, z którego załadowano worklet. Ustawione klucze mają datę ważności 30 dni od ostatniej aktualizacji.
Pole ignoreIfPresent
jest opcjonalne. Jeśli ten tag jest obecny i ma wartość true
, klucz nie jest aktualizowany, jeśli już istnieje. Termin ważności klucza zostanie przedłużony do 30 dni od wywołania funkcji set()
, nawet jeśli klucz nie zostanie zaktualizowany.
Jeśli do udostępnionego miejsca na dane uzyskuje się dostęp wielokrotnie podczas wczytywania tej samej strony za pomocą tego samego klucza, wartość klucza jest nadpisywana. Jeśli klucz musi zachować poprzednią wartość, warto użyć opcji sharedStorage.append()
.
Za pomocą kodu JavaScript
Poza workletem:
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'}
Podobnie w ramach modułu:
sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
Używanie nagłówków odpowiedzi
Możesz też zapisywać dane w Shared Storage za pomocą nagłówków odpowiedzi. Aby to zrobić, użyj w nagłówku odpowiedzi wartości
Shared-Storage-Write
wraz z tymi poleceniami:Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
Wiele elementów może być oddzielonych przecinkami i może łączyć atrybuty
set
,append
,delete
iclear
.Shared-Storage-Write : set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
Dołączanie wartości
Wartość możesz dodać do istniejącego klucza, używając metody append. Jeśli taki klucz nie istnieje, wywołanie funkcji append()
tworzy klucz i ustala jego wartość. Możesz to zrobić za pomocą kodu JavaScript lub nagłówków odpowiedzi.
Za pomocą kodu JavaScript
Aby zaktualizować wartości dotychczasowych kluczy, użyj funkcji
sharedStorage.append()
zarówno wewnątrz, jak i poza elementem roboczym.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'}
Aby dodać element do workleta:
sharedStorage.append('myKey', 'myValue1');
Używanie nagłówków odpowiedzi
Podobnie jak w przypadku ustawiania wartości w Storage współdzielonym, możesz użyć parametru
Shared-Storage-Write
w nagłówku odpowiedzi, aby przekazać parę klucz-wartość.Shared-Storage-Write : append;key="myKey";value="myValue2"
Zbiorcze aktualizowanie wartości
Możesz wywoływać funkcję sharedStorage.batchUpdate()
z poziomu workletu JavaScript lub spoza niego i przekazać uporządkowany tablicowo zbiór metod, które określają wybrane operacje. Każdy konstruktor metody akceptuje te same parametry co odpowiadająca mu metoda do ustawiania, dołączania, usuwania i czyszczenia.
Możesz ustawić blokadę za pomocą JavaScriptu lub nagłówka odpowiedzi:
Za pomocą kodu JavaScript
Dostępne metody JavaScript, które można używać z
batchUpdate()
:SharedStorageSetMethod()
: zapisuje parę klucz-wartość w pamięci współdzielonej.SharedStorageAppendMethod()
: dołącza wartość do istniejącego klucza w Shared Storage.SharedStorageDeleteMethod()
: usuwa parę klucz-wartość z pamięci współdzielonej.SharedStorageClearMethod()
: czyści wszystkie klucze w pamięci współdzielonej.
sharedStorage.batchUpdate([ new SharedStorageSetMethod('keyOne', 'valueOne'), new SharedStorageAppendMethod('keyTwo', 'valueTwo'), new SharedStorageDeleteMethod('keyThree'), new SharedStorageClearMethod() ]);
Używanie nagłówków odpowiedzi
Shared-Storage-Write : batchUpdate;methods="set;key=keyOne;value=valueOne, append;key=keyTwo;value=valueTwo,delete;key=keyThree,clear"
Odczyt z pamięci współdzielonej
Z Shared Storage możesz odczytywać dane tylko z poziomu workleta.
await sharedStorage.get('mykey');
Pochodzenie kontekstu przeglądania, z którego załadowano moduł worklet, określa, czytnik czyje dane z Shared Storage.
Usuwanie z pamięci współdzielonej
Możesz usuwać elementy z Shared Storage za pomocą JavaScriptu zarówno wewnątrz, jak i poza workletem lub za pomocą nagłówków odpowiedzi z delete()
. Aby usunąć wszystkie klucze naraz, użyj clear()
z dowolnego klucza.
Za pomocą kodu JavaScript
Aby usunąć z Shared Storage z zewnątrz workleta:
window.sharedStorage.delete('myKey');
Aby usunąć z Shared Storage z poziomu workleta:
sharedStorage.delete('myKey');
Aby usunąć wszystkie klucze naraz z zewnątrz workletu:
window.sharedStorage.clear();
Aby usunąć wszystkie klucze naraz z poziomu workletu:
sharedStorage.clear();
Używanie nagłówków odpowiedzi
Aby usunąć wartości za pomocą nagłówków odpowiedzi, możesz też użyć w nagłówku odpowiedzi parametru
Shared-Storage-Write
, aby przekazać klucz, który ma zostać usunięty.delete;key="myKey"
Aby usunąć wszystkie klucze za pomocą nagłówków odpowiedzi:
clear;
Odczytywanie grup zainteresowań Protected Audience z pamięci współdzielonej
Grupy zainteresowań Protected Audience możesz odczytać z poziomu workletu Shared Storage. Metoda interestGroups()
zwraca tablicę obiektów StorageInterestGroup, w tym atrybuty AuctionInterestGroup i GenerateBidInterestGroup.
Ten przykład pokazuje, jak odczytywać grupy zainteresowań w kontekście przeglądania oraz jakie operacje można wykonywać na wyodrębnionych grupach zainteresowań. Wykonywane są 2 możliwe operacje: określanie liczby grup zainteresowań i wybieranie grupy zainteresowań z największą liczbą podanych stawek.
async function analyzeInterestGroups() {
const interestGroups = await interestGroups();
numIGs = interestGroups.length;
maxBidCountIG = interestGroups.reduce((max, cur) => { return cur.bidCount > max.bidCount ? cur : max; }, interestGroups[0]);
console.log("The IG that bid the most has name " + maxBidCountIG.name);
}
Pochodzenie kontekstu przeglądania, z którego został załadowany moduł workletu, określa pochodzenie grup zainteresowań odczytywanych domyślnie. Więcej informacji o domyślnym pochodzeniu workletu i o tym, jak go zmienić, znajdziesz w sekcji Wykonywanie funkcji wspólnego miejsca na dane i prywatnej agregacji w przewodniku dotyczącym interfejsu Shared Storage API.
Opcje
Wszystkie metody modyfikatora Shared Storage obsługują opcjonalny obiekt opcji jako ostatni argument.
withLock
Opcja withLock
jest opcjonalna. Jeśli jest określona, ta opcja instruuje metodę, aby przed dalszą realizacją zablokować zdefiniowany zasób za pomocą interfejsu Web Locks API. Podczas wysyłania żądania blokady przekazywana jest nazwa blokady. Nazwa reprezentuje zasób, którego użycie jest koordynowane na wielu kartach, w ramach pracowników lub kodu w pochodzeniu.
Opcji withLock
można używać z tymi metodami modyfikacji współdzielonego magazynu:
- zestaw
- append
- usuń
- wyczyść
- aktualizacja zbiorcza
Możesz ustawić blokadę za pomocą JavaScriptu lub nagłówka odpowiedzi:
Za pomocą kodu JavaScript
sharedStorage.set('myKey', 'myValue', { withLock: 'myResource' });
Używanie nagłówków odpowiedzi
Shared-Storage-Write : set;key="myKey";value="myValue";with_lock="myResource"
Blokady pamięci współdzielonej są dzielone według źródła danych. Blokady są niezależne od blokad uzyskanych za pomocą metody LockManager request(), niezależnie od tego, czy są one w kontekście window
czy worker
. Mają jednak ten sam zakres co blokady uzyskane za pomocą funkcji request()
w kontekście SharedStorageWorklet.
Chociaż metoda request()
umożliwia stosowanie różnych opcji konfiguracji, blokady uzyskane w ramach udostępnionej pamięci zawsze stosują te domyślne ustawienia:
mode: "exclusive"
: nie można jednocześnie trzymać żadnych innych blokad o tej samej nazwie.steal: false
: istniejące blokady o tej samej nazwie nie są odblokowywane, aby uwzględnić inne prośby.ifAvailable: false
: żądania oczekują w nieskończoność, aż blokada stanie się dostępna.
Kiedy używać withLock
Blokady są przydatne w sytuacjach, gdy jednocześnie może działać kilka modułów roboczych (np. kilka modułów roboczych na stronie lub kilka modułów roboczych na różnych kartach), z których każdy korzysta z tych samych danych. W takim przypadku warto owinąć odpowiedni kod workleta za pomocą blokady, aby mieć pewność, że tylko jeden worklet będzie przetwarzać raporty w danym momencie.
Blokady są też przydatne, gdy w ramach workleta trzeba odczytać wiele kluczy, których stan powinien być zsynchronizowany. W takim przypadku należy owinąć wywołania get
za pomocą blokady i upewnić się, że podczas zapisywania tych kluczy jest używana ta sama blokada.
Kolejność zamków
Ze względu na charakter blokad internetowych metody modyfikatorów mogą nie być wykonywane w określonej kolejności. Jeśli pierwsza operacja wymaga blokady i jest opóźniona, druga operacja może się rozpocząć przed zakończeniem pierwszej.
Na przykład:
// This line might pause until the lock is available.
sharedStorage.set('keyOne', 'valueOne', { withLock: 'resource-lock' });
// This line will run right away, even if the first one is still waiting.
sharedStorage.set('keyOne', 'valueTwo');
Przykład modyfikacji wielu kluczy
W tym przykładzie blokada zapewnia, że operacje odczytu i usuwania w ramach workletu są wykonywane razem, co zapobiega zakłóceniom z zewnątrz workletu.
W tym przykładzie modify-multiple-keys.js
ustawia nowe wartości dla zmiennych keyOne
i keyTwo
za pomocą modify-lock
, a następnie wykonuje operację modify-multiple-keys
z workletu:
// modify-multiple-keys.js
sharedStorage.batchUpdate([
new SharedStorageSetMethod('keyOne', calculateValueFor('keyOne')),
new SharedStorageSetMethod('keyTwo', calculateValueFor('keyTwo'))
], { withLock: 'modify-lock' });
const modifyWorklet = await sharedStorage.createWorklet('modify-multiple-keys-worklet.js');
await modifyWorklet.run('modify-multiple-keys');
Następnie w ramach modify-multiple-keys-worklet.js
możesz poprosić o zablokowanie dostępu za pomocą navigator.locks.request()
, aby w razie potrzeby odczytać i zmodyfikować klucze.
// modify-multiple-keys-worklet.js
class ModifyMultipleKeysOperation {
async run(data) {
await navigator.locks.request('modify-lock', async (lock) => {
const value1 = await sharedStorage.get('keyOne');
const value2 = await sharedStorage.get('keyTwo');
// Do something with `value1` and `value2` here.
await sharedStorage.delete('keyOne');
await sharedStorage.delete('keyTwo');
});
}
}
register('modify-multiple-keys', ModifyMultipleKeysOperation);
Przełączanie kontekstu
Dane z Shared Storage są zapisywane w źródle (np. https://example.adtech.com) kontekstu przeglądania, z którego pochodzi wywołanie.
Gdy wczytujesz kod innej firmy za pomocą tagu <script>
, kod jest wykonywany w kontekście przeglądarki osoby, która go osadziła. Dlatego gdy kod innej firmy wywołuje funkcję sharedStorage.set()
, dane są zapisywane w Storage współdzielonym autora. Gdy wczytujesz kod zewnętrzny w elementach iframe, kod otrzymuje nowy kontekst przeglądania, a jego źródłem jest źródło elementu iframe. Dlatego wywołanie sharedStorage.set()
wykonane z poziomu iframe zapisuje dane w współdzielonym magazynie danych źródła iframe.
Kontekst własny
Jeśli na stronie własnej jest umieszczony kod JavaScriptu innej firmy, który wywołuje funkcję sharedStorage.set()
lub sharedStorage.delete()
, para klucz-wartość jest przechowywana w kontekście własnym.

Kontekst zewnętrzny
Parę klucz-wartość można przechowywać w technologii reklamowej lub w kontekście zewnętrznym, tworząc iframe i wywołując set()
lub delete()
w kodzie JavaScript w ramach iframe.

Interfejs Private Aggregation API
Aby mierzyć dane zbiorcze przechowywane w Shared Storage, możesz użyć interfejsu Private Aggregation API.
Aby utworzyć raport, wywołaj funkcję contributeToHistogram()
w ramach workletu z workitemem i wartością. Grupa jest reprezentowana przez bez znaku 128-bitową liczbę całkowitą, która musi zostać przekazana do funkcji jako BigInt
. Wartość jest dodatnią liczbą całkowitą.
Ze względu na ochronę prywatności ładunek raportu, który zawiera zbiornik i wartość, jest szyfrowany podczas przesyłania. Można go odszyfrować i zsumować tylko za pomocą usługi agregacji.
Przeglądarka ograniczy też dane, które witryna może przekazać do zapytania wyjściowego. W szczególności budżet udziału ogranicza łączną liczbę raportów z pojedynczej witryny dla danej przeglądarki w danym okresie we wszystkich zbiorach. Jeśli bieżący budżet zostanie przekroczony, raport nie zostanie wygenerowany.
privateAggregation.contributeToHistogram({
bucket: BigInt(myBucket),
value: parseInt(myBucketValue)
});
Wykonywanie operacji Shared Storage i Private Aggregation
Aby uzyskać dostęp do danych z wspólnego miejsca na dane, musisz utworzyć element roboczy. W tym celu wywołaj createWorklet()
z adresem URL workleta. Domyślnie podczas korzystania z wspólnego magazynu danych z createWorklet()
źródłem partycji danych będzie kontekst wywołania, a nie źródło samego skryptu workletu.
Aby zmienić domyślne działanie, ustaw właściwość dataOrigin
podczas wywoływania funkcji createWorklet
.
dataOrigin: "context-origin"
: (domyślnie) dane są przechowywane w wspólnym magazynie danych pochodzenia wywołującego kontekstu przeglądania.dataOrigin: "script-origin"
: dane są przechowywane w wspólnym magazynie danych źródła skryptu workletu. Pamiętaj, że aby włączyć ten tryb, musisz wyrazić na niego zgodę.
sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});
Aby włączyć tę opcję, gdy używasz "script-origin"
, punkt końcowy skryptu musi odpowiadać nagłówkiem Shared-Storage-Cross-Origin-Worklet-Allowed
. Pamiętaj, że żądania z innych domen powinny być włączone w przypadku CORS.
Shared-Storage-Cross-Origin-Worklet-Allowed : ?1
Korzystanie z elementu iframe w wielu domenach
Aby wywołać worklet Shared Storage, musisz użyć iframe.
W elemencie iframe reklamy wczytaj moduł worklet, wywołując funkcję addModule()
. Aby wywołać metodę zarejestrowaną w pliku worklet sharedStorageWorklet.js
, w tym samym kodzie JavaScript iframe reklamy wywołaj funkcję sharedStorage.run()
.
const sharedStorageWorklet = await window.sharedStorage.createWorklet(
'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.run('shared-storage-report', {
data: { campaignId: '1234' },
});
W skrypcie workletu musisz utworzyć klasę z asynchroniczną metodą run
i register
, aby mogła działać w ramce iframe reklamy. WewnątrzsharedStorageWorklet.js
:
class SharedStorageReportOperation {
async run(data) {
// Other code goes here.
bucket = getBucket(...);
value = getValue(...);
privateAggregation.contributeToHistogram({
bucket,
value
});
}
}
register('shared-storage-report', SharedStorageReportOperation);
Korzystanie z żądania z innej domeny
Pamięć współdzielona i prywatna agregacja umożliwiają tworzenie workletów z różnych źródeł bez potrzeby korzystania z elementów iframe pochodzących z różnych źródeł.
Strona własnego źródła może też wywołać createWorklet()
do punktu końcowego JavaScript w innej domenie. Podczas tworzenia elementu roboczego musisz ustawić źródło partycji danych elementu roboczego na takie samo, co w przypadku źródła skryptu.
async function crossOriginCall() {
const privateAggregationWorklet = await sharedStorage.createWorklet(
'https://cross-origin.example/js/worklet.js',
{ dataOrigin: 'script-origin' }
);
await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();
Punkt końcowy JavaScripta w innej domenie musi odpowiadać nagłówkami Shared-Storage-Cross-Origin-Worklet-Allowed
i zaznaczać, że dla żądania jest włączona obsługa CORS.
Shared-Storage-Cross-Origin-Worklet-Allowed : ?1
Elementy robocze utworzone za pomocą createWorklet()
będą miały selectURL
i run()
.
Funkcja addModule()
nie jest dostępna w tym przypadku.
class CrossOriginWorklet {
async run(data){
// Other code goes here.
bucket = getBucket(...);
value = getValue(...);
privateAggregation.contributeToHistogram({
bucket,
value
});
}
}
Dalsze kroki
Na kolejnych stronach znajdziesz ważne informacje o interfejsach API Shared Storage i Private Aggregation.
- Wprowadzenie do udostępnionego miejsca na dane (Chrome dla deweloperów)
- Przykłady użycia wspólnego miejsca na dane (Chrome dla deweloperów)
- Wprowadzenie do prywatnego agregowania (Chrome dla deweloperów)
- Informacje o współdzielonym miejscu na dane (GitHub)
- Informacje o prywatnej agregacji (GitHub)
- Przykładowe użycie współdzielonej pamięci i prywatnej agregacji
Gdy już zapoznasz się z interfejsami API, możesz zacząć zbierać raporty, które są wysyłane jako żądanie POST do podanych niżej punktów końcowych w postaci danych JSON w treści żądania.
- Raporty debugowania –
context-origin/.well-known/private-aggregation/debug/report-shared-storage
- Raporty –
context-origin/.well-known/private-aggregation/report-shared-storage
Po zebraniu raportów możesz przetestować lokalne narzędzie testowe lub skonfigurować zaufane środowisko wykonywania dla usługi agregacji, aby uzyskać zagregowane raporty.
Prześlij opinię
Opinię na temat interfejsów API i dokumentacji możesz wyrazić na GitHub.