Przewodnik dla programistów interfejsu FLEDGE API

Dla kogo jest ten artykuł?

Ten post zawiera informacje techniczne na temat bieżącej wersji eksperymentalnej wersji interfejsu Protected Audience API.

Co to jest Protected Audience API?

Protected Audience API to oferta pakietowa Piaskownicy prywatności do wyświetlania reklam remarketingu i niestandardowych przypadków użycia list odbiorców, które zostały zaprojektowane tak, by nie innych firm do śledzenia zachowania użytkowników 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 to pierwszy eksperyment zaimplementowany w Chromium Rodzina ofert pakietowych TURTLEDOVE.

Poniższy diagram przedstawia omówienie cyklu życia FLEDGE:

Grafika przedstawiająca każdy etap cyklu życia FLEDGE.
Cykl życia FLEDGE.

Jak mogę skorzystać z Protected Audience API?

Wersja demonstracyjna Protected Audience API

Przewodnik po podstawach wdrażania Protected Audience API w witrynach reklamodawców i wydawców znajdziesz na stronie protected-audience-demo.web.app.

Film demonstracyjny objaśnia działanie kodu demonstracyjnego i pokazuje, jak używać Narzędzi deweloperskich w Chrome do debugowania funkcji Protected Audience.

Weź udział w testowaniu origin w ramach Protected Audience API

Testowanie źródła trafności i pomiarów w Piaskownicy prywatności zostało zakończone udostępnione w Chrome w wersji beta 101.0.4951.26 i nowszych na komputerach dla Protected Audience API. Topics, interfejsów API Attribution Reporting.

Aby wziąć udział w programie, zarejestruj się w celu uzyskania tokena próbnego origin.

Gdy zarejestrujesz się w okresie próbnym, możesz wypróbować na stronach interfejs Protected Audience JavaScript API z prawidłowym tokenem wersji próbnej, na przykład aby poprosić przeglądarkę o dołączenie do co najmniej 1 grupy zainteresowań, a potem przeprowadzenie aukcji reklam, aby wybrać i wyświetlić reklamę.

Prezentacja Protected Audience to podstawowy przykład kompleksowego wdrożenia Protected Audience API.

Podaj token próbny dla każdej strony, na której chcesz uruchomić kod interfejsu Protected Audience API:

  • Jako metatag w sekcji <head>:

    <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">

  • Jako nagłówek HTTP:

    Origin-Trial: TOKEN_GOES_HERE

  • Przez automatyczne podanie tokena:

    const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

Element iframe z kodem Protected Audience API, np. navigator.joinAdInterestGroup() przez właściciela grupy zainteresowań – musi podać token zgodny z jego źródłem.

Szczegóły okresu próbnego pierwszego objętego ochroną odbiorców z Protected Audience API zawiera więcej informacji na temat celów pierwszego okresu próbnego i obsługiwanych funkcji.

Przetestuj ten interfejs API

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

  • Włączenie wszystkich interfejsów API prywatności w reklamach w sekcji chrome://settings/adPrivacy
  • Przez ustawienie flag w wierszu poleceń.

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.

Uruchamianie Chromium z flagami wyjaśnia, jak ustawiać flagi podczas uruchamiania Chrome i innych przeglądarek opartych na Chromium za pomocą polecenia . Pełna lista flag Protected Audience API jest dostępna na tych stronach: Wyszukiwanie kodu w Chromium.

Jakie funkcje są obsługiwane w najnowszej wersji Chrome?

Udostępniamy Protected Audience API w Chromium jako za flagami funkcji jako pierwsze. eksperyment, aby przetestować te funkcje oferty pakietowej z Protected Audience API:

  • grupy zainteresowań: przechowywane przez przeglądarkę, wraz z powiązanymi metadanymi służącymi do konfigurowania określania stawek za reklamy; i renderowanie.
  • 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 aukcji oraz metadanych od kupujących.
  • Renderowanie reklam w tymczasowej wersji Fenced Frames: z dostępem do sieci i logowania i renderowania reklam.

Więcej informacji znajdziesz w objaśnieniu interfejsu API o obsłudze i ograniczeniach funkcji.

Uprawnienia grupy zainteresowań

Ustawieniem domyślnym w obecnej implementacji Protected Audience API jest zezwalanie na wywoływanie funkcji joinAdInterestGroup() z poziomu w dowolnym miejscu na stronie, nawet z międzydomenowych elementów iframe. Gdy właściciele witryn mają już czas, aby dostosować zasady dotyczące uprawnień międzydomenowego elementu iframe, plan zakłada zablokowanie połączeń między domenami, jak to opisano.

Usługa kluczy-wartości

W ramach aukcji reklam z Protected Audience API przeglądarka może uzyskać dostęp do usługa kluczy/wartości , który zwraca proste pary klucz-wartość, aby dostarczyć kupującemu informacje, takie jak pozostałe budżetu kampanii. Obowiązki w zakresie zasad dotyczących Protected Audience API że ten serwer „nie prowadzi rejestrowania na poziomie zdarzenia i nie wywołuje żadnych innych skutków ubocznych opartych na tych żądania”.

Kod usługi kluczy i wartości Protected Audience API jest teraz dostępny w repozytorium GitHub Piaskownicy prywatności. Z tej usługi mogą korzystać deweloperzy Chrome i deweloperzy aplikacji na Androida. Informacje na temat aktualnego stanu znajdziesz w poście na blogu z ogłoszeniem. Więcej informacji o usłudze kluczy i wartości w Protected Audience API znajdziesz w Wyjaśnieniu interfejsu API i wyjaśnieniu modelu zaufania.

Do testów początkowych używany jest model „przynieś własny serwer”. W dłuższej perspektywie do pobierania danych w czasie rzeczywistym firmy AdTech będą musiały korzystać z usług kluczy i wartości dostępnych w ramach Protected Audience API, które działają w zaufanych środowiskach wykonawczych.

Aby zapewnić wystarczającą ilość czasu na testowanie ekosystemu, nie będziemy wymagać korzystania z usług kluczy i wartości open source ani TEE, dopóki nie nastąpi wycofanie plików cookie innych firm. Przed dokonaniem tej zmiany powiadomimy deweloperów o możliwości rozpoczęcia testowania i wdrażania nowych funkcji.

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 mogę zrezygnować z Protected Audience API?

Dostęp do interfejsu Protected Audience API możesz zablokować jako właściciel witryny lub pojedynczy użytkownik.

Jak witryny mogą kontrolować dostęp?

W efekcie w ramach Protected Audience API witryny będą musiały ustawić zasady dotyczące uprawnień aby udostępnić funkcję Protected Audience API. Dzięki temu wybrane firmy zewnętrzne nie będą mogły używać interfejsu API bez identyfikatora witryny wiedzę. Aby jednak ułatwić testowanie podczas pierwszego testowania origin, to wymaganie jest domyślnie uchylone. Witryny, które chcą całkowicie wyłączyć funkcję Protected Audience API w okresie testowania, mogą użyć odpowiednie zasady uprawnień, aby zablokować dostęp.

Istnieją 2 zasady dotyczące uprawnień z Protected Audience API, które można ustawić niezależnie:

  • join-ad-interest-group włącza lub wyłącza funkcję dodawania przeglądarki do grup zainteresowań
  • run-ad-auction włącza lub wyłącza funkcję przeprowadzania aukcji na urządzeniu

Dostęp do interfejsów Protected Audience API można całkowicie wyłączyć we własnych kontekstach, określając: uprawnienia w nagłówku odpowiedzi HTTP:

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

Aby wyłączyć korzystanie z interfejsów API w elemencie iframe, dodaj ten atrybut allow do elementu Element iframe:

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

Więcej informacji znajdziesz w sekcji Proponowana zasada dotycząca uprawnień pierwszego źródła Protected Audience API.

Rezygnacja użytkownika

Użytkownik może zablokować dostęp do interfejsu Protected Audience API i innych funkcji Piaskownicy prywatności, używając dowolnej następujące mechanizmy:

  • Wyłącz wersje próbne Piaskownicy prywatności w ustawieniach Chrome: Ustawienia > Prywatność i bezpieczeństwo > Piaskownica prywatności. Te materiały są też dostępne na stronie chrome://settings/adPrivacy.
  • Wyłącz pliki cookie innych firm w Ustawieniach Chrome: Ustawienia > Prywatność i bezpieczeństwo.
  • Ustaw Pliki cookie i inne dane witryn na „Blokuj pliki cookie innych firm”. lub „Blokuj wszystkie pliki cookie” od chrome://settings/cookies.
  • korzystać z trybu incognito,

Wyjaśnienie dotyczące Protected Audience API zawiera więcej informacji o elementach projektu interfejsu API i opisuje, jak interfejs API dąży do osiągnięcia celów w zakresie prywatności.

Debuguj Worklety Protected Audience

Od wersji Chrome Canary 98.0.4718.0 można debugować Worklety Protected Audience w Narzędziach deweloperskich w Chrome.

Pierwszym krokiem jest ustawienie punktów przerwania za pomocą nowej kategorii w panelu Punkty przerwania detektora zdarzeń. w panelu Źródła.

Zrzut ekranu z Narzędzia deweloperskie w Chrome Canary z wyróżnionym panelem Punkty przerwania detektora zdarzeń w panelu Źródła. W sekcji Worklet aukcji reklam wybierany jest początek fazy ustalania stawek licytującego.

Po aktywowaniu punktu przerwania wykonanie jest wstrzymywane przed pierwszą instrukcją na najwyższym poziomie skrypt Worklet. Aby przejść do określania stawek/wyników/raportów, możesz używać zwykłych punktów przerwania lub poleceń kroków. .

Skrypty Worklet na żywo również będą widoczne w panelu Wątki.

Zrzut ekranu z Narzędzia deweloperskie w Chrome Canary z wyróżnionym panelem Wątki w panelu Źródła: skrypt Worklet, który został wstrzymany.

Ponieważ niektóre Worklety mogą działać równolegle, wiele wątków może trafić do „wstrzymanego” tam, gdzie należy; na liście wątków możesz przełączać się między wątkami i wznawiać lub sprawdzać je dokładniej, odpowiednie.

Obserwuj zdarzenia z Protected Audience API

W panelu Aplikacje w Narzędziach deweloperskich w Chrome możesz obserwować grupę zainteresowań i aukcję w ramach Protected Audience API. zdarzeń.

Odwiedź stronę demonstracyjną Protected Audience API. w przeglądarce z włączoną Protected Audience API, Narzędzia deweloperskie wyświetlą informacje o zdarzeniu join.

Panel aplikacji w Narzędziach deweloperskich w Chrome Canary zawierający informacje o grupie zainteresowań Protected Audience API Dołącz do wydarzenia.

Jeśli wejdziesz na stronę wydawców demonstracyjną Protected Audience API, w przeglądarce z włączoną Protected Audience API, Narzędzia deweloperskie wyświetlą informacje o zdarzeniach bid i win.

Panel aplikacji w Narzędziach deweloperskich w Chrome Canary, przedstawiający informacje o stawce z aukcji z Protected Audience API i wydarzeń.

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 widzi reklamę nowego roweru tej firmy.

1. Użytkownik odwiedza witrynę reklamodawcy

Ilustracja przedstawiająca osoba odwiedzająca w przeglądarce na laptopie stronę internetową producenta rowerów.

Wyobraź sobie, że użytkownik odwiedza witrynę producenta rowerów niestandardowych (reklamodawca w w tym przykładzie) i odwiedza stronę ręcznie robionego stalowego roweru. Dzięki temu funkcja producenta rowerów i skorzystaj z możliwości remarketingu.

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

Grafika przedstawiająca osobę, która przegląda stronę w przeglądarce na laptopie. JavaScript w przeglądarce jest uruchomiony kod JoinAdInterestGroup().

Sekcja wyjaśnienia: Przeglądarki rejestrują grupy zainteresowań

Platforma DSP reklamodawcy (lub ) wywołuje metodę navigator.joinAdInterestGroup(), aby poprosić przeglądarkę o dodanie grupy zainteresowań do sekcji jest listą grup, do których należy przeglądarka. W tym przykładzie grupa nazywa się custom-bikes, właściciel to dsp.example. Właścicielem grupy zainteresowań (w tym przypadku DSP) będzie kupującego w aukcji reklam opisanej w kroku 4. Przynależność do grupy zainteresowań jest przechowywana przez przeglądarkę oraz na urządzeniu użytkownika i nie jest udostępniana od dostawcy przeglądarki.

joinAdInterestGroup() wymaga pozwolenia od:

  • Odwiedzana witryna
  • Właściciel grupy zainteresowań

Na przykład: nie może być możliwe wywołanie funkcji malicious.example joinAdInterestGroup() z użytkownikiem dsp.example jako właścicielem bez pozwolenia dsp.example

Zgoda z odwiedzanej witryny

To samo pochodzenie: domyślnie uprawnienia są przyznawane domyślnie w przypadku wywołań funkcji joinAdInterestGroup() z jest to samo miejsce pochodzenia co odwiedzana witryna, tj. pochodzi z tego samego źródła co ramka najwyższego poziomu bieżącej stronie. Witryny mogą używać nagłówka zasad dotyczących uprawnień Protected Audience API join-ad-interest-group dyrektywa wyłączająca wywołania joinAdInterestGroup().

Z innych domen: wywołanie joinAdInterestGroup() z innych źródeł niż obecne może odnieść sukces tylko wtedy, gdy odwiedzana witryna ma ustawioną zasadę uprawnień zezwalającą na wywołania joinAdInterestGroup() z elementów iframe z innych domen.

Uprawnienie właściciela grupy zainteresowań

Uprawnienie właściciela grupy zainteresowań jest domyślnie przyznawane przez wywołanie joinAdInterestGroup() z elementu iframe o tym samym pochodzeniu co miejsce docelowe właściciela grupy zainteresowań. Przykład: dsp.example Element iframe może wywoływać parametr joinAdInterestGroup() w przypadku grup zainteresowań należących do organizacji dsp.example.

Propozycja zakłada, że joinAdInterestGroup() może uruchamiać się na stronie lub w elemencie iframe w domenie właściciela. mogą być delegowane do innych domen za pomocą listy dostępnej pod adresem URL w usłudze .well-known.

Użycie navigator.joinAdInterestGroup()

Oto przykład wykorzystania interfejsu API:

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

Obiekt interestGroup przekazywany do funkcji nie może mieć więcej niż 50 kiB. W przeciwnym razie nie uda się przeprowadzić połączenia. Drugi parametr określa czas trwania grupy zainteresowań ograniczony do 30. dni. Kolejne wywołania zastępują wcześniej zapisane wartości.

Właściwości grupy zainteresowań

Właściwość Wymagane Przykład Rola
owner Wymagane 'https://dsp.example' Pochodzenie właściciela grupy zainteresowań.
name Wymagane 'custom-bikes' Nazwa grupy zainteresowań.
biddingLogicUrl** Opcjonalny* 'https://dsp.example/bid/custom-bikes/bid.js' Adres URL do ustalania stawek JavaScript uruchamianego w Worklet.
biddingWasmHelperUrl** Opcjonalny* 'https://dsp.example/bid/custom-bikes/bid.wasm' Adres URL kodu WebAssembly pochodzącego z biddingLogicUrl.
dailyUpdateUrl** Opcjonalnie 'https://dsp.example/bid/custom-bikes/update' Adres URL, który zwraca kod JSON, aby zaktualizować atrybuty grupy zainteresowań. (Patrz: Aktualizowanie grupy zainteresowań).
trustedBiddingSignalsUrl** Opcjonalnie 'https://dsp.example/trusted/bidding-signals' Podstawowy adres URL żądań par klucz-wartość wysyłanych do zaufanego serwera licytującego.
trustedBiddingSignalsKeys Opcjonalnie ['key1', 'key2' ...] Klucze dla żądań wysyłanych do zaufanego serwera według par klucz-wartość.
userBiddingSignals Opcjonalnie {...} Dodatkowe metadane, których właściciel może użyć podczas ustalania stawek.
ads Opcjonalny* [bikeAd1, bikeAd2, bikeAd3] Reklamy, które mogą być wyświetlane w przypadku tej grupy zainteresowań.
adComponents Opcjonalnie [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] Komponenty reklam złożonych z wielu elementów.

* Wszystkie właściwości są opcjonalne oprócz owner i name. biddingLogicUrl i ads nieruchomości są opcjonalne, ale wymagane, aby wziąć udział w aukcji. Niektóre przypadki użycia tworząc grupę zainteresowań bez tych właściwości: np. właściciel grupy zainteresowań może chcą dodać przeglądarkę do grupy zainteresowań w kampanii, która nie jest jeszcze uruchomiona, lub do wykorzystania w przyszłości, a budżet reklamowy może się tymczasowo wyczerpać.

** Adresy URL biddingLogicUrl, biddingWasmHelperUrl, dailyUpdateUrl i trustedBiddingSignalsUrl muszą mieć to samo pochodzenie co właściciel. Adresy URL ads i adComponents nie mają takiego ograniczenia.

Aktualizowanie atrybutów grupy zainteresowań

dailyUpdateUrl określa serwer WWW, który zwraca właściwości grupy zainteresowań w formacie JSON, odpowiadający obiektowi grupy zainteresowań przekazany do navigator.joinAdInterestGroup(). Ten zapewnia właścicielowi grupy mechanizm okresowej aktualizacji atrybutów atrybutu grupy zainteresowań. W obecnej implementacji: można zmienić następujące atrybuty:

  • biddingLogicUrl
  • biddingWasmHelperUrl
  • trustedBiddingSignalsUrl
  • trustedBiddingSignalsKeys
  • ads
  • priority

Żadne pola nieokreślone w pliku JSON nie zostaną zastąpione – tylko pola określone w pliku JSON zostaną zaktualizowane – podczas gdy wywołanie navigator.joinAdInterestGroup() spowoduje zastąpienie istniejącej grupy zainteresowań.

Aktualizacje są wykonywane w najlepszy możliwy sposób i mogą zakończyć się niepowodzeniem w tych sytuacjach:

  • Limit czasu żądania sieciowego (obecnie 30 sekund).
  • Inny błąd sieci.
  • Błąd analizy JSON.

Aktualizacje można też anulować, jeśli proces aktualizacji trwa zbyt długo, nie nakłada żadnych ograniczeń na anulowane (pozostałe) aktualizacje. Częstotliwość aktualizacji jest ograniczona do maksymalnie jeden dziennie. aktualizacje, które nie udało się z powodu błędów sieci, są ponawiane po upływie godziny. aktualizacje, które nie powiodły się z powodu odłączenia od internetu, są ponawiane natychmiast przy ponownym połączeniu.

Aktualizacje ręczne

Aktualizacje grup zainteresowań należących do źródła bieżącej klatki można aktywować ręcznie za pomocą: navigator.updateAdInterestGroups() Ograniczenie szybkości zapobiega zbyt częstemu aktualizowaniu treści: powtarzające się wywołania do navigator.updateAdInterestGroups() nie wykonują żadnych działań do czasu osiągnięcia limitu liczby żądań (obecnie jeden dzień). Limit liczby żądań jest resetowany, jeśli Funkcja navigator.joinAdInterestGroup() jest wywoływana ponownie dla tej samej grupy zainteresowań owner i name.

Aktualizacje automatyczne

Wszystkie grupy zainteresowań wczytane na aukcję są aktualizowane automatycznie po jej zakończeniu. podlegają tym samym limitom ruchu co aktualizacje ręczne. Dla każdego właściciela z co najmniej 1 grupą zainteresowań biorąc udział w aukcji, działa tak, jakby kod navigator.updateAdInterestGroups() został wywołany z Element iframe, którego źródło pasuje do tego właściciela.

Określanie reklam dla grupy zainteresowań

Obiekty ads i adComponents zawierają adres URL kreacji oraz, opcjonalnie, dowolny metadanych, 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?

Skrypt pod adresem biddingLogicUrl udostępniony przez właściciela grupy zainteresowań musi zawierać element generateBid() . Gdy sprzedawca z przestrzeni reklamowej wywołuje navigator.runAdAuction(), generatedBid() jest wywoływana raz dla każdej grupy zainteresowań, do której należy przeglądarka, jeśli dane właściciel grupy został zaproszony do ustalania stawek. Oznacza to, że funkcja generateBid() jest wywoływana raz dla każdego kandydata reklama. Sprzedawca udostępnia właściwość decisionLogicUrl w przekazanym parametrze konfiguracji aukcji. do: navigator.runAdAuction(). Kod pod tym adresem URL musi zawierać funkcję scoreAd(), która jest dla każdego licytującego biorącego udział w aukcji, by otrzymać punkty za poszczególne stawki zwrócone przez generateBid().

Skrypt pod adresem biddingLogicUrl udostępniony przez kupującego korzystającego z przestrzeni reklamowej musi zawierać funkcję generateBid(). Ta funkcja jest wywoływana raz dla każdej reklamy kandydującej. runAdAuction() sprawdza każdą reklamę i powiązaną z nią stawkę oraz metadane, a potem przypisuje jej liczbowy wynik przydatności.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

Funkcja generateBid() przyjmuje następujące argumenty:

  • interestGroup,
    Obiekt przekazany do joinAdInterestGroup() przez kupującego reklamy. (Grupa zainteresowań (można zaktualizować w: dailyUpdateUrl).

  • auctionSignals,
    Właściwość argumentu konfiguracja aukcji przekazywana do navigator.runAdAuction() przez sprzedawcę przestrzeni reklamowej. Zapewnia to informacje o kontekście strony (takie jak rozmiar reklamy i identyfikator wydawcy), typ aukcji (pierwsza lub druga cena) oraz inne metadanych.

  • perBuyerSignals,
    Tak jak auctionSignals, właściwość konfiguracji aukcji argument przekazany do navigator.runAdAuction() przez sprzedawcę. Dzięki temu możesz określić, to sygnały z serwera kupującego na temat strony, jeśli sprzedawca to SSP, który wysyła wywołanie określania stawek w czasie rzeczywistym do serwerów kupującego i przesyła odpowiedź do klienta lub jeśli wydawca kontaktuje się bezpośrednio z serwerem kupującego. Jeśli tak, kupujący może sprawdzić kryptografię podpisu tych sygnałów w ramach funkcji generateBid() w celu ochrony przed nieuprawnionymi modyfikacjami.

  • trustedBiddingSignals,
    Obiekt, którego klucze to trustedBiddingSignalsKeys klasy grupy zainteresowań, których wartości są zwracane w żądaniu trustedBiddingSignals.

  • browserSignals,
    Obiekt utworzony przez przeglądarkę, który może zawierać informacje o stronie kontekstu (np. hostname bieżącej strony, który w innym przypadku sprzedawca mógłby zafałszować) i danych dla samej grupy zainteresowań (np. zapis o tym, kiedy grupa wygrała wcześniej aukcję, aby umożliwić ograniczenie liczby wyświetleń na urządzeniu).

Obiekt browserSignals ma te właściwości:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

Aby obliczyć wartość bid, kod w generateBid() może używać właściwości funkcji . Na przykład:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

Funkcja generateBid() zwraca obiekt z 4 właściwościami:

  • ad,
    arbitralne metadane dotyczące reklamy, takie jak informacje, które sprzedawca spodziewa się znaleźć o stawce lub kreacji. Sprzedawca](/privacy-sandbox/resources/glossary#ssp) wykorzystuje te informacje w swojej aukcji i decyzji kreacji. Sprzedawca wykorzystuje te informacje podczas aukcji i podejmowania decyzji logikę logiczną.

  • bid,
    Stawka liczbowa, która weźmie udział w aukcji. Sprzedawca musi mieć możliwość porównywania stawki od różnych kupujących, dlatego stawki muszą być podane w określonej przez sprzedawcę jednostce (np. „PLN za tysiąc”). Jeśli stawka wynosi zero lub jest ujemna, dana grupa zainteresowań nie jest uwzględniana w nie musi wziąć udziału w aukcji. Za pomocą tego mechanizmu kupujący może stosować dowolne reguły reklamodawcy, których reklamy mogą nie być wyświetlane.

  • render,
    Adres URL lub lista adresów URL, które będą używane do renderowania kreacji, jeśli określona stawka wygra aukcję. (Zobacz Reklamy złożone z wielu elementów) w wyjaśnieniu interfejsu API). Wartość musi być zgodna z wartością renderUrl w jednej z reklam zdefiniowanych dla danej grupy zainteresowań.

  • adComponents,
    Opcjonalna lista maksymalnie 20 komponentów dla: reklamy składające się z wielu elementów, pobrane z właściwości adComponents argumentu grupy zainteresowań przekazano do navigator.joinAdInterestGroup().

Proszenie przeglądarki o opuszczenie grupy zainteresowań

Właściciel grupy zainteresowań może poprosić o usunięcie z niej przeglądarki. W innym przeglądarki prosi o usunięcie danej grupy zainteresowań z listy grup, do których należy.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Jeśli użytkownik wróci do witryny i poprosi przeglądarkę o dodanie grupy zainteresowań, właściciel grupy zainteresowań może wywołać funkcję navigator.leaveAdInterestGroup(), aby zażądać usunięcia przez przeglądarkę grupy zainteresowań. Kod reklamy może również wywoływać tę funkcję dla odpowiedniej grupy zainteresowań.

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

Grafika przedstawiająca osobę odwiedzającą stronę z wiadomościami w przeglądarce na laptopie. Witryna ma pusty boks reklamowy.

Później użytkownik odwiedza witrynę, która sprzedaje przestrzeń reklamową, w tym przykładzie witryny z wiadomościami. Witryna zawiera zasobów reklamowych, które sprzedaje w sposób zautomatyzowany za pomocą określania stawek w czasie rzeczywistym.

4. Aukcja reklam jest prowadzona w przeglądarce

Ilustracja przedstawiająca osobę przeglądającą stronę z wiadomościami w przeglądarce na laptopie. Reklamą aukcja za pomocą Protected Audience API.

Sekcja wyjaśnienia: Sprzedawcy przeprowadzają aukcje na urządzeniu

aukcja reklam prawdopodobnie będzie prowadzona przez SSP wydawcy; przez wydawcę. Celem aukcji jest wybór najbardziej odpowiedniej reklamy dla danej boks reklamowy na bieżącej stronie. Aukcja uwzględnia grupy zainteresowań, przeglądarki, wraz z danymi od kupujących przestrzeń reklamową i sprzedawców z usług kluczy/wartości.

Sprzedawca przestrzeni reklamowej wysyła do przeglądarki użytkownika żądanie rozpoczęcia aukcji reklam przez wywołanie navigator.runAdAuction()

Na przykład:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

runAdAuction() zwraca obietnicę przechodzącą do URN (urn:uuid:<something>), który reprezentuje wyniku aukcji reklam. Przeglądarka może go odkodować tylko wtedy, gdy jest przekazywana do chronionej ramki do renderowania: strona wydawcy nie może sprawdzać zwycięskiej reklamy.

Skrypt decisionLogicUrl uwzględnia każdą reklamę wraz z powiązaną z nią stawką i metadanych, a potem przypisuje mu liczbową ocenę przyjęcia.

auctionConfig miejsca zakwaterowania

Właściwość Wymagane Przykład Rola
seller Wymagane 'https://ssp.example' Pochodzenie sprzedawcy.
decisionLogicUrl Wymagane 'https://ssp.example/auction-decision-logic.js' Adres URL JavaScriptu Workleta aukcji.
trustedScoringSignalsUrl Opcjonalnie 'https://ssp.example/scoring-signals' Adres URL zaufanego serwera sprzedawcy.
interestGroupBuyers* Wymagane ['https://dsp.example', 'https://buyer2.example', ...] Źródła wszystkich właścicieli grup zainteresowań, którzy poprosili o udział w aukcji.
auctionSignals Opcjonalnie {...} Informacje o sprzedawcy o kontekście strony, typie aukcji itp.
sellerSignals Opcjonalnie {...} informacje zależne od ustawień wydawcy, wysyłanego kontekstowo żądań reklamy itp.
sellerTimeout Opcjonalnie 100 Maksymalny czas działania skryptu scoreAd() sprzedawcy (w milisekundach).
perBuyerSignals Opcjonalnie {'https://dsp.example': {...},
  'https://another-buyer.example': {...},
...}		 Sygnały kontekstowe dotyczące strony każdego kupującego pochodzące z jego serwera.
perBuyerTimeouts Opcjonalnie 50 Maksymalne czasy działania (w milisekundach) skryptów generateBid() kupującego.
componentAuctions Opcjonalnie [{'seller': 'https://www.some-other-ssp.com',
  'decisionLogicUrl': ..., ...},
  ...]		 Dodatkowe konfiguracje dla aukcji komponentów.

* Sprzedawca może określić interestGroupBuyers: '*', aby umożliwić licytowanie wszystkim grupom zainteresowań. Reklamy są następnie akceptowane lub odrzucane na podstawie kryteriów innych niż uwzględnienie właściciela grupy zainteresowań. Sprzedawca może na przykład sprawdzać kreacje, aby potwierdzić ich zgodność z zasadami.

** Funkcja additionalBids nie jest obsługiwana w obecnej implementacji Protected Audience API. Przeczytaj aukcję Uczestnicy w narzędziu Wyjaśnienie dotyczące Protected Audience API.

Jak wybierane są reklamy?

kod w polu decisionLogicUrl (właściwość obiektu konfiguracji aukcji przekazywana do runAdAuction()) musi zawierać funkcję scoreAd(). Kampania jest przeprowadzana raz na każdą reklamę. aby określić jej cel.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

Funkcja scoreAd() przyjmuje następujące argumenty:

  • adMetadata,
    Dowolne metadane podane przez kupującego.
  • bid,
    Numeryczna wartość stawki.
  • auctionConfig,
    Obiekt konfiguracji aukcji został przekazany do navigator.runAdAuction().
  • trustedScoringSignals,
    wartości pobranych w czasie aukcji z zaufanego serwera sprzedawcy; i przedstawia opinię sprzedawcy o reklamie.
  • browserSignals,
    obiekt utworzony przez przeglądarkę, w tym informacje o tym, że który skrypt aukcji sprzedawcy chce zweryfikować:
{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}

Przed rozpoczęciem aukcji sprzedawca znajduje najlepszą reklamę kontekstową dla dostępnego boksu reklamowego. Część zasada scoreAd() polega na odrzucaniu wszystkich reklam, które nie są lepsze od zwycięskiej reklamy kontekstowej.

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

Ilustracja przedstawiająca osobę przeglądającą 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ść.

Sekcja wyjaśnienia: pobieranie danych w czasie rzeczywistym z usługi kluczy i wartości w Protected Audience API.

Podczas aukcji reklam sprzedawca przestrzeni reklamowej może w czasie rzeczywistym uzyskiwać dane o konkretnych kreacjach reklamowych przez wysyłając żądanie do usługi klucz-wartość za pomocą właściwości trustedScoringSignalsUrl Argument konfiguracji aukcji przekazany do navigator.runAdAuction() wraz z kluczami z właściwości renderUrl wszystkich wpisów w polach ads i adComponents wszystkich do określonych grup zainteresowań.

Podobnie kupujący zajmujący się przestrzenią reklamową może zażądać danych w czasie rzeczywistym z usługi klucz-wartość za pomocą funkcji Właściwości trustedBiddingSignalsUrl i trustedBiddingSignalsKeys argumentu grupy zainteresowań przekazano do navigator.joinAdInterestGroup().

Po wywołaniu funkcji runAdAuction() przeglądarka wysyła żądanie do zaufanego serwera każdego kupującego reklamy. 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

Ilustracja przedstawiająca osobę przeglądającą stronę z wiadomościami w przeglądarce na laptopie. Reklamą dla roweru (20% zniżki) – z kłódką powyżej, która informuje, że reklama z zabezpieczoną ramką.

Wyjaśnienie: Przeglądarki renderują zwycięską reklamę

Jak opisano wcześniej: obietnica zwrócona przez runAdAuction() przechodzi do URN która jest przekazywana do chronionej ramki na potrzeby renderowania, a witryna wyświetla zwycięską reklamę.

7. Wynik aukcji jest raportowany

Sekcja wyjaśnienia: Raportowanie na poziomie zdarzenia (na razie)

Wynik podany przez sprzedawcę

Sekcja wyjaśnienia: Raporty sprzedawcy dotyczące renderowania

Kod JavaScript sprzedawcy dostępny na stronie decisionLogicUrl (z uwzględnieniem również: scoreAd()) może dodaj funkcję reportResult(), by zgłosić wynik aukcji.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Argumenty przekazywane do tej funkcji to:

  • auctionConfig,
    Obiekt konfiguracji aukcji został przekazany do navigator.runAdAuction().


  • (browserSignals) Obiekt utworzony przez przeglądarkę, który dostarcza informacji o aukcji. Przykład:

    {
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

Zwracana wartość tej funkcji jest używana jako argument sellerSignals funkcji zwycięskiego licytującego reportWin().

Wynik podany w raporcie zwycięskiego licytującego

Sekcja wyjaśnienia: raporty kupujących dotyczące renderowania i zdarzeń reklamowych

Kod JavaScript zwycięskiego licytującego (który zawiera również element generateBid()) może zawierać parametr reportWin() do raportowania wyniku aukcji.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Argumenty przekazywane do tej funkcji to:

  • auctionSignals i perBuyerSignals
    Te same wartości przekazane do generateBid() w przypadku zwycięskiego licytującego.
  • sellerSignals,
    Wartość zwrotu reportResult(), który daje sprzedawcy wartość umożliwiają przekazanie informacji kupującemu.

  • browserSignals,
    Obiekt utworzony przez przeglądarkę, który dostarcza informacji o aukcji. Przykład:

    {
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

Tymczasowe wdrożenie raportowania strat/wygranych

W Chrome na potrzeby raportowania aukcji są tymczasowo dostępne 2 metody:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Każda z tych metod wykorzystuje jeden argument: adres URL, który zostanie pobrany po zakończeniu aukcji. Mogą może być wywoływana wiele razy zarówno w metodzie scoreAd(), jak i generateBid() z różnymi argumentami adresu URL.

Chrome wysyła raporty debugowania o utratach/wygranych tylko po zakończeniu aukcji. Jeśli aukcja jest anulowane (np. z powodu nowej nawigacji) nie są generowane żadne raporty.

Te metody są domyślnie dostępne w Chrome. Aby przetestować metody, włącz wszystkie interfejsy Ad Privacy API w usłudze chrome://settings/adPrivacy. Jeśli używasz Chrome z flagami wiersza poleceń, które pozwalają włączyć Protected Audience API, musisz wykonać te czynności: bezpośrednio włączać te metody za pomocą flagi BiddingAndScoringDebugReportingAPI. Jeśli nie jest włączona, metody będą nadal dostępne, ale nie będą działać.

8. Zgłoszenie kliknięcia reklamy

Ilustracja przedstawiająca osoba klikająca reklamę roweru w ogromnej ramce, na stronie z wiadomościami, z raportem do sprzedawców i kupujących.

Rejestrowane jest kliknięcie reklamy renderowanej w ramce. Aby dowiedzieć się więcej o tym, jak to może działać, przeczytaj artykuł Raporty dotyczące reklam z ramkami zabezpieczonymi.


Poniższy diagram przedstawia każdy etap aukcji reklam z użyciem Protected Audience API:

Grafika przedstawiająca każdy etap aukcji reklam z użyciem Protected Audience API.


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

Protected Audience to pierwszy eksperyment zaimplementowany w Chromium w ramach rodziny ofert pakietowych TURTLEDOVE.

Ochrona odbiorców jest zgodna z ogólnymi zasadami TURTLEDOVE. Niektóre reklamy online polegają 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 tej funkcji polegało na rozpoznaniu przez reklamodawców określonej osoby przeglądającej 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, co reklamodawca myśli zainteresowaną osobą.
  • Reklamodawcy mogą wyświetlać reklamy na podstawie zainteresowań, ale nie mogą łączyć tego z innymi o osobie, a w szczególności o tym, kim jest i jaką stronę odwiedza.

Ochrona odbiorców powstała na bazie TURTLEDOVE i zbioru powiązanych propozycji zmian, aby lepiej służyć deweloperom, którzy z niego korzystali:

  • W SPARROW: Criteo zaproponował dodanie parametru model usługi („Gatekeeper”) działający w zaufanym środowisku wykonawczym (TEE). Protected Audience API umożliwia bardziej ograniczone korzystanie z technologii TEE do wyszukiwania danych w czasie rzeczywistym i tworzenia raportów zbiorczych.
  • TERN na NextRoll i Magnite PARRROT opisywały różne role kupujących i sprzedawców w aukcji na urządzeniu. Proces określania stawek lub oceniania reklam w usłudze Protected Audience API opiera się na tych działaniach.
  • oparte na wynikach oraz TURTLEDOVE na poziomie produktu modyfikacje poprawiły model 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 w celu anonimizacji żądań reklam i egzekwowania prywatności usług. Ochrona odbiorców nie wdrożyła tego modelu pośredniczącego. Wprowadzamy interfejsy API JavaScript w działalności PARAKEET i Protected Audience API. Chcemy w ten sposób wspierać przyszłe prace nad połączeniem najlepszych cech obu ofert.

Protected Audience API nie uniemożliwia jeszcze sieci reklamowej w witrynie poznawania reklam wyświetlanych użytkownikowi. Przewidujemy, modyfikować interfejs API, aby z czasem stał się bardziej prywatny.

Jaka konfiguracja przeglądarki jest dostępna?

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 usłudze chrome://settings/adPrivacy. Podczas testów wstępnych użytkownicy zostaną za pomocą tego ogólnego ustawienia Piaskownicy prywatności, aby zrezygnować z korzystania z Protected Audience API. Planowane wprowadzenie Chrome Użytkownicy mogą wyświetlać listę grup zainteresowań, do których zostali dodani w internecie, i zarządzać tą listą odwiedzonych przez nich stron. Podobnie jak w przypadku technologii Piaskownicy prywatności, ustawienia użytkownika mogą ewoluować na podstawie opinii użytkowników, organów regulacyjnych i innych osób.

W miarę postępów oferty Protected Audience API będziemy na bieżąco aktualizować ustawienia dostępne w Chrome, na temat testów i opinii. W przyszłości planujemy udostępnić bardziej szczegółowe ustawienia zarządzania 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, a członkostwo jest jest usuwana, gdy użytkownik wyczyści dane witryny.



Angażuj odbiorców i dziel się opiniami

Uzyskaj pomoc

Aby zadać pytanie na temat Twojej implementacji, wersji demonstracyjnej lub dokumentacji:

W przypadku błędów i problemów z implementacją interfejsu Protected Audience API w Chrome: * Wyświetl istniejące problemy dla interfejsu API. * Zgłoś nowy problem na crbug.com/new.

Otrzymuj powiadomienia

  • Aby otrzymywać powiadomienia o zmianach stanu w interfejsie API, dołącz do listy adresowej dla .
  • Aby dokładnie śledzić wszystkie trwające dyskusje na temat interfejsu API, kliknij przycisk Obejrzyj na stronie oferty pakietowej GitHub. Wymaga to posiadania lub utworzenia konta GitHub .
  • Aby otrzymywać ogólne informacje na temat Piaskownicy prywatności, zasubskrybuj kanał RSS [Postęp w zakresie prywatności (Piaskownica)].

Więcej informacji

Zdjęcie: Ray Hennessy, Unsplash.