Przewodnik dla programistów interfejsu FLEDGE API

Dla kogo jest ten artykuł?

Ten post zawiera informacje techniczne na temat bieżącej wersji eksperymentalnej wersji interfejsu Protected Audience API.

Co to jest Protected Audience API?

Protected Audience API to oferta Piaskownicy prywatności do obsługi remarketingu i niestandardowych przypadków użycia list odbiorców, które zostały zaprojektowane tak, aby inne firmy nie mogły z niej korzystać do śledzenia zachowania użytkowników w różnych witrynach. Dzięki interfejsowi API przeglądarka może wybierać reklamy dopasowane do stron, które użytkownik wcześniej odwiedził.

Protected Audience to pierwszy eksperyment zaimplementowany w Chromium w ramach rodziny ofert pakietowych TURTLEDOVE.

Poniższy diagram przedstawia omówienie cyklu życia FLEDGE:

Grafika przedstawiająca każdy etap cyklu życia FLEDGE.
Cykl życia FLEDGE.

Jak mogę skorzystać z Protected Audience API?

Wersja demonstracyjna Protected Audience API

Instrukcja wdrażania w ramach Protected Audience API w witrynach reklamodawców i wydawców znajdziesz na stronie Protect-audience-demo.web.app.

Film demonstracyjny wyjaśnia, jak działa kod demonstracyjny, i pokazuje, jak używać Narzędzi deweloperskich w Chrome do debugowania z użyciem Protected Audience API.

Weź udział w testowaniu origin w ramach Protected Audience API

W ramach wersji beta 101.0.4951.26 i nowszych wersji Chrome na komputery udostępniliśmy testowanie źródła Piaskownicy prywatności i pomiarów w ramach Piaskownicy prywatności na potrzeby interfejsów Protected Audience API, Topics i Attribution Reporting.

Aby wziąć udział w programie, zarejestruj się w celu uzyskania tokena próbnego origin.

Po zarejestrowaniu się w programie próbnym możesz wypróbować interfejs Protected Audience JavaScript API na stronach, które zawierają prawidłowy token próbny. Możesz na przykład poprosić przeglądarkę o dołączenie do co najmniej 1 grupy zainteresowań, a następnie przeprowadzić aukcję reklam, aby wybrać i wyświetlić reklamę.

Prezentacja Protected Audience to podstawowy przykład kompleksowego wdrożenia Protected Audience API.

Podaj token próbny dla każdej strony, na której chcesz uruchomić kod interfejsu Protected Audience API:

  • Jako metatag w sekcji <head>:

    <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">

  • Jako nagłówek HTTP:

    Origin-Trial: TOKEN_GOES_HERE

  • Przez automatyczne podanie tokena:

    const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

Element iframe z kodem Protected Audience API – np. wywołaniem navigator.joinAdInterestGroup() przez właściciela grupy zainteresowań – musi zawierać token zgodny z jego źródłem.

W artykule Proponowane pierwsze szczegóły okresu próbnego origin Protected Audience API dowiesz się więcej o celach pierwszego okresu próbnego i wyjaśniamy, które funkcje są obsługiwane.

Przetestuj ten interfejs API

Możesz przetestować Protected Audience API dla pojedynczego użytkownika w Chrome w wersji beta 101.0.4951.26 lub nowszej na komputerze:

  • Włączenie wszystkich interfejsów API prywatności w reklamach w sekcji chrome://settings/adPrivacy
  • Przez ustawienie flag w wierszu poleceń.

Renderowanie reklam w elementach iframe lub chronionych ramkach

Reklamy mogą być renderowane w <iframe> lub <fencedframe>, w zależności od ustawionych flag.

Aby używać komponentu <fencedframe> do renderowania reklam:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

Aby używać komponentu <iframe> do renderowania reklam:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

Dodaj flagę BiddingAndScoringDebugReportingAPI, aby włączyć tymczasowe metody raportowania utraconych/wygranych debugowania.

Artykuł Uruchamianie Chromium z flagami wyjaśnia, jak ustawiać flagi podczas uruchamiania Chrome i innych przeglądarek opartych na Chromium z poziomu wiersza poleceń. Pełna lista flag Protected Audience API jest dostępna w wyszukiwarce kodu w Chromium.

Jakie funkcje są obsługiwane w najnowszej wersji Chrome?

Udostępniamy Protected Audience API pod flagami funkcji w Chromium w ramach pierwszego eksperymentu, w ramach którego testujemy te funkcje propozycji Protected Audience:

  • Grupy zainteresowań: przechowywane przez przeglądarkę wraz z powiązanymi metadanymi służącymi do konfigurowania określania stawek i renderowania reklam.
  • Ustalanie stawek na urządzeniu przez kupujących (DSP lub reklamodawcę): na podstawie zapisanych grup zainteresowań i sygnałów od sprzedawcy.
  • Wybór reklamy na urządzeniu przez sprzedawcę (SSP lub wydawcę): na podstawie stawek na aukcji i metadanych kupujących.
  • Renderowanie reklam w tymczasowej wersji Fenced Frames: z dostępem do sieci i logowaniem w celu renderowania reklam.

Wyjaśnienie interfejsu API zawiera więcej informacji o obsłudze i ograniczeniach funkcji.

Uprawnienia grupy zainteresowań

Ustawienie domyślne w obecnej implementacji Protected Audience API pozwala na wywoływanie joinAdInterestGroup() z dowolnego miejsca na stronie – nawet z międzydomenowych elementów iframe. W przyszłości, gdy właściciele witryn będą mieli czas na dostosowanie zasad dotyczących uprawnień międzydomenowych elementów iframe, planem będzie zablokowanie wywołań z takich elementów, jak opisano w objaśnieniu.

Usługa kluczy-wartości

W ramach aukcji reklam z Protected Audience API przeglądarka może uzyskać dostęp do usługi klucz-wartość, która zwraca proste pary klucz-wartość, aby dostarczyć kupującemu reklamy informacje, np. pozostały budżet kampanii. Propozycja Protected Audience API wymaga, aby ten serwer „nie prowadził rejestrowania na poziomie zdarzenia i nie wykazywał żadnych innych skutków ubocznych związanych z tymi żądaniami”.

Kod usługi kluczy i wartości Protected Audience API jest teraz dostępny w repozytorium GitHub Piaskownicy prywatności. Z tej usługi mogą korzystać deweloperzy Chrome i deweloperzy aplikacji na Androida. Informacje na temat aktualnego stanu znajdziesz w poście na blogu z ogłoszeniem. Więcej informacji o usłudze kluczy i wartości w Protected Audience API znajdziesz w Wyjaśnieniu interfejsu API i wyjaśnieniu modelu zaufania.

Do testów początkowych używany jest model „przynieś własny serwer”. W dłuższej perspektywie do pobierania danych w czasie rzeczywistym firmy AdTech będą musiały korzystać z usług kluczy i wartości dostępnych w ramach Protected Audience API, które działają w zaufanych środowiskach wykonawczych.

Aby zapewnić wystarczającą ilość czasu na testy ekosystemu, nie będziemy wymagać korzystania z usług kluczy i wartości open source ani TEE, dopóki nie nastąpi wycofanie plików cookie innych firm. Przed dokonaniem tej zmiany powiadomimy deweloperów o możliwości rozpoczęcia testowania i wdrażania nowych funkcji.

Wykrywanie obsługi funkcji

Zanim użyjesz tego interfejsu API, sprawdź, czy jest on obsługiwany przez przeglądarkę i czy jest dostępny w dokumencie:

'joinAdInterestGroup' in navigator &&
  document.featurePolicy.allowsFeature('join-ad-interest-group') &&
  document.featurePolicy.allowsFeature('run-ad-auction') ?
  console.log('navigator.joinAdInterestGroup() is supported on this page') :
  console.log('navigator.joinAdInterestGroup() is not supported on this page');

Jak mogę zrezygnować z Protected Audience API?

Dostęp do interfejsu Protected Audience API możesz zablokować jako właściciel witryny lub pojedynczy użytkownik.

Jak witryny mogą kontrolować dostęp?

W przyszłości, aby umożliwić dostęp do tej funkcji, w ramach Protected Audience API witryny będą musiały ustawić zasady dotyczące uprawnień. Dzięki temu wybrane firmy zewnętrzne nie będą mogły używać tego interfejsu API bez wiedzy witryny. Aby jednak ułatwić testowanie podczas pierwszego testowania origin, domyślnie rezygnujemy z tego wymogu. Witryny, które chcą całkowicie wyłączyć funkcję Protected Audience API w okresie testowania, mogą zablokować dostęp za pomocą odpowiednich zasad dotyczących uprawnień.

Istnieją 2 zasady dotyczące uprawnień z Protected Audience API, które można ustawić niezależnie:

  • join-ad-interest-group włącza lub wyłącza funkcję dodawania przeglądarki do grup zainteresowań
  • run-ad-auction włącza lub wyłącza funkcję przeprowadzania aukcji na urządzeniu

Dostęp do interfejsów Protected Audience API można całkowicie wyłączyć we własnych kontekstach. W tym celu określ te uprawnienia w nagłówku odpowiedzi HTTP:

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

Aby wyłączyć interfejsy API w elemencie iframe, dodaj do elementu iframe ten atrybut allow:

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

Więcej informacji znajdziesz w sekcji Proponowana zasada dotycząca uprawnień pierwszego źródła Protected Audience API.

Rezygnacja użytkownika

Użytkownik może zablokować dostęp do interfejsu Protected Audience API i innych funkcji Piaskownicy prywatności, korzystając z dowolnego z tych mechanizmów:

  • Wyłącz wersje próbne Piaskownicy prywatności w Ustawieniach Chrome: Ustawienia > Bezpieczeństwo i prywatność > Piaskownica prywatności. Te materiały są też dostępne na stronie chrome://settings/adPrivacy.
  • Wyłącz pliki cookie innych firm w Ustawieniach Chrome: Ustawienia > Prywatność i bezpieczeństwo.
  • Ustaw Pliki cookie i inne dane witryn na „Blokuj pliki cookie innych firm” lub „Blokuj wszystkie pliki cookie” od chrome://settings/cookies.
  • korzystać z trybu incognito,

Wyjaśnienie dotyczące Protected Audience API zawiera więcej informacji o elementach projektu interfejsu API i opisuje, jak interfejs API dąży do osiągnięcia celów w zakresie prywatności.

Debuguj Worklety Protected Audience

Od wersji Chrome Canary 98.0.4718.0 można debugować Worklety Protected Audience w Narzędziach deweloperskich w Chrome.

Pierwszym krokiem jest ustawienie punktów przerwania za pomocą nowej kategorii w panelu Punkty przerwania detektora zdarzeń w panelu Źródła.

Zrzut ekranu przedstawiający Narzędzia deweloperskie w Chrome Canary z wyróżnionym panelem Punkty przerwania detektora w panelu Źródła. W sekcji Worklet aukcji reklam wybierany jest początek fazy ustalania stawek licytującego.

Po aktywowaniu punktu przerwania wykonanie jest wstrzymywane przed pierwszą instrukcją na najwyższym poziomie skryptu listy zadań. Aby przejść do funkcji określania stawek, punktacji/raportowania, możesz używać zwykłych punktów przerwania lub poleceń kroków.

Skrypty Worklet na żywo również będą widoczne w panelu Wątki.

Zrzut ekranu przedstawiający Narzędzia deweloperskie w Chrome Canary z wyróżnionym panelem Wątki w panelu Źródła oraz pokazującym bieżący skrypt zadania, który został wstrzymany.

Ponieważ niektóre Worklety mogą działać równolegle, wiele wątków może zostać zatrzymanych. Za pomocą listy wątków możesz przełączać się między wątkami, a następnie wznawiać lub sprawdzać je dokładniej.

Obserwuj zdarzenia z Protected Audience API

W panelu Aplikacje w Narzędziach deweloperskich w Chrome możesz obserwować grupę zainteresowań Protected Audience API i zdarzenia aukcji.

Jeśli otworzysz wersję demonstracyjną Protected Audience API w przeglądarce z włączoną funkcją Protected Audience API, w Narzędziach deweloperskich pojawią się informacje o zdarzeniu join.

Panel aplikacji w Narzędziach deweloperskich w Chrome Canary z informacjami o zdarzeniu dołączenia do grupy zainteresowań Protected Audience API.

Jeśli teraz w przeglądarce z włączoną Protected Audience API wejdziesz na stronę wydawców Protected Audience API, w Narzędziach deweloperskich zobaczysz informacje o zdarzeniach bid i win.

Panel aplikacji w Narzędziach deweloperskich w Chrome Canary z informacjami o stawkach na aukcji z Protected Audience i zdarzeniach wygranych.

Jak działa interfejs Protected Audience API?

W tym przykładzie użytkownik przegląda witrynę producenta rowerów niestandardowych, a potem odwiedza witrynę z wiadomościami i wyświetla mu się reklama nowego roweru tej firmy.

1. Użytkownik odwiedza witrynę reklamodawcy

Ilustracja przedstawiająca osobę odwiedzającą stronę producenta rowerów niestandardowych w przeglądarce na laptopie.

Wyobraź sobie, że użytkownik odwiedza witrynę producenta rowerów niestandardowych (w tym przykładzie reklamodawca) i odwiedza stronę z ręcznie robionym stalowym rowerem. Dzięki temu producent rowerów może skorzystać z remarketingu.

2. W przeglądarce użytkownika pojawia się prośba o dodanie grupy zainteresowań

Grafika przedstawiająca osobę, która przegląda stronę w przeglądarce na laptopie. W przeglądarce działa kod JavaScript JoinAdInterestGroup().

Sekcja wyjaśnienia: Przeglądarki rejestrują grupy zainteresowań

Platforma DSP reklamodawcy (lub sam reklamodawca) wywołuje metodę navigator.joinAdInterestGroup(), aby poprosić przeglądarkę o dodanie grupy zainteresowań do listy grup, do których należy. W tym przykładzie grupa nazywa się custom-bikes, a właścicielem grupy jest dsp.example. Właściciel grupy zainteresowań (w tym przypadku platforma DSP) będzie kupującym w aukcji reklam opisanej w kroku 4. Przynależność do grupy zainteresowań jest przechowywana przez przeglądarkę oraz na urządzeniu użytkownika i nie jest udostępniana dostawcy przeglądarki ani żadnym innym osobom.

joinAdInterestGroup() wymaga pozwolenia od:

  • Odwiedzana witryna
  • Właściciel grupy zainteresowań

Na przykład: malicious.example nie może wywołać funkcji joinAdInterestGroup() z użytkownikiem dsp.example jako właściciela bez pozwolenia dsp.example.

Zgoda z odwiedzanej witryny

To samo źródło: domyślnie uprawnienia są przyznawane domyślnie w przypadku wywołań funkcji joinAdInterestGroup() z tego samego źródła co odwiedzana witryna, czyli z tego samego źródła co ramka najwyższego poziomu bieżącej strony. Witryny mogą używać nagłówka zasady uprawnień join-ad-interest-group Protected Audience API, aby wyłączyć wywołania joinAdInterestGroup().

Z innych domen: wywołanie joinAdInterestGroup() ze źródeł innych niż strona bieżąca może się udać tylko wtedy, gdy odwiedzana witryna ma ustawioną zasadę uprawnień, która zezwala na wywołania joinAdInterestGroup() z elementów iframe z innych domen.

Uprawnienie właściciela grupy zainteresowań

Uprawnienie właściciela grupy zainteresowań jest domyślnie przyznawane przez wywołanie metody joinAdInterestGroup() z elementu iframe o tym samym pochodzeniu co właściciel grupy zainteresowań. Na przykład element iframe dsp.example może wywołać joinAdInterestGroup() w przypadku grup zainteresowań należących do dsp.example.

Propozycja polega na tym, że usługa joinAdInterestGroup() może być uruchamiana na stronie lub w elemencie iframe w domenie właściciela oraz że może być przekazywana do innych domen za pomocą listy dostępnej pod adresem URL w .well-known.

Użycie navigator.joinAdInterestGroup()

Oto przykład wykorzystania interfejsu API:

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

Obiekt interestGroup przekazywany do funkcji nie może mieć więcej niż 50 KB. W przeciwnym razie wywołanie się nie powiedzie. Drugi parametr określa okres członkostwa w grupie zainteresowań ograniczony do 30 dni. Kolejne wywołania zastępują wcześniej zapisane wartości.

Właściwości grupy zainteresowań

Właściwość Wymagane Przykład Rola
owner Wymagane 'https://dsp.example' Pochodzenie właściciela grupy zainteresowań.
name Wymagane 'custom-bikes' Nazwa grupy zainteresowań.
biddingLogicUrl** Opcjonalny* 'https://dsp.example/bid/custom-bikes/bid.js' Adres URL do ustalania stawek JavaScript uruchamianego w Worklet.
biddingWasmHelperUrl** Opcjonalny* 'https://dsp.example/bid/custom-bikes/bid.wasm' Adres URL kodu WebAssembly pochodzącego z biddingLogicUrl.
dailyUpdateUrl** Opcjonalnie 'https://dsp.example/bid/custom-bikes/update' Adres URL, który zwraca kod JSON, aby zaktualizować atrybuty grupy zainteresowań. (Patrz: Aktualizowanie grupy zainteresowań).
trustedBiddingSignalsUrl** Opcjonalnie 'https://dsp.example/trusted/bidding-signals' Podstawowy adres URL żądań par klucz-wartość wysyłanych do zaufanego serwera licytującego.
trustedBiddingSignalsKeys Opcjonalnie ['key1', 'key2' ...] Klucze dla żądań wysyłanych do zaufanego serwera według par klucz-wartość.
userBiddingSignals Opcjonalnie {...} Dodatkowe metadane, których właściciel może użyć podczas ustalania stawek.
ads Opcjonalny* [bikeAd1, bikeAd2, bikeAd3] Reklamy, które mogą być wyświetlane w przypadku tej grupy zainteresowań.
adComponents Opcjonalnie [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] Komponenty reklam złożonych z wielu elementów.

* Wszystkie właściwości są opcjonalne oprócz owner i name. Właściwości biddingLogicUrl i ads są opcjonalne, ale wymagane, aby mogły brać udział w aukcji. Może się zdarzyć, że utworzysz grupę zainteresowań bez tych właściwości, np. właściciel grupy zainteresowań może chcieć dodać przeglądarkę do grupy zainteresowań na potrzeby kampanii, która jeszcze nie jest aktywna, albo do wykorzystania w innym celu w przyszłości, albo może tymczasowo wyczerpać budżet reklamowy.

** Adresy URL biddingLogicUrl, biddingWasmHelperUrl, dailyUpdateUrl i trustedBiddingSignalsUrl muszą mieć to samo pochodzenie co właściciel. Adresy URL ads i adComponents nie mają takiego ograniczenia.

Aktualizowanie atrybutów grupy zainteresowań

dailyUpdateUrl określa serwer WWW, który zwraca właściwości grupy zainteresowań w formacie JSON, odpowiadającym obiektowi grupy zainteresowań przekazanemu do navigator.joinAdInterestGroup(). Dzięki temu właściciel grupy może okresowo aktualizować atrybuty grupy zainteresowań. W bieżącej implementacji można zmienić te atrybuty:

  • biddingLogicUrl
  • biddingWasmHelperUrl
  • trustedBiddingSignalsUrl
  • trustedBiddingSignalsKeys
  • ads
  • priority

Żadne pola nieokreślone w pliku JSON nie zostaną zastąpione – tylko pola określone w pliku JSON zostaną zaktualizowane, podczas gdy wywołanie navigator.joinAdInterestGroup() spowoduje zastąpienie istniejącej grupy zainteresowań.

Aktualizacje są wykonywane w najlepszy możliwy sposób i mogą zakończyć się niepowodzeniem w tych sytuacjach:

  • Limit czasu żądania sieciowego (obecnie 30 sekund).
  • Inny błąd sieci.
  • Błąd analizy JSON.

Aktualizacje można też anulować, jeśli z powodu zbyt długiego czasu poświęca się na aktualizowanie z bliska. Nie spowoduje to jednak ograniczenia częstotliwości przesyłania anulowanych (pozostałych) aktualizacji. Liczba aktualizacji jest ograniczona do maksymalnie 1 dziennie. Aktualizacje, które nie powiodły się z powodu błędów sieci, są ponawiane po godzinie, a aktualizacje, które nie powiodły się z powodu odłączenia od internetu, są ponawiane natychmiast po ponownym połączeniu.

Aktualizacje ręczne

Aktualizacje grup zainteresowań należących do punktu początkowego bieżącej ramki można aktywować ręcznie za pomocą navigator.updateAdInterestGroups(). Ograniczenie szybkości zapobiega zbyt częstemu aktualizowaniu: powtarzające się wywołania funkcji navigator.updateAdInterestGroups() nie wykonują żadnych działań, dopóki nie minie okres limitu (obecnie jeden dzień). Limit liczby żądań jest resetowany, jeśli funkcja navigator.joinAdInterestGroup() zostanie wywołana ponownie dla tej samej grupy zainteresowań owner i name.

Automatyczne aktualizacje

Wszystkie grupy zainteresowań wczytane na aukcji są aktualizowane automatycznie po jej zakończeniu, z zastrzeżeniem tych samych limitów stawek co w przypadku ręcznych aktualizacji. W przypadku każdego właściciela z co najmniej 1 grupą zainteresowań biorących udział w aukcji funkcja navigator.updateAdInterestGroups() jest wywoływana z elementu iframe, którego źródło pasuje do tego właściciela.

Określanie reklam dla grupy zainteresowań

Obiekty ads i adComponents zawierają adres URL kreacji i opcjonalnie metadane, których można użyć podczas ustalania stawek. Na przykład:

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

Jak kupujący ustalają stawki?

Skrypt pod adresem biddingLogicUrl udostępniony przez właściciela grupy zainteresowań musi zawierać funkcję generateBid(). Jeśli sprzedawca przestrzeni reklamowej wywołuje navigator.runAdAuction(), funkcja generatedBid() jest wywoływana raz dla każdej grupy zainteresowań, do której należy przeglądarka, jeśli jej właściciel jest zaproszony do ustalania stawek. Oznacza to, że funkcja generateBid() jest wywoływana raz dla każdej reklamy kandydującej. Sprzedawca udostępnia właściwość decisionLogicUrl w parametrze konfiguracji aukcji przekazywanym do navigator.runAdAuction(). Kod pod tym adresem URL musi zawierać funkcję scoreAd(), która jest uruchamiana w przypadku każdego licytującego biorącego udział w aukcji, by oceniać stawki zwracane przez funkcję generateBid().

Skrypt pod adresem biddingLogicUrl udostępniony przez kupującego korzystającego z przestrzeni reklamowej musi zawierać funkcję generateBid(). Ta funkcja jest wywoływana raz dla każdej reklamy kandydującej. runAdAuction() sprawdza osobno każdą reklamę i powiązaną z nią stawkę i metadane, a następnie przypisuje jej numeryczny wynik docelowej wartości.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

Funkcja generateBid() przyjmuje następujące argumenty:

  • interestGroup
    Obiekt przekazany do joinAdInterestGroup() przez kupującego reklamy. Możesz zaktualizować grupę zainteresowań w dailyUpdateUrl.

  • auctionSignals
    Właściwość argumentu konfiguracja aukcji przekazywana do navigator.runAdAuction() przez sprzedawcę przestrzeni reklamowej. Raport zawiera informacje o kontekście strony (np. rozmiar reklamy i identyfikator wydawcy), typie aukcji (pierwsza lub druga cena) oraz o innych metadanych.

  • perBuyerSignals
    Tak jak w przypadku auctionSignals – właściwość argumentu konfiguracji aukcji przekazywana przez sprzedawcę do navigator.runAdAuction(). Mogą to być sygnały kontekstowe z serwera kupującego dotyczące strony, jeśli sprzedawca to SSP, który przeprowadza wywołanie określania stawek w czasie rzeczywistym do serwerów kupującego i przeprowadza odpowiedź z powrotem, lub jeśli strona wydawcy kontaktuje się bezpośrednio z serwerem kupującego. Jeśli tak, kupujący może sprawdzić podpis kryptograficzny tych sygnałów w programie generateBid() w celu zabezpieczenia przed modyfikacją.

  • trustedBiddingSignals
    Obiekt, którego klucze to wartości trustedBiddingSignalsKeys dla grupy zainteresowań, a jego wartości są zwracane w żądaniu trustedBiddingSignals.

  • browserSignals
    Obiekt utworzony przez przeglądarkę, który może zawierać informacje o kontekście strony (np. element hostname bieżącej strony, który w innym przypadku sprzedawca mógłby zaszkodzić) i dane grupy zainteresowań (np. zapis o tym, kiedy grupa wcześniej wygrała aukcję, aby umożliwić ograniczenie liczby wyświetleń na urządzeniu).

Obiekt browserSignals ma te właściwości:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

Aby obliczyć wartość bid, kod w komórce generateBid() może używać właściwości parametrów funkcji. Na przykład:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

Funkcja generateBid() zwraca obiekt z 4 właściwościami:

  • ad
    Dowolne metadane dotyczące reklamy, takie jak informacje, które sprzedawca powinien dowiedzieć się o danej stawce lub kreacji. Sprzedawca](/privacy-sandbox/resources/glossary#ssp) wykorzystuje te informacje w swojej kreacji wyświetlanej na aukcji i w reklamie, w której podejmuje decyzje. Sprzedawca wykorzystuje te informacje w swojej aukcji i procesie decyzyjnym.

  • bid
    Stawka liczbowa, która weźmie udział w aukcji. Sprzedawca musi mieć możliwość porównywania stawek różnych kupujących, dlatego stawki muszą być podane w wybranej przez niego jednostce (np. „tysiąc PLN”). Jeśli stawka wynosi zero lub jest ujemna, grupa zainteresowań w ogóle nie weźmie udziału w aukcji sprzedawcy. Przy użyciu tego mechanizmu kupujący może stosować dowolne reguły reklamodawcy określające, gdzie mogą się pojawiać jego reklamy.

  • render
    Adres URL lub lista adresów URL, które będą używane do renderowania kreacji, jeśli określona stawka wygra aukcję. (Patrz: Reklamy złożone z wielu elementów w objaśnieniu interfejsu API). Wartość musi być zgodna z parametrem renderUrl jednej z reklam zdefiniowanych na potrzeby danej grupy zainteresowań.

  • adComponents
    Opcjonalna lista maksymalnie 20 komponentów reklam złożonych z wielu elementów pobranych z właściwości adComponents argumentu „grupa zainteresowań” przekazanej do navigator.joinAdInterestGroup().

Proszenie przeglądarki o opuszczenie grupy zainteresowań

Właściciel grupy zainteresowań może poprosić o usunięcie z niej przeglądarki. Innymi słowy, przeglądarka jest proszona o usunięcie grupy zainteresowań z listy osób, do których należy.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Jeśli użytkownik wróci do witryny, która poprosi przeglądarkę o dodanie grupy zainteresowań, właściciel grupy zainteresowań może wywołać funkcję navigator.leaveAdInterestGroup(), aby poprosić przeglądarkę o usunięcie tej grupy zainteresowań. Kod reklamy może również wywoływać tę funkcję dla odpowiedniej grupy zainteresowań.

3. Użytkownik odwiedza witrynę sprzedającą przestrzeń reklamową.

Grafika przedstawiająca osobę odwiedzającą stronę z wiadomościami w przeglądarce na laptopie. W witrynie jest pusty boks reklamowy.

Później użytkownik odwiedza witrynę, która sprzedaje przestrzeń reklamową, w tym przykładzie witryny z wiadomościami. W witrynie znajdują się zasoby reklamowe, które można sprzedawać w sposób zautomatyzowany z wykorzystaniem określania stawek w czasie rzeczywistym.

4. Aukcja reklam jest prowadzona w przeglądarce

Ilustracja przedstawiająca osobę przeglądającą stronę z wiadomościami w przeglądarce na laptopie. Trwa aukcja reklam z wykorzystaniem Protected Audience API.

Sekcja wyjaśnienia: Sprzedawcy przeprowadzają aukcje na urządzeniu

Aukcja reklam prawdopodobnie będzie prowadzona przez SSP wydawcy lub przez samego wydawcę. Celem aukcji jest wybór najbardziej odpowiedniej reklamy dla danego dostępnego boksu reklamowego na bieżącej stronie. Aukcja uwzględnia grupy zainteresowań, do których należy przeglądarka, a także dane pochodzące od kupujących przestrzeni reklamowej i sprzedawców z usług kluczy/wartości.

Sprzedawca przestrzeni reklamowej wysyła do przeglądarki użytkownika żądanie rozpoczęcia aukcji reklam, wywołując metodę navigator.runAdAuction().

Na przykład:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

runAdAuction() zwraca obietnicę zwracającą wartość URN (urn:uuid:<something>), która reprezentuje wynik aukcji reklam. Przeglądarka może go odkodować tylko wtedy, gdy jest przekazywana do chronionej ramki na potrzeby renderowania: strona wydawcy nie może sprawdzać zwycięskiej reklamy.

Skrypt decisionLogicUrl analizuje pojedynczo każdą reklamę wraz z powiązaną z nią stawką i metadanymi, a następnie przypisuje jej numeryczny wynik jakości.

auctionConfig miejsca zakwaterowania

Właściwość Wymagane Przykład Rola
seller Wymagane 'https://ssp.example' Pochodzenie sprzedawcy.
decisionLogicUrl Wymagane 'https://ssp.example/auction-decision-logic.js' Adres URL JavaScriptu Workleta aukcji.
trustedScoringSignalsUrl Opcjonalnie 'https://ssp.example/scoring-signals' Adres URL zaufanego serwera sprzedawcy.
interestGroupBuyers* Wymagane ['https://dsp.example', 'https://buyer2.example', ...] Źródła wszystkich właścicieli grup zainteresowań, którzy poprosili o udział w aukcji.
auctionSignals Opcjonalnie {...} Informacje o sprzedawcy o kontekście strony, typie aukcji itp.
sellerSignals Opcjonalnie {...} informacje zależne od ustawień wydawcy, wysyłanego kontekstowo żądań reklamy itp.
sellerTimeout Opcjonalnie 100 Maksymalny czas działania skryptu scoreAd() sprzedawcy (w milisekundach).
perBuyerSignals Opcjonalnie {'https://dsp.example': {...},
  'https://another-buyer.example': {...},
...}		 Sygnały kontekstowe dotyczące strony każdego kupującego pochodzące z jego serwera.
perBuyerTimeouts Opcjonalnie 50 Maksymalne czasy działania (w milisekundach) skryptów generateBid() kupującego.
componentAuctions Opcjonalnie [{'seller': 'https://www.some-other-ssp.com',
  'decisionLogicUrl': ..., ...},
  ...]		 Dodatkowe konfiguracje dla aukcji komponentów.

* Sprzedawca może określić interestGroupBuyers: '*', aby umożliwić licytowanie wszystkim grupom zainteresowań. Reklamy są następnie akceptowane lub odrzucane na podstawie kryteriów innych niż uwzględnienie właściciela grupy zainteresowań. Sprzedawca może na przykład sprawdzać kreacje, aby potwierdzić ich zgodność z zasadami.

** Funkcja additionalBids nie jest obsługiwana w obecnej implementacji Protected Audience API. Więcej informacji znajdziesz w sekcji Uczestnicy aukcji w wyjaśnieniu dotyczącym Protected Audience API.

Jak wybierane są reklamy?

Kod w decisionLogicUrl (właściwości obiektu konfiguracji aukcji przekazywanej do runAdAuction()) musi zawierać funkcję scoreAd(). Przeprowadzamy tę czynność raz dla każdej reklamy, aby określić jej przydatność.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

Funkcja scoreAd() przyjmuje następujące argumenty:

  • adMetadata
    Dowolne metadane podane przez kupującego.
  • bid
    Liczbowa wartość stawki.
  • auctionConfig
    Obiekt konfiguracji aukcji został przekazany do navigator.runAdAuction().
  • trustedScoringSignals
    Wartości pobrane w czasie aukcji z zaufanego serwera sprzedawcy, odzwierciedlające opinię sprzedawcy o reklamie.
  • browserSignals
    Obiekt utworzony przez przeglądarkę, w tym informacje znane przeglądarce i skrypt aukcji sprzedawcy, który może chcieć zweryfikować:
{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}

Przed rozpoczęciem aukcji sprzedawca znajduje najlepszą reklamę kontekstową dla dostępnego boksu reklamowego. Zasadą scoreAd() jest odrzucanie wszystkich reklam, które nie są lepsze od zwycięskiej reklamy kontekstowej.

5. Sprzedawcy i kupujący uczestniczący w programie otrzymują dane w czasie rzeczywistym z usługi klucz-wartość

Ilustracja przedstawiająca osobę przeglądającą stronę z wiadomościami w przeglądarce na laptopie. Trwa aukcja reklam z wykorzystaniem interfejsu Protected Audience API, w której uczestnik pobiera dane z usługi klucz-wartość.

Sekcja wyjaśnienia: pobieranie danych w czasie rzeczywistym z usługi kluczy i wartości w Protected Audience API.

Podczas aukcji reklam sprzedawca przestrzeni reklamowej może uzyskać dane o konkretnych kreacjach reklamowych w czasie rzeczywistym, wysyłając żądanie do usługi kluczy/wartości, używając właściwości trustedScoringSignalsUrl w argumencie konfiguracja aukcji przekazanej do navigator.runAdAuction(), a także kluczy z właściwości renderUrl wszystkich wpisów w polach ads i adComponents we wszystkich grupach zainteresowań w aukcji.

Podobnie kupujący zajmujący się przestrzenią reklamową może zażądać danych w czasie rzeczywistym z usługi klucz-wartość, używając właściwości trustedBiddingSignalsUrl i trustedBiddingSignalsKeys w argumencie grupy zainteresowań przekazanym do navigator.joinAdInterestGroup().

Po wywołaniu funkcji runAdAuction() przeglądarka wysyła żądanie do zaufanego serwera każdego kupującego reklamy. URL żądania może wyglądać tak:

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
  • Podstawowy adres URL pochodzi z trustedBiddingSignalsUrl.
  • Element hostname jest dostarczany przez przeglądarkę.
  • Wartość keys jest pobierana z zakresu trustedBiddingSignalsKeys.

Odpowiedź na to żądanie to obiekt JSON zawierający wartości dla każdego z kluczy.

6. Wyświetla się zwycięska reklama

Ilustracja przedstawiająca osobę przeglądającą stronę z wiadomościami w przeglądarce na laptopie. Wyświetla się reklama roweru (20% zniżki) z kłódką powyżej, która informuje, że reklama wyświetla się w ogromnej ramce.

Wyjaśnienie: Przeglądarki renderują zwycięską reklamę

Jak opisano wcześniej: obietnica zwrócona przez funkcję runAdAuction() przechodzi do identyfikatora URN, który jest przekazywany do chronionej ramki w celu renderowania, a witryna wyświetla zwycięską reklamę.

7. Wynik aukcji jest raportowany

Sekcja wyjaśnienia: Raportowanie na poziomie zdarzenia (na razie)

Wynik podany przez sprzedawcę

Sekcja wyjaśnienia: Raporty sprzedawcy dotyczące renderowania

JavaScript sprzedawcy udostępniony na stronie decisionLogicUrl (z podanym też scoreAd()) może zawierać funkcję reportResult() do raportowania wyniku aukcji.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Argumenty przekazywane do tej funkcji to:

  • auctionConfig
    Obiekt konfiguracji aukcji został przekazany do navigator.runAdAuction().

  • browserSignals
    Obiekt utworzony przez przeglądarkę, który zawiera informacje o aukcji. Przykład:

    {
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

Wartość zwrotna tej funkcji jest używana jako argument sellerSignals w funkcji reportWin() zwycięskiego licytującego.

Wynik podany w raporcie zwycięskiego licytującego

Sekcja wyjaśnienia: raporty kupujących dotyczące renderowania i zdarzeń reklamowych

Kod JavaScript zwycięskiego licytującego (który zawiera również element generateBid()) może zawierać funkcję reportWin() do raportowania wyniku aukcji.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Argumenty przekazywane do tej funkcji to:

  • auctionSignals i perBuyerSignals
    Te same wartości przekazane do generateBid() w przypadku zwycięskiego licytującego.
  • sellerSignals
    Wartość zwrócona w wysokości reportResult(), która umożliwia sprzedawcy przekazanie informacji kupującemu.

  • browserSignals
    Obiekt utworzony przez przeglądarkę, który zawiera informacje o aukcji. Przykład:

    {
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

Tymczasowe wdrożenie raportowania strat/wygranych

W Chrome na potrzeby raportowania aukcji są tymczasowo dostępne 2 metody:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Każda z tych metod wykorzystuje jeden argument: adres URL, który zostanie pobrany po zakończeniu aukcji. Można je wywoływać wiele razy (zarówno w parametrze scoreAd(), jak i generateBid()) z różnymi argumentami adresu URL.

Chrome wysyła raporty debugowania o utratach/wygranych tylko po zakończeniu aukcji. Jeśli aukcja zostanie anulowana (np. z powodu nowej nawigacji), raporty nie zostaną wygenerowane.

Te metody są domyślnie dostępne w Chrome. Aby przetestować metody, włącz wszystkie interfejsy Ad Privacy API w usłudze chrome://settings/adPrivacy. Jeśli używasz Chrome z flagami wiersza poleceń, aby włączyć Protected Audience API, musisz wyraźnie włączyć te metody, dodając flagę BiddingAndScoringDebugReportingAPI. Jeśli flaga nie jest włączona, metody nadal będą dostępne, ale nie wymagają żadnych działań.

8. Zgłoszenie kliknięcia reklamy

Grafika przedstawiająca osobę klikającą reklamę roweru w ogromnej ramce w witrynie z wiadomościami, gdzie dane raportu trafiają do sprzedawcy i kupującego.

Rejestrowane jest kliknięcie reklamy renderowanej w ramce. Więcej informacji o tym, jak to może działać, znajdziesz w artykule Raporty dotyczące reklam z zabezpieczonymi ramkami.


Poniższy diagram przedstawia każdy etap aukcji reklam z użyciem Protected Audience API:

Grafika przedstawiająca każdy etap aukcji reklam z użyciem Protected Audience API.


Jaka jest różnica między Protected Audience API a TURTLEDOVE?

Protected Audience to pierwszy eksperyment zaimplementowany w Chromium w ramach rodziny ofert pakietowych TURTLEDOVE.

Ochrona odbiorców jest zgodna z ogólnymi zasadami TURTLEDOVE. Niektóre reklamy online polegają na wyświetlaniu reklamy potencjalnie zainteresowanej osobie, która wcześniej weszła w interakcję z reklamodawcą lub siecią reklamową. W przeszłości działanie tej funkcji polegało na rozpoznaniu przez reklamodawców określonej osoby przeglądającej strony internetowe. Jest to jedna z głównych kwestii związanych z ochroną prywatności we współczesnym internecie.

Celem TURTLEDOVE jest zaoferowanie nowego interfejsu API dostosowanego do tego przypadku użycia oraz kluczowych ulepszeń w zakresie prywatności:

  • Przeglądarka, a nie reklamodawca, przechowuje informacje o tym, czym według niego reklamodawca jest zainteresowany.
  • Reklamodawcy mogą wyświetlać reklamy na podstawie zainteresowań, ale nie mogą łączyć tego zainteresowania z innymi informacjami o użytkowniku, a w szczególności o tym, kim są lub jaką stronę odwiedza.

Ochrona odbiorców powstała na bazie TURTLEDOVE i zbioru powiązanych propozycji zmian, aby lepiej służyć deweloperom, którzy z niego korzystali:

  • W SPARROW: Criteo zaproponował dodanie modelu usługi („Gatekeeper”) działającego w zaufanym środowisku wykonawczym (TEE). Protected Audience API umożliwia bardziej ograniczone korzystanie z technologii TEE do wyszukiwania danych w czasie rzeczywistym i tworzenia raportów zbiorczych.
  • Oferty TERN i PARRROT firmy NextRoll opisywały różne role, jakie kupujący i sprzedawcy mieli w aukcji na urządzeniu. Proces określania stawek lub oceniania reklam w usłudze Protected Audience API opiera się na tych działaniach.
  • Modyfikacje TURTLEDOVE oparte na wynikach i na poziomie produktu TURTLEDOVE poprawiły model anonimowości i możliwości personalizacji aukcji na urządzeniu.
  • PARAKEET to propozycja firmy Microsoft dotycząca usługi reklamowej przypominającej TURTLEDOVE, która opiera się na serwerze proxy działającym w sieci TEE między przeglądarką a dostawcami technologii reklamowych. Służy on do anonimizacji żądań reklam i egzekwowania właściwości prywatności. Ochrona odbiorców nie wdrożyła tego modelu pośredniczącego. Dążymy do ujednolicenia interfejsów API JavaScript w językach PARAKEET i Protected Audience API, aby wspierać przyszłe prace nad połączeniem najlepszych funkcji obu propozycji.

Protected Audience API nie uniemożliwia jeszcze sieci reklamowej w witrynie poznawania reklam wyświetlanych użytkownikowi. Spodziewamy się, że z czasem zmienimy interfejs API, aby stał się bardziej prywatny.

Jaka konfiguracja przeglądarki jest dostępna?

Użytkownicy mogą dostosować swój udział w okresach próbnych Piaskownicy prywatności w Chrome, włączając lub wyłączając ustawienie najwyższego poziomu w chrome://settings/adPrivacy. Podczas wstępnych testów użytkownicy będą mogli użyć tego ogólnego ustawienia Piaskownicy prywatności, aby zrezygnować z udziału w programie Protected Audience API. Chrome planuje umożliwić użytkownikom wyświetlanie listy grup zainteresowań, do których zostali dodani, i zarządzanie nią na odwiedzanych przez nich stronach internetowych. Tak jak w przypadku technologii Piaskownicy prywatności, ustawienia użytkownika mogą się zmieniać pod wpływem opinii użytkowników, organów regulacyjnych i innych osób.

W miarę postępów oferty Protected Audience API będziemy aktualizować dostępne ustawienia w Chrome na podstawie testów i opinii. W przyszłości planujemy udostępnić bardziej szczegółowe ustawienia zarządzania Protected Audience API i powiązanymi danymi.

Osoby wywołujące interfejs API nie mają dostępu do członkostwa w grupie, gdy użytkownicy przeglądają w trybie incognito. Członkostwo jest usuwane, gdy użytkownik wyczyści dane witryny.



Angażuj odbiorców i dziel się opiniami

Uzyskaj pomoc

Aby zadać pytanie na temat Twojej implementacji, wersji demonstracyjnej lub dokumentacji:

W przypadku błędów i problemów z implementacją interfejsu Protected Audience API w Chrome: * Wyświetl istniejące problemy zgłoszone dla interfejsu API. * Zgłoś nowy problem na crbug.com/new.

Otrzymuj powiadomienia

Więcej informacji

Zdjęcie: Ray Hennessy, Unsplash.