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 prywatności Agregacja. Musisz znać oba interfejsy API, ponieważ pamięć współdzielona przechowuje wartości, a agregacja prywatna tworzy raporty agregowane.

Docelowi odbiorcy: dostawcy technologii reklamowych i pomiarów.

Wypróbuj wersję demonstracyjną

Wypróbuj prezentację na żywo. Wykonaj odpowiednie czynności w instrukcji włączania interfejsów API Piaskownicy prywatności. Uruchamiam Chrome Narzędzia deweloperskie ułatwiają wizualizację wyników w różnych przypadkach użycia. Zastosowania 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+
  • Zastosowania ogólne
    • Pomiar zdarzenia najechania kursorem myszy w chronionych ramkach
    • Nawigacja najwyższego poziomu
    • Kontrola nad uprawnieniami innych firm do zapisu

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

Aby sprawdzić, co jest przechowywane w pamięci współdzielonej, użyj Narzędzi deweloperskich w Chrome. Zapisane dane mogą znaleźć w domenie Application -> Shared Storage.

Wyświetlaj dane przechowywane w pamięci współdzielonej za pomocą Narzędzi deweloperskich w Chrome.

Wyświetlanie raportów dotyczących agregacji prywatnej

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

Aby włączyć debugowanie, wykonaj instrukcje podane w artykule na temat debugowania. .

Raporty można wyświetlać na stronie chrome://private-aggregation-internals.

Interfejs Shared Storage API

Aby zapobiec śledzeniu w witrynach, przeglądarki zaczęły partycjonować wszystkie formy pamięci lokalnej, plików cookie itd. Istnieją przypadki użycia, w których wymagane jest przechowywanie bez partycji. Interfejs Shared Storage API zapewnia nieograniczony dostęp do zapisu w różnych witrynach najwyższego poziomu z zachowaniem prywatności uprawnienia do odczytu danych.

Pamięć współdzielona jest ograniczona do źródła kontekstu (wywołania funkcji sharedStorage).

W pamięci współdzielonej obowiązuje limit pojemności na punkt początkowy, a każda pozycja jest ograniczona do maksymalną liczbę znaków. Po osiągnięciu limitu nie można już wprowadzać żadnych danych zapisane. Limity miejsca na dane są przedstawione w sekcji Pamięć współdzielona .

Wywoływanie pamięci współdzielonej

Specjaliści z branży reklamowej mogą zapisywać w pamięci współdzielonej za pomocą kodu JavaScript lub nagłówków odpowiedzi. Odczyt z pamięci współdzielonej odbywa się tylko w obrębie izolowanego kodu JavaScript w środowisku Worklet.

  • Za pomocą JavaScriptu specjaliści ds. technologii reklamowych mogą wykonywać określone funkcje pamięci współdzielonej takich jak ustawianie, dołączanie i usuwanie wartości poza kodem JavaScript Worklet. Funkcje takie jak odczyt pamięci współdzielonej czy Agregację prywatną należy wykonać za pomocą workletu JavaScript. Metody, których można używać poza Workletem JavaScriptu, znajdziesz tutaj Proponowany interfejs API – poza Worklet.

    Metody używane w Workletze podczas operacji można znaleźć tutaj: Proponowany interfejs API – w Worklet.

  • Korzystanie z nagłówków odpowiedzi

    Podobnie jak w języku JavaScript, tylko określone funkcje, takie jak ustawianie, dodawanie a wartości w pamięci współdzielonej można wykonać za pomocą nagłówków odpowiedzi. Do działa ze współdzielonymi danymi w nagłówku odpowiedzi, Shared-Storage-Writable: ?1 musi być zawarte w nagłówku żądania.

    Aby zainicjować żądanie od klienta, uruchom następujący kod w zależności od wybraną metodę:

    • Jak korzystać z aplikacji fetch()
        fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
    • Za pomocą 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 Shared Storage: Response (Pamięć współdzielona: odpowiedź) Nagłówki.

Zapisywanie w pamięci współdzielonej

Aby zapisać dane w pamięci współdzielonej, wywołaj funkcję sharedStorage.set() w aplikacji lub poza nią Worklet JavaScriptu. Jeśli dane zostaną wywołane spoza Worklet, dane są zapisywane w źródło kontekstu przeglądania, z którego wykonano wywołanie. W przypadku połączenia z dane są zapisywane w źródle kontekstu przeglądania który wczytał worklet. Ustawione klucze mają datę ważności równą 30 dni od ostatniej aktualizacji.

Pole ignoreIfPresent jest opcjonalne. Jeśli klucz jest dostępny i ustawiony na true, klucz nie jest aktualizowany, jeśli już istnieje. Ważność klucza została odnowiona na 30 dni z wywołanie set(), nawet jeśli klucz nie został zaktualizowany.

Jeśli podczas tego samego wczytywania strony wielokrotnie uzyskuje się dostęp do pamięci współdzielonej , wartość klucza zostanie zastąpiona. Warto użyć sharedStorage.append(), jeśli klucz musi zachować poprzednią wartość.

  • 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 obrębie Worklet:

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

  • Korzystanie z nagłówków odpowiedzi

    Możesz też zapisywać w pamięci współdzielonej za pomocą nagłówków odpowiedzi. W tym celu użyj Shared-Storage-Write w nagłówku odpowiedzi wraz z tym fragmentem polecenia:

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

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

    Można rozdzielić przecinkami wiele elementów, które można połączyć z tymi atrybutami: 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, korzystając z metody include. Jeśli klucz nie istnieje, wywołanie funkcji append() powoduje utworzenie klucza i ustawienie wartości. Może to spowodować w JavaScript lub nagłówkach odpowiedzi.

  • Używanie JavaScriptu

    Aby zaktualizować wartości istniejących kluczy, użyj parametru sharedStorage.append() z jednego z tych kluczy wewnątrz czy 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ć do Workletu:

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

  • Korzystanie z nagłówków odpowiedzi

    Podobnie jak w przypadku ustawień pamięci współdzielonej, możesz użyć funkcji Shared-Storage-Write w nagłówku odpowiedzi, aby przekazać ją w parze klucz-wartość.

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

Odczyt z pamięci współdzielonej

Możesz odczytywać dane z pamięci współdzielonej tylko w obrębie workletu.

await sharedStorage.get('mykey');

Źródło kontekstu przeglądania, z którego został wczytany moduł Worklet określa, czyja pamięć współdzielona jest odczytywana.

Usuwam z pamięci współdzielonej

Możesz usuwać dane z pamięci współdzielonej za pomocą JavaScriptu z jednego z tych narzędzi lub poza Workletem bądź za pomocą nagłówków odpowiedzi z atrybutem delete(). Aby usunąć wszystkich klawiszy naraz, użyj klawisza clear() dowolnej z nich.

  • Używanie JavaScriptu

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

    window.sharedStorage.delete('myKey');

    Aby usunąć ze współdzielonej pamięci masowej z wewnątrz Workletu:

    sharedStorage.delete('myKey');

    Aby usunąć wszystkie klucze jednocześnie spoza Workletu:

    window.sharedStorage.clear();

    Aby usunąć wszystkie klucze jednocześnie z workletu:

    sharedStorage.clear();

  • Korzystanie z nagłówków odpowiedzi

    Aby usunąć wartości za pomocą nagłówków odpowiedzi, możesz też użyć funkcji Shared-Storage-Write w nagłówku odpowiedzi, aby przekazać klucz do usunięcia.

    delete;key="myKey"

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

    clear;

Przełączanie kontekstu

Dane pamięci współdzielonej są zapisywane w origin, (na przykład https://example.adtech.com) kontekstu przeglądania, przez które wywołanie .

Gdy wczytujesz kod innej firmy za pomocą tagu <script>, kod jest wykonywany. w kontekście przeglądania. Dlatego gdy kod innej firmy wywoła sharedStorage.set(), dane są zapisywane w Miejsce na dane. Gdy ładujesz kod innej firmy w elemencie iframe, kod otrzyma nowym kontekstem przeglądania, a jego źródłem jest źródło elementu iframe. Dlatego wywołanie sharedStorage.set() z elementu iframe zapisuje dane w sekcji Wspólna pamięć masowa źródła elementu iframe.

Kontekst własny

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

Dane przechowywane na stronie własnej z osadzonym kodem JavaScript innej firmy.

Kontekst firmy zewnętrznej

Para klucz-wartość może być przechowywana w kontekście technologii reklamowej lub innej firmy przez tworząc element iframe i wywołując funkcję set() lub delete() w kodzie JavaScript z wewnątrz elementu iframe.

Dane przechowywane w kontekście technologii reklamowych lub usług firm zewnętrznych.

Interfejs Private Aggregation API

Aby mierzyć agregowane dane przechowywane w pamięci współdzielonej, możesz użyć funkcji Prywatny Interfejs API agregacji.

Aby utworzyć raport, wywołaj contributeToHistogram() w workletze ze znakiem odbiorcy i wartości. Zasobnik jest reprezentowany przez nieoznaczoną 128-bitową liczbę całkowitą, która musi zostać przekazana do funkcji w postaci BigInt. Wartość musi być dodatnią liczbą całkowitą.

Aby chronić prywatność, ładunek raportu, który zawiera zasobnik i wartość, jest zaszyfrowany podczas przesyłania i można go odszyfrować i zagregować tylko przy użyciu agregacja danych.

Przeglądarka ogranicza też wpływ witryny na dane wyjściowe zapytania. Konkretnie: wkład ogranicza łączną liczbę wszystkich raportów z jednej witryny dla danej przeglądarki w danym przedziale czasowym we wszystkich zasobnikach. Jeśli bieżący budżet zostanie przekroczony, nie zostanie wygenerowany.

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

Wykonywanie pamięci współdzielonej i agregacji prywatnej

Używanie elementów iframe z innych domen

Do wywołania Workletu pamięci współdzielonej potrzebny jest element iframe.

W elemencie iframe reklamy wczytaj moduł Worklet, wywołując funkcję addModule(). Aby uruchomić zarejestrowanej w pliku worklet sharedStorageWorklet.js, w metodzie taki sam element iframe reklamy, wywołanie sharedStorage.run().

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

W skrypcie Worklet musisz utworzyć klasę z asynchroniczną klasą run . Dodaj też 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);

Używanie żądań z innych domen

Pamięć współdzielona i agregacja prywatna umożliwiają tworzenie Workletów z innych domen bez potrzeby stosowania elementów iframe z innych domen.

Strona własna może wywoływać wywołanie createWorklet() do zasobów z innych domen punkt końcowy JavaScript.

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

Punkt końcowy JavaScript z innych domen będzie musiał odpowiadać z nagłówkami Shared-Storage-Cross-Origin-Worklet-Allowed i zezwól na korzystanie z innych domen za pomocą Access-Control-Allow-Origin

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1
Access-Control-Allow-Origin : https://first-party.dev

Worklety utworzone za pomocą interfejsu createWorklet() będą mieć selectURL i run(). Usługa addModule() jest niedostępna w tym przypadku.

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

Debugowanie

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

privateAggregation.enableDebugMode();

Aby powiązać raporty z kontekstami, które je spowodowały, możesz określić 64-bitowy niepodpisany klucz całkowity do debugowania, który jest przekazywany do wywołania JavaScriptu. debugKey ma status 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ą, dodając do wywołań funkcję try-catch bloki.

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

Debugowanie agregacji prywatnej

Raporty są wysyłane na te adresy: /.well-known/private-aggregation/report-shared-storage oraz /.well-known/private-aggregation/debug/report-shared-storage Raporty debugowania otrzymasz ładunek podobny do tego w formacie JSON. Ten ładunek określa api jako „pamięć-wspólna”.

{
   "aggregation_coordinator_origin": "https://publickeyservice.msmt.gcp.privacysandboxservices.com",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhlKJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAB1vNFaJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAGlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "1569ab37-da44-4a26-80d9-5ed6524ab2a7",
      "payload": "/9nHrWn1MnJWRxFvanbubciWE9mPyIij6uYLi5k351eQCd3/TZpe2knaatUNcniq4a4e61tmKebv50OmMRZFnnCfcAwIdIgLHu1a3en97PojqWJBfO52RiVMIcP7KQTLzMxq2LhvPSdV4zjXo1Teu/JuIK3LIyis3vUMpS+tUAX0QV+I6X5SVmZFiNW9aMb8DwLOtqrBy5JJ/EkOIY0G+1Fi1/3R7UtKsqM1o71A/OzdmlNkwO7EV/VUNinGvWnd19FvDHe/kqkNdTHKbhAnMmbZzHW9bsEQS81leElCla6BTdbdbeeFU/jbTj0AOaoNOIe5r7FU5NG6nW4ULXTCbLLjTQ1mtl3id3IP41Zin1JvABCDC/HUSgLFz8EUqkmbMIOlMfNYA79aURq6FqE0GO0HtICYf0GPNdVv7p4jY3FNn6+JS4l5F3t+3lP9ceo4IpCE+31jzMtYJ+19xFh6C5ufteBR/iknZFcc1w3caQBhgRl5jt8DbaOzYcW4690H8Ul4Oh2wRO+6/njifk+pExLay/O5swLi2lUUph5OUEaaztwwzh2mnhwIBxMkPnfsGihiF+5KDEajVfMZ3NLsIDoZO+l4RTZrkqE+jVkAqaZGBiCIx42Edp/JV0DXfrryypCdQBZr8iEbSzCM9hKsMfLN7S/VkPe5rDwOZbhKCn5XXgfGz5tSx/KbZgsQf4OCEhwAyNPHAh3MHU7xmkQ3pKg4EIUC/WOtKAlVDOtDMmPPoQY1eAwJhw9SxZaYF1kHjUkTm3EnGhgXgOwCRWqeboNenSFaCyp6DbFNI3+ImONMi2oswrrZO+54Tyhca5mnLIiInI+C3SlP4Sv1jFECIUdf/mifJRM5hMj6OChzHf4sEifjqtD4A30c4OzGexWarie2xakdQej9Go4Lm0GZEDBfcAdWLT9HwmpeI2u4HDAblXDvLN8jYFDOOtzOl90oU7AwdhkumUCFLRadXAccXW9SvLfDswRkXMffMJLFqkRKVE1GPonFFtlzaRqp7IgE8L6AOtz6NDcxAjHnEuzDPPMcWMl1AFH0gq7h"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"80d93c0a-a94e-4ab7-aeb5-a4ecd4bfc598\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1717784740\",\"version\":\"0.1\"}"
}

Debuguj ładunek nieszyfrowany

debug_cleartext_payload to Base64 Z kodowaniem CBOR. Możesz wyświetlić zasobnik za pomocą dekodera lub użyj wartości kod JavaScript dostępny w Shared Storage za pomocą dekodera.

Dalsze kroki

Na kolejnych stronach opisujemy ważne aspekty udostępniania pamięci współdzielonej i prywatności Interfejsy API do agregacji.

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ść żą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żna przeprowadzić testy, korzystając z testów lokalnych lub skonfigurować zaufane środowisko wykonawcze dla agregacji. Usługa , aby uzyskać raporty zbiorcze.

Prześlij opinię

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