Przewodnik dla programistów dotyczący aukcji reklam na urządzeniu, które pozwalają wyświetlać reklamy remarketingowe i niestandardowe listy odbiorców bez funkcji śledzenia w witrynach zewnętrznych.
Jeśli dopiero zaczynasz korzystać z Protected Audience API, przeczytaj omówienie tego interfejsu. aby ogólnie zapoznać się z interfejsem API.
Ten post jest przeznaczony dla programistów jako pomoc techniczna w ramach niedawnej iteracji eksperymentalnego interfejsu Protected Audience API. Prezentacja Dostępne jest wdrożenie interfejsu Protected Audience API Materiały referencyjne interfejsu API dla kupujących i sprzedawców reklam
Stan implementacji
- Oferta pakietowa Protected Audience API staje się ogólnodostępna. Zadawanie pytań i obserwowanie dyskusji.
- Stan oczekujących funkcji w Protected Audience API zawiera szczegółowe informacje o zmianach oraz ulepszeniach interfejsu Protected Audience API i jego funkcji.
- Stan mrugnięcia
- Stan platformy Chrome Protected Audience API: specyficzny dla interfejsu Protected Audience API w Chrome.
- Stan platformy Chrome API w Chrome: zbiór interfejsów API ułatwiających wyświetlanie reklam: Protected Audience API, Topics, Fenced Frames i Attribution Reporting.
Aby otrzymywać powiadomienia o zmianach stanu w interfejsie API, dołącz do listy adresowej dla programistów.
Czym jest interfejs Protected Audience API?
Protected Audience API to interfejs API Piaskownicy prywatności przeznaczony do remarketing i wykorzystywanie niestandardowych list odbiorców zaprojektowane w taki sposób, że osoby trzecie nie mogą go używać do śledzenia przeglądanie stron w różnych witrynach. Interfejs API umożliwia przeprowadzanie aukcji na urządzeniu przez przeglądarki w celu wybrania trafnych reklam wyświetlanych w witrynach odwiedzonych wcześniej przez użytkownika.
Protected Audience API to pierwszy eksperyment, który zostanie zaimplementowany w Chromium Rodzina ofert pakietowych TURTLEDOVE.
Wypróbuj interfejs Protected Audience API
Dostępne materiały referencyjne interfejsu API
Ten dokument zawiera omówienie interfejsu Protected Audience API. Jeśli szukasz konkretnych metod i parametrów interfejsu API:
- Przewodnik dla kupujących korzystających z
joinAdInterestGroup()
igenerateBid()
. - Przewodnik dla sprzedawców po interfejsie Protected Audience API
runAdAuction()
- Przewodnik dla kupujących po
reportWin()
i przewodnik sprzedawcyreportResult()
- Rozwiązywanie problemów z interfejsem Protected Audience API
Możesz też zapoznać się ze sprawdzonymi metodami dotyczącymi opóźnienia aukcji reklam w ramach Protected Audience API.
Prezentacja interfejsu Protected Audience API
Przewodnik po podstawach wdrożenia interfejsu Protected Audience API na poziomie reklamodawcy i wydawcy są dostępne pod adresem protected-audience-demo.web.app/.
Przetestuj ten interfejs API
Interfejs Protected Audience API możesz przetestować dla pojedynczego użytkownika w Chrome w wersji beta 101.0.4951.26 lub nowszej na komputery:
- Włącz wszystkie interfejsy Ad Privacy API w sekcji
chrome://settings/adPrivacy
. - ustaw flagi z poziomu wiersza poleceń. Pełną listę dostępnych flag interfejsu Protected Audience API znajdziesz tutaj: Wyszukiwanie kodu w Chromium.
Renderowanie reklam w elementach iframe lub chronionych ramkach
Reklamy mogą być renderowane w <iframe>
lub
<fencedframe>
, w zależności od tego,
flagi są ustawione.
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
Aby włączyć, uwzględnij flagę BiddingAndScoringDebugReportingAPI
tymczasowe metody raportowania utraty/wygrania na potrzeby debugowania.
Obsługiwane funkcje
Protected Audience API za flagami funkcji w Chromium to pierwszy eksperyment, w którym testujemy te funkcje interfejsu Protected Audience API:
- grupy zainteresowań: przechowywane przez przeglądarkę, wraz z powiązanymi metadanymi, skonfigurować określanie stawek i renderowanie 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 stawki aukcji i metadane od kupujących.
- Renderowanie reklam w tymczasowej wersji Fenceed Frames: dostępu do sieci i logowania w przypadku renderowania reklam.
Więcej informacji o obsłudze i ograniczeniach funkcji znajdziesz w Wyjaśnienie do interfejsu Protected Audience API.
Uprawnienia grupy zainteresowań
Ustawienie domyślne w bieżącej implementacji interfejsu Protected Audience API to zezwala na wywoływanie
joinAdInterestGroup()
z dowolnego miejsca na stronie, nawet z międzydomenowych elementów iframe.
Gdy w przyszłości właściciele witryn będą mieli czas na zaktualizowanie swoich danych w wielu domenach zasad uprawnień iframe, jest zablokowanie połączeń z międzydomenowych elementów iframe.
Usługa kluczy-wartości
Aby obsługiwać aukcję reklam w ramach Protected Audience API, przeglądarka może uzyskać dostęp do usługa kluczy/wartości aby pobierać informacje w czasie rzeczywistym na potrzeby aukcji reklam w ramach Protected Audience API. Ten informacje można wykorzystać na wiele sposobów:
- Kupujący mogą chcieć obliczyć pozostały budżet kampanii reklamowej.
- Być może sprzedawcy będą musieli sprawdzić kreacje reklamowe pod kątem zgodności z zasadami dotyczącymi wydawców.
Kod usługi klucz-wartość interfejsu Protected Audience API Usługa jest już dostępna. Informacje na temat aktualnego stanu znajdziesz w poście na blogu z ogłoszeniem.
Do przeprowadzenia wstępnych testów: „przynieś własny serwer” model LLM. W dłuższej perspektywie technologie reklamowe będą musiały wykorzystywać usługi kluczy/wartości interfejsu Protected Audience API open source działające w zaufanym wykonaniu. w różnych środowiskach.
Przeczytaj posta na blogu na temat usług interfejsu Protected Audience API. . Aby deweloperzy mogli zacząć testów i rozpowszechnienia przed tą zmianą.
Wykrywanie obsługi funkcji
Przed użyciem interfejsu API sprawdź, czy jest on obsługiwany przez przeglądarkę i dostępny dokument:
'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 działa interfejs Protected Audience API?
W tym przykładzie użytkownik przegląda witrynę producenta rowerów niestandardowych, a następnie odwiedza witrynę z wiadomościami i widzi reklamę nowego roweru tej firmy.
Funkcje Protected Audience API będą dodawane do interfejsu w miarę postępów wdrażania.
1. Użytkownik odwiedza witrynę reklamodawcy
![Osoba odwiedzająca w przeglądarce na laptopie stronę internetową producenta rowerów.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-visiting-custom-2ca7094e57259.png?authuser=8&hl=pl)
Wyobraź sobie, że użytkownik odwiedza witrynę firmy produkującej rowery niestandardowe (reklamodawcy) w tym przykładzie) i spędza trochę czasu na stronie produktu ze stali wytwarzanej ręcznie. roweru. Dzięki temu producent rowerów może Możliwość remarketingu.
2. W przeglądarce użytkownika pojawia się prośba o dodanie grupy zainteresowań
![Użytkownik otwiera przeglądarkę na laptopie i otwiera stronę internetową. JavaScript
w przeglądarce jest uruchomiony kod dołączania do grup zainteresowań związanych z reklamami.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-user-opens-browser-th-6c2a4e6d97af7.png?authuser=8&hl=pl)
Platforma DSP reklamodawcy (lub sam reklamodawca) wywołuje wywołanie
navigator.joinAdInterestGroup()
, aby poprosić przeglądarkę o dodanie grupy zainteresowań
na liście grup, do których należy przeglądarka.
W tym przykładzie nazwa grupy to custom-bikes
, a jej właścicielem jest dsp.example
. Właściciel grupy zainteresowań (w tym przypadku DSP) będzie kupującym.
w aukcji reklam Protected Audience API. Przynależność do grup zainteresowań jest przechowywana w przeglądarce,
na urządzeniu użytkownika i nie jest udostępniana dostawcy ani nikomu innemu.
- Przeczytaj objaśnienie interfejsu Protected Audience API: Przeglądarki rejestrują grupy zainteresowań.
- Przeczytaj przewodnik po interfejsie API: kupujący i platformy DSP oraz dowiedz się,
joinAdInterestGroup()
i generuj stawki.
Określanie reklam dla grupy zainteresowań
Obiekty ads
i adComponents
zawierają adres URL kreacji oraz
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?
Funkcja generateBid()
jest wywoływana w przypadku każdej grupy zainteresowań, do której należy przeglądarka
– jeśli właściciel grupy zainteresowań został zaproszony do licytacji.
Zapoznaj się z dokumentacją dla deweloperów generatedBid()
.
3. Użytkownik odwiedza witrynę sprzedającą przestrzeń reklamową.
![Osoba odwiedza witrynę z wiadomościami w przeglądarce na laptopie. Witryna
ma pusty boks reklamowy.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-visits-news-web-3209fc4021a42.png?authuser=8&hl=pl)
Później użytkownik odwiedza witrynę sprzedającą przestrzeń reklamową, w tym przypadku witryny. Na stronie znajdują się zasoby reklamowe, które można sprzedawać automatycznie za pomocą określania stawek w czasie rzeczywistym.
4. Aukcja reklam jest prowadzona w przeglądarce
![Osoba przegląda witrynę z wiadomościami w przeglądarce na laptopie. Aby wybrać reklamę do wyświetlenia w dostępnej przestrzeni reklamowej, przeprowadzana jest aukcja reklam interfejsu Protected Audience API.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-views-news-webs-32cbfd93dc442.png?authuser=8&hl=pl)
Aukcja reklam prawdopodobnie będzie prowadzona przez dostawcę usług dostawców wydawcy (SSP) lub przez wydawcę. Celem aukcji jest wybór najbardziej odpowiednia dla pojedynczego dostępnego boksu na bieżącej stronie. uwzględnia grupy zainteresowań, do których należy przeglądarka, wraz z danymi od kupujących przestrzeni reklamowej i sprzedawców Usługi kluczy i wartości.
- Przeczytaj objaśnienie interfejsu Protected Audience API: Sprzedawcy przeprowadzają aukcje na urządzeniu
- Przeczytaj przewodnik po interfejsie API: sprzedawcy mogą dowiedzieć się więcej o
runAdAuction()
oraz sprawdzone metody dotyczące opóźnienia aukcji reklam.
5. Sprzedawca i kupujący uczestniczący w programie proszą usługi klucz-wartość o dostęp do danych w czasie rzeczywistym
![Użytkownik przegląda stronę z wiadomościami w przeglądarce na laptopie. Reklamą
trwa aukcja z wykorzystaniem Protected Audience API, w której uczestnik pobiera dane z usługi klucz-wartość.](https://developers.google.cn/static/privacy-sandbox/assets/images/the-user-views-news-webs-6969c01094b4.png?authuser=8&hl=pl)
Podczas aukcji reklam sprzedawca może zażądać danych o konkretnej reklamie w czasie rzeczywistym
wysyłając żądanie do usługi kluczy/wartości.
Sprzedawca może poprosić o te informacje w trakcie
runAdAuction()
przez właściwość trustedScoringSignalsUrl
,
wraz z kluczami z właściwości renderUrl
wszystkich wpisów w ads
i pola adComponents
wszystkich grup zainteresowań w aukcji.
Kupujący może zażądać danych w czasie rzeczywistym ze swojej usługi kluczy i wartości za pomocą
właściwości trustedBiddingSignalsUrl
i trustedBiddingSignalsKeys
funkcji
argument grupy zainteresowań przekazany do funkcji navigator.joinAdInterestGroup()
.
Po wywołaniu funkcji runAdAuction()
przeglądarka wysyła żądanie do każdej reklamy
zaufanego serwera kupującego. Adres 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 klawiszy.
- Przeczytaj objaśnienie interfejsu Protected Audience API: pobieranie danych w czasie rzeczywistym z usługi kluczy lub wartości interfejsu Protected Audience API.
- Przeczytaj artykuł na temat programu open source usługi kluczy i wartości interfejsu Protected Audience API.
6. Wyświetla się zwycięska reklama
![Osoba przegląda witrynę z wiadomościami w przeglądarce na laptopie. Reklamą
z 20% zniżką, rower jest wyświetlany w bezpiecznej, ogrodzonej ramce.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-views-news-webs-2dc1236041c17.png?authuser=8&hl=pl)
Obietnica zwrócona przez funkcję runAdAuction() zwraca się do obiektu konfiguracji ramki chronionej (FencedFrameConfig
), gdy w konfiguracji aukcji flaga resolveToConfig
jest ustawiona na true
. Ramka chroniona używa konfiguracji ramki, aby przejść do zwycięskiej reklamy, ale adres URL reklamy jest niewidoczny dla umieszczonej reklamy.
Obiekt konfiguracji ramki chronionej jest dostępny od wersji M114. Więcej informacji o obiekcie FencedFrameConfig
znajdziesz w tym artykule na blogu Chrome.
- Przeczytaj objaśnienie interfejsu Protected Audience API: przeglądarki renderują zwycięską reklamę
7. Wynik aukcji jest raportowany
Planem długoterminowym jest umożliwienie przeglądarce raportowania wyników aukcji sprzedawców i kupujących za pomocą interfejsów Private Aggregation API.
Jako tymczasowy mechanizm raportowania na poziomie zdarzenia, kod implementujący
reportResult()
w przypadku sprzedawcy i reportWin()
w przypadku zwycięskiego licytującego.
wywołaj funkcję sendReportTo()
. Przyjmuje to pojedynczy argument: ciąg znaków
reprezentujący adres URL pobierany po zakończeniu aukcji, który koduje
informacje na poziomie zdarzenia,
które mają być raportowane.
- Przeczytaj przewodnik po interfejsie API: dowiedz się więcej o raportowaniu dla sprzedawców i kupujących.
8. Zgłoszenie kliknięcia reklamy
![Użytkownik klika reklamę roweru umieszczoną w ramce ogrodowej w witrynie z wiadomościami. Dane z raportu są wysyłane do sprzedawców i kupujących.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-clicks-an-ad-a-be2111724646f.png?authuser=8&hl=pl)
Rejestrowane jest kliknięcie reklamy renderowanej w ramce. Aby dowiedzieć się więcej o: jak to może działać, zapoznaj się z artykułem Raporty dotyczące reklam z ramkami zabezpieczonymi.
![Omówienie każdego etapu aukcji reklam w ramach Protected Audience API](https://developers.google.cn/static/privacy-sandbox/assets/images/an-overview-each-stage-c8bac3c2c070f.png?authuser=8&hl=pl)
Czym różni się interfejs Protected Audience API od TURTLEDOVE?
Protected Audience API to pierwszy eksperyment, który zostanie zaimplementowany w Chromium Rodzina ofert pakietowych TURTLEDOVE.
Interfejs Protected Audience API jest zgodny z ogólnymi zasadami TURTLEDOVE. Niektóre reklamy online polegają na wyświetleniu reklamy potencjalnie zainteresowanej osobie, która weszli wcześniej w interakcję z reklamodawcą lub siecią reklamową. W przeszłości Gdy reklamodawca rozpoznaje konkretną osobę, która przegląda witryn internetowych, które stanowią dziś podstawę ochrony prywatności.
Celem TURTLEDOVE jest zaoferowanie nowego interfejsu API dostosowanego do tego przypadku użycia. a jednocześnie oferuje kilka ważnych ulepszeń w zakresie prywatności:
- To przeglądarka, a nie reklamodawca, przechowuje informacje o tym, reklamodawca uważa, że dana osoba jest zainteresowana.
- Reklamodawcy mogą wyświetlać reklamy na podstawie zainteresowań, ale nie mogą tego łączyć. innymi informacjami o danej osobie, a w szczególności o tym, czy jaką stronę odwiedzają.
Interfejs Protected Audience API powstał z wykorzystaniem narzędzia TURTLEDOVE i zbioru powiązanych propozycji dotyczących zmiany w celu lepszego wspierania deweloperów korzystających z interfejsu API:
- W SPARROW: Criteo zaproponował(a) dodanie modelu usługi („Gatekeeper”) działającego w zaufanym środowisku wykonawczym (TEE). Interfejs Protected Audience API umożliwia bardziej ograniczone wykorzystanie TEE do wyszukiwania danych w czasie rzeczywistym i tworzenia raportów zbiorczych.
- TERN i PARRROT Magnite opisywały różne role, jakie kupujący i sprzedawcy mieli aukcja na urządzeniu. Proces określania stawek lub oceniania reklam w interfejsie Protected Audience API bazuje na tych pracach.
- Oparty na wynikach RTB House i poziom produktu. Modyfikacje TURTLEDOVE poprawiły model anonimowości i personalizację możliwości aukcji na urządzeniu
- PARAKEET to Propozycja firmy Microsoft dotycząca usługi reklamowej podobnej do TURTLEDOVE, która wymaga serwera proxy serwer działający w sieci TEE, który łączy przeglądarkę z dostawcami technologii reklamowych, anonimizować żądania reklam i wymuszać ochronę prywatności, usług. Interfejs Protected Audience API nie wdrożył tego modelu pośredniczącego. Przedstawiamy interfejsy API JavaScript dla PARAKEET i Protected Audience API w celu dostosowania nad łączeniem w przyszłości najlepszych cech obu ofert.
Interfejs Protected Audience API nie uniemożliwia jeszcze sieci reklamowej witryny poznawania reklam wyświetlanych użytkownikowi. Spodziewamy się, że z czasem zmienimy interfejs API, aby stał się bardziej prywatny.
Czy interfejsu Topics API można używać w połączeniu z interfejsem Protected Audience API?
Tak. Zaobserwowany przez bieżącego użytkownika temat udostępniony przez interfejs Topics API może zostać wykorzystany jako kontekstowych przez sprzedawcę lub licytującego. Temat może być uwzględniony w tych właściwości:
auctionSignals
, właściwość obiektu konfiguracji aukcji przekazywaną donavigator.runAdAuction()
userBiddingSignals
, właściwość konfiguracji grupy zainteresowań obiekt przekazany donavigator.joinAdInterestGroup()
Dostępna konfiguracja przeglądarki
Użytkownicy mogą dostosować swój udział w okresach próbnych Piaskownicy prywatności w Chrome przez
włączanie i wyłączanie ustawienia najwyższego poziomu w
chrome://settings/adPrivacy
Podczas wstępnych testów użytkownicy będą mogli korzystać z tego wysokiego poziomu Prywatność Ustawienie piaskownicy, aby zrezygnować z interfejsu Protected Audience API. Planujemy umożliwić użytkownikom wyświetlanie zarządzać listą grup zainteresowań, do których zostały dodane w całym internecie odwiedzonych przez nich stron. Podobnie jak w przypadku technologii Piaskownicy prywatności, ustawienia mogą się zmieniać na podstawie opinii użytkowników, organów regulacyjnych i innych osób.
Na podstawie testów i opinii będziemy nadal aktualizować dostępne ustawienia w Chrome. W przyszłości planujemy udostępnić bardziej szczegółowe ustawienia do zarządzania interfejsem Protected Audience API oraz powiązane dane.
Osoby wywołujące interfejs API nie mają dostępu do członkostwa w grupie, gdy użytkownicy przeglądają w trybie incognito. a członkostwo jest usuwane, gdy użytkownik wyczyści dane witryny.
Czy Worklety Protected Audience API są przechowywane w pamięci podręcznej przeglądarki?
Zasoby zawierające Worklety Protected Audience API – listy narzędzi do generowania stawek i raportowania kupującego oraz listy wyników reklam i raportowania sprzedawcy – są przechowywane w pamięci podręcznej przeglądarki. Za pomocą nagłówka Cache-Control
możesz kontrolować działanie buforowania.
Angażuj odbiorców i dziel się opiniami
Uzyskaj pomoc
Aby zadać pytania i uzyskać pomoc dotyczącą implementacji, dokumentacja:
- GitHub: przeczytaj Wyjaśnienie, Przesyłaj pytania i śledź dyskusję.
- Demonstracja: zgłoś problem w repozytorium kodu demonstracyjnego.
- Pomoc dla deweloperów: zadawaj pytania i dołączaj do dyskusji na Pomoc dla deweloperów w Piaskownicy prywatności repozytorium. Wybierz szablon problemu dotyczący Protected Audience API.
- Implementacja Chrome: wykrywanie błędów i problemów z implementacją Chrome interfejsu Protected Audience API, możesz wyświetlić dotychczasowe problemy lub zgłaszają nowy problem.
Jeśli masz więcej ogólnych pytań dotyczących korzystania z interfejsu Protected Audience API, zgłosić problem w repozytorium API. Branżowe przypadki użycia można omówić podczas spotkania W3C Ulepszanie grupy biznesowej związanej z reklamą w internecie.
Użyj formularza opinii na temat Piaskownicy prywatności. .
Rezygnacja
Czy chcesz zrezygnować z interfejsu Protected Audience API? Dowiedz się, jak zablokować dostęp do interfejsu Protected Audience API, zarówno Ty, jak i właściciel witryny.
Otrzymuj powiadomienia
- Aby otrzymywać powiadomienia o zmianach stanu interfejsu API, dołącz do listy adresowej dla programistów.
- Aby dokładnie śledzić wszystkie trwające dyskusje na temat interfejsu API, kliknij przycisk Obejrzyj na stronie interfejsu API GitHub. Wymaga to posiadania lub utworzenia konta GitHub .
- Aby otrzymywać ogólne informacje na temat Piaskownicy prywatności, zasubskrybuj kanał RSS [Postęp w Piaskownicy prywatności]
- Dołącz do zaplanowanych wywołań interfejsu Protected Audience API (co drugi tydzień). Każdy jest mile widziany, pamiętaj, aby dołączyć do WICG. Ty mogą aktywnie uczestniczyć lub tylko słuchać.