Dla kogo jest ten artykuł?
Ten post zawiera informacje techniczne na temat bieżącej wersji eksperymentalnej wersji interfejsu Protected Audience API.
Interfejs Protected Audience API zawiera mniej techniczne omówienie oferty i zawiera również glosariusz.
Prezentacja Protected Audience zawiera przewodnik po podstawowym wdrożeniu FLEDGE.
Film demonstracyjny w ramach Protected Audience wyjaśnia, jak działa kod demonstracyjny, i pokazuje, jak używać Narzędzi deweloperskich w Chrome do debugowania tych zasad.
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:
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.
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.
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
.
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
.
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
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ń
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 dojoinAdInterestGroup()
przez kupującego reklamy. Możesz zaktualizować grupę zainteresowań wdailyUpdateUrl
.auctionSignals
Właściwość argumentu konfiguracja aukcji przekazywana donavigator.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 przypadkuauctionSignals
– właściwość argumentu konfiguracji aukcji przekazywana przez sprzedawcę donavigator.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ścitrustedBiddingSignalsKeys
dla grupy zainteresowań, a jego wartości są zwracane w żądaniutrustedBiddingSignals
.browserSignals
Obiekt utworzony przez przeglądarkę, który może zawierać informacje o kontekście strony (np. elementhostname
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 parametremrenderUrl
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ściadComponents
argumentu „grupa zainteresowań” przekazanej donavigator.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ą.
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
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': {...}, |
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', |
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 donavigator.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ść
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 zakresutrustedBiddingSignalsKeys
.
Odpowiedź na to żądanie to obiekt JSON zawierający wartości dla każdego z kluczy.
6. Wyświetla się zwycięska reklama
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 donavigator.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
iperBuyerSignals
Te same wartości przekazane dogenerateBid()
w przypadku zwycięskiego licytującego.sellerSignals
Wartość zwrócona w wysokościreportResult()
, 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
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:
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
- GitHub przeczytaj propozycję, zadawaj pytania i bierz udział w dyskusji.
- W3C: przedyskutuj przypadki użycia w branży w grupie Ulepszanie reklamy internetowej.
- Pomoc dla deweloperów: zadawaj pytania i dołączaj do dyskusji w repozytorium pomocy dla deweloperów Piaskownicy prywatności.
- Lista adresowa FLEDGE: fledge-api-announce zawiera ogłoszenia i aktualności dotyczące interfejsu API.
- Dołącz do zaplanowanych rozmów na temat Protected Audience API (co drugi tydzień). Każdy może dołączyć – jeśli chcesz wziąć udział, dołącz do WICG. Możesz aktywnie uczestniczyć lub po prostu słuchać.
- Za pomocą formularza opinii na temat Piaskownicy prywatności możesz przesłać opinię prywatnie do zespołu Chrome poza forami publicznymi.
Uzyskaj pomoc
Aby zadać pytanie na temat Twojej implementacji, wersji demonstracyjnej lub dokumentacji:
- Otwórz nowy problem w repozytorium privacy-sandbox-dev-support. Pamiętaj, aby wybrać szablon problemu dla Protected Audience API.
- Zgłoś problem w repozytorium kodu demonstracyjnego na GitHubie.
- Jeśli masz bardziej ogólne pytania dotyczące spełniania przypadków użycia interfejsu API, zgłoś problem w repozytorium ofert pakietowych.
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
- Aby otrzymywać powiadomienia o zmianach stanu w interfejsie API, dołącz do listy adresowej dla deweloperów.
- Aby uważnie śledzić wszystkie trwające dyskusje na temat interfejsu API, kliknij przycisk Obejrzyj na stronie oferty pakietowej w GitHubie. Wymaga to posiadania lub utworzenia konta GitHub.
- Aby otrzymywać ogólne informacje na temat Piaskownicy prywatności, zasubskrybuj kanał RSS [postępy w Piaskownicy prywatności].
Więcej informacji
- Protected Audience API: mniej techniczny opis oferty pakietowej.
- Prezentacja Protected Audience API: przewodnik po podstawach wdrażania Protected Audience API.
- Film demonstracyjny z funkcją Protected Audience: wyjaśnia kod demonstracyjny i pokazuje, jak używać Narzędzi deweloperskich w Chrome do debugowania tych zasad.
- Wyjaśnienie techniczne interfejsu Protected Audience API
- Więcej informacji o Piaskownicy prywatności
- Zamiar prototypu
Zdjęcie: Ray Hennessy, Unsplash.