Protected Audience API: przewodnik dla programistów

Przewodnik dla programistów po aukcjach reklam na urządzeniu w celu obsługi remarketingu i niestandardowych list odbiorców bez śledzenia w witrynach zewnętrznych.

Jeśli jesteś nowym użytkownikiem interfejsu Protected Audience API, przeczytaj omówienie tego interfejsu, aby poznać ogólne omówienie interfejsu API.

Ten post jest przeznaczony dla deweloperów i zawiera informacje techniczne o najnowszej wersji eksperymentalnej interfejsu Protected Audience API. Dostępna jest prezentacja podstawowego wdrożenia interfejsu Protected Audience API oraz materiały referencyjne interfejsu API dla kupujących i sprzedawców reklam.

Stan implementacji

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 z myślą o remarketingu i niestandardowych przypadkach użycia list odbiorców. Zaprojektowany w taki sposób, że inne firmy nie mogą go używać do śledzenia działań użytkowników w różnych witrynach. Interfejs API umożliwia przeglądarce w aukcjach na urządzeniu wybór trafnych reklam do witryn, które odwiedzał wcześniej.

Protected Audience API to pierwszy eksperyment, który został wdrożony 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:

Możesz też zapoznać się z artykułem na temat sprawdzonych metod dotyczących opóźnienia aukcji reklam w ramach Protected Audience API.

Wersja demonstracyjna interfejsu Protected Audience API

Szczegółowa instrukcja wdrażania interfejsu Protected Audience API w witrynach reklamodawców i wydawców jest dostępna na stronie 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.

Testowanie za pomocą flagi chrome://flags lub funkcji

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

Renderowanie reklam w elementach iframe lub ramkach ogrodzonych

Reklamy mogą być renderowane w polu <iframe> lub <fencedframe>, w zależności od tego, które flagi są ustawione.

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

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

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

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

Dołącz flagę BiddingAndScoringDebugReportingAPI, aby włączyć tymczasowe metody raportowania utraty/wygrania.

Obsługiwane funkcje

Protected Audience API sterowana flagami funkcji w Chromium to pierwszy eksperyment, który ma na celu przetestowanie tych funkcji interfejsu Protected Audience API:

  • Grupy zainteresowań: przechowywane przez przeglądarkę wraz z powiązanymi metadanymi do konfigurowania określania stawek i renderowania reklam.
  • Określanie stawek na urządzeniu przez kupujących (DSP lub reklamodawcę): na podstawie zapisanych grup zainteresowań i sygnałów od sprzedawcy.
  • Wybór reklam na urządzeniu przez sprzedawcę (SSP lub wydawcę): na podstawie stawek z aukcji i metadanych kupujących.
  • Renderowanie reklam w tymczasowo spokojniejszej wersji Chronionych ramek: z dozwolonym dostępem do sieci i rejestrowaniem reklam.

Więcej informacji o obsłudze i ograniczeniach funkcji znajdziesz w objaśnieniu dotyczącym Protected Audience API.

Uprawnienia grupy zainteresowań

Domyślnym ustawieniem w bieżącej implementacji interfejsu Protected Audience API jest zezwalanie na wywoływanie metody joinAdInterestGroup() z dowolnego miejsca na stronie, nawet z międzydomenowych elementów iframe.

W przyszłości, gdy właściciele witryn zdążą zaktualizować swoje zasady uprawnień w ramach iframe w wielu domenach, plan będzie blokować wywołania pochodzące z międzydomenowych elementów iframe.

Usługa kluczy/wartości

Aby umożliwić obsługę aukcji reklam w interfejsie Protected Audience API, przeglądarka może korzystać z usługi klucz-wartość, która może w czasie rzeczywistym pobierać informacje na potrzeby aukcji reklam interfejsu Protected Audience API. Te informacje można wykorzystać na różne sposoby:

  • Być może kupujący chcą obliczyć pozostały budżet kampanii reklamowej.
  • Sprzedawcy mogą być zobowiązani do sprawdzenia reklam pod kątem zgodności z zasadami wydawców.

Dostępny jest kod usługi klucz-wartość interfejsu Protected Audience API. Informacje o zmianie stanu znajdziesz w poście na blogu z ogłoszeniem.

Na potrzeby początkowych testów wprowadziliśmy model „Przynieś własny serwer”. W dłuższej perspektywie technologie reklamowe będą musiały korzystać z usług klucza i wartości interfejsu Protected Audience API na licencji open source działających w zaufanych środowiskach wykonawczych.

Zmiany w harmonogramie znajdziesz w poście na blogu na temat usług Protected Audience API. Przed tą zmianą deweloperzy otrzymają powiadomienie o rozpoczęciu testów i wdrożenia.

Wykrywanie obsługi funkcji

Zanim użyjesz tego interfejsu API, sprawdź, czy jest on obsługiwany przez przeglądarkę i 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 na zamówienie, a następnie odwiedza witrynę z wiadomościami i wyświetla mu się reklama nowego roweru tej firmy.

Funkcje interfejsu Protected Audience API będą dodawane z czasem w miarę postępów w implementacji.

1. Użytkownik odwiedza witrynę reklamodawcy.

Osoba odwiedzająca stronę producenta rowerów spersonalizowanych w przeglądarce na laptopie.

Wyobraź sobie, że użytkownik odwiedza w tym przykładzie witrynę producenta rowerów na zamówienie (reklamodawca) i spędza trochę czasu na stronie produktu ręcznie robionego stalowego roweru. Daje mu to możliwość remarketingu.

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

Użytkownik otwiera przeglądarkę na laptopie i odwiedza stronę. W przeglądarce działa kod JavaScript do łączenia grup zainteresowań.

Platforma DSP reklamodawcy (lub sam reklamodawca) wywołuje funkcję navigator.joinAdInterestGroup(), by poprosić przeglądarkę o dodanie grupy zainteresowań do listy grup, do której należy przeglądarka.

W tym przykładzie grupa nazywa się 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 Protected Audience API. Członkostwo w grupie zainteresowań jest przechowywane przez przeglądarkę, na urządzeniu użytkownika i nie jest udostępniane dostawcy przeglądarki ani nikomu innemu.

Określ reklamy dla grupy zainteresowań

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

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

W jaki sposób 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ń ma zaproszenie do licytowania.

Zapoznaj się z dokumentacją dla deweloperów aplikacji generatedBid().

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

Osoba odwiedza witrynę z wiadomościami w przeglądarce na laptopie. Boks reklamowy w witrynie jest pusty.

Później użytkownik odwiedza witrynę sprzedającą przestrzeń reklamową – w tym przykładzie jest to witryna z wiadomościami. W witrynie są zasoby reklamowe, które sprzedaje w sposób zautomatyzowany z określaniem stawek w czasie rzeczywistym.

4. Aukcja reklam odbywa się w przeglądarce

Osoba wyświetla witrynę z wiadomościami w przeglądarce na laptopie. Przeprowadzana jest aukcja reklam w interfejsie Protected Audience API, aby wybrać reklamę do wyświetlenia w dostępnej przestrzeni reklamowej.

Aukcja reklam prawdopodobnie zostanie przeprowadzona przez dostawcę platformy reklamowej wydawcy lub przez samego wydawcę. Aukcja ma na celu wybranie najbardziej odpowiedniej reklamy dla pojedynczego dostępnego boksu reklamowego na bieżącej stronie. Aukcja uwzględnia grupy zainteresowań, do których należy przeglądarka, oraz dane od kupujących przestrzeń reklamową i sprzedawców z usług kluczy/wartości.

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

Użytkownik wyświetla witrynę z wiadomościami w przeglądarce na laptopie. Trwa aukcja reklam korzystająca z Protected Audience API, a uczestnik otrzymuje dane z usługi klucz/wartość.

Podczas aukcji reklam sprzedawca może zażądać danych w czasie rzeczywistym o konkretnych kreacjach reklamowych, przesyłając żądanie do usługi klucz/wartość. Sprzedawca może poprosić o te informacje podczas runAdAuction() przez właściwość trustedScoringSignalsUrl, a także o klucze z właściwości renderUrl wszystkich wpisów w polach ads i adComponents wszystkich grup zainteresowań biorących udział w aukcji.

Kupujący może zażądać danych w czasie rzeczywistym z usługi klucz/wartość za pomocą właściwości trustedBiddingSignalsUrl i trustedBiddingSignalsKeys argumentu grupy zainteresowań przekazywanego do navigator.joinAdInterestGroup().

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

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

Odpowiedź na to żądanie to obiekt JSON z wartościami dla każdego klucza.

6. Wyświetlono zwycięską reklamę

Osoba wyświetla witrynę z wiadomościami w przeglądarce na laptopie. Reklama 20% zniżki na rower wyświetlana w bezpiecznej ramce.

Obietnica zwrócona przez funkcję runAdAuction() przechodzi do obiektu konfiguracji ramki chronionej (FencedFrameConfig), gdy flaga resolveToConfig jest ustawiona w konfiguracji aukcji na true. Konfiguracja ramki jest używana przez chronioną ramkę do przejścia do zwycięskiej reklamy, ale URL reklamy jest niewidoczny dla narzędzia do umieszczania ramek.

Obiekt konfiguracji ramki chronionej jest dostępny od wersji M114. Więcej informacji o obiekcie FencedFrameConfig znajdziesz w artykule na blogu Chrome.

7. Raport dotyczący wyniku aukcji

Plan długoterminowy zakłada, że przeglądarka będzie mogła raportować wyniki aukcji dotyczące sprzedawcy i kupujących za pomocą interfejsów API agregacji prywatnej.

W ramach tymczasowego mechanizmu 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(). Przyjmuje się pojedynczy argument: ciąg znaków reprezentujący adres URL pobrany po zakończeniu aukcji. Koduje informacje na poziomie zdarzenia, które mają być raportowane.

8. Raportowane kliknięcie reklamy

Użytkownik klika w witrynie z wiadomościami reklamę roweru umieszczoną w ramce otoczonej płotem. Dane z raportu są wysyłane do sprzedawcy i kupujących.

Rejestrowane jest kliknięcie reklamy wyrenderowanej w ramce otoczonej ramką. Więcej informacji o tym, jak to działa, znajdziesz w artykule Raporty o reklamach w ramkach Fenced Frames.

Omówienie każdego etapu aukcji reklam w ramach Protected Audience API
Ten diagram przedstawia każdy etap aukcji Protected Audience API.

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

Protected Audience API to pierwszy eksperyment wdrożony w Chromium w ramach rodziny ofert pakietowych TuRTLEDOVE.

Interfejs Protected Audience API jest zgodny z ogólnymi zasadami TURTLEDOVE. Część reklam online opiera się na pokazaniu reklamy potencjalnie zainteresowanej osobie, która wcześniej weszła w interakcję z reklamodawcą lub siecią reklamową. W przeszłości reklamodawca uznał za konkretną osobę, gdy przegląda strony internetowe. Jest to kluczowa kwestia dotycząca prywatności we współczesnym internecie.

W ramach projektu TURTLEDOVE opracujemy nowy interfejs API, który pomoże Ci rozwiązać ten problem, a jednocześnie najważniejsze nowości w zakresie ochrony prywatności:

  • Przeglądarka, a nie reklamodawca, przechowuje informacje o tym, co według reklamodawcy zainteresuje osoba.
  • Reklamodawcy mogą wyświetlać reklamy na podstawie zainteresowań, ale nie mogą łączyć tego zainteresowania z innymi informacjami o osobie, w szczególności o tym, kim są lub jakie strony odwiedzają.

Interfejs Protected Audience API rozwinął się w ramach TURTLEDOVE i zestawu powiązanych propozycji modyfikacji, które byłyby lepiej dostosowane do potrzeb deweloperów korzystających z tego interfejsu:

  • W SPARROW: Criteo zaproponował dodanie modelu usługi („Gatekeeper”) działającego w zaufanym środowisku wykonawczym (TEE). Interfejs Protected Audience API obejmuje bardziej ograniczone korzystanie z TEE do wyszukiwania danych w czasie rzeczywistym i raportowania zbiorczego.
  • Oferty TERN i PARRROT firmy NextRoll opisują różne role, jakie pełnili kupujący i sprzedawcy w aukcji na urządzeniu. Na tej podstawie opiera się proces określania stawek i wyniku reklam w interfejsie Protected Audience API.
  • Modyfikacje RTB House na podstawie wyników 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 bazuje na serwerze proxy działającym w TEE między przeglądarką a dostawcami technologii reklamowych w celu zanonimizowania żądań reklam i egzekwowania właściwości prywatności. Interfejs Protected Audience API nie przejął tego modelu serwera proxy. W ramach przyszłych prac nad łączeniem najlepszych funkcji obu pakietów ujednolicamy interfejsy API JavaScript do obsługi PARAKEET i Protected Audience API.

Protected Audience API nie blokuje jeszcze sieci reklamowej witryny uczenia się, które reklamy widzi użytkownik. Planujemy z czasem zmodyfikować interfejs API, aby stał się bardziej prywatny.

Czy interfejsu Topics API można używać razem z Protected Audience API?

Tak. Obserwowany temat dla bieżącego użytkownika podany przez Topics API może zostać wykorzystany jako informacje kontekstowe przez sprzedawcę lub licytującego. Temat może zostać uwzględniony w tych usługach:

  • auctionSignals – właściwość obiektu konfiguracji aukcji przekazana do navigator.runAdAuction();
  • userBiddingSignals – właściwość obiektu konfiguracji grupy zainteresowań przekazana do navigator.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 sekcji chrome://settings/adPrivacy.

Podczas wstępnych testów użytkownicy będą mogli zrezygnować z interfejsu Protected Audience API za pomocą tego ogólnego ustawienia Piaskownicy prywatności. Chrome umożliwia użytkownikom wyświetlanie listy grup zainteresowań, do których zostali dodani w odwiedzonych witrynach, oraz zarządzanie nią. Ustawienia użytkowników, podobnie jak technologie Piaskownicy prywatności, mogą ewoluować na podstawie opinii użytkowników, organów regulacyjnych i innych osób.

Nadal będziemy aktualizować ustawienia dostępne w Chrome na podstawie testów i opinii. W przyszłości planujemy udostępnienie bardziej szczegółowych ustawień 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 korzystają z przeglądarki w trybie incognito, a członkostwo jest usuwane, gdy użytkownik wyczyści dane swojej witryny.

Czy worklety Protected Audience są przechowywane w pamięci podręcznej przeglądarki?

Zasoby, które zawierają Worklety Protected Audience (Worklety służące do generowania stawek i raportowania przez kupującego oraz oceny reklam i raporty sprzedawcy) – są zapisywane w pamięci podręcznej przeglądarki; Aby kontrolować sposób zapisu w pamięci podręcznej, możesz użyć nagłówka Cache-Control.

Angażuj i dziel się opiniami

Uzyskaj pomoc

Aby zadać pytanie i uzyskać pomoc dotyczącą implementacji, wersji demonstracyjnej lub dokumentacji:

Jeśli masz ogólne pytania dotyczące spełniania Twoich potrzeb związanych z interfejsem Protected Audience API, zgłoś problem w repozytorium API. Możesz też omówić przypadki użycia w branży w ramach grupy W3C Ulepszanie reklamy internetowej.

Za pomocą formularza opinii Piaskownicy prywatności możesz prywatnie przesyłać opinie zespołowi Chrome poza publicznymi forami.

Rezygnacja

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