Protected Audience API: przewodnik dla programistów

Przewodnik dla deweloperów dotyczący aukcji reklam na urządzeniu, które umożliwiają wyświetlanie reklam remarketingowych i reklam kierowanych na niestandardowe grupy odbiorców bez śledzenia użytkowników w witrynach przez inne firmy.

Jeśli dopiero zaczynasz korzystać z interfejsu Protected Audience API, przeczytaj omówienie interfejsu Protected Audience API, aby poznać ogólne informacje o tym interfejsie.

Ten post jest przeznaczony dla programistów i zawiera informacje techniczne na temat najnowszej wersji eksperymentalnego interfejsu Protected Audience API. Dostępna jest wersja demonstracyjna podstawowego wdrożenia interfejsu Protected Audience API, a także dokumentacja interfejsu API dla kupujących i sprzedających reklamy.

Stan wdrożenia

Aby otrzymywać powiadomienia o zmianach stanu interfejsu API, zapisz się na listę adresową dla programistów.

Czym jest interfejs Protected Audience API?

Interfejs Protected Audience API to interfejs API Piaskownicy prywatności, który służy do obsługi przypadków użycia remarketingu i niestandardowych grup odbiorców. Został zaprojektowany tak, aby nie można go było używać do śledzenia przez podmioty zewnętrzne zachowań użytkowników w witrynach. Interfejs API umożliwia przeprowadzanie w przeglądarce aukcji na urządzeniu, aby wybierać trafne reklamy do wyświetlania w witrynach, które użytkownik odwiedził wcześniej.

Interfejs Protected Audience API to pierwszy eksperyment wdrożony w Chromium w ramach rodziny propozycji TURTLEDOVE.

Wypróbuj interfejs Protected Audience API

Dostępna dokumentacja API

Ten dokument zawiera opis interfejsu Protected Audience API. Jeśli szukasz konkretnych metod i parametrów interfejsu API:

Możesz też przeczytać sprawdzone metody dotyczące opóźnień w aukcjach reklamowych z użyciem Protected Audience API.

Wersja demonstracyjna interfejsu Protected Audience API

Podstawowe wdrożenie interfejsu Protected Audience API w witrynach reklamodawców i wydawców jest dostępne na stronie protected-audience-demo.web.app/.

Obejrzyj to wdrożenie od początku do końca, aby dowiedzieć się, jak działa kod demonstracyjny Protected Audience API i jak używać Narzędzi deweloperskich w Chrome do debugowania.

Testowanie tego interfejsu API

Interfejs Protected Audience API możesz przetestować na jednym użytkowniku w Chrome Beta w wersji 101.0.4951.26 lub nowszej na komputerze:

renderować reklamy w elementach iframe lub ramkach chronionych,

Reklamy mogą być renderowane w <iframe> lub <fencedframe> w zależności od ustawionych flag.

Aby renderować reklamy za pomocą funkcji <fencedframe>:

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

Aby renderować reklamy za pomocą funkcji <iframe>:

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

Dodaj flagę BiddingAndScoringDebugReportingAPI, aby włączyć tymczasowe metody raportowania wygranych i przegranych w trybie debugowania.

Obsługiwane funkcje

Interfejs Protected Audience API za 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, które służą do konfigurowania określania stawek za reklamy i ich renderowania.
  • Licytowanie na urządzeniu przez kupujących (platformę DSP lub reklamodawcę): na podstawie zapisanych grup zainteresowań i sygnałów od sprzedawcy.
  • Wybieranie reklam na urządzeniu przez sprzedawcę (platformę SSP lub wydawcę): na podstawie stawek w aukcji i metadanych od kupujących.
  • Wyświetlanie reklam w tymczasowo uproszczonej wersji Fenced Frames: z dostępem do sieci i rejestrowaniem danych na potrzeby wyświetlania reklam.

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

Uprawnienia dotyczące grup zainteresowań

W obecnej implementacji interfejsu Protected Audience API domyślnie zezwala się na wywoływanie funkcji joinAdInterestGroup() z dowolnego miejsca na stronie, nawet z elementów iframe z innych domen.

W przyszłości, gdy właściciele witryn będą mieli czas na zaktualizowanie zasad dotyczących uprawnień międzydomenowych elementów iframe, planujemy zablokować wywołania z takich elementów.

Usługa kluczy-wartości

Aby obsługiwać aukcję reklam w ramach Protected Audience API, przeglądarka może uzyskać dostęp do usługi klucz/wartość, aby pobierać informacje w czasie rzeczywistym, które obsługują aukcję reklam w ramach Protected Audience API. Te informacje mogą być wykorzystywane na wiele sposobów:

  • Kupujący mogą chcieć obliczyć pozostały budżet w kampanii reklamowej.
  • Sprzedawcy mogą być zobowiązani do sprawdzania kreacji reklamowych pod kątem zgodności z zasadami wydawcy.

Dostępny jest już kod usługi klucz/wartość interfejsu Protected Audience API. Aktualne informacje znajdziesz w poście na blogu.

Na potrzeby wstępnych testów wprowadziliśmy model „Przynieś własny serwer”. W dłuższej perspektywie dostawcy technologii reklamowych będą musieli korzystać z usług klucz/wartość Protected Audience API o otwartym kodzie źródłowym, które działają w zaufanych środowiskach wykonawczych.

Aktualności dotyczące harmonogramu znajdziesz na blogu o usługach Protected Audience API. Zanim wprowadzimy tę zmianę, powiadomimy deweloperów z dużym wyprzedzeniem, aby mogli rozpocząć testowanie i wdrażanie.

Wykrywanie obsługi funkcji

Zanim zaczniesz korzystać z 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, w której wyświetla mu się reklama nowego roweru tego producenta.

Funkcje interfejsu Protected Audience API będą dodawane z czasem w miarę postępów prac nad wdrożeniem.

1. Użytkownik odwiedza witrynę reklamodawcy.

Osoba odwiedzająca w przeglądarce na laptopie witrynę producenta rowerów na zamówienie.

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

2. Przeglądarka użytkownika jest proszona o dodanie grupy zainteresowań.

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

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

W tym przykładzie grupa ma nazwę 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 reklamowej Protected Audience API. Informacja o przynależności do grupy zainteresowań jest zapisywana 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 reklamy oraz opcjonalnie dowolne metadane, które można wykorzystać w momencie składania oferty. Na przykład:

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

Jak kupujący składają oferty?

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 składania ofert.

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

3. Użytkownik odwiedza witrynę, która sprzedaje miejsce na reklamę.

Osoba odwiedza witrynę z wiadomościami w przeglądarce na laptopie. Witryna ma pusty boks reklamowy.

Później użytkownik odwiedza witrynę, która sprzedaje miejsce na reklamy, w tym przykładzie jest to witryna z wiadomościami. Witryna ma zasoby reklamowe, które sprzedaje automatycznie za pomocą określania stawek w czasie rzeczywistym.

4. W przeglądarce przeprowadzana jest aukcja reklam.

Osoba przegląda stronę z wiadomościami w przeglądarce na laptopie. Przeprowadzana jest aukcja reklam z użyciem Protected Audience API, aby wybrać reklamę do wyświetlenia w dostępnej przestrzeni reklamowej.

Aukcję reklamową przeprowadza prawdopodobnie dostawca platformy po stronie sprzedaży (SSP) wydawcy lub sam wydawca. Celem aukcji jest 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 miejsce na reklamę i sprzedawców z usług klucz/wartość.

5. Sprzedawca i kupujący biorący udział w aukcji przesyłają do usługi klucz/wartość żądania danych w czasie rzeczywistym.

Użytkownik przegląda witrynę z wiadomościami w przeglądarce na laptopie. Aukcja reklamowa z użyciem interfejsu Protected Audience API, w której uczestnik pobiera dane z usługi klucz/wartość.

Podczas aukcji reklam sprzedawca może poprosić o dane w czasie rzeczywistym dotyczące konkretnych kreacji reklamowych, wysyłając żądanie do usługi klucz/wartość. Sprzedawca może poprosić o te informacje podczas runAdAuction() za pomocą właściwości trustedScoringSignalsUrl, a także kluczy z właściwości renderUrl wszystkich wpisów w polach ads i adComponents wszystkich grup zainteresowań w aukcji.

Kupujący może poprosić o dane w czasie rzeczywistym z usługi klucz/wartość, korzystając z właściwości trustedBiddingSignalsUrl i trustedBiddingSignalsKeys argumentu grupy zainteresowań przekazywanego do funkcji navigator.joinAdInterestGroup().

Gdy wywoływana jest funkcja runAdAuction(), przeglądarka wysyła żądanie do zaufanego serwera każdego reklamodawcy. 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.
  • hostname jest dostarczany przez przeglądarkę.
  • Wartość keys jest pobierana z trustedBiddingSignalsKeys.

Odpowiedzią na to żądanie jest obiekt JSON zawierający wartości poszczególnych kluczy.

6. Wyświetlenie zwycięskiej reklamy

Osoba przegląda stronę z wiadomościami w przeglądarce na laptopie. Reklama roweru z 20-procentową zniżką wyświetla się w bezpiecznej ramce.

Obietnica zwrócona przez funkcję runAdAuction() jest rozwiązywana w obiekcie konfiguracji ramki chronionej (FencedFrameConfig), gdy w konfiguracji aukcji flaga resolveToConfig jest ustawiona na true. Konfiguracja ramki jest używana przez ramkę z ograniczeniami do przekierowania do zwycięskiej reklamy, ale adres URL reklamy nie jest widoczny dla osoby osadzającej ramkę.

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

7. Wynik aukcji jest zgłaszany

Długoterminowy plan zakłada, że przeglądarka będzie mogła raportować wyniki aukcji sprzedawcy i kupującym za pomocą interfejsów Private Aggregation API.

Jako tymczasowy mechanizm raportowania na poziomie zdarzeń kod implementujący reportResult() w przypadku sprzedawcy i reportWin() w przypadku zwycięskiego oferenta może wywoływać funkcję sendReportTo(). Przyjmuje 1 argument: ciąg znaków reprezentujący adres URL, który jest pobierany po zakończeniu aukcji i który koduje informacje o zdarzeniu do raportowania.

8. Zgłoszono kliknięcie reklamy

Użytkownik klika reklamę roweru z osadzonym w niej ogrodzonym obrazem na stronie z wiadomościami. Dane raportu są wysyłane do sprzedawcy i kupujących.

Kliknięcie reklamy wyświetlanej w ramce z ograniczeniami jest raportowane. Więcej informacji o tym, jak to może działać, znajdziesz w artykule Raportowanie reklam w ramkach ograniczonych.

Omówienie poszczególnych etapów aukcji reklamowej z użyciem interfejsu Protected Audience API
Ten diagram przedstawia poszczególne etapy aukcji Protected Audience API.

Czym różni się interfejs Protected Audience API od TURTLEDOVE?

Interfejs Protected Audience API to pierwszy eksperyment wdrożony w Chromium w ramach rodziny propozycji TURTLEDOVE.

Interfejs Protected Audience API jest zgodny z ogólnymi zasadami TURTLEDOVE. Niektóre reklamy online były wyświetlane osobom, które mogły być zainteresowane danym produktem lub usługą, ponieważ wcześniej weszły w interakcję z reklamodawcą lub siecią reklamową. W przeszłości reklamodawcy rozpoznawali konkretne osoby podczas przeglądania przez nie różnych witryn. Jest to podstawowy problem związany z prywatnością w dzisiejszym internecie.

Projekt TURTLEDOVE ma na celu udostępnienie nowego interfejsu API, który będzie obsługiwać ten przypadek użycia, a jednocześnie zapewniać kluczowe postępy w zakresie ochrony prywatności:

  • Informacje o tym, co według reklamodawcy interesuje daną osobę, są przechowywane w przeglądarce, a nie u reklamodawcy.
  • Reklamodawcy mogą wyświetlać reklamy na podstawie zainteresowań, ale nie mogą łączyć tych zainteresowań z innymi informacjami o osobie, w szczególności z tym, kim jest i jaką stronę odwiedza.

Protected Audience API powstał na bazie TURTLEDOVE i zbioru powiązanych propozycji zmian, które lepiej odpowiadają potrzebom deweloperów korzystających z tego interfejsu:

  • W SPARROW:Criteo zaproponowało dodanie modelu usługi („Gatekeeper”) działającego w zaufanym środowisku wykonawczym (TEE). Interfejs Protected Audience API obejmuje bardziej ograniczone wykorzystanie środowisk TEE na potrzeby wyszukiwania danych w czasie rzeczywistym i raportowania zbiorczego.
  • Propozycje TERN od NextRoll i PARRROT od Magnite opisywały różne role kupujących i sprzedawców w aukcji na urządzeniu. Proces określania stawek za reklamy i oceniania reklam w interfejsie Protected Audience API opiera się na tych pracach.
  • Modyfikacje RTB House oparte na wynikach i na poziomie produktu TURTLEDOVE poprawiły anonimowość i możliwości personalizacji aukcji na urządzeniu.
  • PARAKEET to propozycja Microsoftu dotycząca usługi reklamowej podobnej do TURTLEDOVE, która opiera się na serwerze proxy działającym w środowisku TEE między przeglądarką a dostawcami technologii reklamowych. Ma on anonimizować żądania reklam i egzekwować właściwości związane z ochroną prywatności. Interfejs Protected Audience API nie korzysta z tego modelu proxy. Ujednolicamy interfejsy JavaScript API dla PARAKEET i Protected Audience API, aby w przyszłości połączyć najlepsze funkcje obu propozycji.

Interfejs Protected Audience API nie uniemożliwia jeszcze sieci reklamowej witryny uzyskiwania informacji o tym, które reklamy widzi dana osoba. Z czasem planujemy zmodyfikować interfejs API, aby zwiększyć ochronę prywatności.

Czy interfejs Topics API może być używany z interfejsem Protected Audience API?

Tak. Obserwowany temat dotyczący bieżącego użytkownika, udostępniany przez interfejs Topics API, może być używany przez sprzedawcę lub licytującego jako informacja kontekstowa. Temat może być uwzględniony w tych właściwościach:

  • auctionSignals, właściwość obiektu konfiguracji aukcji przekazanego do metody navigator.runAdAuction()
  • userBiddingSignals, właściwość obiektu konfiguracji grupy zainteresowań przekazywanego do navigator.joinAdInterestGroup()

Dostępna konfiguracja przeglądarki

Użytkownicy mogą dostosowywać swój udział w testach Piaskownicy prywatności w Chrome, włączając lub wyłączając ustawienie najwyższego poziomu w chrome://settings/adPrivacy.

W początkowej fazie testów użytkownicy będą mogli używać tego ustawienia Piaskownicy prywatności wyższego poziomu, aby zrezygnować z interfejsu Protected Audience API. Chrome planuje umożliwić użytkownikom wyświetlanie listy grup zainteresowań, do których zostali dodani, w odwiedzanych przez nich witrynach, a także zarządzanie tą listą. Podobnie jak same technologie Piaskownicy prywatności, ustawienia użytkownika mogą się zmieniać w odpowiedzi na opinie użytkowników, organów regulacyjnych i innych podmiotów.

Będziemy nadal aktualizować dostępne ustawienia w Chrome na podstawie testów i opinii. W przyszłości planujemy udostępnić bardziej szczegółowe ustawienia do zarządzania interfejsem Protected Audience API i powiązanymi z nim danymi.

Wywołujący interfejs API nie mają dostępu do członkostwa w grupach, gdy użytkownicy przeglądają internet w trybie incognito, a członkostwo jest usuwane, gdy użytkownicy wyczyszczą dane witryny.

Czy worklety interfejsu Protected Audience API są buforowane przez przeglądarkę?

Zasoby zawierające worklety Protected Audience – worklety generowania stawek i raportowania kupującego oraz worklety oceniania reklam i raportowania sprzedawcy – są buforowane przez przeglądarkę. Do kontrolowania działania pamięci podręcznej możesz używać nagłówka Cache-Control.

Angażowanie się i przesyłanie opinii

Uzyskaj pomoc

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

Jeśli masz bardziej ogólne pytania dotyczące spełniania Twoich potrzeb za pomocą interfejsu Protected Audience API, zgłoś problem w repozytorium interfejsu API. Możesz też omówić przypadki użycia w branży w ramach grupy biznesowej W3C ds. ulepszania reklam internetowych.

Użyj formularza opinii Piaskownicy prywatności, aby przesłać opinię prywatnie do zespołu Chrome poza forami publicznymi.

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 użytkownik.

Otrzymuj powiadomienia