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

Ten dokument zawiera krótkie wprowadzenie do korzystania z pamięci współdzielonej i agregacji prywatnej. Konieczna jest znajomość obu interfejsów API, ponieważ pamięć współdzielona przechowuje wartości, a agregacja prywatna tworzy raporty z możliwością agregacji.

Docelowi odbiorcy: dostawcy technologii reklamowych i usług pomiarowych.

Wypróbuj wersję demonstracyjną

Wypróbuj prezentację na żywo. Wykonaj czynności opisane w instrukcjach demonstracyjnych, aby włączyć interfejsy API Piaskownicy prywatności. Otwarcie Narzędzi deweloperskich w Chrome pozwala zwizualizować wyniki różnych zastosowań. Przypadki użycia dostępne w wersji demonstracyjnej:

• Agregacja prywatna
  • Pomiar zasięgu wśród unikalnych użytkowników
  • Pomiar danych demograficznych
  • Pomiar częstotliwości K+
• Zastosowanie ogólne
  • Mierz zdarzenie najechania kursorem w chronionych ramkach
  • Nawigacja najwyższego poziomu
  • Określanie, gdzie inne firmy mogą zapisywać

Jak wyświetlić pamięć współdzieloną

Aby zobaczyć, co jest przechowywane w pamięci współdzielonej, użyj Narzędzi deweloperskich w Chrome. Zapisane dane można znaleźć tutaj: Application -> Shared Storage.

Wyświetlanie raportów agregacji prywatnej

Aby wyświetlić wysłane raporty zbiorcze, otwórz chrome://private-aggregation-internals. Gdy tryb debugowania jest włączony, raport jest wysyłany natychmiast (bez opóźnienia) na [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage wraz z raportem opóźnionym, który ma zostać wysłany do [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage.

Aby włączyć debugowanie, postępuj zgodnie z instrukcjami w sekcji debugowania.

Interfejs Shared Storage API

Aby zapobiec śledzeniu w witrynach, przeglądarki zaczęły partycjonować wszystkie formy pamięci, w tym pamięć lokalną, pliki cookie itd. Istnieją jednak przypadki użycia, w których wymagane jest miejsce na dane bez partycji. Interfejs Shared Storage API zapewnia nieograniczony dostęp do zapisu w różnych witrynach najwyższego poziomu z zachowaniem poufności w zakresie odczytu.

Pamięć współdzielona jest ograniczona do źródła kontekstu (elementu wywołującego sharedStorage).

W przypadku pamięci współdzielonej obowiązuje limit pojemności na punkt początkowy, a każdy wpis ma maksymalną liczbę znaków. Jeśli limit zostanie osiągnięty, żadne dalsze dane wejściowe nie będą przechowywane. Limity miejsca na dane zostały opisane we objaśnieniu dotyczącym pamięci współdzielonej.

Wywołuję pamięć współdzieloną

Technologie reklamowe mogą zapisywać dane w pamięci współdzielonej za pomocą kodu JavaScript lub nagłówków odpowiedzi. Odczytywanie z pamięci współdzielonej odbywa się tylko w izolowanym środowisku JavaScript nazywanym workletem.

Worklet umożliwia uruchamianie określonych funkcji JavaScript i zwracanie informacji z powrotem do żądającego. Worklet może uruchamiać kod JavaScript, ale nie pozwala na interakcję ani komunikację ze stroną zewnętrzną.

Worklety służą do przechowywania i wyodrębniania danych za pomocą interfejsu Shared Storage API.

• Używanie JavaScriptu Technologie reklamowe mogą wykonywać określone funkcje współdzielonej pamięci masowej, takie jak ustawianie, dodawanie i usuwanie wartości poza workletem JavaScript. Jednak takie funkcje jak odczytywanie pamięci współdzielonej i wykonywanie agregacji prywatnej muszą być wykonywane za pomocą workletu JavaScript. Metody, których można używać poza workletem JavaScript, znajdziesz w artykule Proposed API Surface - Outside the worklet.

  Metody używane w workletze podczas operacji znajdziesz w sekcji Proposed API Surface - In the worklet (Proponowana powierzchnia interfejsu API – w workecie).

• Używanie nagłówków odpowiedzi

  Ta funkcja jest dostępna w wersji M119.

  Podobnie jak w przypadku JavaScriptu, nagłówki odpowiedzi można wykonywać tylko w określonych funkcjach, takich jak ustawianie, dołączanie i usuwanie wartości w pamięci współdzielonej. Aby można było używać pamięci współdzielonej w nagłówku odpowiedzi, w nagłówku żądania musi być uwzględniony element Shared-Storage-Writable: ?1.

  Aby zainicjować żądanie od klienta, uruchom w zależności od wybranej metody ten kod:

  • 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 sekcji Shared Storage: Headers (Pamięć współdzielona: nagłówki odpowiedzi).

Zapisywanie w pamięci współdzielonej

Aby zapisywać dane w pamięci współdzielonej, wywołaj sharedStorage.set() z wewnątrz lub na zewnątrz workletu JavaScript. Jeśli zostanie wywołana z zewnątrz workletu, dane zostaną zapisane w źródle kontekstu przeglądania, z którego pochodzi to wywołanie. Jeśli zostanie wywołana z workletu, dane zostaną zapisane w źródle kontekstu przeglądania, który go załadował. Ustawione klucze mają datę ważności 30 dni od ostatniej aktualizacji.

Pole ignoreIfPresent jest opcjonalne. Jeśli klucz jest obecny i ma wartość true, nie zostanie zaktualizowany, jeśli już istnieje. Wygaśnięcie klucza jest odnawiane na 30 dni od wywołania set(), nawet jeśli klucz nie został zaktualizowany.

Jeśli podczas tego samego wczytywania strony użytkownik korzysta kilka razy z pamięci współdzielonej za pomocą tego samego klucza, wartość klucza zostanie zastąpiona. Warto użyć sharedStorage.append(), jeśli klucz ma utrzymać poprzednią wartość.

• Używanie JavaScriptu

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

  Analogicznie wewnątrz workletu:

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

• Używanie nagłówków odpowiedzi

  W pamięci współdzielonej możesz też zapisywać dane przy użyciu nagłówków odpowiedzi. Aby to zrobić, wpisz w nagłówku odpowiedzi ciąg Shared-Storage-Write wraz z następującymi poleceniami:

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
  

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
  

  Kilka elementów można rozdzielić przecinkami i połączyć set, append, delete i clear.

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

Dołączenie wartości

Wartość możesz dołączyć do istniejącego klucza za pomocą metody dołączania. Jeśli klucz nie istnieje, wywołanie metody append() tworzy klucz i ustawia 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 sharedStorage.append() wewnątrz lub na zewnątrz workletu.

  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 dołączyć w workletze:

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

• Używanie nagłówków odpowiedzi

  Podobnie jak w przypadku ustawiania wartości w pamięci współdzielonej możesz przekazać parę klucz-wartość za pomocą Shared-Storage-Write w nagłówku odpowiedzi.

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

Odczyt z pamięci współdzielonej

Dane z pamięci współdzielonej możesz odczytywać tylko z poziomu workletu.

await sharedStorage.get('mykey');

Pochodzenie kontekstu przeglądania, z którego został wczytany moduł workletu, decyduje o tym, czyj pamięć współdzielona jest odczytywana.

Usuwam z pamięci współdzielonej

Możesz usuwać elementy z pamięci współdzielonej za pomocą kodu JavaScriptu wewnątrz lub na zewnątrz workletu albo używając nagłówków odpowiedzi z funkcją delete(). Aby usunąć wszystkie klucze naraz, użyj klawisza clear() w jednym z nich.

• Używanie JavaScriptu

  Aby usunąć z pamięci współdzielonej spoza workletu:

  window.sharedStorage.delete('myKey');
  

  Aby usunąć z pamięci współdzielonej z poziomu workletu:

  sharedStorage.delete('myKey');
  

  Aby usunąć wszystkie klucze naraz, spoza workletu:

  window.sharedStorage.clear();
  

  Aby usunąć wszystkie klucze naraz 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 polecenia Shared-Storage-Write w celu przekazania klucza do usunięcia.

  delete;key="myKey"
  

  Aby usunąć wszystkie klucze przy użyciu nagłówków odpowiedzi:

  clear;
  

Przełączanie kontekstu

Dane w pamięci współdzielonej są zapisywane w źródle (np. https://example.adtech.com) kontekstu przeglądania, z którego pochodzi wywołanie.

Gdy wczytujesz kod firmy zewnętrznej za pomocą tagu <script>, jest on uruchamiany w kontekście przeglądania w narzędziu do umieszczania na stronie. Dlatego gdy kod zewnętrzny wywołuje sharedStorage.set(), dane są zapisywane w pamięci współdzielonej osoby umieszczonej. Gdy wczytujesz kod firmy zewnętrznej w elemencie iframe, otrzymuje on nowy kontekst przeglądania, a jego źródłem jest pochodzenie elementu iframe. Dlatego wywołanie sharedStorage.set() z elementu iframe przechowuje dane w pamięci współdzielonej źródła elementu iframe.

Kontekst własny

Jeśli strona własna zawiera umieszczony kod JavaScript innej firmy, który wywołuje sharedStorage.set() lub sharedStorage.delete(), para klucz-wartość jest przechowywana we własnym kontekście.

Kontekst firmy zewnętrznej

Parę klucz-wartość można przechowywać w kontekście technologii reklamowej lub firmy zewnętrznej przez utworzenie elementu iframe i wywołanie set() lub delete() w kodzie JavaScript z poziomu elementu iframe.

Interfejs Private Aggregation API

Aby mierzyć dane zbiorcze przechowywane w pamięci współdzielonej, możesz użyć interfejsu Private Agregation API.

Aby utworzyć raport, wywołaj contributeToHistogram() w workletu 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 zasobnik i wartość, jest szyfrowany w trakcie przesyłania i może być odszyfrowywany i agregowany tylko za pomocą usługi agregacji.

Przeglądarka ograniczy też ilość danych, jakie witryna może wykonać w zapytaniu wyjściowym. W szczególności budżet na wpłaty ogranicza łączną liczbę wszystkich raportów z jednej witryny dotyczących danej przeglądarki w danym przedziale czasu we wszystkich zasobnikach. Jeśli aktualny budżet zostanie przekroczony, raport nie zostanie wygenerowany.

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

Wykonywanie pamięci współdzielonej i agregacji prywatnej

Wczytaj moduł workletu w elemencie iframe reklamy, wywołując metodę addModule(). Aby uruchomić metodę zarejestrowaną w pliku workletu sharedStorageWorklet.js, w tym samym kodzie JavaScript elementu iframe reklamy wywołaj sharedStorage.run().

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

W skrypcie workletu utwórz klasę z użyciem asynchronicznej metody run. I register tę klasę do uruchomienia w elemencie iframe reklamy. Wewnątrz 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);

Debugowanie

Aby włączyć debugowanie, wywołaj metodę JavaScript enableDebugMode() w tym samym kontekście, w którym używana jest pamięć współdzielona i agregacja prywatna. Będzie ona stosowana w przyszłych raportach w tym samym kontekście.

privateAggregation.enableDebugMode();

Aby powiązać raporty z kontekstami, które je wywołały, możesz ustawić 64-bitowy klucz debugowania liczby całkowitej bez znaku, który jest przekazywany do wywołania JavaScript. debugKey to BigInt.

privateAggregation.enableDebugMode({debugKey: 1234});

Debugowanie pamięci współdzielonej

Pamięć współdzielona zwraca ogólny komunikat o błędzie:

Promise is rejected without and explicit error message

Możesz debugować pamięć współdzieloną, pakując wywołania blokami try-catch.

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

Debugowanie agregacji prywatnej

Raporty są wysyłane na adresy /.well-known/private-aggregation/report-shared-storage i /.well-known/private-aggregation/debug/report-shared-storage. Raporty debugowania otrzymują ładunek podobny do tego poniżej. Ten ładunek definiuje pole api jako „miejsce współdzielone”.

{
   "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\"}"
}

Debugowanie ładunku tekstu nieszyfrowanego

debug_cleartext_payload jest zakodowany w Base64 CBOR. Możesz wyświetlić zasobnik i wartość za pomocą dekodera lub użyć kodu JavaScript z dekodera pamięci współdzielonej.

Dalsze kroki

Na kolejnych stronach objaśniamy ważne aspekty interfejsów API pamięci współdzielonej i prywatnej agregacji.

• Wprowadzenie do pamięci współdzielonej (Chrome dla deweloperów)
• Przypadki użycia pamięci współdzielonej (Chrome dla deweloperów)
• Wprowadzenie do agregacji prywatnej (dla programistów Chrome)
• Wyjaśnienie dotyczące pamięci współdzielonej (GitHub)
• Wyjaśnienie agregacji prywatnej (GitHub)
• Wersja demonstracyjna agregacji współdzielonej i prywatnej

Po zapoznaniu się z interfejsami API możesz zacząć zbierać raporty, które są wysyłane jako żądanie POST do poniższych punktów końcowych w postaci kodu 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 je przetestować za pomocą lokalnego narzędzia do testowania lub skonfigurować zaufane środowisko wykonawcze dla usługi agregacji, aby otrzymywać raporty zbiorcze.

Prześlij opinię

Możesz podzielić się swoją opinią na temat interfejsów API i dokumentacji na GitHubie.

• Pamięć współdzielona
• Agregacja prywatna