Ta strona została przetłumaczona przez Cloud Translation API.

Obsługa kierowania na odbiorców niestandardowych za pomocą interfejsu Protected Audience API

Ostatnie aktualizacje

Dodaliśmy informacje o planowaniu aktualizacji niestandardowych odbiorców.
Dodaliśmy integrację raportów atrybucji z Protected Audience API
Opublikowano oś czasu funkcji Protected Audience API.
FLEDGE zostało zmienione na Protected Audience API.
Dodano propozycję przekazywania niestandardowych list odbiorców.
Usunęliśmy wymaganie k-anonimowości w przypadku adresu URL codziennej aktualizacji.

Ochrona odbiorców jest w wersji beta i można ją testować na urządzeniach publicznych.

Protected Audience API umożliwia:

Zarządzanie odbiorcami niestandardowymi na podstawie wcześniejszych działań użytkowników.
Inicjuj aukcje na urządzeniu z pomocą pojedynczego sprzedawcy lub pomocą w ramach zapośredniczenia kaskadowego.
Raporty wyświetleń ćwiczenia po wybraniu reklamy.

Na początek przeczytaj przewodnik dla programistów dotyczący Protected Audience API. Chętnie poznamy Twoją opinię, która pomoże nam rozwijać Protected Audience API.

Oś czasu

W najbliższych miesiącach wprowadzimy nowe funkcje. Dokładne daty wydania będą się różnić w zależności od funkcji, a ta tabela będzie aktualizowana o linki do dokumentacji, gdy stanie się dostępna.

Funkcja	Dostępne w podglądzie dla programistów	Dostępne w wersji beta
Raporty na poziomie zdarzenia	I kw. 2023 roku	III kw. 2023 roku
Zapośredniczenie kaskadowe,	I kw. 2023 roku	IV kw. 2023 roku
Filtrowanie reklam promujących instalacje aplikacji	II kw. 2023 roku	III kw. 2023 roku
Filtrowanie limitów wyświetleń na użytkownika	II kw. 2023 roku	III kw. 2023 roku
Przekazywanie reklam kontekstowych do procesu wyboru reklamy na potrzeby filtrowania	II kw. 2023 roku	III kw. 2023 roku
Raportowanie interakcji	II kw. 2023 roku	III kw. 2023 roku
Dołącz do przekazywania dostępu do niestandardowych odbiorców	III kw. 2023 roku	IV kw. 2023 roku
płatności bez CPM,	III kw. 2023 roku	IV kw. 2023 roku
Integracja ustalania stawek z usługami aukcyjnymi	III kw. 2023 roku	IV kw. 2023 roku
Raportowanie debugowania	III kw. 2023 roku	IV kw. 2023 roku
Integracja raportów atrybucji	Nie dotyczy	IV kw. 2023 roku
Zapośredniczenie z Otwartym ustalaniem stawek	IV kw. 2023 roku	IV kw. 2023 roku
Zarządzanie walutami	I kw. 2024 roku	II kw. 2024 roku
Integracja k-anon	Nie dotyczy	II kw. 2024 roku
Integracja raportów zbiorczych	III kw. 2024 roku	IV kw. 2024 roku

Przegląd

W przypadku reklam mobilnych reklamodawcy zwykle muszą wyświetlać reklamy zainteresowanym użytkownikom na podstawie ich wcześniejszych interakcji z aplikacją danego reklamodawcy. Na przykład deweloper aplikacji SportingGoodsApp może wyświetlać reklamy użytkownikom, którzy mają jeszcze produkty w koszyku, wyświetlając im reklamy przypominające o zakupie. W branży często stosuje się takie pojęcia jak „remarketing” czy „niestandardowe kierowanie na odbiorców”.

Obecnie takie zastosowania są zazwyczaj realizowane przez udostępnianie platformom technologii reklamowych informacji kontekstowych o sposobie wyświetlania reklamy (np. nazwy aplikacji) i informacji prywatnych, takich jak listy odbiorców. Dzięki tym informacjom reklamodawcy mogą wybierać na swoich serwerach trafne reklamy.

Interfejs Protected Audience API na Androida (dawniej FLEDGE) obejmuje te interfejsy API dla platform technologii reklamowych i reklamodawców, aby obsługiwać typowe przypadki użycia oparte na interakcjach w sposób ograniczający udostępnianie osobom trzecim identyfikatorów aplikacji oraz informacji o interakcji użytkownika w aplikacji:

Custom Audience API: Koncentruje się na abstrakcji „niestandardowych odbiorców”, która reprezentuje odbiorców oznaczonych przez reklamodawcę o podobnych zamiarach. Informacje o odbiorcach są przechowywane na urządzeniu i można je powiązać z odpowiednimi reklamami kandydującymi do ich wyświetlenia oraz z dowolnymi metadanymi, np. sygnałami dotyczącymi określania stawek. Te informacje mogą służyć do określania stawek reklamodawcy oraz filtrowania i renderowania reklam.
Interfejs Ad Selection API: zapewnia platformę, która zarządza przepływami pracy platform technologii reklamowych, które wykorzystują sygnały z urządzenia do określenia „zwycięskiej” reklamy na podstawie danych o reklamach kandydujących zapisanych lokalnie i przetwarzania dodatkowych reklam kandydujących, które platforma technologii reklamowych zwraca na urządzenie.

Wykres blokowy przedstawiający proces niestandardowego zarządzania odbiorcami i wyboru reklam w Piaskownicy prywatności na urządzeniach z Androidem.

Ogólnie integracja działa w ten sposób:

SportingGoodsApp chce przypomnieć swoim użytkownikom, by kupili produkty pozostawione w koszyku, jeśli nie dokonają zakupu w ciągu 2 dni. SportingGoodsApp korzysta z interfejsu Custom Audience API, aby dodać użytkownika do listy odbiorców „Produkty w koszyku”. Platforma zarządza listą odbiorców i przechowuje ją na urządzeniu, co ogranicza udostępnianie jej osobom trzecim. SportingGoodsApp współpracuje z platformą technologii reklamowej, by wyświetlać reklamy użytkownikom z listy odbiorców. Platforma technologii reklamowych zarządza metadanymi list odbiorców i udostępnia reklamy kandydujące, które są udostępniane procesowi wyboru reklam do rozważenia. Platformę można skonfigurować tak, aby okresowo pobierała w tle zaktualizowane reklamy oparte na odbiorcach. Dzięki temu lista reklam kandydatów do kierowania na odbiorców jest zawsze aktualna i niezwiązana z żądaniami wysyłanymi do serwerów reklamowych firm zewnętrznych w momencie wystąpienia możliwości wyświetlenia reklamy (tj. w ramach kontekstowego żądania reklamy).
Gdy użytkownik gra w FrisbeeGame na tym samym urządzeniu, może zobaczyć reklamę przypominającą o dokończeniu zakupu przedmiotów pozostawionych w koszyku na zakupy SportingGoodsApp. Aby to zrobić, FrisbeeGame (ze zintegrowanym pakietem SDK do wyświetlania reklam) wywołuje interfejs Ad Selection API, aby wybrać zwycięską reklamę dla użytkownika na podstawie dowolnej listy odbiorców, do której należy (w tym przykładzie będzie to niestandardowa lista odbiorców „produkty w koszyku” utworzona przez SportingGoodsApp). Proces wyboru reklamy można skonfigurować tak, aby uwzględniał reklamy pobrane z serwerów platform technologii reklamowych, a także reklamy wyświetlane na urządzeniu powiązane z niestandardowymi odbiorcami i inne sygnały z urządzenia. Proces ten można dostosować za pomocą platformy technologii reklamowej i pakietu SDK do wyświetlania reklam, stosując ustalanie stawek niestandardowych i metodę oceniania, aby osiągnąć odpowiednie cele reklamowe. Dzięki temu procesowi doboru reklam będą wykorzystywane dane o zainteresowaniach użytkownika lub jego interakcjach z aplikacjami, jednocześnie ograniczając udostępnianie tych danych osobom trzecim.
Aplikacja do wyświetlania reklam lub pakiet SDK platformy technologii reklamowych renderuje wybraną reklamę.
Platforma umożliwia raportowanie wyświetleń i wyników wyboru reklamy. Ta funkcja raportowania jest uzupełnieniem interfejsu Attribution Reporting API. Platformy technologii reklamowych mogą dostosowywać się do swoich potrzeb w zakresie raportowania.

Dostęp do interfejsów Protected Audience API na Androida

Platformy technologii reklamowych muszą się zarejestrować, aby uzyskać dostęp do interfejsu Protected Audience API. Więcej informacji znajdziesz w artykule Rejestrowanie konta Piaskownicy prywatności.

Zarządzanie niestandardowymi odbiorcami

Niestandardowa lista odbiorców

Niestandardowa lista odbiorców reprezentuje grupę użytkowników określoną przez reklamodawcę o wspólnych zamiarach lub zainteresowaniach. Aplikacja lub pakiet SDK może używać niestandardowej listy odbiorców, aby wskazać konkretnych odbiorców, na przykład takich, którzy „pozostali produkty w koszyku” lub „ukończyli poziom dla początkujących”. Platforma obsługuje i przechowuje informacje o odbiorcach lokalnie na urządzeniu, ale nie podaje, do jakich niestandardowych odbiorców należy użytkownik. Niestandardowe listy odbiorców różnią się od grup zainteresowań w ramach Protected Audience API w Chrome i nie można ich udostępniać w internecie ani w aplikacjach. Pomaga to ograniczyć udostępnianie informacji o użytkownikach.

Aplikacja reklamodawcy lub zintegrowany pakiet SDK może join do niestandardowej listy odbiorców lub ją opuścić na podstawie na przykład zaangażowania użytkownika w aplikacji.

Metadane niestandardowych odbiorców

Każda niestandardowa lista odbiorców zawiera te metadane:

Właściciel: nazwa pakietu aplikacji będącej właścicielem. Jest domyślnie ustawiona na nazwę pakietu aplikacji wywołującej.
Kupujący: sieć reklamowa kupującego, która zarządza reklamami dla tej niestandardowej grupy odbiorców. Kupujący reprezentuje też stronę, która może uzyskiwać dostęp do niestandardowej listy odbiorców i pobierać istotne informacje o reklamie. Kupujący jest określony zgodnie z formatem eTLD+1.
Nazwa:dowolna nazwa lub identyfikator niestandardowych odbiorców, np. „osoby, które porzuciły koszyk”. Można go wykorzystać np. jako jedno z kryteriów kierowania w kampaniach reklamowych reklamodawcy lub ciąg zapytania w adresie URL do pobierania kodu ustalania stawek.
Czas aktywacji i okres ważności: te pola określają przedział czasu, kiedy ta niestandardowa lista odbiorców zacznie obowiązywać. Platforma wykorzystuje te informacje, aby wycofać członkostwo z grupy niestandardowych odbiorców. Okres ważności nie może przekraczać maksymalnego okresu, aby ograniczyć czas trwania niestandardowej listy odbiorców.
URL z codzienną aktualizacją: adres URL używany przez platformę do cyklicznego pobierania reklam kandydujących i innych metadanych zdefiniowanych w polach „Sygnały dotyczące określania stawek przez użytkownika” i „Zaufane sygnały dotyczące określania stawek”. Więcej informacji znajdziesz w sekcji o pobieraniu reklam kandydujących do niestandardowych list odbiorców.
Sygnały dotyczące określania stawek przez użytkowników: sygnały specyficzne dla platformy technologii reklamowej na potrzeby określania stawek za reklamy remarketingowe. Przykłady sygnałów: przybliżona lokalizacja użytkownika, preferowany region itp.
Zaufane dane dotyczące określania stawek: do pobierania i oceniania reklam platformy technologii reklamowych wykorzystują dane w czasie rzeczywistym. Budżet może się np. wyczerpać i trzeba natychmiast przestać się wyświetlać. Technologie reklamowe mogą zdefiniować punkt końcowy adresu URL, z którego można pobrać dane w czasie rzeczywistym, oraz zestaw kluczy, które mają być wyszukiwane w czasie rzeczywistym. Serwerem obsługującym to żądanie będzie zaufany serwer zarządzany przez platformę technologii reklamowych.
Adres URL logiki określania stawek: adres URL używany przez platformę do pobierania kodu określania stawek z platformy DSP. Platforma wykonuje ten krok po rozpoczęciu aukcji reklam.
Reklamy: lista reklam kandydujących do niestandardowej listy odbiorców. Obejmują one metadane reklamy związane z daną platformą technologii reklamowych oraz adres URL służący do renderowania reklamy. Po zainicjowaniu aukcji dla niestandardowych odbiorców lista metadanych reklamy będzie brana pod uwagę. Ta lista reklam będzie odświeżana z użyciem punktu końcowego adresu URL codziennej aktualizacji, gdy będzie to możliwe. Ze względu na ograniczenia zasobów urządzeń mobilnych liczba reklam, które można przechowywać na liście odbiorców niestandardowych, jest ograniczona.

Przekazywanie niestandardowych list odbiorców

Tradycyjne definiowanie i konfiguracja niestandardowych list odbiorców zwykle opierają się na technologiach po stronie serwera i integracji obsługiwanych przez technologie reklamowe we współpracy z klientami i partnerami z agencji i reklamodawców. Protected Audience API umożliwia definiowanie i konfigurowanie niestandardowych list odbiorców przy jednoczesnej ochronie prywatności użytkowników. Aby dołączyć do niestandardowej listy odbiorców, kupujący korzystający z technologii reklamowych kupujących, którzy nie korzystają z pakietów SDK w aplikacjach, muszą współpracować z technologiami reklamowymi działającymi na urządzeniu, np. z partnerami pomiarowymi (MMP) i platformami dostawców (SSP). Interfejs Protected Audience API ma pomagać w obsłudze tych pakietów SDK przez zapewnienie elastycznych rozwiązań do zarządzania niestandardowymi odbiorcami, umożliwiając na urządzeniu wywoływanie tworzenia niestandardowych list odbiorców w imieniu kupujących. Ten proces nazywa się przekazywaniem niestandardowych list odbiorców. Aby skonfigurować przekazywanie dostępu do niestandardowych list odbiorców, wykonaj te czynności:

Dołącz do grupy niestandardowych odbiorców

Do niestandardowych grup odbiorców możesz dołączyć na 2 sposoby:

joinCustomAudience()

Aplikacja lub pakiet SDK może poprosić o dołączenie do niestandardowej listy odbiorców, wywołując joinCustomAudience() po utworzeniu wystąpienia obiektu CustomAudience z oczekiwanymi parametrami. Oto przykładowy fragment kodu:

CustomAudience audience = new CustomAudience(
    Buyer = "example-dsp.com",
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    DailyUpdateURL = Uri.parse("https://..."),
    UserBiddingSignals = new JSONObject("{...}"),
    TrustedBiddingURL = Uri.parse("https://..."),
    TrustedBiddingKeys = {'key1","key2", ...,"key n"},
    BiddingLogicURL =  Uri.parse("https://..."),
    Ads = [new AdData(renderUrl = Uri.parse("https://..."),
           metadata = new JSONObject("{...}"), ...];

// Invoke ad services API to join a custom audience.
joinCustomAudience(audience);

fetchAndJoinCustomAudience()

Aplikacja lub pakiet SDK może poprosić o dołączenie do niestandardowej listy odbiorców w imieniu technologii reklamowej, która nie jest obecna na urządzeniu, wywołując funkcję fetchAndJoinCustomAudience() z oczekiwanymi parametrami, jak w tym przykładzie:

FetchAndJoinCustomAudienceRequest fetchRequest = new FetchAndJoinCustomAudienceRequest(
    // Example: Optional verification token passed inside the fetch URL
    FetchURI = Uri.parse("https://example-dsp.com/...?mytoken=arbitrary1234"),
    // All the following parameters are optional
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    UserBiddingSignals = new JSONObject("{...}")
);

fetchAndJoinCustomAudience(fetchRequest);

Punkt końcowy URL, który należy do kupującego, odpowiada w treści odpowiedzi za pomocą obiektu JSON CustomAudience. Pola kupującego i właściciela w przypadku niestandardowej listy odbiorców są ignorowane (i automatycznie wypełniane przez interfejs API). Ten interfejs wymusza też, aby URL z codzienną aktualizacją był zgodny z adresem eTLD+1 kupującego.

{
 "name": "running-shoes",
 "activation_time": 1680603133000,
 "expiration_time": 1680803133000,
 "user_bidding_signals" : {"signal1": "value"},
 "trusted_bidding_data": {
    "trusted_bidding_uri": "https://example-dsp.com/.."
    "trusted_bidding_keys": ["k1", "k2"],
 },
 "bidding_logic_uri": "https://example-dsp.com/...",
 "daily_update_uri": "https://example-dsp.com/...",
 "ads": [
   {
     "render_uri": "https://example-dsp.com/...",
     "metadata": {},
     "ad_filters": {
       "frequency_cap": {
         "win": [
           {
             "ad_counter_key": 1,
             "max_count": 2,
             "interval_in_seconds": 60
           },
         ],
         "view": [
           {
             "ad_counter_key": 2,
             "max_count": 10,
             "interval_in_seconds": 3600
           },
         ]
       },
       "app_install": {
         "package_names": [
           "package.name.one",
           "package.name.two", ...
         ]
       }
     }
   },
   ...
 ]
}

Interfejs API fetchAndJoinCustomAudience() określa tożsamość kupującego na podstawie eTLD+1 domeny fetchUri. Tożsamość kupującego CustomAudience służy do przeprowadzania tych samych testów rejestracji i autoryzacji aplikacji co joinCustomAudience(). Nie można jej zmienić w odpowiedzi na pobranie. Właścicielem listy CustomAudience jest nazwa pakietu aplikacji wywołującej. Nie ma żadnej innej weryfikacji domeny fetchUri niż eTLD+1, w szczególności nie ma kontroli k-anon. Interfejs API fetchAndJoinCustomAudience() wysyła żądanie HTTP GET do fetchUri i oczekuje obiektu JSON reprezentującego odbiorców niestandardowych. Do odpowiedzi są stosowane te same obowiązkowe, opcjonalne ograniczenia i wartości domyślne do pól niestandardowego obiektu odbiorców. Aktualne wymagania i ograniczenia znajdziesz w naszym przewodniku dla programistów.

Każda odpowiedź z błędem HTTP od kupującego powoduje błąd fetchAndJoinCustomAudience. W szczególności odpowiedź stanu HTTP 429 (Za dużo żądań) blokuje żądania z bieżącej aplikacji na zdefiniowany okres. Wywołanie interfejsu API zakończy się też niepowodzeniem, jeśli odpowiedź kupującego jest nieprawidłowa. Błędy są zgłaszane do elementu wywołującego interfejs API, który odpowiada za ponowienie próby z powodu tymczasowych awarii (np. serwer nie odpowiada) lub obsługi trwałych awarii (takich jak błędy weryfikacji danych lub inne nieprzejściowe błędy komunikacji z serwerem).

Obiekt CustomAudienceFetchRequest pozwala wywołującemu interfejs API zdefiniować niektóre informacje o niestandardowych odbiorcach za pomocą opcjonalnych właściwości pokazanych w przykładzie powyżej. Jeśli te wartości są ustawione w żądaniu, nie można ich zastąpić odpowiedzią kupującego odebraną przez platformę. Protected Audience API ignoruje pola w odpowiedzi. Jeśli nie są one ustawione w żądaniu, musisz je ustawić w odpowiedzi, ponieważ te pola są niezbędne do utworzenia niestandardowej listy odbiorców. Reprezentacja w formacie JSON zawartości wywołania CustomAudience częściowo zdefiniowana przez element wywołujący interfejs API znajduje się w żądaniu GET wysyłanym do fetchUri w specjalnym nagłówku X-CUSTOM-AUDIENCE-DATA. Wielkość zserializowanej danych określonych dla niestandardowych odbiorców jest ograniczona do 8 KB. Jeśli rozmiar przekracza limit, wywołanie interfejsu API fetchAndJoinCustomAudience kończy się niepowodzeniem.

Brak kontroli k-anon umożliwia użycie fetchUri do weryfikacji kupującego i udostępniania informacji między kupującym a pakietem SDK. Aby ułatwić weryfikację niestandardowych odbiorców, kupujący może podać token weryfikacyjny. Pakiet SDK na urządzeniu powinien zawierać ten token w zasadzie fetchUri, aby punkt końcowy hostowany przez kupującego mógł pobierać zawartość niestandardowej listy odbiorców oraz używać tokena weryfikacyjnego do sprawdzania, czy operacja fetchAndJoinCustomAudience() odpowiada kupującemu i pochodzi od zaufanego partnera na urządzeniu. Aby udostępnić informacje, kupujący może wyrazić zgodę na element wywołujący na urządzeniu, że niektóre informacje używane do utworzenia niestandardowej grupy odbiorców zostaną dodane do funkcji fetchUri jako parametry zapytania. Dzięki temu kupujący może skontrolować wywołania i wykryć, czy token weryfikacyjny nie został użyty przez szkodliwą technologię reklamową do utworzenia kilku różnych niestandardowych list odbiorców.

Uwaga na temat definicji i miejsca na dane tokena weryfikacyjnego

Token weryfikacyjny nie jest używany do żadnych celów przez interfejs Protected Audience API i jest opcjonalny.
- Kupujący może użyć tokena weryfikacyjnego, aby upewnić się, że tworzone listy odbiorców są tworzone w jego imieniu.
- Oferta pakietowa Protected Audience API nie określa ani formatu tokena weryfikacyjnego, ani sposobu, w jaki kupujący przenosi token weryfikacyjny do wywołującego. Na przykład token weryfikacyjny może być wstępnie wczytywany w pakiecie SDK lub backendzie właściciela albo może być pobierany w czasie rzeczywistym przez pakiet SDK właściciela z serwera kupującego.

Opuść grupę odbiorców niestandardowych

Właściciel grupy odbiorców niestandardowych może ją opuścić, wywołując funkcję leaveCustomAudience(), jak widać na poniższym fragmencie kodu:

// Invoke ad services API to leave a custom audience.
leaveCustomAudience(buyer, name);

Aby ograniczyć wykorzystanie miejsca na dane i innych zasobów urządzenia, listy niestandardowych odbiorców wygasają i są usuwane ze sklepu na urządzeniu po upływie określonego czasu. Wartość domyślna jest do ustalenia. Właściciel może zastąpić wartość domyślną.

Kontrola użytkowników

Propozycja ma na celu zapewnienie użytkownikom widoczności listy zainstalowanych aplikacji, które mają utworzoną co najmniej 1 listę odbiorców niestandardowych
Użytkownicy mogą usuwać aplikacje z tej listy. Usunięcie spowoduje usunięcie wszystkich niestandardowych list odbiorców powiązanych z aplikacjami, a aplikacje nie będą mogły dołączać do nowych niestandardowych list odbiorców.
Użytkownicy mogą całkowicie zresetować Protected Audience API. W takim przypadku wszystkie niestandardowe listy odbiorców znajdujące się na urządzeniu zostaną wyczyszczone.
Użytkownicy mogą całkowicie zrezygnować z Piaskownicy prywatności na urządzeniach z Androidem, w tym z interfejsu Protected Audience API. Jeśli użytkownik zrezygnował z Piaskownicy prywatności, interfejs Protected Audience API zakończy się niepowodzeniem.

Prace nad tą funkcją wciąż trwają. Szczegóły zostaną uwzględnione w kolejnej aktualizacji.

Zaplanowane aktualizacje

Opisane wcześniej rozwiązania wymagają, aby pakiet SDK aplikacji lub AdTech SDK wywoływał interfejsy API, gdy aplikacja działa na pierwszym planie, i przekazywał pełne właściwości niestandardowych odbiorców – bezpośrednio lub przez przekazanie dostępu. Reklamodawcy i dostawcy technologii reklamowych nie zawsze mogą jednak w czasie rzeczywistym określić, do jakich odbiorców należy użytkownik, gdy korzysta z aplikacji.

Aby to ułatwić, technologie reklamowe mogą wywoływać interfejs API scheduleCustomAudienceUpdate(). Ten interfejs API pozwala elementowi wywołującemu określić opóźnienie wykonania wywołania interfejsu API, co zapewnia dodatkowy czas na przetworzenie zdarzeń na poziomie aplikacji i określenie, z których Protected Audience API użytkownik powinien dołączyć lub z których powinien zostać usunięty.

/**
* API To schedule delayed update events for Custom Audience
*
* @param delayedCustomUpdates List of Delayed Update events that trigger a
* call to DSP endpoint provided inside the DelayedCustomUpdate object
*/

public void scheduleCustomAudienceUpdates(
    @NonNull DelayedCustomUpdate delayedCustomAudienceUpdate,
    @NonNull @CallBackExecutor Executor executor,
    @NonNull AdServicesOutcomeReceiver<Object, Exception> receiver)

DelayedCustomAudienceUpdate

public final class DelayedCustomAudienceUpdate {
    // Required Field
    @NonNull public Uri getUpdateUri() {
    return mUpdateUri;
  }

    // Required Field
    @NonNull public Duration getMinDelay() {
    return mMinDelay;
  }

    //  Required Field
    @NonNull public List<PartialCustomAudience> getPartialCustomAudiences() {
    return mPartialCustomAudiences;
  }
}

DelayedCustomAudienceUpdate zawiera informacje potrzebne do zarejestrowania opóźnionego zadania, które ma działać na platformie. Po upływie określonego opóźnienia zadanie w tle będzie okresowo działać i wysyłać żądania. DelayedCustomAudienceUpdate może zawierać te informacje:

UpdateUri: punkt końcowy identyfikatora URI, do którego wysyłane jest wywołanie GET w celu pobrania aktualizacji. Tożsamość kupującego jest wywnioskowana z domeny eTLD+1 i nie musi być wyraźnie określona. Nie można jej zmienić w odpowiedzi na aktualizację. Zwrócone żądanie GET oczekuje obiektu JSON zawierającego listę obiektów customAudience.
DelayTime: czas oznacza opóźnienie od momentu wywołania wywołania interfejsu API scheduleCustomAudienceUpdate() do zaplanowania aktualizacji.

PartialCustomAudience: interfejs API umożliwia pakietowi SDK na urządzeniu wysyłanie listy częściowo utworzonych niestandardowych list odbiorców. Dzięki temu pakiety SDK w aplikacji mogą pełnić podwójną rolę – od pełnej kontroli po częściową kontrolę nad zarządzaniem niestandardowymi odbiorcami na podstawie współpracy z platformami DSP.
- Zapewnia to również zgodność tego interfejsu API z interfejsem API fetchAndJoinCustomAudience(), który umożliwia udostępnianie podobnych informacji.

Uprawnienia aplikacji i kontrola nad nimi

Oferta ma zapewnić aplikacjom kontrolę nad niestandardowymi odbiorcami:

Aplikacja może zarządzać powiązaniami z niestandardowymi odbiorcami.
Aplikacja może przyznać zewnętrznym platformom technologii reklamowych uprawnienia do zarządzania niestandardowymi odbiorcami w jej imieniu.

Prace nad tą funkcją wciąż trwają. Szczegóły zostaną uwzględnione w kolejnej aktualizacji.

Kontrola platformy technologii reklamowych

Propozycja ta przedstawia sposoby, w jakie technologie reklamowe mogą kontrolować odbiorców niestandardowych:

Specjaliści ds. technologii reklamowych rejestrują się w Piaskownicy prywatności i podają domenę eTLD+1, która pasuje do wszystkich adresów URL niestandardowych odbiorców.
Specjaliści ds. technologii reklamowych mogą współpracować z aplikacjami lub pakietami SDK, aby dostarczać tokeny weryfikacyjne używane do weryfikowania tworzenia niestandardowych list odbiorców. Po przekazaniu tego procesu partnerowi można skonfigurować tworzenie niestandardowych list odbiorców tak, aby wymagało potwierdzenia przez zespół technologii reklamowych.
Technologia reklamowa może wyłączyć wywołania funkcji joinCustomAudience w jej imieniu i zezwolić interfejsowi API fetchAndJoinCustomAudience na włączenie wszystkich wywołań niestandardowych list odbiorców. Ustawienie można zaktualizować podczas rejestracji w Piaskownicy prywatności. Pamiętaj, że to ustawienie zezwala albo na wszystkie technologie reklamowe, albo na żadną. Ze względu na ograniczenia platformy uprawnienia do przekazywania dostępu nie mogą dotyczyć poszczególnych technologii reklamowych.

Odpowiedź dotycząca reklam i metadanych kandydatów

Reklamy i metadane kandydatów zwracane z platformy po stronie kupującego powinny zawierać te pola:

Metadane: metadane reklam dotyczących kupującego związane z technologią reklamową. Mogą to być na przykład informacje o kampanii reklamowej i kryteriach kierowania, takich jak lokalizacja i język.
URL renderowania: punkt końcowy renderowania kreacji reklamy.
Filtrowanie: opcjonalne informacje potrzebne interfejsowi Protected Audience API do filtrowania reklam na podstawie danych z urządzenia. Więcej informacji znajdziesz w sekcji na temat logiki filtrowania po stronie kupującego.

Proces wyboru reklamy

Ta propozycja ma na celu poprawę ochrony prywatności przez wprowadzenie interfejsu Ad Selection API, który administruje przeprowadzaniem aukcji na platformach technologii reklamowych.

Obecnie platformy technologii reklamowych ustalają stawki i wybierają reklamy wyłącznie na swoich serwerach. W ramach tej oferty dostęp do niestandardowych list odbiorców i innych poufnych sygnałów użytkownika, takich jak informacje o dostępnych zainstalowanych pakietach, będzie dostępny tylko przez interfejs Ad Selection API. Dodatkowo na potrzeby remarketingu, reklamy mogą być pobierane z innego zakresu (tj. nie w kontekście, w którym będą wyświetlane). Platformy z branży technologii reklamowych będą musiały przygotować się do wdrożenia i wykonania na urządzeniu niektórych elementów logiki procesu wyboru reklam i aukcji. Platformy technologii reklamowych mogą rozważyć następujące zmiany w procesie wyboru reklam:

Jeśli informacje o zainstalowanym pakiecie nie są dostępne na serwerze, platformy technologii reklamowych mogą chcieć odesłać wiele reklam kontekstowych z powrotem do urządzenia i uruchomić proces wyboru reklamy, aby umożliwić filtrowanie na podstawie instalacji aplikacji i maksymalizację szans na wyświetlenie odpowiedniej reklamy.
Reklamy remarketingowe są pobierane poza zakres, więc może zaistnieć konieczność zaktualizowania obecnych modeli ustalania stawek. Platformy technologii reklamowych mogą zechcieć utworzyć podmodele ustalania stawek (implementacja może opierać się na modelu 2 wieży), który może osobno pracować nad funkcjami reklam i sygnałami kontekstowymi oraz łączyć dane wyjściowe modelu podrzędnego na urządzeniu, aby prognozować stawki. Dla każdej możliwości reklamy mogą to być aukcje po stronie serwera oraz aukcje.

Takie podejście umożliwia podejmowanie decyzji o wyborze reklam na podstawie danych o interakcjach z aplikacją użytkownika, ograniczając udostępnianie tych danych osobom trzecim.

Wykres ciągły, który pokazuje rozpoczęcie procesu wyboru reklamy.

Ten proces wyboru reklamy administruje wykonywaniem na urządzeniu kodu JavaScript dostarczonego przez technologie reklamowe na podstawie tej sekwencji:

Realizacja logiki ustalania stawek po stronie kupującego
Filtrowanie i przetwarzanie reklam po stronie kupującego
Realizacja logiki decyzyjnej dla sprzedawców

W przypadku wyboru reklam dotyczących niestandardowych odbiorców platforma pobierze kod JavaScript od strony zakupu dostarczany z boku strony na podstawie publicznego punktu końcowego adresu URL zdefiniowanego przez metadane niestandardowego adresu URL określania stawek. Punkt końcowy adresu URL na potrzeby kodu decyzji po stronie sprzedaży również zostanie przekazany jako dane wejściowe rozpoczęcia procesu wyboru reklamy.

Projekty wyboru reklam, które nie korzystają z niestandardowych list odbiorców, są w fazie aktywnego projektowania.

Rozpocznij proces wyboru reklamy

Gdy aplikacja musi wyświetlić reklamę, pakiet SDK platformy technologii reklamowych może zainicjować proces wyboru reklamy, wywołując metodę selectAds() po utworzeniu wystąpienia obiektu AdSelectionConfig z oczekiwanymi parametrami:

Sprzedawca: identyfikator platformy reklamowej SSP w formacie eTLD+1
Adres URL mechanizmu decyzyjnego: po zainicjowaniu aukcji reklam platforma użyje tego adresu URL, aby pobrać kod JavaScript z platformy SSP i wygrać zwycięską reklamę.
Nabywcy niestandardowych list odbiorców: lista platform po stronie kupującego z niestandardowym opartym na odbiorcach popytem na potrzeby tej aukcji, w formacie eTLD+1.
Sygnały dotyczące wyboru reklamy: informacje o aukcji (rozmiar reklamy, format reklamy itp.).
Sygnały dla sprzedawców: sygnały specyficzne dla platformy dostawców.
Adres URL zaufanych sygnałów punktowych: adres URL punktu końcowego zaufanego sygnału po stronie sprzedawcy, z którego można pobrać w czasie rzeczywistym informacje o konkretnej kreacji.
Sygnały według kupującego: uczestniczące w programie strony popytu mogą używać tego parametru do przesyłania danych wejściowych na potrzeby aukcji. Parametr ten może np. zawierać kompleksowe informacje kontekstowe przydatne przy określaniu stawek.

Ten przykładowy fragment kodu pokazuje, jak pakiet SDK platformy technologii reklamowych inicjuje proces wyboru reklamy przez określenie obiektu AdSelectionConfig, a następnie wywołanie selectAds, by uzyskać zwycięską reklamę:

AdSelectionConfig myAdSelectionConfig = new AdSelectionConfig {
    Seller = "example-ssp1.com",
    DecisionLogicURL = Uri.parse("https://..."),
    CustomAudienceBuyerList = Arrays.asList("example-dsp1.com","bexample-dsp2.com"),
    AdSelectionSignals = "{"min_price": 10,"auction_attempts": 3}"
    SellerSignals = "{"seller_type": "news", "content_category": "sports","mature_ads_accepted" :"false"}"
    PerBuyerSignals = " {"buyer1Name": {"key1" : "value1"},
                         "buyer2Name": {"key1" : "value1", "key2" : "value2" }"
};

// Invoke ad services API to initiate ad selection workflow.
Ad winningAd = selectAds(myAdSelectionConfig);

Logika ustalania stawek po stronie kupującego

Logika ustalania stawek jest zwykle udostępniana przez platformy po stronie kupującego. Celem tego kodu jest ustalanie stawek dla reklam kandydujących. Przy ustalaniu wyniku może zastosować dodatkową logikę biznesową.

Platforma użyje metadanych „adresu URL określania stawek” niestandardowych odbiorców, aby pobrać kod JavaScript, który powinien zawierać poniższy podpis funkcji:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ...};
}

Metoda generateBid() zwraca obliczoną kwotę stawki. Platforma po kolei wywoła tę funkcję dla wszystkich reklam (kontekstowych lub remarketingowych). Jeśli istnieje kilku dostawców logiki ustalania stawek, system nie gwarantuje kolejności ich wykonywania.

Funkcja oczekuje tych parametrów:

Reklama: reklama uwzględniana przy użyciu kodu ustalania stawek po stronie kupującego. To będzie reklama z kwalifikującej się niestandardowej grupy odbiorców,
Sygnały z aukcji: sygnały dotyczące sprzedaży i konkretnej platformy.
Sygnały według kupującego: uczestniczące w programie strony popytu mogą używać tego parametru do przesyłania danych wejściowych na potrzeby aukcji. Parametr ten może np. zawierać kompleksowe informacje kontekstowe przydatne przy określaniu stawek.
Zaufane sygnały dotyczące określania stawek: podczas pobierania i oceniania reklam platformy technologii reklamowych korzystają z danych w czasie rzeczywistym. Budżet kampanii reklamowej może się np. wyczerpać i trzeba natychmiast ją zatrzymać. Dział technologii reklamowych może zdefiniować punkt końcowy adresu URL, z którego można pobrać dane w czasie rzeczywistym, oraz zestaw kluczy, których dotyczy wyszukiwanie w czasie rzeczywistym. Zarządzany serwer platformy technologii reklamowych, który obsługuje to żądanie, będzie zaufanym serwerem zarządzanym przez platformę technologii reklamowych.
Sygnały kontekstowe: mogą to być przybliżone sygnatury czasowe, informacje o przybliżonej lokalizacji lub koszt kliknięcia reklamy.
Sygnały dla użytkowników: mogą to być informacje m.in. o dostępnych informacjach o zainstalowanym pakiecie.

Koszt reklamy

Oprócz stawki platformy po stronie kupującego mogą w ramach generateBid() zwrócić koszt kliknięcia. Na przykład:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ..., 'adCost': ...,};
}

W przypadku zwycięzcy parametr adCost jest stochastycznie zaokrąglany do 8 bitów w celu ochrony prywatności. Zaokrąglona wartość adCost jest następnie przekazywana do parametru contextual_signals w reportWin podczas raportowania wyświetleń.

Logika filtrowania po stronie kupującego

Platformy po stronie kupującego będą mogły filtrować reklamy na podstawie dodatkowych sygnałów na urządzeniu dostępnych na etapie wyboru reklamy. Platformy technologii reklamowych mogą na przykład wdrożyć funkcję ograniczenia liczby wyświetleń. Jeśli istnieje kilku dostawców filtrowania, system nie gwarantuje sekwencji wykonywania poszczególnych dostawców.

Logikę filtrowania po stronie kupującego można wdrożyć w ramach logiki określania stawek przez zwrócenie w przypadku danej reklamy wartości stawki wynoszącej 0.

Dodatkowo platformy po stronie kupującego będą mogły zasygnalizować, że dana reklama powinna zostać odfiltrowana na podstawie dodatkowych sygnałów z urządzenia dostępnych dla Protected Audience API, które nie opuszczają urządzenia. W miarę ulepszania logiki filtrowania w przypadku platform po stronie kupującego ta sama struktura sygnalizuje konieczność filtrowania.

Logika oceny sprzedawcy

Zasady dotyczące punktacji są zwykle udostępniane przez platformę SSP. Celem tego kodu jest określenie zwycięskiej reklamy na podstawie danych wyjściowych z logiką określania stawek. Do określenia wyników może być stosowana dodatkowa logika biznesowa. Jeśli istnieje wielu dostawców logiki decyzyjnej, system nie gwarantuje sekwencji wykonywania u nich. Platforma użyje parametru wejściowego „Decision Logic URL” (URL logiki decyzji) z interfejsu API selectAds(), aby pobrać kod JavaScript, który powinien zawierać poniższy podpis funkcji:

scoreAd(ad, bid, auction_config, trusted_scoring_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return score_for_this_ad;
}

Funkcja oczekuje tych parametrów:

Reklama: oceniana reklama; dane wyjściowe funkcji generateBid().
Stawka: wartość stawki uzyskana z funkcji generateBid().
Konfiguracja aukcji: parametr wejściowy metody selectAds().
Zaufane sygnały oceny: podczas filtrowania i oceniania reklam platformy technologii reklamowych wykorzystują dane w czasie rzeczywistym. Wydawca aplikacji może na przykład zablokować wyświetlanie w niej reklam z kampanii reklamowej. Dane te są pobierane z parametru adresu URL zaufanego sygnału punktowego w konfiguracji aukcji. Serwer wyświetlający to żądanie powinien być zaufanym serwerem zarządzanym przez technologię reklamową.
Sygnał kontekstowy: może to być przybliżona sygnatura czasowa lub informacje o przybliżonej lokalizacji.
Sygnał użytkownika: może to obejmować informacje takie jak sklep z aplikacjami, który zainicjował instalację aplikacji.
Niestandardowy sygnał dotyczący odbiorców: jeśli ocena reklamy pochodzi od niestandardowej listy odbiorców na urządzeniu, identyfikator zawiera takie informacje jak czytelnik i nazwa tej grupy.

Środowisko wykonawcze kodu wyboru reklamy

W ofercie pakietowej system pobierze kod aukcji udostępniony przez platformę technologii reklamowych z konfigurowalnych adresów URL punktów końcowych i wykona je na urządzeniu. Ze względu na ograniczenia zasobów na urządzeniach mobilnych kod aukcji powinien być zgodny z tymi wytycznymi:

Wykonanie kodu powinno się zakończyć we wcześniej zdefiniowanym czasie. To ograniczenie będzie obowiązywać jednakowo we wszystkich sieciach reklamowych kupującego. Szczegóły tego ograniczenia zostaną udostępnione w kolejnej aktualizacji.
Kod musi być autonomiczny i nie może mieć żadnych zależności zewnętrznych.

Ponieważ kod aukcji, np. logika określania stawek, może potrzebować dostępu do prywatnych danych użytkowników, takich jak źródła instalacji aplikacji, środowisko wykonawcze nie zapewnia dostępu do sieci ani miejsca na dane.

Język programowania

Kod aukcji udostępniany przez platformę technologii reklamowych powinien być napisany w języku JavaScript. Umożliwiłoby to platformom technologii reklamowych udostępnianie kodu ustalania stawek różnym platformom, które obsługują Piaskownicę prywatności.

Zwycięskie renderowanie reklam

Reklama z najwyższym wynikiem jest uznawana za zwycięzcę aukcji. W tej początkowej ofercie zwycięska reklama jest przekazywana do SDK do renderowania.

Chodzi o opracowanie rozwiązania w taki sposób, aby aplikacja lub pakiet SDK nie mogła określać informacji o przynależności użytkownika do niestandardowych list odbiorców lub jego historii zaangażowania w aplikację na podstawie informacji o zwycięskiej reklamie (podobnie jak w przypadku propozycji z ramkami zabezpieczonymi w Chrome).

Raporty o wyświetleniach i zdarzeniach

Po wyrenderowaniu reklamy zwycięskie wyświetlenie można zgłosić ponownie platformom po stronie kupującego i sprzedawcy. Dzięki temu kupujący i sprzedawcy mogą dołączyć do raportu zwycięskiego wyświetlenia informacje z aukcji, np. stawkę lub niestandardową nazwę odbiorców. Dodatkowo platforma po stronie sprzedającego i zwycięska z zakupu może otrzymywać dodatkowe raporty na poziomie zdarzenia dotyczące zwycięskiej reklamy. Umożliwia to uwzględnienie informacji o aukcji (stawka, nazwa niestandardowej grupy odbiorców itp.) z kliknięciami, wyświetleniami i innymi zdarzeniami reklamowymi. Platforma wywołuje logikę raportowania w tej kolejności:

Raporty sprzedażowe
Raportowanie po stronie kupującego.

Dzięki temu platformy po stronie kupującego i sprzedawcy mogą przesyłać ważne informacje z urządzenia z powrotem na serwery, co pozwala korzystać z takich funkcji jak ustalanie budżetu w czasie rzeczywistym, aktualizacje modelu ustalania stawek i dokładne procesy rozliczeniowe. Raportowanie wyświetleń jest uzupełnieniem interfejsu Attribution Reporting API.

Aby włączyć raportowanie zdarzeń, musisz wykonać 2 kroki: JavaScript po stronie sprzedawcy i po stronie kupującego musi zarejestrować zdarzenie, o którym ma otrzymywać raporty o zdarzeniach, a strona sprzedająca odpowiada za raportowanie informacji na poziomie zdarzenia.

Protected Audience API to mechanizm subskrybowania przyszłych wydarzeń związanych ze zwycięskiej aukcji za pomocą rejestrowania obrazów typu beacon. W funkcji JavaScript sprzedawcy reportResult() platformy SSP mogą rejestrować obrazy typu beacon za pomocą dostępnej na platformie funkcji registerAdBeacon(). Podobnie platformy po stronie kupującego mogą wywoływać metodę registerAdBeacon() z poziomu funkcji JavaScriptu reportWin().

registerAdBeacon(beacons)

Urządzenie wejściowe:

event_key: ciąg tekstowy wskazujący typ interakcji, który ma zostać zarejestrowany. Dane te służą jako klucz do odnalezienia punktu końcowego pingów platformy podczas raportowania wyników aukcji.
reporting_url: adres URL należący do platformy AdTech do obsługi zdarzenia.

Klucze zdarzeń to identyfikatory ciągu znaków, które należą do pakietu SDK platformy sprzedażowej odpowiedzialnego za raportowanie wyników aukcji. Aby wykonać wywołanie zwrotne, specjaliści ds. technologii reklamowych rejestrują beacony z kluczami pasującymi do kluczy używanych przez stronę sprzedającą podczas raportowania zdarzeń. Nie muszą one być k-anonimowe, ale obowiązują ograniczenia dotyczące liczby i długości kluczy, które można zarejestrować na potrzeby określonej grupy odbiorców niestandardowych. Jeśli żądanie reportEvent() jest wywoływane, platformy SSP, które przeprowadziły aukcję, mogą otrzymywać te raporty o zdarzeniach. Tylko platforma po stronie kupującego, która wygrała aukcję, może otrzymać te raporty.

Raporty sprzedażowe

Platforma wywołuje funkcję JavaScript reportResult() w kodzie udostępnionym po stronie dostawców, który został pobrany z parametru Decision Logic URL (URL decyzji) sprzedawcy w interfejsie API selectAds():

reportResult(render_url, bid, auction_config, contextual_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_url": reporting_url,
                  "signals_for_buyer": signals_for_buyer}};
}

Dane wyjściowe: obiekt JSON zawierający

Stan: 0 oznacza sukces, dowolna inna wartość oznaczająca niepowodzenie.
URL raportowania: platforma wywołuje ten adres URL zwrócony z funkcji.
Sygnały dla kupującego: obiekt JSON, który ma zostać przekazany do funkcji reportWin kupującego.

Strona dostawców może kodować odpowiednie sygnały w adresie URL raportowania, aby uzyskać więcej informacji na temat aukcji i zwycięskiej reklamy. Mogą one na przykład obejmować te sygnały:

URL renderowania reklamy
Kwota zwycięskiej stawki
Nazwa aplikacji
Identyfikatory zapytań
Sygnały dla kupującego: aby obsługiwać udostępnianie danych między po stronie dostawców i popytem, platforma przekazuje tę wartość zwrotną jako parametr wejściowy do kodu raportowania po stronie popytu.

Raportowanie po stronie kupującego

Platforma wywołuje funkcję JavaScriptu reportWin() w kodzie udostępnionym po stronie popytu pobranym z metadanych adresu URL mechanizmu ustalania stawek niestandardowych odbiorców powiązanych z aukcją.

reportWin(render_url, bid, auction_signals, per_buyer_signals,
        signals_for_buyer, contextual_signals, custom_audience_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_uri": reporting_uri}};
}

Urządzenie wejściowe:

Dane auction_signals i per_buyer_signals są pobierane z AuctionConfig. Wszelkie informacje, które platforma po stronie kupującego musi przekazać do adresu URL raportowania, mogą pochodzić z tego punktu odniesienia.
signals_for_buyer to wynik raportu o stronach sprzedających. Dzięki temu platforma po stronie sprzedającego może udostępniać dane na potrzeby raportowania platformie po stronie kupującego.
contextual_signals zawiera takie informacje jak nazwa aplikacji, a custom_audience_signals zawiera informacje o niestandardowych odbiorcach. W przyszłości możemy dodać więcej informacji.

Dane wyjściowe:

Stan: 0 oznacza sukces, dowolna inna wartość oznaczająca niepowodzenie.
URL raportowania: platforma wywołuje ten adres URL zwrócony z funkcji.

Raportowanie zdarzeń

Raportowanie zdarzeń jest możliwe dopiero po zakończeniu raportowania wyświetleń dla aukcji. Za zgłaszanie zdarzeń odpowiada pakiet SDK po stronie sprzedawcy. Platforma udostępnia interfejs API, który wykorzystuje parametr ReportEventRequest, który określa niedawno przeprowadzoną aukcję, raportowany klucz zdarzenia, dane powiązane z tym kluczem, informacje o tym, czy raport ma zostać wysłany do kupującego czy sprzedawcy (albo do obu tych grup), oraz opcjonalne zdarzenie wejściowe w przypadku zdarzeń reklamowych. Klient określa klucz zdarzenia i zbieranie danych do raportowania.

ReportEventRequest request = new ReportEventRequest(
  AdSelectionId = ad_selection_id,
  event_key = "view"
  event_data = "{ "viewTimeInSeconds" :1 }",
  reporting_destinations =
    FLAG_REPORTING_DESTINATION_SELLER |
      FLAG_REPORTING_DESTINATION_BUYER,
  input_event = clickInputEvent // or null for view
  )

reportEvent(request)

Urządzenie wejściowe:

Wartość ad_selection_id musi być wartością AdSelectionId niedawno przeprowadzonej aukcji pobranej z: AdSelectionOutcome.
event_key to ciąg znaków zdefiniowany po stronie sprzedaży, który opisuje zdarzenie interakcji.
event_data to ciąg znaków reprezentujący dane powiązane z polem event_key
reporting_destinations to maska bitowa ustawiona za pomocą flag dostarczanych przez platformę. Może to być FLAG_REPORTING_DESTINATION_SELLER, FLAG_REPORTING_DESTINATION_BUYER lub obie.
Interfejs input_event (opcjonalny) służy do integracji z interfejsem Attribution Reporting API. Jest to obiekt InputEvent (w przypadku zdarzenia kliknięcia) lub wartość null (w przypadku zdarzenia wyświetlenia). Więcej informacji o tym parametrze znajdziesz w artykule Integracja interfejsu Attribution Reporting API.

Gdy pakiet SDK po stronie sprzedawcy wywoła reportEvent, a w zależności od flagi reporting_destinations platforma próbuje dopasować event_key do kluczy zarejestrowanych przez kupujących i sprzedawców w ich funkcjach JavaScript reportWin i reportResult. Jeśli występuje dopasowanie, platforma wysyła żądanie event_data do powiązanego elementu reporting_url. Typ treści żądania to zwykły tekst, którego treść to event_data. To żądanie jest wykonywane w miarę możliwości i kończy się niepowodzeniem w przypadku błędu sieci, odpowiedzi błędu serwera lub braku pasujących kluczy.

Integracja interfejsu Attribution Reporting API

Aby pomóc kupującym, którzy biorą udział w aukcji Protected Audience API, udostępniamy funkcje obejmujące różne interfejsy API w interfejsach Protected Audience API i Attribution Reporting API (ARA). Ta funkcja pozwala technikom reklamowym ocenić skuteczność atrybucji w ramach różnych taktyk remarketingowych i dowiedzieć się, które typy odbiorców zapewniają najwyższy ROI.

Dzięki integracji różnych interfejsów API Adtechs może:

Utwórz mapę klucz-wartość identyfikatorów URI, która będzie używana 1) do raportowania interakcji z reklamą i 2) do rejestracji źródła.
Uwzględnianie danych z aukcji z Protected Audience API w mapowaniu kluczy po stronie źródła na potrzeby zbiorczych raportów podsumowujących (za pomocą interfejsu Attribution Reporting API). Więcej informacji znajdziesz w propozycji projektu interfejsu ARA.

Gdy użytkownik zobaczy lub kliknie reklamę:

Adres URL służący do zgłaszania tych interakcji ze zdarzeniami z wykorzystaniem Protected Audience API dostarczy kupującemu niezbędne dane, które będą używane do zarejestrowania wyświetlenia lub kliknięcia jako kwalifikującego się źródła za pomocą Attribution Reporting API.
Technika reklamowa może zdecydować o przekazywaniu CustomAudience (lub innych istotnych informacji kontekstowych o reklamie, takich jak miejsce docelowe reklamy lub czas oglądania) za pomocą tego adresu URL. Dzięki temu te metadane mogą zostać przekazane do raportów podsumowujących, gdy technologia reklamowa sprawdza zbiorczą skuteczność kampanii.

Włączanie rejestracji źródła

Funkcja reportEvent() będzie akceptować nowy opcjonalny parametr InputEvent. Zwycięzcy kupujący, którzy zarejestrują beacony, mogą wybrać, które raporty reportEvent mają zostać zarejestrowane przy użyciu interfejsów Attribution Reporting API jako zarejestrowane źródło. Nagłówek żądania Attribution-Reporting-Eligible zostanie dodany do wszystkich żądań raportowania zdarzeń wysyłanych z konta reportEvent(). Wszystkie odpowiedzi z odpowiednimi nagłówkami ARA będą analizowane w taki sam sposób, jak każda inna odpowiedź rejestracji źródła ARA. Aby dowiedzieć się, jak zarejestrować źródłowy adres URL, przeczytaj wyjaśnienie dotyczące interfejsu Attribution Reporting API.

ARA na Androidzie obsługuje zdarzenia wyświetlenia i kliknięcia, dlatego do rozróżniania tych 2 typów służą zdarzenia InputEvents. Tak jak w przypadku rejestracji źródła ARA, interfejs reportEvent() API zinterpretuje InputEvent zweryfikowane przez platformę jako zdarzenie kliknięcia. Jeśli brakuje atrybutu InputEvent, ma on wartość null lub jest nieprawidłowy, rejestracja źródła jest uznawana za widok.

Pamiętaj, że po aukcji eventData może zawierać informacje poufne, dlatego platforma pomija eventData w żądaniach rejestracji źródła, które przekierowywano.

Przykład raportowania zaangażowania i konwersji

W tym przykładzie przyjrzymy się temu z perspektywy kupującego, który chce powiązać ze sobą dane z aukcji, renderowanej reklamy i aplikacji do konwersji.

W tym procesie kupujący kontaktuje się ze sprzedawcą, aby przesłać unikalny identyfikator na aukcję. Podczas aukcji kupujący przesyła ten unikalny identyfikator razem z danymi z aukcji. Podczas renderowania i konwersji dane z renderowanej reklamy również są wysyłane z tym samym unikalnym identyfikatorem. Później za pomocą tego identyfikatora połączymy ze sobą te raporty.

Przepływ pracy: przed rozpoczęciem aukcji kupujący wysyła do sprzedawcy unikalny identyfikator w ramach odpowiedzi na pytanie o stawkę w ramach automatyzacji określania stawek w czasie rzeczywistym (RTB). Identyfikator można ustawić jako zmienną, np. auctionId. Identyfikator jest przekazywany w elemencie auctionConfig jako perBuyerSignals i staje się dostępny w logice ustalania stawek kupującego.

Podczas wykonywania kodu reportWin kupujący może zarejestrować beacon, który ma być aktywowany w czasie renderowania reklamy oraz w przypadku określonych zdarzeń interakcji (registerAdBeacon()). Aby powiązać sygnały aukcji z danym zdarzeniem reklamy, ustaw auctionId jako parametr zapytania adresu URL obrazu typu beacon.
Podczas renderowania reklamy beacony zarejestrowane w czasie aukcji mogą być wywoływane lub wzmacniane za pomocą danych na poziomie zdarzenia. Sprzedawca musi aktywować funkcję reportEvent() i przekazywać dane na poziomie zdarzenia. Platforma wyśle ping do adresu URL obrazu typu beacon zarejestrowanego przez kupującego, który jest powiązany z uruchomionym parametrem reportEvent().
Kupujący rejestruje reklamę w interfejsie Attribution Reporting API, odpowiadając na żądania beaconu za pomocą nagłówka Attribution-Reporting-Register-Source. Aby powiązać sygnały aukcji w przypadku zdarzenia konwersji, w polu Zarejestruj źródłowy adres URL ustaw parametr auctionId.

Po zakończeniu tego procesu kupujący otrzyma raport aukcji, raport interakcji i raport konwersji, które będzie można skorelować za pomocą unikalnego identyfikatora, który można powiązać ze sobą.

Podobny proces ma zastosowanie w przypadku sprzedawcy, który potrzebuje dostępu do danych atrybucji. Sprzedawca może też użyć unikalnego identyfikatora, aby wysłać zamówienie za pomocą registerAdBeacon(). Wywołanie reportEvent() zawiera właściwość docelową, której można używać do wysyłania raportu zarówno do kupującego, jak i sprzedawcy.

Zaufany serwer zarządzany przez platformę technologii reklamowych

Obecnie logika wyboru reklam wymaga informacji w czasie rzeczywistym, np. o stanie wyczerpania budżetu, aby określić, czy kandydaci reklam powinni zostać wybrani do aukcji. Zarówno platformy po stronie kupującego, jak i platformy SSP będą mogły uzyskiwać te informacje ze swoich serwerów. Aby zminimalizować wyciek informacji poufnych przez te serwery, oferta pakietowa wymaga wprowadzenia tych ograniczeń:

Działanie tych serwerów, opisane w dalszej części tej sekcji, nie spowodowałoby wycieku informacji o użytkownikach.
Serwery nie tworzą pseudonimów na podstawie dostępnych danych, co oznacza, że muszą być „zaufane”.

Po stronie kupującego: gdy kupujący inicjuje logikę ustalania stawek po stronie kupującego, platforma wykonuje pobieranie HTTP danych ustalania stawek z zaufanego serwera. Składa się on z adresu URL i kluczy zawartych w metadanych sygnałów dotyczących zaufanego określania stawek przetwarzanych niestandardowych odbiorców. Pobieranie odbywa się tylko podczas przetwarzania reklam z niestandardowych list odbiorców na urządzeniu. Na tym etapie kupujący może egzekwować budżety, sprawdzać stan wstrzymywania i wznawiania kampanii, ustawiać kierowanie itp.

Poniżej znajdziesz przykładowy adres URL, z którego można pobrać dane dotyczące zaufanego określania stawek na podstawie metadanych zaufanego sygnału ustalania stawek z grupy niestandardowych odbiorców:

https://www.kv-server.example/getvalues?keys=key1,key2

Odpowiedź z serwera powinna być obiektem JSON, którego klucze to klucz1, klucz2 itd., a wartości zostaną udostępnione funkcjom ustalania stawek kupującego.

Strona sprzedawcy: podobnie jak w przypadku powyższego procesu po stronie kupującego, strona sprzedająca może chcieć pobierać informacje o kreacjach biorących udział w aukcji. Wydawca może na przykład wymusić brak wyświetlania niektórych kreacji w aplikacji ze względu na obawy o bezpieczeństwo marki. Te informacje można pobrać i udostępnić logice aukcji po stronie sprzedaży. Podobnie jak w przypadku wyszukiwania zaufanego serwera po stronie kupującego, wyszukiwanie takiego serwera odbywa się również przez pobieranie HTTP. Składa się on z dołączonego adresu URL zaufanego wskaźnika oceny wraz z adresami URL renderowania kreacji, w przypadku których należy pobrać dane.

Poniżej znajduje się przykładowy adres URL umożliwiający pobranie informacji o kreacjach, które brały udział w aukcji, na podstawie adresów URL renderowania kreacji:

https://www.kv-server.example/getvalues?renderUrls=render_url1,render_url2

Odpowiedź z serwera powinna być obiektem JSON, którego klucze to renderowane adresy URL wysyłane w żądaniu.

Serwery te działałyby w zaufany sposób i zapewniałyby kilka korzyści w zakresie bezpieczeństwa i ochrony prywatności:

Można zaufać, że wartość zwracana przez serwer dla każdego klucza opiera się tylko na tym kluczu.
Serwer nie rejestruje zdarzeń na poziomie zdarzenia.
Serwer nie ma żadnych innych efektów ubocznych związanych z tymi żądaniami.

W ramach mechanizmu tymczasowego kupujący i sprzedawca mogą pobierać te sygnały ustalania stawek z dowolnego serwera, w tym z tego, który działa samodzielnie. Jednak w wersji produkcyjnej żądanie będzie wysyłane tylko do zaufanego serwera typu klucz-wartość.

Kupujący i sprzedawcy mogą używać wspólnego zaufanego serwera klucz-wartość na potrzeby platform zgodnych z Piaskownicą prywatności na Androida i w internecie.