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

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:

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

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

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

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.

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.

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.

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.

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.

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.

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

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

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

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.

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.

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.

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

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

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