Omówienie interfejsu Private Aggregation API

generować raporty danych zbiorczych na podstawie danych z chronionej listy odbiorców i danych z wielu witryn z Udostępnionego miejsca na dane.

Aby zapewnić działanie funkcji, na których opiera się internet, prywatne API zostało stworzone z myślą o zbieraniu i raportowaniu danych z różnych witryn w sposób zapewniający ochronę prywatności.

Stan wdrożenia

Proposal Status
Prevent invalid Private Aggregation API reports with report verification for Shared Storage
Explainer		 Available in Chrome
Private Aggregation debug mode availability dependent on 3PC eligibility
GitHub issue		 Available in Chrome M119
Reducing report delay
Explainer		 Available in Chrome M119
Private Aggregation contribution timeout for Shared Storage
Explainer		 Available in M119
Support for Private Aggregation API and Aggregation Service for Google Cloud
Explainer		 Available in Chrome M121
Padding for aggregatable report payloads
Explainer		 Available in Chrome M119
Private Aggregation debug mode available for auctionReportBuyers reporting
Explainer		 Available in Chrome M123
Filtering ID support
Explainer		 Available in Chrome M128
Client-side contribution merging
Explainer		 Available in Chrome M129

Czym jest interfejs Private Aggregation API

Interfejs Private Aggregation API umożliwia deweloperom generowanie raportów zbiorczych z danymi z interfejsu Protected Audience API oraz danymi z różnych witryn z interfejsu Shared Storage.

Główną funkcją tego interfejsu API jest contributeToHistogram(). Operacja histogramu umożliwia zliczanie danych dotyczących użytkowników w każdym zdefiniowanym przez Ciebie zbiorze (w interfejsie API nazywanym kluczem agregacji). Wywołanie histogramu gromadzi wartości i zwraca wynik agregowany z dodatkowym szumem w formie raportu podsumowania. Raport może na przykład zawierać informacje o liczbie witryn, w których użytkownik zobaczył Twoje treści, lub o błędach w skrypcie zewnętrznym. Ta operacja jest wykonywana w ramach workletu innego interfejsu API.

Jeśli np. wcześniej zarejestrujesz w Shared Storage dane demograficzne i geograficzne, możesz użyć interfejsu Private Aggregation API, aby utworzyć histogram, który pokaże Ci, ilu użytkowników w Nowym Jorku widziało Twoje treści w różnych witrynach. Aby zsumować dane w tym przypadku, możesz zakodować wymiar geografii w kluczu agregacji i policzyć użytkowników w wartości podlegającej agregacji.

Kluczowych pojęć

Gdy wywołasz interfejs Private Aggregation API z kluczem agregacji i wartością podlegającą agregacji, przeglądarka generuje raport podlegający agregacji.

Raporty podlegające agregacji są wysyłane na serwer w celu zebrania i zbiorczego przetwarzania. Raporty zbiorcze są później przetwarzane przez usługę agregacji i generowany jest raport podsumowujący.

Więcej informacji o kluczowych pojęciach związanych z Private Aggregation API znajdziesz w dokumentacji Private Aggregation API – podstawy.

Różnice w raportowaniu atrybucji

Interfejs Private Aggregation API ma wiele cech wspólnych z interfejsem Attribution Reporting API. Attribution Reporting to samodzielny interfejs API przeznaczony do pomiaru konwersji, a Private Aggregation służy do pomiarów w wielu witrynach w połączeniu z interfejsami API takimi jak Protected Audience API i Shared Storage. Oba interfejsy API generują raporty, które można agregować, a które są wykorzystywane przez backend usługi agregacji do generowania raportów podsumowujących.

Raportowanie atrybucji łączy dane zebrane ze zdarzenia wyświetlenia i zdarzenia konwersji, które występują w różnych momentach. Prywatna agregacja mierzy pojedyncze zdarzenie w wielu witrynach.

Testowanie tego interfejsu API

Aby przetestować interfejs Private Aggregation API lokalnie, włącz wszystkie interfejsy Ad Privacy API w sekcji chrome://settings/adPrivacy.

Dowiedz się więcej o testowaniu w eksperymencie i zostań jego uczestnikiem.

Korzystanie z wersji demonstracyjnej

Demonstrację interfejsu Private Aggregation API na potrzeby Shared Storage można znaleźć na stronie goo.gle/shared-storage-demo, a kod jest dostępny na GitHub. Demonstracja wdraża operacje po stronie klienta i tworzy raport, który można agregować i przesyłać na serwer.

W przyszłości opublikujemy wersję demonstracyjną interfejsu Private Aggregation API dla Protected Audience API.

Przypadki użycia

Prywatna agregacja to ogólny interfejs API do pomiarów w wielu witrynach. Można go używać w elementach worklet Shared Storage i Protected Audience API. Najpierw musisz określić, jakie informacje chcesz zbierać. Te punkty danych stanowią podstawę kluczy agregacji.

Pamięć współdzielona

Usługa Shared Storage umożliwia odczytywanie i zapisywanie danych między witrynami w bezpiecznym środowisku, aby zapobiec wyciekom danych. Interfejs Private Aggregation API umożliwia pomiar danych między witrynami przechowywanych w Shared Storage.

Pomiar zasięgu wśród unikalnych użytkowników

Możesz chcieć sprawdzić, ilu unikalnych użytkowników obejrzało Twoje treści. Interfejs Private Aggregation API może podać odpowiedź w takim brzmieniu: „Około 317 unikalnych użytkowników obejrzało treści o identyfikatorze treści 861”.

W Shared Storage możesz ustawić flagę, która wskazuje, czy użytkownik widział już daną treść. Podczas pierwszej wizyty, w której nie ma flagi, następuje wywołanie prywatnego agregatora, a potem ustawiana jest flaga. Podczas kolejnych wizyt użytkownika, w tym w różnych witrynach, możesz sprawdzić udostępnione miejsce na dane i pominąć przesyłanie raportu do prywatnego agregatora, jeśli ustawiony jest odpowiedni parametr. Więcej informacji o metodach implementacji tych pomiarów znajdziesz w dokumentacji dotyczącej zasięgu.

Pomiar danych demograficznych

Możesz mierzyć dane demograficzne użytkowników, którzy widzieli Twoje treści w różnych witrynach.

Prywatna agregacja może podać odpowiedź, np. „Około 317 unikalnych użytkowników w wieku 18–45 lat pochodzi z Niemiec”. Użyj Shared Storage, aby uzyskać dostęp do danych demograficznych z kontekstu zewnętrznego. W późniejszym czasie możesz wygenerować raport z korzystaniem z zbiorczości prywatnej, kodując wymiary grupa wiekowa i kraj w kluczu agregacji.

Pomiar częstotliwości K+

Możesz mierzyć liczbę użytkowników, którzy w danej przeglądarce widzieli dany element treści lub reklamę co najmniej K razy, przy czym wartość K została wybrana wcześniej.

Prywatna agregacja może dostarczyć odpowiedzi w postaci „Około 89 użytkowników widziało identyfikator treści 581 co najmniej 3 razy”. Licznik może być zwiększany w pamięci współdzielonej z różnych witryn i może być odczytywany w ramach workletu. Gdy liczba osiągnie wartość K, możesz przesłać raport za pomocą prywatnego agregatora.

Atrybucja uwzględniająca różne interakcje

Te wskazówki zostaną opublikowane na stronie dla programistów, aby specjaliści ds. technologii reklamowych mogli się dowiedzieć, jak wdrażać MTA w ramach wspólnego magazynu i prywatnej agregacji.

Za pomocą interfejsu Protected Audience API

Interfejs Protected Audience API umożliwia tworzenie reklam remarketingowych i kierowanych na niestandardowe listy odbiorców, a Private Aggregation pozwala zgłaszać zdarzenia z workletów kupujących i sprzedawców. Interfejsu API można używać do wykonywania takich zadań jak pomiar rozkładu stawek aukcji.

W ramach workletu Protected Audience API możesz agregować dane bezpośrednio za pomocą funkcji contributeToHistogram() i generować raporty na podstawie wyzwalacza za pomocą funkcji contributeToHistogramOnEvent(), która jest specjalnym rozszerzeniem interfejsu Protected Audience API.

Dostępne funkcje

W obiekcie privateAggregation dostępnym w elementach Shared Storage i Protected Audience API dostępne są te funkcje:

contributeToHistogram()

Możesz wywołać funkcję privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }), gdzie klucz agregacji to bucket, a wartość podlegająca agregacji to value. W przypadku parametru bucket wymagany jest parametr BigInt. W przypadku parametru value wymagana jest liczba całkowita.

Oto przykład wywołania w Shared Storage na potrzeby pomiaru zasięgu:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', {
  data: { contentId: '1234' }
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await sharedStorage.get(key) === 'true';

    // Don't send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId),
      value: 1 * SCALE_FACTOR
    });

    // Set the flag in Shared Storage
    await sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

Poprzedni przykład kodu wywołuje prywatne agregacje za każdym razem, gdy wczytywane są treści w ramce iframe na różnych stronach. Kod iframe wczytuje worklet, a worklet wywołuje interfejs Private Aggregation API z identyfikatorem treści przekształconym w klucz agregacji (grupę).

contributeToHistogramOnEvent()

Tylko w przypadku modułów Protected Audience API udostępniamy mechanizm oparty na regułach, który umożliwia wysyłanie raportu tylko wtedy, gdy wystąpi określone zdarzenie. Ta funkcja umożliwia też, aby zasobnik i wartość zależały od sygnałów, które nie są jeszcze dostępne w danym momencie aukcji.

Metoda privateAggregation.contributeToHistogramOnEvent(eventType, contribution) przyjmuje parametr eventType, który określa wywołujące zdarzenie, oraz parametr contribution, który ma zostać przesłany po wywołaniu zdarzenia. Zdarzenie wywołujące może pochodzić z samej aukcji po jej zakończeniu, np. zdarzenie wygrania lub przegrania aukcji, albo z ograniczonego elementu, który wyświetlił reklamę.

Aby wysłać raport o wydarzeniach aukcji, możesz użyć 2 zarezerwowanych słów kluczowych: reserved.win, reserved.loss i reserved.always. Aby przesłać raport wywołany przez zdarzenie z ogrodzonego elementu, zdefiniuj typ zdarzenia niestandardowego. Aby wywołać zdarzenie z ramki wydzielonej, użyj metody fence.reportEvent() dostępnej w interfejsie Fenced Frames Ads Reporting API.

W tym przykładzie raport wyświetleń jest wysyłany, gdy nastąpiło zdarzenie wygrania aukcji, a raport kliknięć – gdy z ramki odizolowanej, w której została wyrenderowana reklama, zostanie wywołane zdarzenie click. Z tych 2 wartości można obliczyć współczynnik klikalności.

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

Aby dowiedzieć się więcej, przeczytaj omówienie raportowania zbiorczego na potrzeby prywatności.

enableDebugMode()

Pliki cookie innych firm są nadal dostępne, ale udostępnimy tymczasowy mechanizm, który ułatwi debugowanie i testowanie dzięki włączeniu trybu debugowania. Raport debugowania jest przydatny do porównywania pomiarów opartych na plikach cookie z pomiarami prywatnej agregacji. Pozwala też szybko sprawdzić integrację interfejsu API.

Wywołanie funkcji privateAggregation.enableDebugMode() w worklecie powoduje włączenie trybu debugowania, co powoduje, że raporty podlegające agregacji zawierają niezaszyfrowany (w pełnym tekście) ładunek. Następnie możesz przetworzyć te dane za pomocą lokalnego narzędzia do testowania usługi agregacji.

Tryb debugowania jest dostępny tylko dla wywołujących, którzy mają dostęp do plików cookie innych firm. Jeśli wywołujący nie ma dostępu do plików cookie innych firm,enableDebugMode() nie zostanie wykonany.

Klucz debugowania możesz też ustawić, wywołując funkcję privateAggregation.enableDebugMode({ <debugKey: debugKey> }), gdzie BigInt może być używany jako klucz debugowania. Klucza debugowania można używać do kojarzenia danych z pomiaru opartego na plikach cookie i danych z pomiaru prywatnego.

Można je wywołać tylko raz na kontekst. Wszystkie kolejne wywołania wywołają wyjątek.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

Weryfikacja zgłoszenia

Interfejs Private Aggregation API umożliwia pomiary w wielu witrynach przy jednoczesnym zachowaniu prywatności użytkowników. Nieuczciwe osoby mogą jednak próbować manipulować dokładnością tych pomiarów. Aby tego uniknąć, możesz użyć identyfikatora kontekstu do weryfikacji autentyczności raportów.

Ustawienie identyfikatora kontekstu pomaga zapewnić prawidłowość danych, które przyczyniają się do końcowych wyników zbiorczych. Aby to osiągnąć:

  • Zapobieganie nielegalnym lub nieprawdziwym zgłoszeniom: upewnij się, że zgłoszenia są generowane za pomocą prawidłowych i autentycznych wywołań interfejsu API, co utrudnia ich fałszowanie przez osoby niepowołane.
  • Zapobieganie ponownemu odtwarzaniu raportów: wykrywanie i odrzucanie prób ponownego użycia starych raportów, aby każdy raport był uwzględniany w wynikach zbiorczych tylko raz.

Pamięć współdzielona

Jeśli używasz pamięci współdzielonej do wykonywania operacji, która może wysyłać agregowany raport, możesz ustawić nieprzewidywalny identyfikator poza elementem worklet.

Ten identyfikator jest umieszczany w raporcie utworzonym na podstawie elementu roboczego. Możesz go określić, wywołując metody run() lub selectURL() Shared Storage w obiekcie opcji pod kluczem privateAggregationConfig.

Na przykład:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

Po ustawieniu tego identyfikatora możesz go użyć, aby sprawdzić, czy raport został wysłany z operacji Shared Storage. Aby zapobiec wyciekowi informacji, na każdą operację w ramach udostępnionego miejsca na dane wysyłany jest dokładnie 1 raport (nawet jeśli nie ma żadnych wkładów), niezależnie od liczby wywołań contributeToHistogram().

Interfejs Private Aggregation API wysyła raporty podlegające agregacji z losowym opóźnieniem do 1 godziny, ale ustawienie identyfikatora kontekstu w celu weryfikacji raportu skraca to opóźnienie. W tym przypadku występuje stały, mniejszy o 5 sekund opóźnienie od momentu rozpoczęcia operacji na współdzielonym magazynie.

Przykładowy proces weryfikacji raportu

Przykładowy przepływ pracy (jak na diagramie powyżej):

  1. Operacja Shared Storage jest wykonywana z konfiguracją prywatnej agregacji, która określa identyfikator kontekstu, a następnie generowany jest raport możliwy do agregacji.
  2. Identyfikator kontekstu jest umieszczany w wygenerowanym raporcie możliwym do agregacji i wysyłanym na serwer.
  3. Twój serwer zbiera wygenerowane raporty podlegające agregacji.
  4. Procesy na serwerze sprawdzają identyfikator kontekstu w każdym raporcie możliwym do zgrupowania na podstawie identyfikatorów przechowywanych kontekstów, aby upewnić się, że jest on prawidłowy, zanim zbiorczo wyśle raporty do usługi agregacji.

Weryfikacja identyfikatora kontekstu

Raporty przychodzące na serwer kolektora można zweryfikować na kilka różnych sposobów, zanim zostaną wysłane do usługi agregacji. Raporty z nieprawidłowymi identyfikatorami kontekstu mogą zostać odrzucone, jeśli identyfikator kontekstu:

  • Nieznany: jeśli raport zawiera identyfikator kontekstu, którego nie utworzono w Twoim systemie, możesz go odrzucić. Zapobiega to wstrzykiwaniu danych do potoku agregacji przez nieznane lub złośliwe podmioty.
  • Duplikat: jeśli otrzymasz 2 raporty (lub więcej) z tym samym identyfikatorem kontekstu, musisz wybrać, który z nich odrzucić.
  • Oznaczone w wykrywaniu spamu:
    • Jeśli podczas przetwarzania zgłoszenia wykryjesz podejrzaną aktywność użytkownika, np. nagłą zmianę jego aktywności, możesz odrzucić zgłoszenie.
    • Raporty możesz przechowywać wraz z ich identyfikatorami kontekstu i wszelkimi odpowiednimi sygnałami (np. agentem użytkownika, źródłem odsyłacza itp.). Później, gdy analizujesz zachowanie użytkowników i identyfikujesz nowe wskaźniki spamu, możesz ponownie ocenić zapisane raporty na podstawie powiązanych z nimi identyfikatorów kontekstu i sygnałów. Dzięki temu możesz odrzucać zgłoszenia od użytkowników, które wskazują na podejrzaną aktywność, nawet jeśli nie zostały początkowo oznaczone.

Uzyskiwanie opinii i ich udostępnianie

Interfejs Private Aggregation API jest obecnie przedmiotem dyskusji i może ulec zmianie w przyszłości. Jeśli wypróbujesz ten interfejs API i masz opinię na jego temat, chętnie ją poznamy.