Omówienie interfejsu Private Aggregation API

Generowanie raportów z danymi zbiorczymi na podstawie danych z Protected Audience i danych z różnych witryn z Shared Storage.

Aby udostępniać kluczowe funkcje, na których opiera się internet, interfejs Private Aggregation API został stworzony do agregowania i raportowania danych z różnych witryn w sposób zapewniający ochronę prywatności.

Stan wdrożenia

Czym jest interfejs Private Aggregation API

Interfejs Private Aggregation API umożliwia deweloperom generowanie raportów z zagregowanymi danymi na podstawie danych z interfejsu Protected Audience API i  danych z różnych witryn z Shared Storage.

Główna funkcja tego interfejsu API to contributeToHistogram(). Operacja histogramu umożliwia agregowanie danych użytkowników w każdym zdefiniowanym przez Ciebie przedziale (w interfejsie API nazywanym kluczem agregacji). Wywołanie histogramu gromadzi wartości i zwraca zaszumiony zagregowany wynik w postaci raportu podsumowującego. Raport może na przykład pokazywać, na ilu stronach użytkownicy widzieli Twoje treści lub napotkali błąd w skrypcie firmy zewnętrznej. Ta operacja jest wykonywana w worklecie innego interfejsu API.

Jeśli na przykład masz już zapisane w Shared Storage dane demograficzne i geograficzne, możesz użyć interfejsu Private Aggregation API do utworzenia histogramu, który pokaże Ci, ilu użytkowników w Nowym Jorku zobaczyło Twoje treści w różnych witrynach. Aby dokonać agregacji na potrzeby tego pomiaru, możesz zakodować wymiar geograficzny w kluczu agregacji i zliczyć 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 wygeneruje raport podlegający agregacji.

Raporty z możliwością agregacji są wysyłane na Twój serwer w celu zbierania i grupowania. Raporty w partiach są później przetwarzane przez usługę do agregacji, która generuje raport podsumowujący.

Więcej informacji o kluczowych koncepcjach związanych z interfejsem Private Aggregation API znajdziesz w dokumencie Podstawy interfejsu Private Aggregation API.

Różnice w stosunku do Attribution Reporting

Interfejs Private Aggregation API ma wiele podobieństw do 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ć. Są one wykorzystywane przez backend usługi do 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 jedno zdarzenie w wielu witrynach.

Testowanie tego interfejsu API

Aby przetestować interfejs Private Aggregation API lokalnie, włącz wszystkie interfejsy API dotyczące prywatności w reklamach w sekcji chrome://settings/adPrivacy.

Więcej informacji o testowaniu znajdziesz w sekcji Eksperymenty i udział w nich.

Korzystanie z wersji demonstracyjnej

Wersja demonstracyjna interfejsu Private Aggregation API na potrzeby pamięci współdzielonej jest dostępna na stronie goo.gle/shared-storage-demo, a kod można znaleźć w GitHub. W wersji demonstracyjnej zaimplementowano operacje po stronie klienta i wygenerowano raport z możliwością agregacji, który jest wysyłany na Twój serwer.

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

Przypadki użycia

Private Aggregation to uniwersalny interfejs API do pomiarów w wielu witrynach, który można stosować w Shared Storage i Protected Audience API. Pierwszym krokiem jest określenie, jakie informacje chcesz zbierać. Te punkty danych stanowią podstawę kluczy agregacji.

Pamięć współdzielona

Shared Storage umożliwia odczytywanie i zapisywanie danych z różnych witryn w bezpiecznym środowisku, aby zapobiegać wyciekom, a interfejs Private Aggregation API pozwala mierzyć dane z różnych witryn przechowywane w Shared Storage.

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

Możesz chcieć zmierzyć, ilu unikalnych użytkowników widziało Twoje treści. Interfejs Private Aggregation API może podać odpowiedź w rodzaju „Treść z identyfikatorem 861 zobaczyło około 317 unikalnych użytkowników”.

W pamięci współdzielonej możesz ustawić flagę, która będzie wskazywać, czy użytkownik widział już treści. Podczas pierwszej wizyty, gdy oznaczenie nie istnieje, wykonywane jest wywołanie do prywatnej agregacji, a następnie ustawiane jest oznaczenie. Podczas kolejnych wizyt użytkownika, w tym wizyt w różnych witrynach, możesz sprawdzić Shared Storage i pominąć przesyłanie raportu do Private Aggregation, jeśli flaga jest ustawiona. Aby dowiedzieć się więcej o metodach implementowania tych pomiarów, przeczytaj nasz dokument na temat zasięgu.

Pomiar danych demograficznych

Możesz chcieć 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 od 18 do 45 lat pochodzi z Niemiec”. Używaj Shared Storage, aby uzyskiwać dostęp do danych demograficznych w kontekście innej firmy. W późniejszym czasie możesz wygenerować raport z użyciem interfejsu Private Aggregation, kodując w kluczu agregacji wymiary grupy wiekowej i kraju.

Pomiar częstotliwości K+

Możesz chcieć zmierzyć liczbę użytkowników, którzy zobaczyli treści lub reklamę co najmniej K razy w danej przeglądarce, dla wybranej wartości K.

Prywatna agregacja może podać odpowiedź w formie „Około 89 użytkowników widziało Content ID 581 co najmniej 3 razy”. Licznik może być zwiększany w pamięci współdzielonej z różnych witryn i odczytywany w worklecie. Gdy liczba osiągnie wartość K, można przesłać raport za pomocą interfejsu Private Aggregation API.

Atrybucja uwzględniająca różne interakcje

Atrybucja marketingowa to metoda stosowana przez reklamodawców do określania udziału taktyk marketingowych i późniejszych interakcji z reklamami w sprzedaży lub konwersjach.

W ramach Protected Audience API

Interfejs Protected Audience API umożliwia korzystanie z remarketingu i niestandardowych grup odbiorców, a Private Aggregation pozwala raportować zdarzenia z procesów roboczych kupujących i sprzedawców. Interfejs API może być używany do zadań takich jak pomiar rozkładu stawek w aukcji.

W worklecie Protected Audience API możesz bezpośrednio agregować dane za pomocą funkcji contributeToHistogram() i raportować je 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 roboczych interfejsów Shared Storage API 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 pamięci współdzielonej 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);

W poprzednim przykładzie kodu funkcja Private Aggregation będzie wywoływana za każdym razem, gdy załaduje się zawartość elementu iframe z innej domeny. Kod elementu iframe wczytuje worklet, a worklet wywołuje interfejs Private Aggregation API z identyfikatorem treści przekształconym w klucz agregacji (zasobnik).

contributeToHistogramOnEvent()

W przypadku elementów roboczych Protected Audience API udostępniamy mechanizm oparty na wyzwalaczach, który umożliwia wysyłanie raportu tylko wtedy, gdy wystąpi określone zdarzenie. Ta funkcja umożliwia też uzależnienie koszyka i wartości od sygnałów, które nie są jeszcze dostępne w danym momencie aukcji.

Metoda privateAggregation.contributeToHistogramOnEvent(eventType, contribution) przyjmuje argument eventType, który określa zdarzenie wywołujące, oraz argument 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 wygranej lub przegranej aukcji, albo z ramki ograniczonej, w której wyświetlono reklamę.

Aby wysłać raport o zdarzeniach 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 ramki ograniczonej, zdefiniuj niestandardowy typ zdarzenia. Aby wywołać zdarzenie z ramki z ograniczeniami, użyj metody fence.reportEvent() dostępnej w interfejsie Fenced Frames Ads Reporting API.

W tym przykładzie raport o wyświetleniu jest wysyłany, gdy zostanie wywołane zdarzenie wygranej aukcji, a raport o kliknięciu – gdy z ramki z ograniczeniami, w której wyświetlono reklamę, zostanie wywołane zdarzenie click. Na podstawie 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
  });

Więcej informacji znajdziesz w wyjaśnieniu dotyczącym rozszerzonego raportowania w ramach Private Aggregation.

enableDebugMode()

Chociaż pliki cookie innych firm są nadal dostępne, 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 uzyskanymi za pomocą interfejsu Private Aggregation API. Umożliwia też szybkie sprawdzenie integracji interfejsu API.

Wywołanie privateAggregation.enableDebugMode() w worklecie włącza tryb debugowania, w którym raporty podlegające agregacji zawierają niezaszyfrowany (tekst jawny) ładunek. Następnie możesz przetwarzać te ładunki 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, funkcja enableDebugMode() nie będzie działać.

Klucz debugowania możesz też ustawić, wywołując privateAggregation.enableDebugMode({ <debugKey: debugKey> }), gdzie BigInt może być używany jako klucz debugowania. Klucz debugowania może służyć do łączenia danych z pomiarów opartych na plikach cookie i danych z pomiarów Private Aggregation.

Można je wywołać tylko raz w danym kontekście. Wszystkie kolejne wywołania spowodują wyjątek.

// Enables debug mode
privateAggregation.enableDebugMode();

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

Zgłoś weryfikację

Interfejs Private Aggregation API umożliwia pomiary w różnych witrynach przy jednoczesnej ochronie prywatności użytkowników. Jednak osoby o złych zamiarach mogą próbować manipulować dokładnością tych pomiarów. Aby temu zapobiec, możesz użyć identyfikatora kontekstu do weryfikacji autentyczności raportów.

Ustawienie identyfikatora kontekstu pomaga zapewnić dokładność danych podczas tworzenia końcowych wyników zbiorczych. Można to osiągnąć w ten sposób:

• Zapobieganie nieprawidłowym lub nieautentycznym raportom: sprawdzaj, czy raporty są generowane za pomocą prawidłowych i autentycznych wywołań interfejsu API, co utrudnia złośliwym podmiotom tworzenie fałszywych raportów.
• Zapobieganie ponownemu wykorzystaniu raportów: wykrywanie i odrzucanie wszelkich prób ponownego wykorzystania starych raportów, aby każdy raport był uwzględniany w wynikach zbiorczych tylko raz.

Pamięć współdzielona

Jeśli używasz Shared Storage do uruchamiania operacji, która może wysyłać raport zbiorczy, możesz ustawić nieprzewidywalny identyfikator poza workletem.

Ten identyfikator jest umieszczony w raporcie utworzonym na podstawie elementu roboczego. Możesz go określić podczas wywoływania metod 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 Pamięci współdzielonej. Aby zapobiec wyciekowi informacji, na każdą operację Shared Storage wysyłany jest dokładnie 1 raport (nawet jeśli nie ma w niej żadnych danych), niezależnie od liczby wywołań funkcji contributeToHistogram().

Interfejs Private Aggregation API wysyła raporty z możliwością agregacji z losowym opóźnieniem do godziny. Ustawienie identyfikatora kontekstu w celu weryfikacji raportu zmniejsza jednak to opóźnienie. W tym przypadku występuje stałe, mniejsze opóźnienie wynoszące 5 sekund od rozpoczęcia operacji Shared Storage.

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

1. Operacja Shared Storage jest wykonywana z konfiguracją Private Aggregation, która określa identyfikator kontekstu, a następnie generowany jest raport podlegający agregacji.
2. Identyfikator kontekstu jest umieszczony w wygenerowanym raporcie podlegającym agregacji, który jest wysyłany na Twój serwer.
3. Serwer zbiera wygenerowane raporty z możliwością agregacji.
4. Procesy na serwerze sprawdzają identyfikator kontekstu w każdym raporcie podlegającym agregacji z zapisywanymi identyfikatorami kontekstu, aby zweryfikować jego ważność przed zgrupowaniem raportów i wysłaniem ich do usługi do agregacji.

Weryfikacja identyfikatora kontekstu

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

• Nieznany: jeśli raport zawiera identyfikator kontekstu, który nie został utworzony 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 lub więcej raportów z tym samym identyfikatorem kontekstu, musisz wybrać, który z nich odrzucić.
• Oznaczono w ramach wykrywania spamu:
  • Jeśli podczas przetwarzania zgłoszenia użytkownika wykryjesz podejrzaną aktywność, np. nagłą zmianę aktywności użytkownika, możesz odrzucić zgłoszenie.
  • Możesz przechowywać raporty wraz z identyfikatorami kontekstu i wszelkimi odpowiednimi sygnałami (np. ciągiem tekstowym User-Agent, źródłem odesłania itp.). Później, gdy przeanalizujesz zachowania użytkowników i zidentyfikujesz 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 wykazujących podejrzaną aktywność, nawet jeśli nie zostali oni początkowo oznaczeni.

Angażowanie się i przesyłanie opinii

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

• GitHub przeczytaj wyjaśnienie, zadawaj pytania i uczestnicz w dyskusji.
• Pomoc dla deweloperów: zadawaj pytania i bierz udział w dyskusjach w repozytorium pomocy dla deweloperów Piaskownicy prywatności.
• Dołącz do grupy Shared Storage API i grupy Protected Audience API, aby otrzymywać najnowsze informacje o interfejsie Private Aggregation.