Krótkie wprowadzenie do wdrożenia pamięci współdzielonej i agregacji prywatnej

Ten dokument zawiera krótki przewodnik po korzystaniu z pamięci współdzielonej i agregacji prywatnej. 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 pamięci współdzielonej obowiązuje limit pojemności na punkt początkowy, a każdy wpis jest ograniczony do maksymalnej liczby znaków. Po osiągnięciu limitu dane wejściowe nie są przechowywane. 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ółdzielonego miejsca na dane i wykonywanie prywatnej agregacji muszą być realizowane za pomocą workletu 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 JavaScriptu tylko określone funkcje, takie jak ustawianie, dołączanie i usuwanie wartości w pamięci współdzielonej, można wykonać za pomocą nagłówków odpowiedzi. 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 lub img

      <iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
      
    • Używanie atrybutu IDL z tagiem iframe lub img

      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 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 dane zostaną wywołane spoza Worklet, dane są zapisywane w źródle kontekstu przeglądania, z którego wywołano 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. Ważność klucza jest odnawiana na 30 dni od wywołania set(), nawet jeśli klucz nie został 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().

  • Używanie JavaScriptu

    Poza obszarem roboczym:

    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 workleta:

    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 oraz tych poleceń:

    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, deleteclear.

    Shared-Storage-Write :
    set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
    

Dołączanie wartości

Wartość możesz dołączyć do istniejącego klucza, używając metody append. Jeśli 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.

  • Używanie JavaScriptu

    Aby zaktualizować wartości istniejących kluczy, użyj polecenia sharedStorage.append() wewnątrz lub poza nim.

    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 pamięci współdzielonej, pary klucz-wartość możesz przekazywać za pomocą Shared-Storage-Write w nagłówku odpowiedzi.

    Shared-Storage-Write : append;key="myKey";value="myValue2"
    

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 z nich.

  • Za pomocą kodu JavaScript

    Aby usunąć z Shared Storage z zewnątrz workleta:

    window.sharedStorage.delete('myKey');
    

    Aby usunąć element z udostępnionego magazynu z poziomu workleta:

    sharedStorage.delete('myKey');
    

    Aby usunąć wszystkie klucze naraz z zewnątrz workletu:

    window.sharedStorage.clear();
    

    Aby usunąć wszystkie klucze jednocześnie z 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 Shared-Storage-Write, aby przekazać klucz do usunięcia.

    delete;key="myKey"
    

    Aby usunąć wszystkie klucze za pomocą nagłówków odpowiedzi:

    clear;
    

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 zewnętrzny za pomocą tagu <script>, kod jest wykonywany w kontekście przeglądania w przypadku umieszczonego elementu. Dlatego gdy kod innej firmy wywołuje funkcję sharedStorage.set(), dane są zapisywane w Google Cloud Storage. Gdy ładujesz 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 strona własna zawiera kod JavaScript innej firmy, który wywołuje sharedStorage.set() lub sharedStorage.delete(), para klucz-wartość jest przechowywana w kontekście własnym.

Dane przechowywane na stronie własnej z osadzonym kodem JavaScript należącym do zewnętrznej firmy.

Kontekst firmy zewnętrznej

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.

dane przechowywane w technologiach reklamowych lub w kontekście usług zewnętrznych;

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 contributeToHistogram() w Workletie z zasobnikiem i wartością. Zasobnik jest reprezentowany przez nieoznaczoną 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 funkcję createWorklet(), podając URL workleta. Domyślnie podczas korzystania z wspólnego magazynu danych z createWorklet() źródłem podziału danych będzie kontekst przeglądania wywołania, a nie źródło samego skryptu workletu.

Aby zmienić domyślne działanie, ustaw właściwość dataOrigin przy wywoływaniu funkcji createWorklet.

  • dataOrigin: "context-origin" (domyślna): dane są przechowywane w pamięci współdzielonej punktu początkowego wywołania kontekstu przeglądania.
  • dataOrigin: "script-origin": dane są przechowywane w wspólnym magazynie danych pochodzenia skryptu workletu. 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 w przypadku żądań z różnych domen powinien być włączony 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 uruchomić metodę zarejestrowaną w pliku Worklet sharedStorageWorklet.js, wywołaj sharedStorage.run() w tym samym kodzie JavaScriptu elementu iframe reklamy.

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ą runregister, 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 elementów worklet pochodzących z różnych źródeł bez konieczności 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 modułu roboczego musisz ustawić źródło partycji danych modułu roboczego na takie samo, co źródło 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 opisujemy ważne aspekty interfejsów API pamięci współdzielonej oraz Private Aggregation API.

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 wykonania do obsługi usługi agregacji, aby uzyskać zagregowane raporty.

Prześlij opinię

Swoje opinie na temat interfejsów API i dokumentacji możesz podzielić się na GitHub.