Protected Audience API: przewodnik dla programistów

Przewodnik dla programistów dotyczący aukcji reklam na urządzeniu, które wyświetlają reklamy remarketingowe i kierowane na niestandardowe listy odbiorców bez śledzenia użytkowników w różnych witrynach przez firmy zewnętrzne.

Jeśli dopiero zaczynasz korzystać z interfejsu Protected Audience API, przeczytaj omówienie Protected Audience API, aby poznać jego ogólne założenia.

Ten post jest przeznaczony dla programistów i stanowi odnośnik techniczny do najnowszej wersji eksperymentalnej interfejsu Protected Audience API. Dostępne jest demo podstawowego wdrożenia interfejsu Protected Audience API, a także dokumentacja interfejsu API dla kupujących i sprzedawców reklam.

Stan wdrożenia

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 Piaskownica prywatności, który służy do obsługi przypadków użycia związanych z remarketingiem i list odbiorców niestandardowych. Został tak zaprojektowany, aby nie można było go używać do śledzenia zachowań użytkowników w różnych witrynach. API umożliwia przeprowadzanie aukcji na urządzeniu przez przeglądarkę, aby wybierać trafne reklamy dla witryn, które użytkownik odwiedził wcześniej.

Interfejs Protected Audience API jest pierwszym eksperymentem wdrożonym w Chromium w ramach rodziny propozycji TURTLEDOVE.

Wypróbuj Protected Audience API

Dostępna dokumentacja interfejsu API

Ten dokument zawiera opis 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 Protected Audience API.

Demonstracja Protected Audience API

Przewodnik po podstawowym wdrażaniu interfejsu Protected Audience API w witrynach reklamodawców i wydawców jest dostępny pod adresem protected-audience-demo.web.app/.

Obejrzyj ten film o pełnym wdrożeniu, 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 testować dla pojedynczego użytkownika w wersji Chrome Beta 101.0.4951.26 lub nowszej na komputerze:

renderowanie reklam w elementach iframe lub fenced frames.

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

Aby renderować reklamy za pomocą <fencedframe>:

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

Aby renderować reklamy za pomocą <iframe>:

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

Uwzględnij flagę BiddingAndScoringDebugReportingAPI, aby włączyć tymczasowe metody raportowania wygranych i przegranych do debugowania.

Obsługiwane funkcje

Interfejs Protected Audience API za pomocą flag funkcji w Chromium to pierwszy eksperyment mający na celu przetestowanie tych funkcji interfejsu Protected Audience API:

  • Grupy zainteresowań: są przechowywane przez przeglądarkę wraz z powiązanymi metadanymi, które służą do konfigurowania ustalania stawek i renderowania reklam.
  • Określanie stawek na urządzeniu przez kupujących (platformy DSP lub reklamodawców): na podstawie zapisanych grup zainteresowań i sygnałów od sprzedawcy.
  • Wybór reklamy na urządzeniu przez sprzedawcę (SSP lub wydawcę): na podstawie stawek aukcji i metadanych od kupujących.
  • Wyświetlanie reklam w tymczasowo zrelaksowanym wariancie ograniczonych ram: dostęp do sieci i rejestrowanie są dozwolone w celu wyświetlania reklam.

Więcej informacji o obsługiwanych funkcjach i o ograniczeniach znajdziesz w artykule Protected Audience API – informacje ogólne.

Uprawnienia dotyczące grup zainteresowań

Domyślnie w przypadku obecnej implementacji interfejsu Protected Audience API wywołanie interfejsu joinAdInterestGroup() jest dozwolone z dowolnego miejsca na stronie, nawet z elementów iframe w innych domenach.

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

Usługa kluczy-wartości

Aby obsługiwać aukcję reklam Protected Audience API, przeglądarka może uzyskać dostęp do usługi klucz-wartość, aby pobrać informacje w czasie rzeczywistym, które obsługują aukcję reklam 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 reklam pod kątem zgodności z zasadami wydawcy.

Kod usługi klucz-wartość interfejsu Protected Audience API jest już dostępny. Aktualny stan znajdziesz w poście na blogu z ogłoszeniem.

Na potrzeby wstępnego testowania zastosowaliśmy model „przynieś własny serwer”. W długoterminowej perspektywie technologie reklamowe będą musiały korzystać z otwartych usług klucza/wartości interfejsu Protected Audience API działających w zaufanych środowiskach wykonania.

Aby uzyskać informacje o planowanym harmonogramie, przeczytaj bloga Protected Audience API. Zanim wprowadzimy tę zmianę, powiadomimy deweloperów o tym z odpowiednim wyprzedzeniem, aby mogli rozpocząć testowanie i wdrażanie.

Wykrywanie obsługi funkcji

Zanim użyjesz interfejsu API, sprawdź, czy jest on obsługiwany przez przeglądarkę i czy jest dostępny w tym 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, a potem odwiedza witrynę z wiadomościami, gdzie wyświetla mu się reklama nowego roweru od tego producenta.

Funkcje interfejsu Protected Audience API będą dodawane w miarę postępów w wdrażaniu.

1. Użytkownik odwiedza stronę reklamodawcy

Osoba odwiedzająca witrynę producenta rowerów na laptopie.

Wyobraź sobie, że użytkownik odwiedza witrynę producenta rowerów (w tym przykładzie reklamodawcy) i przebywa przez jakiś czas na stronie produktu, którym jest ręcznie robiony stalowy rower. Daje to producentowi rowerów możliwość remarketingu.

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

Użytkownik otwiera przeglądarkę na laptopie i odwiedza witrynę. Kod JavaScript służący do dołączania do grup zainteresowań reklamami jest wykonywany w przeglądarce.

Platforma DSP reklamodawcy (lub sam reklamodawca) wywołuje funkcję navigator.joinAdInterestGroup(), aby poprosić przeglądarkę 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 użytkownik dsp.example. Właściciel grupy zainteresowań (w tym przypadku DSP) będzie kupującym w ramach aukcji reklam 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 w grupie zainteresowań

Obiekty ads i adComponents zawierają adres URL kreacji reklamy oraz opcjonalnie dowolne metadane, które mogą być używane podczas określania stawek. Na przykład:

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

Jak kupujący ustalają stawki?

generateBid() jest wywoływany w przypadku każdej grupy zainteresowań, której przeglądarka jest członkiem, jeśli właściciel grupy jest zaproszony do licytowania.

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

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.

Następnie użytkownik odwiedza witrynę, która sprzedaje miejsce na reklamy, w tym przypadku witrynę z wiadomościami. Witryna ma zasoby reklamowe, które sprzedaje automatycznie za pomocą automatycznego określania stawek w czasie rzeczywistym.

4. Aukcja reklam jest uruchamiana w przeglądarce

Osoba przeglądająca witrynę z wiadomościami w przeglądarce na laptopie. W celu wybrania reklamy na potrzeby dostępnej przestrzeni reklamowej przeprowadzana jest aukcja reklamy interfejsu Protected Audience API.

Aukcję reklam prawdopodobnie przeprowadza dostawca dostawy (SSP) lub sam wydawca. Celem aukcji jest wybranie najbardziej odpowiedniej reklamy dla pojedynczego dostępnego boksu reklamowego na bieżącej stronie. Podczas aukcji uwzględniane są grupy zainteresowań, do których należy przeglądarka, a także dane kupujących i sprzedawców miejsca na reklamy z usług klucz-wartość.

5. Sprzedawca i uczestniczący kupujący żądają danych w czasie rzeczywistym z usługi Key/Value

Użytkownik przegląda witrynę z wiadomościami w przeglądarce na laptopie. W trakcie jest aukcja reklamy za pomocą interfejsu Protected Audience API, a uczestnik pobiera dane z usługi klucz-wartość.

Podczas aukcji reklam sprzedawca może poprosić o dane o konkretnych kreacjach reklamy w czasie rzeczywistym, 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 oraz kluczy z właściwości renderUrl wszystkich wpisów w polach ads i adComponents wszystkich grup zainteresowań w aukcji.

Kupujący może żądać danych w czasie rzeczywistym z usługi klucz-wartość, używając właściwości trustedBiddingSignalsUrl i trustedBiddingSignalsKeys argumentu grupy zainteresowań przekazanego do navigator.joinAdInterestGroup().

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

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

.

6. Wyświetla się zwycięska reklama

Osoba przeglądająca witrynę z wiadomościami w przeglądarce na laptopie. Reklama z 20% rabatem na rower wyświetla się w bezpiecznej ramce.

Obiet na obietnice zwracany przez funkcję runAdAuction() jest rozwiązywany do obiektu konfiguracji ramki odizolowanej (FencedFrameConfig), gdy w konfiguracji aukcji parametr resolveToConfig ma wartość true. Konfiguracja ramki jest używana przez ramkę odizolowaną do nawigacji do reklamy zwycięskiej, ale adres URL reklamy nie jest widoczny dla osoby umieszczającej ramkę.

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

7. Wynik aukcji jest zgłaszany

Na dłuższą metę planujemy umożliwić przeglądarce raportowanie wyników aukcji sprzedawcy i kupującym za pomocą interfejsów Private Aggregation API.

Jako tymczasowy mechanizm raportowania na poziomie zdarzenia kod implementujący funkcję reportResult() dla sprzedawcy i funkcję reportWin() dla zwycięskiego licytującego może wywołać funkcję sendReportTo(). Funkcja ta przyjmuje 1 argument: ciąg znaków reprezentujący adres URL, który jest pobierany po zakończeniu aukcji i zawiera zakodowane informacje na potrzeby raportowania na poziomie zdarzenia.

8. Zgłoszono kliknięcie reklamy

Użytkownik klika reklamę roweru z ramą ogrodzeniową na stronie internetowej z wiadomościami. Dane z raportu są wysyłane do sprzedawcy i kupujących.

Rejestruje się kliknięcie reklamy renderowanej w ramce wydzielonej. Więcej informacji o tym, jak to działa, znajdziesz w artykule Raportowanie reklam w ramkach ograniczonych.

Omówienie poszczególnych etapów aukcji reklamy w Protected Audience API
Ten diagram przedstawia poszczególne etapy aukcji Protected Audience API.

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

Interfejs Protected Audience API jest pierwszym eksperymentem, który zostanie wdrożony w Chromium w ramach rodziny propozycji TURTLEDOVE.

Interfejs Protected Audience API jest zgodny z ogólnymi zasadami TURTLEDOVE. Niektóre reklamy online wyświetlają się potencjalnie zainteresowanym osobom, które wcześniej miały kontakt z reklamodawcą lub siecią reklamową. W przeszłości działało to w ten sposób, że reklamodawca rozpoznawał daną osobę podczas przeglądania przez nią stron internetowych, co było jednym z głównych problemów z prywatnością w dzisiejszym internecie.

Projekt TURTLEDOVE ma na celu udostępnienie nowego interfejsu API do obsługi tego przypadku użycia, a także wprowadzenie kilku kluczowych ulepszeń dotyczących prywatności:

  • Informacje o tym, czym według reklamodawcy interesuje się użytkownik, przechowywane są w przeglądarce, a nie w systemie reklamodawcy.
  • Reklamodawcy mogą wyświetlać reklamy na podstawie zainteresowań, ale nie mogą łączyć tych zainteresowań z innymi informacjami o użytkowniku, w szczególności z informacjami o tym, kim jest użytkownik lub którą stronę odwiedza.

Interfejs Protected Audience API powstał na bazie interfejsu TURTLEDOVE i zbioru powiązanych propozycji modyfikacji, które miały służyć do ulepszania usług dla deweloperów korzystających z interfejsu API:

  • W SPARROW: Criteo zaproponowało dodanie modelu usługi („Gatekeeper”) działającej w zaufanym środowisku wykonawczym (TEE). Interfejs Protected Audience API umożliwia ograniczone korzystanie z interfejsów TEE na potrzeby wyszukiwania danych w czasie rzeczywistym i tworzenia zbiorczych raportów.
  • W ramach propozycji TERN firmy NextRoll i PARRROT firmy Magnite opisano różne role, jakie kupujący i sprzedający pełnią w aukcji na urządzeniu. Na tej podstawie działają przepływy określania stawek i punktacji reklam w Protected Audience API.
  • Modyfikacje TURTLEDOVE dotyczące modelu opartej na wynikach i produktu w ramach RTB House poprawiły model anonimowości i możliwości personalizacji aukcji na urządzeniu
  • PARAKEET to usługa reklamowa podobna do TURTLEDOVE, która polega na korzystaniu z serwera proxy działającego w ramach TEE między przeglądarką a dostawcami technologii reklamowych. Usługa ta służy do anonimizacji żądań reklam i zapewnienia ochrony prywatności. Interfejs Protected Audience API nie korzysta z tego modelu zastępowania. Dopasowujemy interfejsy JavaScript PARAKEET i Protected Audience API, aby ułatwić przyszłe prace nad połączeniem najlepszych funkcji obu tych interfejsów.

Interfejs Protected Audience API nie zapobiega jeszcze temu, aby sieć reklamowa witryny dowiadywała się, które reklamy widzi dana osoba. Z czasem planujemy zmodyfikować interfejs API, aby był bardziej prywatny.

Czy interfejs Topics API można używać z interfejsem Protected Audience API?

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

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

Dostępna konfiguracja przeglądarki

Użytkownicy mogą dostosować swoje uczestnictwo 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 ogólnego ustawienia Piaskownicy prywatności, aby zrezygnować z korzystania z interfejsu Protected Audience API. Chrome planuje umożliwić użytkownikom wyświetlanie i zarządzanie listą grup zainteresowań, do których zostali dodani na podstawie odwiedzanych stron internetowych. Podobnie jak w przypadku technologii Piaskownicy prywatności, ustawienia użytkownika mogą się zmieniać pod wpływem opinii użytkowników, organów regulacyjnych i innych osób.

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 interfejsu Protected Audience API i powiązanych z nim danych.

Interfejsy API nie mają dostępu do członkostwa w grupie, gdy użytkownicy przeglądają treści w trybie incognito. Członkostwo jest usuwane, gdy użytkownicy usuwają dane witryny.

Czy przeglądarka przechowuje w pamięci podręcznej moduły Protected Audience?

Zasoby zawierające moduły Protected Audience (moduł generowania i raportowania stawek kupującego oraz moduł oceniania i raportowania reklam sprzedawcy) są przechowywane w pamięci podręcznej przeglądarki. Do kontrolowania zachowania pamięci podręcznej możesz użyć nagłówka Cache-Control.

Zaangażowanie i przesyłanie opinii

Uzyskaj pomoc

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

W przypadku bardziej ogólnych pytań dotyczących 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 roboczej W3C ds. ulepszania reklam internetowych.

Użyj formularza opinii na temat Piaskownicy prywatności, aby prywatnie przekazać zespołowi Chrome opinie poza publicznymi forami.

Rezygnacja

Chcesz zrezygnować z korzystania z interfejsu Protected Audience API? Dowiedz się, jak jako właściciel witryny lub użytkownik możesz zablokować dostęp do interfejsu Protected Audience API.

Otrzymuj powiadomienia