Protected Audience API: przewodnik dla programistów

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

To be notified of status changes in the API, join the mailing list for developers.

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:

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/.

Obejrzyj to kompleksowe wdrożenie, aby dowiedzieć się, jak działa kod demonstracyjny interfejsu Protected Audience API i jak używać Narzędzi deweloperskich w Chrome do debugowania.

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:

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.

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.

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.

.

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.

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.

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.

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ść.

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 zakresu trustedBiddingSignalsKeys.

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

.

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.

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.

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.

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.

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
Ten schemat przedstawia każdy etap aukcji Protected Audience API.

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ą do navigator.runAdAuction()
  • userBiddingSignals, właściwość konfiguracji grupy zainteresowań obiekt przekazany do navigator.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:

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