Przewodnik dla programistów interfejsu FLEDGE API

Dla kogo jest ten artykuł?

Ten post zawiera informacje techniczne o obecnej wersji eksperymentalnej interfejsu Protected Audience API.

Czym jest Protected Audience?

Protected Audience API to oferta Piaskownicy prywatności, która umożliwia wyświetlanie remarketingu i niestandardowych list odbiorców w taki sposób, aby inne firmy nie mogły go używać do śledzenia działań użytkowników w różnych witrynach. Interfejs API umożliwia przeglądarce w aukcjach na urządzeniu wybór trafnych reklam do witryn, które odwiedzał wcześniej.

Protected Audience to pierwszy eksperyment, który został wdrożony w Chromium w ramach rodziny ofert pakietowych TURTLEDOVE.

Poniższy schemat przedstawia cykl życia FLEDGE:

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

Jak mogę wypróbować Protected Audience?

Wersja demonstracyjna usługi Protected Audience

Przewodnik po podstawowym wdrożeniu Protected Audience API w witrynach reklamodawców i wydawców jest dostępny na stronie Protected-audience-demo.web.app.

Film demonstracyjny wyjaśnia, jak działa kod demonstracyjny, i pokazuje, jak używać Narzędzi deweloperskich w Chrome do debugowania w ramach Protected Audience.

Weź udział w testowaniu origin Protected Audience

Udostępniliśmy okres próbny sprawdzania trafności i pomiarów Piaskownicy prywatności w Chrome w wersji 101.0.4951.26 i nowszych na komputerach w ramach interfejsów Protected Audience API, Topics i Attribution Reporting.

Aby z niej skorzystać, zarejestruj się i uzyskaj token próbny origin.

Po zarejestrowaniu się w okresie próbnym możesz wypróbować interfejs Protected Audience API na stronach, które mają prawidłowy token próbny, na przykład aby poprosić przeglądarkę o dołączenie do co najmniej 1 grupy zainteresowań, a potem przeprowadzić aukcję reklam, aby wybrać i wyświetlić reklamę.

Prezentacja Protected Audience zawiera podstawowy przykład pełnego 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 elemencie <head>:

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

  • Jako nagłówek HTTP:

    Origin-Trial: TOKEN_GOES_HERE

  • Udostępniając token automatycznie:

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

Element iframe z kodem w ramach Protected Audience API, np. wywołaniem funkcji navigator.joinAdInterestGroup() przez właściciela grupy zainteresowań, musi zawierać token zgodny ze swoim źródłem.

Szczegóły proponowanego źródła w programie First Protected Audience Origin (szczegóły) zawierają więcej informacji o celach pierwszego okresu próbnego i wyjaśniają, które funkcje są obsługiwane.

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

W Chrome Beta w wersji 101.0.4951.26 i nowszych wersji na komputerze możesz przetestować funkcje Protected Audience API dla pojedynczego użytkownika: * Włączając funkcję chrome://flags/#privacy-sandbox-ads-apis. * Przez ustawienie flag z poziomu wiersza poleceń.

Renderowanie reklam w elementach iframe lub ramkach ogrodzonych

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

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

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

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

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

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

W artykule Uruchamianie Chromium z flagami wyjaśniamy, jak ustawić flagi w przypadku uruchamiania Chrome i innych przeglądarek opartych na Chromium z poziomu wiersza poleceń. Pełna lista flag Protected Audience API jest dostępna w wyszukiwarce kodu Chromium.

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

Udostępniamy Protected Audience za flagami funkcji w Chromium w ramach pierwszego eksperymentu, który ma na celu przetestowanie tych funkcji tej oferty:

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

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

Uprawnienia grupy zainteresowań

Domyślnym ustawieniem w obecnej implementacji Protected Audience jest zezwalanie na wywoływanie metody joinAdInterestGroup() z dowolnego miejsca na stronie, nawet z międzydomenowych elementów iframe. W przyszłości, gdy właściciele witryn zdołają dostosować zasady uprawnień w elementach iframe w różnych domenach, plan będzie blokować wywołania pochodzące z międzydomenowych elementów iframe, jak wyjaśniamy w wyjaśnieniu.

Usługa kluczy/wartości

W ramach aukcji reklam w ramach Protected Audience API przeglądarka może korzystać z usługi klucz-wartość, która zwraca proste pary klucz-wartość, aby przekazać kupującemu reklamy informacje takie jak pozostały budżet kampanii. W ofercie pakietowej Protected Audience wymagamy, by serwer „nie przeprowadzał logowania na poziomie zdarzenia i nie ma innych skutków ubocznych na podstawie tych żądań”.

Kod usługi klucz/wartość Protected Audience API jest teraz dostępny w repozytorium Piaskownicy prywatności na GitHubie. Z tej usługi mogą korzystać deweloperzy Chrome i Androida. Informacje o zmianie stanu znajdziesz w poście na blogu z ogłoszeniem. Więcej informacji o usłudze klucz-wartość Protected Audience znajdziesz w objaśnieniu interfejsu API i objaśnieniu modelu zaufania.

Do początkowych testów używany jest model „Przynieś własny serwer”. W dłuższej perspektywie technologie adTech będą musiały pobierać dane w czasie rzeczywistym z oprogramowania typu open source w zakresie kluczy/wartości Protected Audience API, działających w zaufanych środowiskach wykonawczych.

Aby zapewnić wystarczającą ilość czasu na testy ekosystemu, nie będziemy wymagać korzystania z usług typu klucz/wartość typu open source ani technologii TEE do jakiegoś czasu po wycofaniu plików cookie innych firm. Przed tym przeniesieniem deweloperzy otrzymają powiadomienie o możliwości rozpoczęcia testów i wdrażania.

Wykrywanie obsługi funkcji

Zanim użyjesz tego interfejsu API, sprawdź, czy jest on obsługiwany przez przeglądarkę i dostępny w dokumencie:

'joinAdInterestGroup' in navigator &&
  document.featurePolicy.allowsFeature('join-ad-interest-group') &&
  document.featurePolicy.allowsFeature('run-ad-auction') ?
  console.log('navigator.joinAdInterestGroup() is supported on this page') :
  console.log('navigator.joinAdInterestGroup() is not supported on this page');

Jak mogę zrezygnować z Protected Audience?

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

W jaki sposób witryny mogą kontrolować dostęp?

Protected Audience API będzie wymagać od witryn ustawienia zasady uprawnień, która umożliwi korzystanie z funkcji Protected Audience. Dzięki temu wybrane osoby trzecie nie będą mogły korzystać z interfejsu API bez wiedzy o witrynie. Jednak aby ułatwić testowanie w trakcie pierwszego okresu próbnego origin, domyślnie to wymaganie jest wyłączone. Witryny, które w okresie testowania chcą całkowicie wyłączyć tę funkcję, mogą blokować dostęp, używając odpowiedniej zasady dotyczącej uprawnień.

Istnieją 2 zasady dotyczące uprawnień w ramach 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 w nagłówku odpowiedzi HTTP tę zasadę uprawnień:

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

Aby wyłączyć interfejsy API w elemencie iframe, dodaj do elementu iframe ten atrybut allow:

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

Więcej informacji znajdziesz w sekcji Proponowane uprawnienia dotyczące źródła w ramach okresu próbnego w ramach pierwszej chronionej grupy odbiorców.

Rezygnacja użytkownika

Użytkownik może zablokować dostęp do interfejsu Protected Audience API i innych funkcji Piaskownicy prywatności za pomocą jednego z tych mechanizmów:

  • Wyłącz wersje próbne Piaskownicy prywatności w ustawieniach Chrome: Ustawienia > Bezpieczeństwo i prywatność > Piaskownica prywatności. Ta strona jest też dostępna na stronie chrome://settings/adPrivacy.
  • Wyłącz pliki cookie innych firm w ustawieniach Chrome: Ustawienia > Bezpieczeństwo i prywatność.
  • Ustaw opcję Pliki cookie i inne dane witryn na „Blokuj pliki cookie innych firm” lub „Blokuj wszystkie pliki cookie” z chrome://settings/cookies.
  • korzystać z trybu incognito,

Wyjaśnienie Protected Audience zawiera więcej informacji o elementach projektu interfejsu API i opisuje, w jaki sposób interfejs API ma pomagać w osiąganiu celów związanych z prywatnością.

Debugowanie workletów Protected Audience

Od wersji Chrome Canary 98.0.4718.0 można debugować worklety Protected Audience przy użyciu Narzędzi deweloperskich w Chrome.

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

Zrzut ekranu przedstawiający Narzędzia deweloperskie w Chrome Canary z wyróżnionym panelem Punkty przerwania detektora zdarzeń w panelu Źródła. Rozpoczęcie fazy określania stawek przez licytującego wybrano w Workletu aukcji reklam.

Po uruchomieniu punktu przerwania wykonanie jest wstrzymywane przed pierwszą instrukcją na najwyższym poziomie skryptu worklet. Aby przejść do samej funkcji określania stawek, wyników lub raportowania, możesz użyć zwykłych punktów przerwania lub poleceń krokowych.

Skrypty aktywnego obszaru roboczego pojawią się również w panelu Wątki.

Zrzut ekranu przedstawiający Narzędzia deweloperskie w Chrome Canary z wyróżnionym panelem Wątki w panelu Źródła i wyświetlonym aktualnie wstrzymanym skryptem workletu.

Ponieważ niektóre Worklety mogą działać równolegle, wiele wątków może znaleźć się w stanie wstrzymania. Za pomocą listy wątków możesz przełączać się między wątkami i w razie potrzeby je wznawiać lub sprawdzać dokładniej.

Obserwowanie zdarzeń w ramach Protected Audience API

W panelu Aplikacje w Narzędziach deweloperskich w Chrome możesz obserwować zdarzenia związane z grupą zainteresowań i aukcjami w ramach Protected Audience API.

Jeśli otworzysz prezentacyjną stronę zakupów w ramach Protected Audience API w przeglądarce z włączoną funkcją Protected Audience, Narzędzia deweloperskie wyświetlą informacje o zdarzeniu join.

Panel aplikacji Narzędzi deweloperskich w Chrome Canary z informacjami o zdarzeniu dołączenia do grupy zainteresowań w ramach Protected Audience API.

Jeśli teraz otworzysz witrynę wydawcy demonstracyjnej w ramach Protected Audience API w przeglądarce z włączoną funkcją Protected Audience, Narzędzia deweloperskie wyświetlą informacje o zdarzeniach bid i win.

Panel aplikacji Narzędzi deweloperskich w Chrome Canary z informacjami o stawce na aukcji w ramach Protected Audience API i zdarzeniach wygranych.

Jak działa interfejs Protected Audience API?

W tym przykładzie użytkownik przegląda witrynę producenta rowerów na zamówienie, a następnie odwiedza witrynę z wiadomościami i widzi reklamę nowego roweru tej firmy.

1. Użytkownik odwiedza witrynę reklamodawcy.

Grafika przedstawiająca osobę, która odwiedza w przeglądarce na laptopie stronę producenta rowerów.

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

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

Ilustracja przedstawiająca osobę przeglądającą stronę internetową w przeglądarce na laptopie. W przeglądarce działa kod JavaScript JoinAdInterestGroup().

Sekcja Wyjaśnienie: Przeglądarki rejestrują grupy zainteresowań

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 przeglądarka. W tym przykładzie grupa nazywa się custom-bikes, a jej właścicielem jest dsp.example. Właściciel grupy zainteresowań (w tym przypadku platforma DSP) będzie kupującym w aukcji reklam opisanym w kroku 4. Członkostwo w grupie zainteresowań jest przechowywane przez przeglądarkę, na urządzeniu użytkownika i nie jest udostępniane dostawcy przeglądarki ani nikomu innemu.

joinAdInterestGroup() wymaga pozwolenia od: * odwiedzanej witryny, * właściciela grupy zainteresowań.

Na przykład: malicious.example nie może wywołać metody joinAdInterestGroup() z użytkownikiem dsp.example w roli właściciela bez pozwolenia ze strony dsp.example.

Uprawnienia odwiedzanej witryny

To samo źródło: domyślnie uprawnienia są domyślnie przyznawane w przypadku wywołań funkcji joinAdInterestGroup() z tego samego źródła co odwiedzana witryna, tj. z tego samego źródła co ramka najwyższego poziomu bieżącej strony. Witryny mogą używać nagłówka zasady uprawnień join-ad-interest-group dyrektywy Protected Audience API do wyłączania wywołań joinAdInterestGroup().

Pomiędzy źródłem: wywołanie metody joinAdInterestGroup() z innych źródeł niż bieżąca strona może się udać tylko wtedy, gdy odwiedzana witryna ma ustawioną zasadę uprawnień, która zezwala na wywołania joinAdInterestGroup() z innych domen iframe.

Uprawnienia właściciela grupy zainteresowań

Uprawnienia właściciela grupy zainteresowań jest domyślnie przyznawane przez wywołanie elementu joinAdInterestGroup() z elementu iframe o tym samym pochodzeniu co właściciel grupy zainteresowań. Na przykład element dsp.example element iframe może wywoływać metodę joinAdInterestGroup() w przypadku grup zainteresowań należących do dsp.example.

Zgodnie z propozycją joinAdInterestGroup() może działać na stronie lub w elemencie iframe w domenie właściciela albo być delegowana do innych domen dostarczonych za pomocą listy znajdującej się pod adresem URL .well-known.

Za pomocą 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 przekazany do funkcji nie może mieć więcej niż 50 kiB. W przeciwnym razie wywołanie zakończy się niepowodzeniem. Drugi parametr określa czas trwania grupy zainteresowań z ograniczeniem 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** Opcjonalnie* 'https://dsp.example/bid/custom-bikes/bid.js' Adres URL na potrzeby ustalania stawek JavaScriptu uruchamiany w workletu.
biddingWasmHelperUrl** Opcjonalnie* 'https://dsp.example/bid/custom-bikes/bid.wasm' Adres URL kodu WebAssembly pobrany z biddingLogicUrl.
dailyUpdateUrl** Opcjonalnie 'https://dsp.example/bid/custom-bikes/update' Adres URL, który zwraca plik JSON, aby aktualizować atrybuty grupy zainteresowań. (zobacz Aktualizowanie grupy zainteresowań).
trustedBiddingSignalsUrl** Opcjonalnie 'https://dsp.example/trusted/bidding-signals' Podstawowy adres URL na potrzeby żądań par klucz-wartość wysyłanych do zaufanego serwera licytującego.
trustedBiddingSignalsKeys Opcjonalnie ['key1', 'key2' ...] Klucze dla żądań wysyłanych do zaufanego serwera par klucz-wartość.
userBiddingSignals Opcjonalnie {...} Dodatkowe metadane, których właściciel może używać podczas ustalania stawek.
ads Opcjonalnie* [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 z wyjątkiem owner i name. Właściwości biddingLogicUrl i ads są opcjonalne, ale wymagane do udziału w aukcji. Grupy zainteresowań bez tych właściwości mogą się przydać w niektórych sytuacjach. Na przykład właściciel grupy zainteresowań może dodać przeglądarkę do grupy zainteresowań w przypadku nieaktywnej kampanii lub w inny sposób. Może też wyczerpać mu się tymczasowo budżet reklamowy.

** Adresy URL biddingLogicUrl, biddingWasmHelperUrl, dailyUpdateUrl i trustedBiddingSignalsUrl muszą mieć to samo źródło 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ąc obiektowi grupy zainteresowań przekazanym do navigator.joinAdInterestGroup(). Dzięki temu właściciel grupy może okresowo aktualizować jej atrybuty. W obecnej implementacji można zmieniać te atrybuty:

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

Pole, które nie jest określone w pliku JSON, nie zostanie zastąpione (zaktualizowane są tylko pola określone w pliku JSON), natomiast wywołanie navigator.joinAdInterestGroup() zastępuje dotychczasową grupę zainteresowań.

Aktualizacje są przeprowadzane zgodnie z możliwością wyboru i mogą zakończyć się niepowodzeniem w tych sytuacjach: * Limit czasu żądania sieci (obecnie 30 sekund). * Inna awaria sieci. * Błąd analizy JSON.

Aktualizacje można też anulować, jeśli aktualizacja zajmuje zbyt dużo czasu. Nie ogranicza to jednak częstotliwości anulowanych (pozostałych) aktualizacji. Częstotliwość aktualizacji jest ograniczona do maksymalnie jednego dziennie. Aktualizacje, które nie powiodły się z powodu błędów sieci, są ponawiane po godzinie, a aktualizacje zakończone niepowodzeniem z powodu utraty połączenia z internetem są od razu ponawiane natychmiast po ponownym połączeniu.

Aktualizacje ręczne

Aktualizacje grup zainteresowań należących do źródła bieżącej ramki można aktywować ręcznie przez navigator.updateAdInterestGroups(). Ograniczenie liczby żądań zapobiega zbyt częstym aktualizacjom: powtarzające się wywołania navigator.updateAdInterestGroups() nie wykonują żadnych działań, dopóki nie minie okres limitu liczby żądań (obecnie 1 dzień). Limit stawki zostanie zresetowane, jeśli funkcja navigator.joinAdInterestGroup() zostanie wywołana ponownie dla tej samej grupy zainteresowań owner i name.

Automatyczne aktualizacje

Wszystkie grupy zainteresowań wczytane w ramach aukcji są aktualizowane automatycznie po jej zakończeniu, z zastrzeżeniem tych samych limitów stawki co w przypadku aktualizacji ręcznych. W przypadku każdego właściciela z co najmniej 1 grupą zainteresowań biorących udział w aukcji działa to tak, jakby funkcja navigator.updateAdInterestGroups() była wywoływana z elementu iframe, którego źródło pasuje do tego właściciela.

Określ reklamy dla grupy zainteresowań

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

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

W jaki sposób kupujący ustalają stawki?

Skrypt pod adresem biddingLogicUrl udostępniony przez właściciela grupy zainteresowań musi zawierać funkcję generateBid(). Gdy sprzedawca przestrzeni reklamowej wywołuje funkcję navigator.runAdAuction(), funkcja generatedBid() jest wywoływana raz dla każdej grupy zainteresowań, do której należy przeglądarka (jeśli właściciel grupy zainteresowań ma zaproszenie do ustalania stawek). Oznacza to, że funkcja generateBid() jest wywoływana raz na każdą reklamę kandydującą. Sprzedawca udostępnia właściwość decisionLogicUrl w parametrze konfiguracji aukcji przekazywanym do navigator.runAdAuction(). Kod pod tym adresem URL musi zawierać funkcję scoreAd(), która jest uruchamiana w przypadku każdego licytującego biorącego udział w aukcji, która służy do oceniania poszczególnych stawek zwróconych przez funkcję generateBid().

Skrypt pod adresem biddingLogicUrl dostarczony przez kupującego przestrzeń reklamową musi zawierać funkcję generateBid(). Funkcja jest wywoływana raz dla każdej reklamy kandydującej. runAdAuction() pojedynczo sprawdza każdą reklamę wraz z powiązaną z nią stawką i metadanymi, a potem przypisuje do niej liczbową wartość celu.

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

Funkcja generateBid() przyjmuje te argumenty:

  • interestGroup
    Obiekt przekazany do joinAdInterestGroup() przez kupującego reklamy. Grupę zainteresowań można zaktualizować za pomocą dailyUpdateUrl.

  • auctionSignals
    Właściwość argumentu konfiguracja aukcji przekazana do navigator.runAdAuction() przez sprzedawcę przestrzeni reklamowej. Zapewnia to informacje o kontekście strony (np. o rozmiarze reklamy i identyfikatorze wydawcy), typie aukcji (pierwsza lub druga cena) i innych metadanych.

  • perBuyerSignals
    Tak jak w przypadku auctionSignals, właściwość argumentu konfiguracji aukcji przekazana przez sprzedawcę do navigator.runAdAuction(). Dzięki temu możesz dostarczać sygnały kontekstowe dotyczące strony z serwera kupującego, jeśli sprzedawca jest platformą SSP, która przesyła do serwerów kupujących wywołanie określania stawek w czasie rzeczywistym i przesyła odpowiedź lub jeśli strona wydawcy kontaktuje się bezpośrednio z serwerem kupującego. Jeśli tak, kupujący może zechcieć sprawdzić podpis kryptograficzny tych sygnałów w ramach funkcji generatebid() w celu zabezpieczenia przed manipulacją.

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

  • browserSignals
    Obiekt utworzony przez przeglądarkę, który może zawierać informacje o kontekście strony (np. hostname bieżącej strony, który sprzedawca mógłby sfałszować) oraz dane dotyczące samej grupy zainteresowań (np. informacje o tym, kiedy grupa wcześniej wygrała 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 funkcji generateBid() może korzystać z właściwości parametrów funkcji. Na przykład:

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

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

  • ad
    Dowolne metadane reklamy, np. informacje, które sprzedawca chce uzyskać o określonej stawce lub kreacji reklamy. Sprzedawca](/privacy-sandbox/resources/glossary#ssp) wykorzystuje te informacje w kreacji na potrzeby aukcji i decyzji. Sprzedawca wykorzystuje te informacje podczas aukcji i strategii decyzyjnych.

  • bid
    Stawka numeryczna, która bierze udział w aukcji. Sprzedawca musi mieć możliwość porównywania stawek różnych kupujących, dlatego stawki muszą być określone w jakiejś jednostce wybranej przez sprzedawcę (np. „USD za tysiąc”). Jeśli stawka wynosi zero lub jest ujemna, dana grupa zainteresowań w ogóle nie weźmie udziału w aukcji sprzedawcy. Dzięki temu mechanizmowi kupujący może wdrażać dowolne reguły reklamodawcy określające, gdzie jego reklamy mogą się pojawiać, ale nie.

  • render
    Adres URL lub lista adresów URL, które będą używane do renderowania kreacji, gdy ta stawka wygra aukcję. (patrz Reklamy składające się z wielu elementów w objaśnieniu interfejsu API). Wartość musi być zgodna z wartością renderUrl jednej z reklam zdefiniowanych dla grupy zainteresowań.

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

Proszenie przeglądarki o opuszczenie grupy zainteresowań

Właściciel grupy zainteresowań może poprosić o usunięcie przeglądarki z tej grupy. Inaczej mówiąc, przeglądarka jest proszona o usunięcie grupy zainteresowań z listy tych, do których należy.

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

Jeśli użytkownik wróci do witryny, w której poprosiła przeglądarkę o dodanie grupy zainteresowań, jej właściciel może wywołać funkcję navigator.leaveAdInterestGroup(), aby poprosić przeglądarkę o jej usunięcie. Kod reklamy może też wywoływać tę funkcję w przypadku jej grupy zainteresowań.

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

Grafika przedstawiająca osobę odwiedzającą witrynę z wiadomościami w przeglądarce na laptopie. Boks reklamowy w witrynie jest pusty.

Później użytkownik odwiedza witrynę sprzedającą przestrzeń reklamową – w tym przykładzie jest to witryna z wiadomościami. Witryna zawiera zasoby reklamowe, które są sprzedawane automatycznie za pomocą określania stawek w czasie rzeczywistym.

4. Aukcja reklam odbywa się w przeglądarce

Ilustracja przedstawiająca osobę przeglądającą witrynę z wiadomościami w przeglądarce na laptopie. Trwa aukcja reklam z wykorzystaniem interfejsu Protected Audience API.

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

Aukcja reklam prawdopodobnie zostanie przeprowadzona przez platformę SSP wydawcy lub przez samego wydawcę. Aukcja ma na celu wybranie najbardziej odpowiedniej reklamy dla pojedynczego dostępnego boksu reklamowego na bieżącej stronie. Aukcja bierze pod uwagę grupy zainteresowań, do których należy przeglądarka, oraz dane od kupujących przestrzeń reklamową i sprzedawców z usług klucz-wartość.

Sprzedawca przestrzeni reklamowej wysyła do przeglądarki użytkownika żądanie rozpoczęcia aukcji reklam, wywołując metodę 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ę, która prowadzi do wartości URN (urn:uuid:<something>) wskazującej wynik aukcji reklam. Wartość może zostać dekodowana przez przeglądarkę tylko po przekazaniu do chronionej ramki na potrzeby renderowania: strona wydawcy nie może sprawdzić zwycięzcy reklamy.

Skrypt decisionLogicUrl analizuje po kolei każdą reklamę wraz z powiązaną z nią stawką i metadanymi, a potem przypisuje jej liczbową ocenę pożądaną.

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' URL skryptu JavaScript workletu aukcji.
trustedScoringSignalsUrl Opcjonalnie 'https://ssp.example/scoring-signals' Adres URL zaufanego serwera sprzedawcy.
interestGroupBuyers* Wymagane ['https://dsp.example', 'https://buyer2.example', ...] Pochodzenie 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 na podstawie ustawień wydawcy, żądania reklamy kontekstowej itp.
sellerTimeout Opcjonalnie 100 Maksymalny czas działania (ms) skryptu scoreAd() sprzedawcy.
perBuyerSignals Opcjonalnie {'https://dsp.example': {...},
  'https://another-buyer.example': {...},
...}		 Sygnały kontekstowe dotyczące strony poszczególnych kupujących z ich serwera.
perBuyerTimeouts Opcjonalnie 50 Maksymalny czas działania (ms) skryptów generateBid() określonego kupującego.
componentAuctions Opcjonalnie [{'seller': 'https://www.some-other-ssp.com',
  'decisionLogicUrl': ..., ...},
  ...]		 Dodatkowe konfiguracje aukcji komponentów.

* Sprzedawca może określić interestGroupBuyers: '*', aby zezwolić na licytowanie wszystkim grupom zainteresowań. Reklamy są następnie akceptowane lub odrzucane na podstawie innych kryteriów 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 bieżącej implementacji Protected Audience. Więcej informacji znajdziesz w sekcji Uczestnicy aukcji w wyjaśnieniu dotyczącym ochrony odbiorców.

Jak wybierane są reklamy?

Kod w sekcji decisionLogicUrl (właściwość obiektu konfiguracji aukcji przekazany do runAdAuction()) musi zawierać funkcję scoreAd(). Robimy to raz dla każdej reklamy, aby określić jej celowość.

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

scoreAd() przyjmuje te argumenty: * adMetadata
Dowolne metadane dostarczone przez kupującego. * bid
Liczbowa wartość stawki. * auctionConfig
Obiekt konfiguracji aukcji został przekazany do navigator.runAdAuction(). * trustedScoringSignals
Wartości pobierane z zaufanego serwera sprzedawcy w czasie aukcji i reprezentujące opinię sprzedawcy o reklamie. * browserSignals
Obiekt utworzony przez przeglądarkę, który obejmuje informacje znane przeglądarce i weryfikacje przez skrypt aukcji sprzedawcy:

{
  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. Jednym z elementów scoreAd() jest odrzucanie reklam, które nie mogą pokonać zwycięskich reklam kontekstowych.

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

Ilustracja przedstawiająca osobę przeglądającą witrynę z wiadomościami w przeglądarce na laptopie. Trwa aukcja reklam korzystająca z Protected Audience API, a uczestnik otrzymuje dane z usługi klucz/wartość.

Sekcja Wyjaśnienie: Pobieranie danych w czasie rzeczywistym z usługi klucz/wartość w chronionej grupie odbiorców.

Podczas aukcji reklam sprzedawca przestrzeni reklamowej może uzyskać w czasie rzeczywistym dane o konkretnych kreacjach, wysyłając żądanie do usługi kluczy/wartości za pomocą argumentu właściwości trustedScoringSignalsUrl konfiguracji aukcji przekazanego do navigator.runAdAuction(), a także kluczy z właściwości renderUrl wszystkich wpisów w polach ads i adComponents we wszystkich grupach zainteresowań w aukcji.

Podobnie kupujący przestrzeni reklamowej może zażądać danych w czasie rzeczywistym z usługi klucz/wartość, używając właściwości trustedBiddingSignalsUrl i trustedBiddingSignalsKeys argumentu grupy zainteresowań przekazywanego do navigator.joinAdInterestGroup().

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

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

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

6. Wyświetlono zwycięską reklamę

Ilustracja przedstawiająca osobę przeglądającą witrynę z wiadomościami w przeglądarce na laptopie. Wyświetlana jest reklama roweru (20% taniej) z kłódką powyżej, która wskazuje, że reklama jest wyświetlana w ramce ogrodzonej.

Sekcja wyjaśniająca: Przeglądarki renderują zwycięskią reklamę

Jak pisaliśmy wcześniej: obietnica zwrócona przez runAdAuction() przechodzi do URN, który jest przekazywany do chronionej ramki do renderowania, a witryna wyświetla zwycięską reklamę.

7. Raport dotyczący wyniku aukcji

Sekcja Wyjaśnienie: Raportowanie na poziomie zdarzenia (na razie)

Wynik w raportach sprzedawcy

Sekcja Wyjaśnienie: Raporty sprzedawcy o renderowaniu

Kod JavaScript sprzedawcy podany na stronie decisionLogicUrl (zawiera też element scoreAd()) może zawierać funkcję reportResult(), która służy do raportowania wyniku aukcji.

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

Argumenty przekazywane do tej funkcji to:

  • auctionConfig
    Obiekt konfiguracji aukcji został przekazany do narzędzia navigator.runAdAuction().

  • browserSignals
    Obiekt utworzony przez przeglądarkę i dostarczający informacje o aukcji. Przykład:

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

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

Wynik w raportach dotyczących zwycięskiego licytującego

Sekcja Wyjaśnienie: Raporty kupującego dotyczące renderowania i zdarzeń reklamowych

Kod JavaScript zwycięskiego licytującego (zawierający również parametr generateBid()) może zawierać funkcję reportWin() do zgłaszania wyniku aukcji.

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

Argumenty przekazywane do tej funkcji to:

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

  • browserSignals
    Obiekt utworzony przez przeglądarkę i dostarczający informacje 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>
}

Wdrożenie raportowania tymczasowej straty/zyska

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

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

Każda z tych metod przyjmuje jeden argument: adres URL pobierany po zakończeniu aukcji. Można je wywoływać wiele razy w ustawieniach scoreAd() i generateBid(), podając różne argumenty adresu URL.

Chrome wysyła raporty o stratach/wygranych na potrzeby debugowania tylko po zakończeniu aukcji. Jeśli aukcja zostanie anulowana (np. z powodu nowej nawigacji), nie zostaną wygenerowane żadne raporty.

Te metody są domyślnie dostępne w Chrome, jeśli włączono chrome://flags/#privacy-sandbox-ads-apis. Jeśli jednak używasz Chrome z flagami wiersza poleceń, aby włączyć Protected Audience, musisz jednoznacznie włączyć te metody, dodając flagę BiddingAndScoringDebugReportingAPI. Jeśli flaga nie jest włączona, metody wciąż są dostępne, ale nie działają.

8. Raportowane kliknięcie reklamy

Ilustracja przedstawiająca osobę klikającą reklamę roweru w ramce otoczonej płotem w witrynie z wiadomościami oraz z danymi przekazywanymi sprzedawcy i kupującym.

Rejestrowane jest kliknięcie reklamy wyrenderowanej w ramce otoczonej ramką. Więcej informacji na ten temat znajdziesz w artykule Raporty o reklamach w ramkach.


Poniższy schemat przedstawia każdy etap aukcji reklam w ramach Protected Audience API:

Grafika obrazująca każdy etap aukcji reklam w ramach Protected Audience API


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

Protected Audience to pierwszy eksperyment, który został wdrożony w Chromium w ramach rodziny ofert pakietowych TURTLEDOVE.

Protected Audience jest zgodna z ogólnymi zasadami TURTLEDOVE. Część reklam online opiera się na wyświetlaniu reklamy potencjalnie zainteresowanej osobie, która wcześniej weszła w interakcję z reklamodawcą lub siecią reklamową. W przeszłości takie podejście było efektem tego, że reklamodawca rozpoznawał określoną osobę podczas przeglądania witryn internetowych, która była podstawowym problemem ochrony prywatności współczesnych użytkowników internetu.

W ramach projektu TURTLEDOVE opracujemy nowy interfejs API, który pomoże rozwiązać ten problem, a jednocześnie zapewnimy kluczowe korzyści związane z ochroną prywatności:

  • Przeglądarka, a nie reklamodawca, przechowuje informacje o tym, co według reklamodawcy interesuje użytkownika.
  • Reklamodawcy mogą wyświetlać reklamy na podstawie zainteresowań, ale nie mogą łączyć tego zainteresowania z innymi informacjami o danej osobie, a w szczególności z tym, kim jest lub którą stronę odwiedza.

Rozwiązanie Protected Audience rozwinęło się z platformy TURTLEDOVE i zestawu powiązanych propozycji modyfikacji z myślą o deweloperach korzystających z interfejsu API:

  • W SPARROW: Criteo zaproponował dodanie modelu usługi („Gatekeeper”) działającego w zaufanym środowisku wykonawczym (TEE). W ramach Protected Audience możesz w ograniczonym stopniu korzystać z TEE do wyszukiwania danych w czasie rzeczywistym i tworzenia raportów zbiorczych.
  • Oferty TERN i PARRROT opracowane przez firmę NextRoll oraz firmy Magnite opisują różne role, jakie pełnili kupujący i sprzedawcy w aukcji na urządzeniu. Na tej podstawie opiera się proces określania stawek i oceny reklam w ramach Protected Audience API.
  • Modyfikacje TURTLEDOVE na podstawie wyników i na poziomie produktu w RTB House poprawiły model anonimowości i możliwości personalizacji aukcji na urządzeniu
  • PARAKEET to propozycja firmy Microsoft dotycząca usługi reklamowej przypominającej TURTLEDOVE, która bazuje na serwerze proxy działającym w TEE między przeglądarką a dostawcami technologii reklamowych w celu anonimizacji żądań reklam i egzekwowania właściwości prywatności. W ramach Protected Audience API ten model nie jest używany. Chcemy ujednolicić interfejsy API JavaScript w modelu PARAKEET i Protected Audience, aby w przyszłości umożliwić dalsze łączenie najlepszych funkcji obu pakietów.

Protected Audience nie uniemożliwia jeszcze sieci reklamowej witryny informacji o tym, jakie reklamy widzi użytkownik. Zamierzamy z czasem zmodyfikować interfejs API, aby 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 na stronie chrome://settings/adPrivacy. Podczas wstępnych testów użytkownicy będą mogli skorzystać z tego zaawansowanego ustawienia Piaskownicy prywatności, aby zrezygnować z funkcji Protected Audience. Chrome umożliwia użytkownikom wyświetlanie listy grup zainteresowań, do których zostali dodani w odwiedzonych witrynach, oraz zarządzanie nią. Ustawienia użytkowników, podobnie jak technologie Piaskownicy prywatności, mogą ewoluować na podstawie opinii użytkowników, organów regulacyjnych i innych podmiotów.

W miarę postępów oferty Protected Audience API będziemy aktualizować ustawienia dostępne w Chrome na podstawie testów i opinii. W przyszłości planujemy udostępnienie bardziej szczegółowych ustawień do zarządzania funkcją Protected Audience i powiązanymi danymi.

Osoby wywołujące interfejs API nie mają dostępu do członkostwa w grupie, gdy użytkownicy korzystają z przeglądarki w trybie incognito, a członkostwo jest usuwane, gdy użytkownik wyczyści dane swojej witryny.



Angażuj i dziel się opiniami

Uzyskaj pomoc

Aby zadać pytanie na temat Twojej implementacji, prezentacji lub dokumentacji: * Otwórz nowy problem w repozytorium privacy-sandbox-dev-support. Pamiętaj, aby wybrać szablon problemu dla Protected Audience API. * Zgłosić problem w repozytorium kodu demonstracyjnego na GitHubie. * Aby uzyskać bardziej ogólne pytania o realizowanie przypadków użycia interfejsu API, zgłoś problem w repozytorium ofert pakietowych.

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

Otrzymuj powiadomienia

Więcej informacji

Zdjęcie: Ray Hennessy, Unsplash.