Przewodnik dla programistów interfejsu FLEDGE API

Dla kogo jest przeznaczony ten artykuł?

Ten post zawiera techniczną dokumentację obecnej wersji eksperymentalnej interfejsu Protected Audience API.

Czym jest Protected Audience?

Interfejs Protected Audience API to propozycja Piaskownicy prywatności dotycząca remarketingu i list odbiorców niestandardowych. Został on 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.

Protected Audience to pierwszy eksperyment, który zostanie wdrożony w Chromium w ramach rodziny propozycji TURTLEDOVE.

Diagram poniżej przedstawia cykl życia FLEDGE:

Ilustracja przedstawiająca przegląd wszystkich etapów cyklu życia FLEDGE
Cykl życia FLEDGE.

Jak mogę wypróbować Protected Audience?

Protected Audience – prezentacja

Przewodnik po podstawowym wdrażaniu odbiorców chronionych w witrynach reklamodawców i wydawców jest dostępny pod adresem protected-audience-demo.web.app.

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

Udział w testowaniu origin interfejsu Protected Audience

W Chrome na komputery w wersji beta 101.0.4951.26 lub nowszej udostępniliśmy test origin dotyczący trafności i pomiaru w Piaskownicy prywatności. Dotyczy on interfejsów Protected Audience API, Topics API i Attribution Reporting API.

Aby wziąć udział w testach, zarejestruj się, aby otrzymać token wersji próbnej.

Po zarejestrowaniu się w programie testów możesz korzystać z interfejsu Protected Audience JavaScript API na stronach, które udostępniają prawidłowy token testowy. Możesz na przykład poprosić przeglądarkę o dołączenie do jednej lub więcej grup zainteresowań, a potem przeprowadzić aukcję reklam, aby wybrać i wyświetlić reklamę.

Demo Protected Audience zawiera podstawowy przykład pełnego wdrożenia tej funkcji.

Podaj token testowy 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

  • Przekazując token programowo:

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

Iframe z kodem Protected Audience, np. wywołanie navigator.joinAdInterestGroup() przez właściciela grupy zainteresowań, musi zawierać token pasujący do jego pochodzenia.

Szczegóły proponowanego pierwszego testu origin Protected Audience zawiera więcej informacji o celach pierwszego testu i wyjaśnia, które funkcje są obsługiwane.

Testowanie tego interfejsu API

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

  • Włącz wszystkie interfejsy API dotyczące prywatności reklam w sekcji chrome://settings/adPrivacy
  • przez ustawienie flag w wierszu poleceń;

renderowanie reklam w elementach iframe lub fenced frames.

Reklamy mogą być renderowane w trybie <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 w celu debugowania.

Uruchom Chromium z flagami zawiera informacje o tym, jak ustawiać flagi podczas uruchamiania Chrome i innych przeglądarek opartych na Chromium z poziomu wiersza poleceń. Pełną listę flag Protected Audience znajdziesz w wyszukiwarce kodu Chromium.

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

Protected Audience jest udostępniana za pomocą flag funkcji w Chromium jako pierwszy eksperyment mający na celu przetestowanie tych funkcji propozycji Protected Audience:

  • Grupy zainteresowań: przechowywane przez przeglądarkę wraz z powiązanymi metadanymi, które służą do konfigurowania określania stawek i renderowania reklam.
  • Określanie stawek na urządzeniu przez kupujących (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 zmodyfikowanej wersji ograniczonych ramek: dostęp do sieci i rejestrowanie są dozwolone w celu wyświetlania reklam.

Więcej informacji o obsługiwanych funkcjach i ograniczeniach znajdziesz w opisie interfejsu API

Uprawnienia dotyczące grup zainteresowań

Domyślnie w bieżącej implementacji Protected Audience wywoływanie funkcji 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 dostosowanie zasad dotyczących uprawnień iframe między domenami, planujemy zablokować wywołania z iframe między domenami, jak opisano w sekcji z wyjaśnieniami.

Usługa kluczy-wartości

W ramach aukcji reklam w Protected Audience przeglądarka może uzyskać dostęp do usługi klucz-wartość, która zwraca proste pary klucz-wartość, aby przekazać nabywcy reklam informacje, np. o pozostałym budżecie kampanii. Propozycja dotycząca chronionych odbiorców wymaga, aby ten serwer „nie wykonywał żadnego rejestrowania na poziomie zdarzenia i nie miał żadnych innych efektów ubocznych na podstawie tych żądań”.

Kod usługi klucz-wartość chronionych list odbiorców jest teraz dostępny w repozytorium Piaskownicy prywatności na GitHubie. Z tej usługi mogą korzystać deweloperzy Chrome i Androida. Aktualny stan znajdziesz w poście na blogu z ogłoszeniem. Więcej informacji o usłudze kluczy/wartości Protected Audience znajdziesz w opisie interfejsu API i opisie modelu zaufania.

Do wstępnego testowania używany jest model „przynieś własny serwer”. W długim okresie firmy zajmujące się technologiami reklamowymi będą musiały używać usług klucz-wartość Protected Audience w wersji open source działających w zaufanych środowiskach wykonania do pobierania danych w czasie rzeczywistym.

Aby zapewnić ekosystemowi wystarczająco dużo czasu na przetestowanie, nie wymagamy korzystania z usług kluczy/wartości na licencji open source ani z usług TEE do czasu wycofania plików cookie innych firm. Zanim wprowadzimy tę zmianę, powiadomimy deweloperów z 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 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?

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

Jak witryny mogą kontrolować dostęp?

W przyszłości funkcja Protected Audience będzie wymagać od witryn skonfigurowania zasad dotyczących uprawnień, aby umożliwić korzystanie z tej funkcji. Dzięki temu dowolne osoby trzecie nie będą mogły korzystać z interfejsu API bez wiedzy właściciela witryny. Aby jednak ułatwić testowanie podczas pierwszego testowania origin, ten wymóg jest domyślnie pomijany. W przypadku witryn, które chcą wyraźnie wyłączyć funkcję Protected Audience w okresie testów, można użyć odpowiedniej zasady dotyczącej uprawnień, aby zablokować dostęp.

Istnieją 2 zasady dotyczące uprawnień odbiorców chronionych, które można ustawiać niezależnie:

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

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

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

Możesz wyłączyć korzystanie z interfejsów API w ramach iframe, dodając do elementu iframe atrybut allow:

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

Więcej informacji znajdziesz w sekcji Proposed First Protected Audience Origin Trial Permissions-Policy (Propozycja zasad dotyczących uprawnień w ramach pierwszej wersji testowej origin Protected Audience).

Rezygnacja użytkownika

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

  • Wyłącz funkcje próbne piaskownicy prywatności w ustawieniach Chrome: Ustawienia > Bezpieczeństwo i prywatność > Piaskownica prywatności. Informacje te są też dostępne na stronie chrome://settings/adPrivacy.
  • Wyłącz pliki cookie innych firm w ustawieniach Chrome: Ustawienia > Bezpieczeństwo i prywatność.
  • W sekcji chrome://settings/cookies Pliki cookie i inne dane witryn ustaw opcję „Blokuj pliki cookie innych firm” lub „Blokuj wszystkie pliki cookie”.
  • Używaj trybu incognito.

W artykule Protected Audience API znajdziesz więcej informacji o elementach konstrukcyjnych interfejsu API oraz o tym, jak interfejs ten pomaga osiągać cele związane z ochroną prywatności.

Debugowanie modułów Protected Audience

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

Najpierw musisz ustawić punkty graniczne za pomocą nowej kategorii w panelu Punkty graniczne odbiornika zdarzeń w panelu Źródła.

Zrzut ekranu przedstawiający Narzędzia deweloperskie w Chrome Canary, na którym zaznaczono panel Punkty przerwania detektora zdarzeń w oknie Źródła. W sekcji Worklet aukcji reklam wybrano opcję Początek fazy licytowania przez licytującego.

Gdy punkt przerwania zostanie uruchomiony, wykonanie zostanie wstrzymane przed pierwszym oświadczeniem na najwyższym poziomie skryptu workletu. Aby dotrzeć do funkcji ustalania stawek, oceniania lub raportowania, możesz użyć zwykłych punktów przełamania lub poleceń kroku.

Skrypty workletów na żywo będą też widoczne w panelu wątków.

Zrzut ekranu przedstawiający Narzędzia deweloperskie w Chrome Canary, w którym zaznaczono panel Wątek w panelu Źródła, pokazujący bieżący skrypt workleta, który został wstrzymany.

Ponieważ niektóre worklety mogą działać równolegle, wiele wątków może mieć stan „Wstrzymane”. Możesz przełączać się między wątkami, a także wznawiać ich działanie lub dokładniej je analizować.

Obserwowanie zdarzeń Protected Audience

Na panelu Aplikacja w Narzędziach deweloperskich w Chrome możesz obserwować zdarzenia dotyczące grupy zainteresowań i aukcji w ramach Protected Audience.

Jeśli otworzysz witrynę sklepu z demo Protected Audience w przeglądarce z włączoną funkcją Protected Audience, DevTools wyświetli informacje o zdarzeniach join.

Panel aplikacji w Narzędziach dewelopera w Chrome Canary, który zawiera informacje o zdarzeniu dołączenia do grupy zainteresowań Protected Audience.

Jeśli teraz otworzysz witrynę demo wydawcy Protected Audience w przeglądarce z włączoną funkcją Protected Audience, DevTools wyświetli informacje o zdarzeniach bid i win.

Panel aplikacji Narzędzia deweloperskie w Chrome Canary, który zawiera informacje o zdarzeniach ustalania stawek i wygranych aukcji w ramach Protected Audience API.

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 i widzi reklamę nowego roweru od tego producenta.

1. Użytkownik odwiedza stronę reklamodawcy

Ilustracja przedstawiająca osobę, która w przeglądarce na laptopie odwiedza stronę internetową producenta rowerów na zamówienie.

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

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

Ilustracja przedstawiająca osobę przeglądającą witrynę w przeglądarce na laptopie. Kod JavaScript joinAdInterestGroup() jest wykonywany w przeglądarce.

Sekcja z wyjaśnieniami: Grupy zainteresowań rejestrowane przez przeglądarki

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 dsp.example. Właściciel grupy zainteresowań (w tym przypadku platforma DSP) będzie kupującym w aukcji reklam opisanej w kroku 4. 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.

joinAdInterestGroup() wymaga uprawnień:

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

Na przykład: malicious.example nie może wywoływać funkcji joinAdInterestGroup() z uprawnieniami dsp.example bez zgody właściciela dsp.example.

Uprawnienia z witryny, która jest odwiedzana

Ten sam origin: domyślnie uprawnienia są domyślnie przyznawane wywołaniom joinAdInterestGroup() z tego samego originu co odwiedzana witryna, czyli z tego samego originu co ramka najwyższego poziomu bieżącej strony. Strony mogą używać dyrektywy join-ad-interest-group w nagłówku zasad dotyczących uprawnień Protected Audience, aby wyłączyć wywołania joinAdInterestGroup().

Inne pochodzenie: wywołanie metody joinAdInterestGroup() z innego pochodzenia niż bieżąca strona może się powieść tylko wtedy, gdy odwiedzana witryna ma ustawioną zasadę uprawnień, która zezwala na wywoływanie metody joinAdInterestGroup() z ramek iframe z innych źródeł.

Uprawnienia właściciela grupy zainteresowań

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

Proponujemy, aby usługa joinAdInterestGroup() mogła działać na stronie lub w ramce iframe w domenie właściciela lub zostać przypisana do innych domen podanych na liście w adresie URL .well-known.

Używanie funkcji navigator.joinAdInterestGroup()

Oto przykład użycia 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ć rozmiaru większego niż 50 KiB, w przeciwnym razie wywołanie zakończy się niepowodzeniem. Drugi parametr określa czas trwania grupy zainteresowań, który nie może przekroczyć 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 kodu JavaScript służącego do określania stawek, który jest uruchamiany w ramach workletu.
biddingWasmHelperUrl** Opcjonalnie* 'https://dsp.example/bid/custom-bikes/bid.wasm' Adres URL kodu WebAssembly obsługiwanego przez biddingLogicUrl.
dailyUpdateUrl** Opcjonalny 'https://dsp.example/bid/custom-bikes/update' Adres URL zwracający dane w formacie JSON, aby zaktualizować atrybuty grupy zainteresowań. (zobacz Aktualizowanie grupy zainteresowań).
trustedBiddingSignalsUrl** Opcjonalny 'https://dsp.example/trusted/bidding-signals' Podstawowy adres URL żądań par klucz-wartość wysyłanych do zaufanych serwerów licytujących.
trustedBiddingSignalsKeys Opcjonalny ['key1', 'key2' ...] Klucze do żądań wysyłanych do zaufanych serwerów par klucz-wartość.
userBiddingSignals Opcjonalny {...} dodatkowe metadane, których właściciel może używać podczas określania stawek;
ads Opcjonalnie* [bikeAd1, bikeAd2, bikeAd3] Reklamy, które mogą być renderowane dla tej grupy zainteresowań.
adComponents Opcjonalny [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] Komponenty reklam składających się z kilku elementów.

* Wszystkie właściwości są opcjonalne z wyjątkiem właściwości owner i name. Właściwości biddingLogicUrl i ads są opcjonalne, ale wymagane, aby wziąć udział w aukcji. Tworzenie grupy zainteresowań bez tych właściwości może być przydatne w takich przypadkach: właściciel grupy zainteresowań może np. chcieć dodać przeglądarkę do grupy zainteresowań w kampanii, która jeszcze się nie wyświetla, lub do innego celu w przyszłości, albo może mieć tymczasowo wyczerpany budżet reklamowy.

** Adresy URL biddingLogicUrl, biddingWasmHelperUrl, dailyUpdateUrl i trustedBiddingSignalsUrl muszą mieć ten sam element domeny co właściciel. Adresy URL ads i adComponents nie mają takich ograniczeń.

Aktualizowanie atrybutów grupy zainteresowań

dailyUpdateUrl określa serwer internetowy, który zwraca dane JSON definiujące właściwości grupy zainteresowań odpowiadające obiektowi grupy zainteresowań przekazanemu do navigator.joinAdInterestGroup(). Dzięki temu właściciel grupy może okresowo aktualizować atrybuty grupy zainteresowań. W obecnej implementacji można zmienić te atrybuty:

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

Żadne pole niewymienione w pliku JSON nie zostanie zastąpione – zostaną zaktualizowane tylko pola wymienione w pliku JSON. Wywołanie funkcji navigator.joinAdInterestGroup() spowoduje zastąpienie wszystkich dotychczasowych grup zainteresowań.

Aktualizacje są wykonywane według najlepszej wiedzy i mogą się nie udać w tych przypadkach:

  • Limit czasu żądania sieci (obecnie 30 sekund).
  • Inny błąd sieci.
  • Nie udało się przeanalizować danych w formacie JSON.

Aktualizacje mogą być też anulowane, jeśli aktualizacja trwała zbyt długo, ale nie powoduje to nałożenia żadnych ograniczeń dotyczących szybkości w przypadku anulowanych (pozostałych) aktualizacji. Aktualizacje są ograniczone do maksymalnie 1 na dzień. Aktualizacje, które nie powiodły się z powodu błędów sieciowych, są ponownie próbowane po godzinie, a aktualizacje, które nie powiodły się z powodu utraty połączenia z internetem, są ponownie próbowane natychmiast po ponownym nawiązaniu połączenia.

Aktualizacje ręczne

Aktualizacje grup zainteresowań należących do źródła bieżącego ramki można wywołać ręcznie za pomocą navigator.updateAdInterestGroups(). Ograniczenie częstotliwości zapobiega zbyt częstym aktualizacjom: powtarzające się wywołania funkcji navigator.updateAdInterestGroups() nie robią nic, dopóki nie upłynie okres ograniczonego tempa (obecnie 1 dzień). Limit częstotliwości jest resetowany, gdy funkcja navigator.joinAdInterestGroup() jest ponownie wywoływana w przypadku tej samej grupy zainteresowań owner i name.

Aktualizacje automatyczne

Wszystkie grupy zainteresowań załadowane na potrzeby aukcji są aktualizowane automatycznie po zakończeniu aukcji, z uwzględnieniem tych samych limitów stawek co w przypadku aktualizacji ręcznych. W przypadku każdego właściciela, który ma co najmniej 1 grupę zainteresowań uczestniczącą w aukcji, wygląda to tak, jakby funkcja navigator.updateAdInterestGroups() była wywoływana z ramki iframe, której pochodzenie jest zgodne z tym właścicielem.

Określanie reklam w grupie zainteresowań

Obiekty ads i adComponents zawierają adres URL kreacji reklamy oraz opcjonalnie dowolne metadane, które można wykorzystać podczas określania 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ć funkcję generateBid(). Gdy sprzedawca miejsca na reklamę wywołuje funkcję navigator.runAdAuction(), funkcja generatedBid() jest wywoływana raz dla każdej grupy zainteresowań, której przeglądarka jest członkiem, jeśli właściciel grupy jest zaproszony do licytowania. Inaczej mówiąc, funkcja generateBid() jest wywoływana raz dla każdej reklamy kandydata. Sprzedawca udostępnia właściwość decisionLogicUrl w ramach parametru konfiguracji aukcji przekazywanego do navigator.runAdAuction(). Kod pod tym adresem URL musi zawierać funkcję scoreAd(), która jest wykonywana dla każdego licytującego w aukcji, aby ocenić każdą stawkę zwróconą przez funkcję generateBid().

Skrypt pod adresem biddingLogicUrl udostępniony przez kupującego miejsce reklamowe musi zawierać funkcję generateBid(). Ta funkcja jest wywoływana raz dla każdej reklamy kandydata. runAdAuction()sprawdza każdą reklamę z powiązaną stawką i metadanymi, a następnie przypisuje jej liczbową ocenę pożądania.

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 reklamę. (grupę zainteresowań można zaktualizować za pomocą dailyUpdateUrl).

  • auctionSignals
    Właściwość argumentu konfiguracja aukcji przekazanego do navigator.runAdAuction() przez sprzedawcę miejsca na reklamę. Zawiera on informacje o kontekście strony (np. rozmiar reklamy i identyfikator wydawcy), typie aukcji (aukcja pierwszej lub drugiej ceny) oraz inne metadane.

  • perBuyerSignals
    Podobnie jak w przypadku auctionSignals, argument konfiguracja aukcji przekazywany przez sprzedawcę do navigator.runAdAuction(). Może to zapewnić sygnały kontekstowe ze serwera kupującego dotyczące strony, jeśli sprzedawca jest SSP, który wykonuje wywołanie określania stawek w czasie rzeczywistym na serwerach kupujących i przekazuje odpowiedź z powrotem, lub jeśli strona wydawcy kontaktuje się bezpośrednio z serwerem kupującego. W takim przypadku kupujący może chcieć sprawdzić podpis kryptograficzny tych sygnałów w funkcji generateBid(), aby chronić się przed modyfikacją.

  • trustedBiddingSignals
    Obiekt, którego klucze to trustedBiddingSignalsKeys grupy zainteresowań, a 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. rekord, kiedy grupa wygrała wcześniej aukcję, aby umożliwić ograniczenie częstotliwości 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 używać właściwości parametrów tej 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 dotyczące reklamy, np. informacje, które sprzedawca chce poznać o tej stawce lub kreacji reklamowej. Sprzedawca korzysta z tych informacji w ramach aukcji i tworzenia kreacji reklamy. Sprzedawca używa tych informacji w ramach aukcji i logiki podejmowania decyzji.

  • bid
    Stawka liczbowa, która wejdzie do aukcji. Sprzedawca musi mieć możliwość porównywania stawek różnych kupujących, dlatego stawki muszą być podawane w jednostce wybranej przez sprzedawcę (np. „USD za tysiąc”). Jeśli stawka jest równa 0 lub ujemna, grupa zainteresowań nie bierze w ogóle udziału w aukcji sprzedawcy. Dzięki temu mechanizmowi kupujący może wdrożyć dowolne reguły reklamodawcy dotyczące tego, gdzie mogą się wyświetlać jego reklamy.

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

  • adComponents
    Opcjonalna lista maksymalnie 20 komponentów reklam złożonych z kilku elementów, pobrana z właściwości adComponents argumentu grupy zainteresowań przekazanego do navigator.joinAdInterestGroup().

Prośba o opuszczenie grupy zainteresowań

Właściciel grupy zainteresowań może poprosić o usunięcie przeglądarki z grupy. Innymi słowy, przeglądarka prosi o usunięcie 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, która poprosiła przeglądarkę o dodanie grupy zainteresowań, właściciel grupy zainteresowań może wywołać funkcję navigator.leaveAdInterestGroup(), aby poprosić przeglądarkę o usunięcie grupy zainteresowań. Kod reklamy może też wywołać tę funkcję dla grupy zainteresowań.

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

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

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

4. Aukcja reklam jest uruchamiana w przeglądarce

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

Sekcja wyjaśnień: aukcje na urządzeniu prowadzone przez sprzedawców

Aukcję reklam prawdopodobnie prowadził SSP wydawcy 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 reklamę z usług klucz-wartość.

Sprzedawca miejsca na reklamę wysyła żądanie do przeglądarki użytkownika, aby rozpocząć aukcję reklamy, wywołując 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 przekształca się w URN (urn:uuid:<something>) reprezentujący wynik aukcji reklamy. Dane te mogą być dekodowane przez przeglądarkę tylko wtedy, gdy zostaną przekazane do ramki odizolowanej na potrzeby renderowania: strona wydawcy nie może sprawdzić reklamy zwycięskiej.

Skrypt decisionLogicUrl rozpatruje po kolei każdą reklamę wraz z powiązaną stawką i metadanymi, a następnie przypisuje jej liczbową ocenę pożądania.

auctionConfig miejsca zakwaterowania

Właściwość Wymagane Przykład Rola
seller Wymagane 'https://ssp.example' Kraj pochodzenia sprzedawcy.
decisionLogicUrl Wymagane 'https://ssp.example/auction-decision-logic.js' Adres URL kodu JavaScript workletu aukcji.
trustedScoringSignalsUrl Opcjonalny '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órych poproszono o ustawienie stawki na aukcji.
auctionSignals Opcjonalny {...} informacje o kontekście strony, typie aukcji itp.
sellerSignals Opcjonalny {...} informacje na podstawie ustawień wydawcy, żądanie reklamy kontekstowej itp.
sellerTimeout Opcjonalny 100 Maksymalny czas działania (ms) skryptu scoreAd() sprzedawcy.
perBuyerSignals Opcjonalny {'https://dsp.example': {...},
  'https://another-buyer.example': {...},
...}		 sygnały kontekstowe dotyczące strony każdego konkretnego kupującego z jego serwera;
perBuyerTimeouts Opcjonalny 50 Maksymalny czas działania (ms) skryptów generateBid() konkretnego kupującego.
componentAuctions Opcjonalny [{'seller': 'https://www.some-other-ssp.com',
  'decisionLogicUrl': ..., ...},
  ...]		 dodatkowe konfiguracje aukcji komponentów.

* Sprzedawca może określić wartość interestGroupBuyers: '*', aby zezwolić wszystkim grupom zainteresowań na licytowanie. 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 sprawdzić kreacje reklamy, aby potwierdzić zgodność z jego zasadami.

** additionalBids nie jest obsługiwana w bieżącej implementacji Protected Audience. Aby dowiedzieć się więcej, zapoznaj się z sekcją Uczestnicy aukcji w artykule Protected Audience.

Jak wybierane są reklamy?

Kod w miejscu decisionLogicUrl (właściwość obiektu konfiguracji aukcji przekazana do runAdAuction()) musi zawierać funkcję scoreAd(). Jest ona wykonywana raz w przypadku każdej reklamy w celu określenia jej atrakcyjności.

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

Funkcja scoreAd() przyjmuje te argumenty:

  • adMetadata
    dowolne metadane udostępnione przez kupującego.
  • bid
    Wartość liczbowa stawki.
  • auctionConfig
    Obiekt konfiguracji aukcji przekazany do navigator.runAdAuction().
  • trustedScoringSignals
    Wartości pobierane w momencie aukcji z zaufanego serwera sprzedawcy, które reprezentują jego opinię na temat reklamy.
  • browserSignals
    Obiekt utworzony przez przeglądarkę, zawierający informacje, które zna przeglądarka i które skrypt aukcji sprzedawcy może chcieć 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ęścią logiki scoreAd() jest odrzucanie reklam, które nie mogą pokonać zwycięzcy kontekstowego.

5. Sprzedawca i kupujący biorący udział w programie otrzymują dane w czasie rzeczywistym z usługi Key/Value.

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

Sekcja z informacjami: pobieranie danych w czasie rzeczywistym z usługi Protected Audience Key/Value.

Podczas aukcji reklam sprzedawca miejsca reklamowego może uzyskiwać dane o konkretnych kreacjach reklamowych w czasie rzeczywistym, wysyłając żądanie do usługi klucz-wartość, używając argumentu trustedScoringSignalsUrl właściwości konfiguracji aukcji przekazanego do navigator.runAdAuction(), wraz z kluczami z właściwości renderUrl wszystkich wpisów w polach ads i adComponents wszystkich grup zainteresowań w aukcji.

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

Gdy wywołana zostanie metoda runAdAuction(), przeglądarka wysyła żądanie do zaufanych serwerów każdego kupującego reklamę. 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

Ilustracja przedstawiająca osobę przeglądającą witrynę z wiadomościami w przeglądarce na laptopie Wyświetla się reklama roweru (20% zniżki) z ikoną kłódki, która wskazuje, że reklama jest wyświetlana w odizolowanym obramowaniu.

Sekcja z tłumaczeniem: Przeglądarki renderują zwycięską reklamę

Jak już wspomnieliśmy, obietnica zwracana przez runAdAuction() jest rozwiązywana do URN, który jest przekazywany do ramki zabezpieczonej w celu renderowania, a witryna wyświetla reklamę zwycięską.

7. Wynik aukcji jest zgłaszany

Sekcja wyjaśnień: raportowanie na poziomie zdarzenia (obecnie)

Wynik zgłoszenia od sprzedawcy

Sekcja wyjaśnień: Zgłoszenia sprzedawcy dotyczące Render

Kod JavaScript sprzedawcy podany w pliku decisionLogicUrl (który zawiera też kod scoreAd()) może zawierać funkcję reportResult(), która raportuje wynik aukcji.

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

Argumenty przekazywane do tej funkcji to:

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

  • browserSignals
    Obiekt utworzony przez przeglądarkę, który zawiera informacje o aukcji. Na przykład:

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

Wartość zwracana przez tę funkcję jest używana jako argument sellerSignals funkcji reportWin() zwycięskiego oferenta.

Wynik raportu zwycięskiego oferenta

Sekcja z tłumaczeniem: raportowanie kupującego o zdarzeniach renderowania i reklam

Kod JavaScript zwycięzcy aukcji (który zawiera też funkcję generateBid()) może zawierać funkcję reportWin(), która przekazuje wynik aukcji.

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

Argumenty przekazywane do tej funkcji to:

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

  • browserSignals
    Obiekt utworzony przez przeglądarkę, który zawiera informacje o aukcji. Na 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>
}

Tymczasowa implementacja raportowania wygranych i przegranych

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

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

Każda z tych metod przyjmuje 1 argument: adres URL do pobrania po zakończeniu aukcji. Można je wywoływać wielokrotnie, zarówno w funkcji scoreAd(), jak i generateBid(), z różnymi argumentami adresu URL.

Chrome wysyła raporty debugowania o wygrywaniu i przegrywaniu tylko wtedy, gdy aukcja została zakończona. Jeśli aukcja zostanie anulowana (np. z powodu nowej nawigacji), nie zostaną wygenerowane żadne raporty.

Te metody są domyślnie dostępne w Chrome. Aby móc testować metody, włącz wszystkie interfejsy API dotyczące prywatności w reklamach w sekcji chrome://settings/adPrivacy. Jeśli używasz Chrome z flagami wiersza poleceń, aby włączyć Protected Audience, musisz wyraźnie włączyć te metody, dodając flagę BiddingAndScoringDebugReportingAPI. Jeśli flaga nie jest włączona, metody są nadal dostępne, ale nie robią nic.

8. Zgłoszono kliknięcie reklamy

Ilustracja przedstawiająca osobę, która klika reklamę roweru w ramce na stronie internetowej z wiadomościami. Dane z raportu są przesył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.


Na schemacie poniżej przedstawiono poszczególne etapy aukcji reklamowej w przypadku Protected Audience:

Ilustracja przedstawiająca przegląd poszczególnych etapów aukcji reklamy z Protected Audience API


Czym różnią się Protected Audience i TURTLEDOVE?

Protected Audience to pierwszy eksperyment, który zostanie wdrożony w Chromium w ramach rodziny propozycji TURTLEDOVE.

Protected Audience działa zgodnie z ogólnymi zasadami TURTLEDOVE. Niektóre reklamy online wyświetlają się potencjalnie zainteresowanym osobom, które weszły wcześniej w interakcję z reklamodawcą lub siecią reklamową. W przeszłości reklamodawca rozpoznawał daną osobę, gdy przeglądała ona strony internetowe, 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 zastosowania, a jednocześnie zapewnienie kluczowych ulepszeń w zakresie ochrony prywatności:

  • Informacje o tym, czym według reklamodawcy interesuje się użytkownik, przechowuje przeglądarka, a nie reklamodawca.
  • 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 jaką 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 lepszego obsługiwania programistów korzystających z interfejsu API:

  • W SPARROW: Criteo zaproponowało dodanie modelu usługi („Gatekeeper”) działającej w zaufanym środowisku wykonawczym (TEE). Lista odbiorców chronionych obejmuje bardziej ograniczone korzystanie z usług TEE, które służą do wyszukiwania danych w czasie rzeczywistym i tworzenia zbiorczych raportów.
  • W ramach 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ą przetargi reklamowe i schemat oceniania reklam w Protected Audience.
  • Zmiany w TURTLEDOVE opracowane przez RTB House w ramach modelu opartego na wynikach i modelu na poziomie produktu poprawiły model anonimowości i możliwości personalizacji aukcji na urządzeniu.
  • PARAKEET to usługa reklamowa podobna do TURTLEDOVE, która korzysta z serwera proxy działającego w trybie TEE między przeglądarką a dostawcami technologii reklamowych. Jej zadaniem jest anonimizacja żądań reklamy i przestrzeganie prywatności. Grupa odbiorców chronionych nie korzysta z tego modelu zastępowania. Dopasowujemy interfejsy JavaScript PARAKEET i Protected Audience, aby ułatwić dalsze prace nad połączeniem najlepszych funkcji obu tych rozwiązań.

Lista odbiorców chronionych nie zapobiega jeszcze sieci reklamowej witryny przed poznaniem, które reklamy widzi dana osoba. Spodziewamy się, że interfejs API będzie z czasem zapewniał większą ochronę prywatności.

Jaka konfiguracja przeglądarki jest dostępna?

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. Podczas wstępnych testów użytkownicy będą mogli używać tego ogólnego ustawienia Piaskownicy prywatności, aby zrezygnować z korzystania z listy odbiorców chronionych. Chrome planuje umożliwić użytkownikom wyświetlanie listy grup zainteresowań, do których zostali dodani, oraz zarządzanie nią. 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 podmiotów.

W miarę rozwoju interfejsu Protected Audience API 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 zarządzania interfejsem Protected Audience API i powiązanymi z nim danymi.

Gdy użytkownicy korzystają z przeglądania w trybie incognito, wywołujący interfejs API nie mają dostępu do członkostwa w grupach, a członkostwo jest usuwane, gdy użytkownicy usuwają dane witryny.



Zaangażowanie i przesyłanie opinii

Uzyskaj pomoc

Aby zadać pytanie dotyczące implementacji, demonstracji lub dokumentacji:

W przypadku błędów i problemów z wdrożeniem interfejsu Protected Audience API w Chrome: * Zobacz istniejące problemy zgłoszone w przypadku interfejsu API. * Prześlij nowy problem na stronie crbug.com/new.

Otrzymuj powiadomienia

Więcej informacji

Zdjęcie autorstwa Ray Hennessy z Unsplash.