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 artykuł Omówienie Protected Audience API, aby poznać jego ogólny charakter.
Ten post został napisany z myślą o deweloperach, aby zawierał informacje techniczne dotyczące najnowszej wersji eksperymentalnej wersji Protected Audience API. Dostępne są prezentacja podstawowego wdrożenia interfejsu Protected Audience API oraz materiały referencyjne na temat interfejsu API dla nabywców 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 zaprojektowany do obsługi remarketingu i niestandardowych zastosowań list odbiorców. Zaprojektowano go tak, aby inne firmy nie mogły używać go 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 API to pierwszy eksperyment zaimplementowany w Chromium w ramach rodziny 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 dotyczący Protected Audience API
runAdAuction()
- Przewodnik po
reportWin()
dla kupujących i przewodnik dla sprzedawców:reportResult()
- 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 dotyczący podstawowego wdrożenia interfejsu Protected Audience API w witrynach reklamodawców i wydawców jest dostępny na stronie Protected-audience-demo.web.app/.
Przetestuj ten interfejs API
Możesz przetestować interfejs Protected Audience API dla pojedynczego użytkownika w Chrome w wersji beta 101.0.4951.26 lub nowszej na komputerze:
- 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 w artykule 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 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.
Obsługiwane funkcje
Protected Audience API za flagami funkcji w Chromium to pierwszy eksperyment mający na celu przetestowanie tych funkcji interfejsu Protected Audience API:
- 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 od kupujących.
- Renderowanie reklam w tymczasowej wersji Fencingu Frames: z dostępem do sieci i logowaniem na potrzeby renderowania reklam.
Więcej informacji o obsługiwanych funkcjach i ograniczeniach znajdziesz w wyjaśnieniu na temat 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.
W przyszłości, gdy właściciele witryn będą mieli czas na zaktualizowanie zasad uprawnień międzydomenowych elementów iframe, planowane będzie zablokowanie wywołań z takich elementów.
Usługa kluczy-wartości
Aby obsługiwać aukcję reklam w ramach Protected Audience API, przeglądarka może korzystać z usługi klucz-wartość, która pobiera w czasie rzeczywistym informacje potrzebne do przeprowadzenia aukcji reklam w ramach Protected Audience API. Te 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.
Jest już dostępny kod usługi klucz-wartość interfejsu Protected Audience API. Informacje na temat aktualnego stanu znajdziesz w poście na blogu z ogłoszeniem.
Do testów wstępnych wprowadziliśmy model „przynieś własny serwer”. W dłuższej perspektywie specjaliści ds. technologii reklamowych będą musieli korzystać z usług kluczy i wartości interfejsu Protected Audience API open source działających w zaufanych środowiskach wykonawczych.
Aktualne informacje o harmonogramie znajdziesz w poście na blogu na temat usług Protected Audience API. Przed wprowadzeniem tej zmiany deweloperzy otrzymają od nas istotne powiadomienie o możliwości rozpoczęcia testowania i wdrażania.
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 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.
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=3&hl=pl)
Wyobraź sobie, że użytkownik odwiedza w tym przykładzie witrynę firmy produkującej rowery na zamówienie (reklamodawcę) i przegląda stronę produktu ręcznie robionego roweru stalowego. Dzięki temu producent rowerów zyskuje 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ą. W przeglądarce działa kod JavaScript służący do 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=3&hl=pl)
Platforma DSP reklamodawcy (lub sam reklamodawca) wywołuje metodę navigator.joinAdInterestGroup()
, aby poprosić przeglądarkę o dodanie grupy zainteresowań do listy grup, do której należy.
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 platforma DSP) będzie kupującym w aukcji reklam interfejsu Protected Audience API. Przynależność do grupy zainteresowań jest przechowywana przez przeglądarkę na urządzeniu użytkownika i nie jest udostępniana dostawcy przeglądarki ani nikomu innemu.
- Przeczytaj objaśnienie interfejsu Protected Audience API: Przeglądarki rejestrują grupy zainteresowań.
- Przeczytaj przewodnik po interfejsie API: znajdziesz tu informacje dla kupujących i platform DSP oraz informacje o
joinAdInterestGroup()
i generowaniu stawek.
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 jej właściciel został zaproszony do ustalania stawek.
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. W witrynie jest pusty boks reklamowy.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-visits-news-web-3209fc4021a42.png?authuser=3&hl=pl)
Później użytkownik odwiedza witrynę sprzedającą przestrzeń reklamową, w tym przykładzie witryny z wiadomościami. Na stronie 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
![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=3&hl=pl)
Aukcja reklam prawdopodobnie będzie prowadzona przez dostawcę platformy dostawców reklam wydawcy lub przez samego wydawcę. Celem aukcji jest wybór najbardziej odpowiedniej reklamy dla pojedynczego dostępnego boksu reklamowego na bieżącej stronie. Podczas aukcji brane są pod uwagę grupy zainteresowań, do których należy przeglądarka, oraz dane od nabywców przestrzeni reklamowej i sprzedawców z usług kluczy/wartości.
- Przeczytaj objaśnienie interfejsu Protected Audience API: Sprzedawcy przeprowadzają aukcje na urządzeniu
- Przeczytaj przewodnik po interfejsie API: sprzedawcy mogą się dowiedzieć więcej o
runAdAuction()
i sprawdzonych metodach dotyczących opóźnień w aukcjach reklam.
5. Sprzedawca i kupujący uczestniczący w programie proszą usługę klucz-wartość o dostęp do danych w czasie rzeczywistym
![Użytkownik przegląda 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ść.](https://developers.google.cn/static/privacy-sandbox/assets/images/the-user-views-news-webs-6969c01094b4.png?authuser=3&hl=pl)
Podczas aukcji reklam sprzedawca może zażądać danych w czasie rzeczywistym o konkretnych kreacjach reklamowych, wysyłając żądanie do usługi kluczy/wartości.
Sprzedawca może poprosić o te informacje podczas runAdAuction()
za pomocą właściwości trustedScoringSignalsUrl
, wraz z kluczami z właściwości renderUrl
wszystkich wpisów w polach ads
i adComponents
we wszystkich grupach zainteresowań w aukcji.
Kupujący może zażądać danych w czasie rzeczywistym ze swojej usługi klucz-wartość, używając właściwości trustedBiddingSignalsUrl
i trustedBiddingSignalsKeys
argumentu grupy zainteresowań przekazanej do navigator.joinAdInterestGroup()
.
Po wywołaniu funkcji runAdAuction()
przeglądarka wysyła żądanie do zaufanego serwera każdego kupującego reklamy. 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 z kluczy.
- 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. Reklama 20% zniżki na rower jest wyświetlana w bezpiecznej ramce.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-views-news-webs-2dc1236041c17.png?authuser=3&hl=pl)
Obietnica zwrócona przez funkcję runAdAuction() przechodzi 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 dla 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 może wywoływać funkcję sendReportTo()
. Chodzi o 1 argument: ciąg znaków reprezentujący adres URL pobierany po zakończeniu aukcji, który koduje informacje na poziomie zdarzenia do uwzględnienia w raportach.
- 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=3&hl=pl)
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.
![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=3&hl=pl)
Czym różni się interfejs Protected Audience API od TURTLEDOVE?
Protected Audience API to pierwszy eksperyment zaimplementowany w Chromium w ramach rodziny ofert pakietowych TURTLEDOVE.
Interfejs Protected Audience API jest zgodny z ogólnymi zasadami TURTLEDOVE. Niektóre reklamy online polegały 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 polegało na tym, że reklamodawca rozpoznaje konkretną osobę, która przegląda 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 się interesuje.
- Reklamodawcy mogą wyświetlać reklamy na podstawie zainteresowań, ale nie mogą łączyć tych zainteresowań z innymi informacjami o użytkowniku, a w szczególności o tym, kim oni są ani jaką stronę odwiedza.
Interfejs Protected Audience API powstał z wykorzystaniem 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). Interfejs Protected Audience API umożliwia bardziej ograniczone wykorzystanie 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 interfejsie Protected Audience API bazuje na tych pracach.
- Modyfikacje TURTLEDOVE oparte na wynikach i na poziomie produktu zwiększyły poziom anonimowości i możliwości personalizacji aukcji na urządzeniu.
- PARAKEET to propozycja firmy Microsoft dotycząca usługi reklamowej podobnej do TURTLEDOVE, która opiera się na serwerze proxy działającym w 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. Interfejs Protected Audience API nie wdrożył tego modelu pośredniczącego. Dążymy do ujednolicenia interfejsów API JavaScript w PARAKEET i Protected Audience API w związku z dalszymi pracami nad połączeniem najlepszych funkcji 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 temat bieżącego użytkownika udostępniony przez interfejs Topics API może zostać wykorzystany przez sprzedawcę lub licytującego jako informacje kontekstowe. Tematem może być:
auctionSignals
, właściwość obiektu konfiguracji aukcji przekazywaną donavigator.runAdAuction()
userBiddingSignals
, właściwość obiektu konfiguracji grupy zainteresowań przekazanej donavigator.joinAdInterestGroup()
,
Dostępna konfiguracja przeglądarki
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 korzystania z 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. Podobnie jak w przypadku technologii Piaskownicy prywatności, ustawienia użytkownika mogą zmieniać się 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 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.
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, prezentacji lub dokumentacji:
- GitHub przeczytaj wyjaśnienie, zadawaj pytania i bierz udział w dyskusji.
- Demonstracja: zgłoś problem w repozytorium kodu demonstracyjnego.
- Pomoc dla deweloperów: zadawaj pytania i dołączaj do dyskusji w repozytorium pomocy dla deweloperów Piaskownicy prywatności. Wybierz szablon problemu dotyczący Protected Audience API.
- Implementacja w Chrome: w przypadku błędów lub problemów z implementacją interfejsu Protected Audience API w Chrome możesz wyświetlić obecne problemy lub zgłosić nowy.
Aby otrzymać odpowiedzi na bardziej ogólne pytania dotyczące korzystania z interfejsu Protected Audience API, zgłoś problem w repozytorium interfejsów API. Możesz także omówić przypadki użycia w różnych branżach w ramach grupy W3C Ulepszanie reklamy w internecie w grupie biznesowej (w języku angielskim).
Za pomocą formularza opinii na temat Piaskownicy prywatności możesz przesłać opinię prywatnie do zespołu Chrome poza forami publicznymi.
Rezygnacja
Czy chcesz zrezygnować z interfejsu Protected Audience API? Dowiedz się, jak zablokować dostęp do interfejsu Protected Audience API jako właściciel witryny lub pojedynczy użytkownik.
Otrzymuj powiadomienia
- Aby otrzymywać powiadomienia o zmianach stanu interfejsu API, zapoznaj się z listą adresową dla deweloperów.
- Aby na bieżąco śledzić wszystkie dyskusje na temat interfejsu API, kliknij przycisk Obejrzyj na stronie interfejsu API 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].
- Dołącz do zaplanowanych wywołań interfejsu Protected Audience API (co 2 tygodnie). Każdy może dołączyć – jeśli chcesz wziąć udział, musisz dołączyć do WICG. Możesz aktywnie uczestniczyć lub po prostu słuchać.