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

Ostatnie aktualizacje

• Dodaliśmy informacje o planowaniu aktualizacji niestandardowych list odbiorców.
• Dodano integrację Attribution Reporting z Protected Audience
• Opublikowaliśmy oś czasu funkcji Protected Audience API.
• FLEDGE zmienił nazwę na Protected Audience API.
• Dodano propozycję delegowania niestandardowych list odbiorców.
• Usunęliśmy wymaganie dotyczące k-anonimowości w przypadku adresu URL codziennej aktualizacji.

Interfejs Protected Audience jest dostępny w wersji beta i można go używać do celów programistycznych.

Dzięki Protected Audience możesz:

• zarządzać niestandardowymi grupami odbiorców na podstawie wcześniejszych działań użytkowników;
• Inicjuj aukcje na urządzeniu z obsługą pojedynczego sprzedawcy lub kaskadowego zapośredniczenia.
• Raportowanie wyświetleń ćwiczeń po wybraniu reklamy.

Aby zacząć, przeczytaj przewodnik dla programistów dotyczący Protected Audience. Twoja opinia jest dla nas bardzo ważna, ponieważ stale rozwijamy Protected Audience.

Oś czasu

W najbliższych miesiącach udostępnimy nowe funkcje. Dokładne daty wprowadzenia będą się różnić w zależności od funkcji. W miarę udostępniania dokumentacji będziemy aktualizować tę tabelę o odpowiednie linki.

Przegląd

W reklamie mobilnej reklamodawcy często muszą wyświetlać reklamy potencjalnie zainteresowanym użytkownikom na podstawie ich wcześniejszych interakcji z aplikacją reklamodawcy. Na przykład deweloper SportingGoodsApp może chcieć wyświetlać reklamy użytkownikom, którzy mają produkty w koszyku, aby przypomnieć im o dokonaniu zakupu. W branży to ogólne pojęcie jest zwykle określane terminami takimi jak „remarketing” i „kierowanie na niestandardowych odbiorców”.

Obecnie te przypadki użycia są zwykle realizowane przez udostępnianie platformom technologii reklamowych informacji kontekstowych o sposobie wyświetlania reklamy (np. nazwy aplikacji) oraz informacji prywatnych, takich jak listy odbiorców. Na podstawie tych informacji reklamodawcy mogą wybierać odpowiednie reklamy na swoich serwerach.

Interfejs Protected Audience API na Androida (wcześniej znany jako FLEDGE) obejmuje te interfejsy API dla platform technologii reklamowych i reklamodawców, które obsługują typowe przypadki użycia oparte na interakcjach w sposób ograniczający udostępnianie identyfikatorów w aplikacjach oraz informacji o interakcjach użytkownika z aplikacjami podmiotom zewnętrznym:

1. Custom Audience API: ten interfejs API jest oparty na abstrakcji „niestandardowi odbiorcy”, która reprezentuje wyznaczoną przez reklamodawcę grupę odbiorców o podobnych zamiarach. Informacje o odbiorcach są przechowywane na urządzeniu i mogą być powiązane z odpowiednimi reklamami dla odbiorców oraz dowolnymi metadanymi, takimi jak sygnały licytowania. Informacje te mogą być wykorzystywane do określania stawek reklamodawców, filtrowania i renderowania reklam.
2. Interfejs Ad Selection API: udostępnia on platformę, która koordynuje procesy platform technologii reklamowych korzystające z sygnałów na urządzeniu w celu określenia „zwycięskiej” reklamy poprzez uwzględnienie reklam kandydatów przechowywanych lokalnie i przeprowadzenie dodatkowego przetwarzania reklam kandydatów, które platforma technologii reklamowych zwraca na urządzenie.

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

1. Aplikacja SportingGoodsApp chce przypominać użytkownikom o zakupie produktów, które pozostawili w koszyku, jeśli nie dokonali zakupu w ciągu 2 dni. Aplikacja SportingGoodsApp używa interfejsu Custom Audience API, aby dodać użytkownika do listy odbiorców „produkty w koszyku”. Platforma zarządza tą listą odbiorców i przechowuje ją na urządzeniu, co ogranicza udostępnianie jej osobom trzecim. Firma SportingGoodsApp współpracuje z platformą technologii reklamowych, aby wyświetlać reklamy użytkownikom z listy odbiorców. Platforma technologii reklamowych zarządza metadanymi list odbiorców i dostarcza reklamy kandydujące, które są udostępniane w procesie wyboru reklam. Platformę można skonfigurować tak, aby okresowo pobierała w tle zaktualizowane reklamy oparte na odbiorcach. Dzięki temu lista reklam kwalifikujących się do wyświetlenia na podstawie odbiorców jest aktualna i nie jest powiązana z żądaniami wysyłanymi do serwerów reklamowych firm zewnętrznych w momencie wyświetlenia reklamy (czyli z kontekstowym żądaniem reklamy).

2. Gdy użytkownik zagra w FrisbeeGame na tym samym urządzeniu, może zobaczyć reklamę przypominającą mu o dokończeniu zakupu produktów pozostawionych w koszyku aplikacji SportingGoodsApp. Można to osiągnąć, wywołując w grze FrisbeeGame (z zintegrowanym pakietem SDK reklam) interfejs Ad Selection API, aby wybrać zwycięską reklamę dla użytkownika na podstawie dowolnej listy odbiorców, do której może on należeć (w tym przykładzie jest to lista odbiorców niestandardowych „produkty w koszyku” utworzona przez aplikację SportingGoodsApp). Proces wyboru reklam można skonfigurować tak, aby uwzględniał reklamy pobrane z serwerów platform reklamowych, a także reklamy na urządzeniu powiązane z odbiorcami niestandardowymi i inne sygnały na urządzeniu. Proces ten może być też dostosowywany przez platformę technologii reklamowych i pakiet SDK do reklam za pomocą niestandardowych strategii określania stawek i logiki oceniania, aby osiągać odpowiednie cele reklamowe. Takie podejście umożliwia wykorzystywanie danych o zainteresowaniach użytkownika lub interakcjach z aplikacją do wybierania reklam, a jednocześnie ogranicza udostępnianie tych danych podmiotom zewnętrznym.

3. Wybrana reklama jest renderowana przez pakiet SDK aplikacji wyświetlającej reklamy lub platformy technologii reklamowych.

4. Platforma ułatwia raportowanie wyświetleń i wyników wyboru reklam. Ta funkcja raportowania uzupełnia interfejs Attribution Reporting API. Platformy technologii reklamowych mogą dostosowywać te informacje do swoich potrzeb w zakresie raportowania.

Uzyskiwanie dostępu do interfejsów Protected Audience API na Androidzie

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

Zarządzanie niestandardowymi listami odbiorców

Niestandardowa lista odbiorców

Odbiorcy niestandardowi to grupa użytkowników określona przez reklamodawcę, którzy mają podobne zamiary lub zainteresowania. Aplikacja lub pakiet SDK może używać niestandardowych odbiorców do wskazywania określonych odbiorców, np. osób, które „zostawiły produkty w koszyku” lub „ukończyły poziomy dla początkujących” w grze. Platforma przechowuje informacje o odbiorcach lokalnie na urządzeniu i nie ujawnia, do których niestandardowych odbiorców należy użytkownik. Odbiorcy niestandardowi różnią się od grup zainteresowań interfejsu Protected Audience API w Chrome i nie można ich udostępniać w internecie i aplikacjach. Pomaga to ograniczyć udostępnianie informacji o użytkownikach.

Aplikacja reklamodawcy lub zintegrowany pakiet SDK mogą dołączać do niestandardowych list odbiorców lub z nich występować na podstawie np. zaangażowania użytkownika w aplikacji.

Metadane niestandardowych odbiorców

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

• Właściciel: nazwa pakietu aplikacji będącej właścicielem. Jest ona niejawnie ustawiana na nazwę pakietu aplikacji wywołującej.
• Kupujący: sieć reklamowa kupującego, która zarządza reklamami kierowanymi na tę niestandardową listę odbiorców. Kupujący to również podmiot, który może uzyskać dostęp do niestandardowych odbiorców i pobrać odpowiednie informacje o reklamach. Kupujący jest określony w formacie eTLD+1.
• Nazwa: dowolna nazwa lub identyfikator odbiorców niestandardowych, np. użytkownik, który „porzucił koszyk”. Ten atrybut może być używany np. jako jedno z kryteriów kierowania w kampaniach reklamowych reklamodawcy lub jako ciąg zapytania w adresie URL służącym do pobierania kodu licytowania.
• Czas aktywacji i czas wygaśnięcia: te pola określają przedział czasu, w którym ta lista odbiorców niestandardowych będzie aktywna. Platforma wykorzystuje te informacje do wycofywania członkostwa w niestandardowej grupie odbiorców. Czas wygaśnięcia nie może przekraczać maksymalnego okresu, aby ograniczyć czas życia niestandardowej listy odbiorców.
• Adres URL codziennej aktualizacji: adres URL, którego platforma używa do cyklicznego pobierania kandydatów na reklamy i innych metadanych zdefiniowanych w polach „Sygnały licytowania przez użytkownika” i „Zaufane sygnały licytowania”. Więcej informacji znajdziesz w sekcji dotyczącej pobierania reklam kandydatów na potrzeby odbiorców niestandardowych.
• Sygnały określania stawek przez użytkowników: sygnały specyficzne dla platformy technologii reklamowej w przypadku określania stawek za reklamy remarketingowe. Przykłady sygnałów: przybliżona lokalizacja użytkownika lub preferowany język.
• Zaufane dane o licytacjach: platformy technologii reklamowej korzystają z danych w czasie rzeczywistym, aby informować o pobieraniu i ocenianiu reklam. Na przykład reklama może wyczerpać budżet i trzeba natychmiast przerwać jej wyświetlanie. Dostawca technologii reklamowych może zdefiniować punkt końcowy adresu URL, z którego można pobierać te dane w czasie rzeczywistym, oraz zestaw kluczy, dla których należy przeprowadzić wyszukiwanie w czasie rzeczywistym. Serwer obsługujący to żądanie będzie zaufanym serwerem zarządzanym przez platformę technologii reklamowej.
• Adres URL logiki określania stawek: adres URL, którego platforma używa do pobierania kodu określania stawek z platformy po stronie popytu. Platforma wykonuje ten krok, gdy rozpoczyna się aukcja reklam.
• Reklamy: lista reklam, które mogą być wyświetlane odbiorcom niestandardowym. Obejmuje to metadane reklamy specyficzne dla platformy technologii reklamowej i adres URL do renderowania reklamy. Gdy dla odbiorców niestandardowych rozpocznie się aukcja, ta lista metadanych reklamy zostanie uwzględniona. Lista reklam będzie odświeżana za pomocą punktu końcowego adresu URL codziennej aktualizacji, gdy będzie to możliwe. Ze względu na ograniczenia zasobów na urządzeniach mobilnych istnieje limit liczby reklam, które można przechowywać na liście odbiorców niestandardowych.

Delegowanie uprawnień do niestandardowych list odbiorców

Ustalona metoda definiowania i konfigurowania niestandardowych list odbiorców opiera się zwykle na technologiach po stronie serwera i integracjach obsługiwanych przez technologie reklamowe we współpracy z klientami i partnerami agencji oraz reklamodawców. Protected Audience API umożliwia definiowanie i konfigurowanie niestandardowych grup odbiorców przy jednoczesnej ochronie prywatności użytkowników. Aby dołączyć do niestandardowej listy odbiorców, technologie reklamowe kupującego, które nie mają pakietu SDK w aplikacjach, muszą współpracować z technologiami reklamowymi, które są obecne na urządzeniu, np. z partnerami ds. pomiarów mobilnych (MMP) i platformami dostawców (SSP). Interfejs Protected Audience API ma na celu obsługę tych pakietów SDK przez zapewnienie elastycznych rozwiązań do zarządzania niestandardowymi listami odbiorców, umożliwiając wywołującym na urządzeniu tworzenie niestandardowych list odbiorców w imieniu kupujących. Ten proces nazywa się delegowaniem list klientów. Aby skonfigurować delegowanie uprawnień do list niestandardowych odbiorców:

Dołączanie do grupy odbiorców niestandardowych

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

joinCustomAudience()

Aplikacja lub pakiet SDK może wysłać prośbę o dołączenie do listy odbiorców niestandardowych, wywołując funkcję joinCustomAudience() po utworzeniu instancji 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 wysłać prośbę o dołączenie do niestandardowej listy odbiorców w imieniu dostawcy technologii reklamowych, który nie jest obecny na urządzeniu. W tym celu należy wywołać 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 adresu URL należący do kupującego odpowiada obiektem JSON CustomAudience w treści odpowiedzi. Pola kupującego i właściciela niestandardowych odbiorców są ignorowane (i wypełniane automatycznie przez interfejs API). Interfejs API sprawdza też, czy adres URL codziennej aktualizacji jest zgodny z 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 fetchAndJoinCustomAudience() API określa tożsamość kupującego na podstawie domeny eTLD+1 fetchUri. Tożsamość kupującego CustomAudience jest używana do przeprowadzania tych samych weryfikacji rejestracji i autoryzacji aplikacji, które są wykonywane przez joinCustomAudience(). Nie można jej zmienić w odpowiedzi na pobranie. Właścicielem CustomAudience jest nazwa pakietu aplikacji wywołującej. Nie ma innej weryfikacji parametru fetchUri niż sprawdzenie domeny eTLD+1, a w szczególności nie ma sprawdzania k-anon. Interfejs fetchAndJoinCustomAudience() API wysyła żądanie HTTP GET do fetchUri i oczekuje obiektu JSON reprezentującego niestandardową listę odbiorców. W odpowiedzi obowiązują te same obowiązkowe i opcjonalne ograniczenia oraz wartości domyślne dla pól obiektu odbiorców niestandardowych. Więcej informacji o aktualnych wymaganiach i ograniczeniach znajdziesz w Przewodniku dla programistów.

Każda odpowiedź z błędem HTTP od kupującego powoduje niepowodzenie fetchAndJoinCustomAudience. W szczególności odpowiedź ze stanem HTTP 429 (Za dużo żądań) blokuje żądania z bieżącej aplikacji na określony czas. Wywołanie interfejsu API kończy się też niepowodzeniem, jeśli odpowiedź kupującego ma nieprawidłowy format. Błędy są zgłaszane do wywołującego interfejs API, który jest odpowiedzialny za ponawianie prób w przypadku tymczasowych błędów (np. gdy serwer nie odpowiada) lub obsługę trwałych błędów (np. błędów weryfikacji danych lub innych nietrwałych błędów komunikacji z serwerem).

Obiekt CustomAudienceFetchRequest umożliwia wywołującemu interfejs API zdefiniowanie niektórych informacji o niestandardowej grupie odbiorców za pomocą opcjonalnych właściwości pokazanych w przykładzie. Jeśli te wartości są ustawione w żądaniu, nie można ich zastąpić odpowiedzią kupującego otrzymaną przez platformę. Protected Audience API ignoruje pola w odpowiedzi. Jeśli nie są one ustawione w żądaniu, muszą być ustawione w odpowiedzi, ponieważ te pola są wymagane do utworzenia niestandardowej listy odbiorców. Reprezentacja JSON zawartości CustomAudience, częściowo zdefiniowana przez wywołującego interfejs API, jest dołączana do żądania GET wysyłanego do fetchUri w specjalnym nagłówku X-CUSTOM-AUDIENCE-DATA. Rozmiar serializowanej formy danych określonych dla odbiorców niestandardowych jest ograniczony do 8 KB. Jeśli rozmiar zostanie przekroczony, wywołanie interfejsu API fetchAndJoinCustomAudience się nie powiedzie.

Brak sprawdzania k-anonimowości umożliwia używanie fetchUri do weryfikacji kupującego i włączania udostępniania informacji między kupującym a pakietem SDK. Aby ułatwić weryfikację niestandardowych list odbiorców, kupujący może podać token weryfikacyjny. Pakiet SDK na urządzeniu powinien zawierać ten token w parametrze fetchUri, aby punkt końcowy hostowany przez kupującego mógł pobrać zawartość niestandardowej listy odbiorców i użyć tokena weryfikacyjnego do sprawdzenia, czy operacja fetchAndJoinCustomAudience() odpowiada kupującemu i pochodzi od zaufanego partnera na urządzeniu. Aby udostępnić informacje, kupujący może uzgodnić z wywołującym na urządzeniu, że niektóre informacje, które mają być użyte do utworzenia niestandardowych odbiorców, zostaną dodane jako parametry zapytania do fetchUri. Umożliwia to kupującemu sprawdzanie wywołań i wykrywanie, czy złośliwa technologia reklamowa użyła tokena weryfikacyjnego do utworzenia kilku różnych list odbiorców niestandardowych.

Uwaga na temat definicji i przechowywania tokena weryfikacyjnego

• Token weryfikacyjny nie jest używany do żadnych celów przez interfejs Protected Audience API i jest opcjonalny.

  • Token weryfikacyjny może być używany przez kupującego do weryfikowania, czy listy odbiorców są tworzone w jego imieniu.
  • Propozycja interfejsu Protected Audience API nie określa formatu tokena weryfikacyjnego ani sposobu, w jaki kupujący przekazuje go do wywołującego. Na przykład token weryfikacyjny może być wstępnie załadowany w zestawie SDK lub backendzie właściciela albo może być pobierany w czasie rzeczywistym przez zestaw SDK właściciela z serwera kupującego.

Opuszczanie grupy odbiorców niestandardowych

Właściciel niestandardowych odbiorców może zrezygnować z udziału w tej grupie, wywołując funkcję leaveCustomAudience(), jak pokazano w tym przykładowym fragmencie kodu:

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

Aby oszczędzać miejsce na dane i inne zasoby urządzenia, listy odbiorców niestandardowych wygasają i są usuwane z pamięci urządzenia po upływie określonego czasu. Wartość domyślna zostanie określona. Właściciel może zastąpić tę wartość domyślną.

Kontrola sprawowana przez użytkowników

• Propozycja ma na celu udostępnienie użytkownikom listy zainstalowanych aplikacji, które utworzyły co najmniej 1 odbiorców niestandardowych.
• Użytkownicy mogą usuwać aplikacje z tej listy. Usunięcie spowoduje wyczyszczenie wszystkich niestandardowych list odbiorców powiązanych z aplikacjami i uniemożliwi aplikacjom dołączanie do nowych niestandardowych list odbiorców.
• Użytkownicy mogą całkowicie zresetować interfejs Protected Audience API. W takim przypadku wszystkie niestandardowe listy odbiorców na urządzeniu zostaną usunięte.
• Użytkownicy mogą całkowicie zrezygnować z Piaskownicy prywatności na Androidzie, w tym z interfejsu Protected Audience API. Jeśli użytkownik zrezygnował z Piaskownicy prywatności, interfejs Protected Audience API nie zgłasza błędu.

Projekt tej funkcji jest w trakcie opracowywania, a szczegóły zostaną podane w późniejszej aktualizacji.

Zaplanowane aktualizacje

Opisane wcześniej rozwiązania wymagają, aby aplikacja lub pakiet SDK technologii reklamowej wywoływały interfejsy API, gdy aplikacja jest na pierwszym planie, i podawały pełne właściwości niestandardowej listy odbiorców bezpośrednio lub za pomocą delegowania. Reklamodawcy i dostawcy technologii reklamowych nie zawsze mogą jednak określić w czasie rzeczywistym, do których list odbiorców należy użytkownik korzystający z aplikacji.

Aby to ułatwić, technologia reklamowa może wywoływać interfejs API scheduleCustomAudienceUpdate(). Ten interfejs API umożliwia wywołującemu określenie opóźnienia wywołania interfejsu API, co daje dodatkowy czas na przetwarzanie zdarzeń na poziomie aplikacji przez platformę reklamową i określanie, do których chronionych list odbiorców użytkownik powinien dołączyć lub z których powinien zostać usunięty.

/**
* API To schedule delayed update events for Custom Audience
*
* @param request Criteria that determine when and where to trigger a call to a
* DSP endpoint to update one or more Custom Audiences
*/

public void scheduleCustomAudienceUpdate(
    @NonNull ScheduleCustomAudienceUpdateRequest request,
    @NonNull @CallBackExecutor Executor executor,
    @NonNull AdServicesOutcomeReceiver<Object, Exception> receiver)

ScheduleCustomAudienceUpdateRequest

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

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

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

  //  Optional Field (default false)
  public boolean shouldReplacePendingUpdates () {
    return mShouldReplacePendingUpdates;
  }
}

ScheduleCustomAudienceUpdateRequest zawiera informacje niezbędne do zarejestrowania opóźnionego zadania, które ma być uruchomione na platformie. Po określonym opóźnieniu zadanie w tle będzie uruchamiane okresowo i będzie wysyłać żądania. ScheduleCustomAudienceUpdateRequest może zawierać te informacje:

• UpdateUri: punkt końcowy URI, do którego zostanie wysłane wywołanie GET w celu pobrania aktualizacji. Tożsamość kupującego jest domyślnie wywnioskowana z eTLD+1 i nie musi być podana wprost. Nie można jej też zmienić w odpowiedzi na aktualizację. Żądanie GET oczekuje w odpowiedzi obiektu JSON zawierającego listę obiektów customAudience.
• DelayTime: czas opóźnienia od momentu wywołania interfejsu APIscheduleCustomAudienceUpdate() do zaplanowania aktualizacji.

• PartialCustomAudience: interfejs API umożliwia też pakietowi SDK na urządzeniu wysyłanie listy częściowo utworzonych list odbiorców niestandardowych. Dzięki temu pakiety SDK w aplikacji mogą pełnić podwójną rolę – od pełnej do częściowej kontroli nad zarządzaniem listami niestandardowych odbiorców – w zależności od współpracy z platformami DSP.

  • Dzięki temu interfejs API jest też zgodny z interfejsem fetchAndJoinCustomAudience() API, który umożliwia podobne udostępnianie informacji.

• ShouldReplacePendingUpdates: wartość logiczna określająca, czy anulować oczekujące zaplanowane aktualizacje i zastąpić je aktualizacją opisaną w bieżącym ScheduleCustomAudienceUpdateRequest. Jeśli to pole ma wartość false i w przypadku tego samego kupującego w tej samej aplikacji są jeszcze oczekujące aktualizacje, wywołanie funkcji scheduleCustomAudienceUpdate z tym parametrem ScheduleCustomAudienceUpdateRequest zakończy się niepowodzeniem. Domyślna wartość to false.

Uprawnienia aplikacji i kontrola

Propozycja ma na celu zapewnienie aplikacjom kontroli nad ich listami odbiorców niestandardowych:

• Aplikacja może zarządzać powiązaniami z odbiorcami niestandardowymi.
• Aplikacja może przyznawać platformom technologii reklamowych innych firm uprawnienia do zarządzania w jej imieniu niestandardowymi listami odbiorców.

Projekt tej funkcji jest w trakcie opracowywania, a szczegóły zostaną podane w późniejszej aktualizacji.

Ustawienia platformy technologii reklamowych

Ta propozycja przedstawia sposoby, w jakie dostawcy technologii reklamowych mogą kontrolować swoje listy odbiorców niestandardowych:

• Firmy zajmujące się technologiami reklamowymi rejestrują się w Piaskownicy prywatności i podają domenę eTLD+1, która pasuje do wszystkich adresów URL niestandardowych odbiorców.
• Dostawcy technologii reklamowych mogą współpracować z aplikacjami lub pakietami SDK, aby udostępniać tokeny weryfikacyjne, które służą do weryfikowania tworzenia niestandardowych list odbiorców. Gdy ten proces jest delegowany na partnera, tworzenie niestandardowych list odbiorców można skonfigurować tak, aby wymagało potwierdzenia przez technologię reklamową.
• Technologia reklamowa może dezaktywować wywołania joinCustomAudience w imieniu użytkownika i zezwalając tylko interfejsowi fetchAndJoinCustomAudience API na włączanie wszystkich niestandardowych list odbiorców wywołań. Grupę kontrolną można zaktualizować podczas rejestracji w Piaskownicy prywatności. Pamiętaj, że to ustawienie pozwala włączyć wszystkie technologie reklamowe lub żadną z nich. Ze względu na ograniczenia platformy uprawnienia do delegowania nie mogą być przyznawane w przypadku poszczególnych technologii reklamowych.

Odpowiedź dotycząca reklam kandydujących i metadanych

Kandydujące reklamy i metadane zwracane z platformy zakupowej powinny zawierać te pola:

• Metadane: metadane reklam po stronie kupującego, które są specyficzne dla technologii reklamowych. Może to obejmować na przykład informacje o kampanii reklamowej i kryteriach kierowania, takich jak lokalizacja i język.
• URL renderowania: punkt końcowy renderowania kreacji reklamy.
• Filtr: opcjonalne informacje niezbędne do filtrowania reklam przez Protected Audience API na podstawie danych na urządzeniu. Więcej informacji znajdziesz w sekcji dotyczącej logiki filtrowania po stronie kupującego.

Proces wyboru reklamy

Ta propozycja ma na celu zwiększenie prywatności użytkowników przez wprowadzenie interfejsu Ad Selection API, który koordynuje przeprowadzanie aukcji na platformach technologii reklamowych.

Obecnie platformy technologii reklamowych przeprowadzają licytację i wybór reklam wyłącznie na swoich serwerach. Zgodnie z tą propozycją niestandardowe listy odbiorców i inne sygnały dotyczące użytkowników, np. informacje o zainstalowanych pakietach, będą dostępne tylko za pomocą interfejsu Ad Selection API. Dodatkowo w przypadku remarketingu kandydaci do wyświetlenia reklam będą pobierani poza pasmem (tzn. nie w kontekście, w którym będą wyświetlane reklamy). Platformy technologii reklamowych będą musiały przygotować się na wdrożenie i wykonywanie na urządzeniu niektórych części obecnej logiki aukcji i wyboru reklam. Platformy technologii reklamowych mogą wprowadzić w procesie wyboru reklam następujące zmiany:

• Jeśli na serwerze nie ma informacji o zainstalowanych pakietach, platformy technologii reklamowych mogą wysyłać na urządzenie wiele reklam kontekstowych i wywoływać proces wyboru reklam, aby włączyć filtrowanie na podstawie instalacji aplikacji i zwiększyć szanse na wyświetlenie trafnej reklamy.
• Reklamy remarketingowe są pobierane poza pasmem, więc obecne modele ustalania stawek mogą wymagać aktualizacji. Platformy technologii reklamowych mogą tworzyć podmodele określania stawek (implementacja może być oparta na wzorcu zwanym modelem dwuwieżowym), które mogą działać oddzielnie na podstawie funkcji reklam i sygnałów kontekstowych, a następnie łączyć na urządzeniu wyniki podmodeli, aby prognozować stawki. Może to przynieść korzyści zarówno w przypadku aukcji po stronie serwera, jak i aukcji dotyczących dowolnej możliwości wyświetlenia reklamy.

Takie podejście umożliwia wykorzystywanie danych o interakcjach użytkownika z aplikacją do wybierania reklam, a jednocześnie ogranicza udostępnianie tych danych osobom trzecim.

Ten proces wyboru reklam koordynuje wykonywanie na urządzeniu kodu JavaScript dostarczonego przez technologię reklamową w tej kolejności:

1. Wykonywanie logiki ustalania stawek po stronie kupującego
2. Filtrowanie i przetwarzanie reklam po stronie kupującego
3. Wykonywanie logiki decyzji po stronie sprzedawcy

W przypadku wyboru reklam, które obejmują niestandardowych odbiorców, platforma pobierze kod JavaScript dostarczony przez stronę kupującą na podstawie publicznego punktu końcowego adresu URL zdefiniowanego przez metadane „Adres URL logiki określania stawek” niestandardowych odbiorców. Adres URL punktu końcowego kodu decyzji po stronie sprzedawcy będzie też przekazywany jako dane wejściowe w celu zainicjowania przepływu pracy wyboru reklamy.

Projektowanie wyborów reklam, które nie obejmują odbiorców niestandardowych, jest w trakcie aktywnego projektowania.

Inicjowanie procesu wyboru reklamy

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

• Sprzedawca: identyfikator platformy reklamowej po stronie sprzedawcy w formacie eTLD+1.
• URL logiki podejmowania decyzji: gdy rozpocznie się aukcja reklam, platforma użyje tego adresu URL, aby pobrać z platformy sprzedażowej kod JavaScript, który pozwoli ocenić zwycięską reklamę.
• Kupujący korzystający z odbiorców niestandardowych: lista platform kupujących z popytem opartym na odbiorcach niestandardowych w przypadku tej aukcji, w formacie eTLD+1.
• Sygnały wyboru reklamy: informacje o aukcji (rozmiar reklamy, format reklamy itp.).
• Sygnały sprzedawcy: sygnały specyficzne dla platformy SSP.
• URL sygnałów zaufanego oceniania: URL punktu końcowego zaufanego sygnału po stronie sprzedawcy, z którego można pobierać informacje w czasie rzeczywistym dotyczące kreacji.
• Sygnały dotyczące kupującego: uczestniczące platformy popytu mogą używać tego parametru do przekazywania danych wejściowych na potrzeby aukcji. Ten parametr może na przykład zawierać obszerne informacje kontekstowe przydatne do określania stawek.

Poniższy przykładowy fragment kodu pokazuje, jak pakiet SDK platformy technologii reklamowej inicjuje proces wyboru reklamy, najpierw definiując AdSelectionConfig, a potem wywołując selectAds, aby 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

Logikę określania stawek zwykle udostępniają platformy po stronie kupującego. Celem kodu jest określanie stawek za reklamy kwalifikujące się do wyświetlenia. Może ona stosować dodatkową logikę biznesową, aby określić wynik.

Platforma użyje metadanych „Adres URL logiki określania stawek” odbiorców niestandardowych, aby pobrać kod JavaScript, który powinien zawierać następującą sygnaturę 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 będzie wywoływać tę funkcję sekwencyjnie w przypadku wszystkich reklam (kontekstowych lub remarketingowych). Jeśli jest wielu dostawców logiki ustalania stawek, system nie gwarantuje kolejności wykonywania działań przez tych dostawców.

Funkcja oczekuje tych parametrów:

• Reklama: reklama rozpatrywana przez kod licytujący po stronie kupującego. Będzie to reklama wyświetlana kwalifikującym się odbiorcom niestandardowym.
• Sygnały aukcji: sygnały specyficzne dla platformy po stronie sprzedawcy.
• Sygnały dotyczące kupującego: uczestniczące platformy popytu mogą używać tego parametru do przekazywania danych wejściowych na potrzeby aukcji. Ten parametr może na przykład zawierać obszerne informacje kontekstowe przydatne do określania stawek.
• Zaufane sygnały określania stawek: platformy technologii reklamowej korzystają z danych w czasie rzeczywistym, aby informować o pobieraniu i ocenianiu reklam. Na przykład kampania reklamowa może wyczerpać budżet i trzeba natychmiast przerwać jej wyświetlanie. Dostawca technologii reklamowych może zdefiniować punkt końcowy adresu URL, z którego można pobierać te dane w czasie rzeczywistym, oraz zestaw kluczy, dla których należy przeprowadzić wyszukiwanie w czasie rzeczywistym. Zarządzany serwer platformy technologii reklamowych, który obsługuje to żądanie, będzie zaufanym serwerem zarządzanym przez tę platformę.
• Sygnały kontekstowe: mogą obejmować przybliżoną sygnaturę czasową lub przybliżone informacje o lokalizacji albo koszt kliknięcia reklamy.
• Sygnały użytkownika: mogą obejmować informacje takie jak informacje o dostępnych zainstalowanych pakietach.

Koszt reklamy

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

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

Jeśli ta reklama wygra aukcję, wartość adCost zostanie zaokrąglona stochastycznie 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 z urządzenia dostępnych w fazie wyboru reklamy. Na przykład platformy technologii reklamowej mogą tu wdrażać funkcje ograniczenia liczby wyświetleń. Jeśli jest wielu dostawców filtrowania, system nie gwarantuje kolejności wykonywania działań przez tych dostawców.

Logikę filtrowania po stronie kupującego można wdrożyć w ramach logiki określania stawek, zwracając wartość stawki 0 w przypadku danej reklamy.

Oprócz tego platformy po stronie kupującego będą mogły sygnalizować, że dana reklama powinna być filtrowana na podstawie dodatkowych sygnałów na urządzeniu dostępnych dla Protected Audience, które nie opuszczają urządzenia. Gdy dopracujemy projekty dodatkowej logiki filtrowania, platformy po stronie kupującego będą stosować tę samą strukturę, aby sygnalizować, że filtrowanie powinno nastąpić.

Logika oceniania po stronie sprzedawcy

Logikę oceniania zwykle udostępnia platforma po stronie sprzedającego. Celem kodu jest określenie zwycięskiej reklamy na podstawie wyników logiki określania stawek. Może on stosować dodatkową logikę biznesową, aby określić wynik. Jeśli jest wielu dostawców logiki podejmowania decyzji, system nie gwarantuje kolejności wykonywania działań przez tych dostawców. Platforma użyje parametru wejściowego „Decision logic URL” interfejsu selectAds() API, aby pobrać kod JavaScript, który powinien zawierać ten 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:

• Ad: reklama podlegająca ocenie; dane wyjściowe funkcji generateBid().
• Stawka: kwota stawki wygenerowana przez funkcję generateBid().
• Auction config: parametr wejściowy metody selectAds().
• Zaufane sygnały oceny: platformy technologii reklamowych korzystają z danych w czasie rzeczywistym, aby informować o filtrowaniu i ocenianiu reklam. Na przykład wydawca aplikacji może zablokować wyświetlanie reklam w aplikacji w ramach kampanii reklamowej. Te dane są pobierane z parametru adresu URL zaufanych sygnałów oceny w konfiguracji aukcji. Serwer obsługujący to żądanie powinien być zaufanym serwerem zarządzanym przez dostawcę technologii reklamowych.
• Sygnał kontekstowy: może obejmować przybliżoną sygnaturę czasową lub przybliżone informacje o lokalizacji.
• Sygnał użytkownika: może zawierać informacje takie jak sklep z aplikacjami, który zainicjował instalację aplikacji.
• Sygnał dotyczący listy odbiorców niestandardowych: jeśli oceniana reklama pochodzi z listy odbiorców niestandardowych na urządzeniu, będzie zawierać informacje takie jak czytelnik i nazwa listy odbiorców niestandardowych.

Czas działania kodu wyboru reklamy

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

• Kod powinien zakończyć wykonywanie w określonym czasie. Ten limit będzie obowiązywać jednolicie we wszystkich sieciach reklamowych kupujących. Szczegóły tego limitu zostaną podane w późniejszej aktualizacji.
• Kod musi być samodzielny i nie może mieć żadnych zależności zewnętrznych.

Kod aukcji, np. logika określania stawek, może potrzebować dostępu do prywatnych danych użytkownika, takich jak źródła instalacji aplikacji, więc środowisko wykonawcze nie zapewni dostępu do sieci ani pamięci.

Język programowania

Kod aukcji udostępniany przez platformę technologii reklamowej powinien być napisany w języku JavaScript. Umożliwi to np. platformom technologii reklamowych udostępnianie kodu licytowania na platformach obsługujących Piaskownicę prywatności.

Renderowanie zwycięskiej reklamy

Reklama z najwyższym wynikiem jest uznawana za zwycięzcę aukcji. W tej wstępnej propozycji wygrywająca reklama jest przekazywana do pakietu SDK w celu renderowania.

Planujemy rozwinąć to rozwiązanie, aby zweryfikować, czy informacje o przynależności użytkownika do niestandardowej listy odbiorców lub historii zaangażowania w aplikację nie mogą być określane przez aplikację ani pakiet SDK na podstawie informacji o wygrywającej reklamie (podobnie jak w przypadku propozycji dotyczącej ramek ograniczonych w Chrome).

Raportowanie wyświetleń i zdarzeń

Po wyrenderowaniu reklamy zwycięskie wyświetlenie może zostać zgłoszone do uczestniczących platform po stronie kupującego i sprzedającego. Dzięki temu kupujący i sprzedawcy mogą dołączać do raportu o wyświetleniu, które wygrało aukcję, informacje z aukcji, takie jak stawka lub nazwa listy odbiorców niestandardowych. Dodatkowo platforma po stronie sprzedającego i zwycięska platforma po stronie kupującego mogą otrzymywać dodatkowe raporty na poziomie zdarzenia dotyczące zwycięskiej reklamy. Umożliwia to dołączanie do kliknięć, wyświetleń i innych zdarzeń związanych z reklamami informacji o aukcji (np. stawki czy nazwy niestandardowych odbiorców). Platforma wywołuje logikę raportowania w tej kolejności:

1. Raportowanie po stronie sprzedawcy.
2. Raportowanie po stronie kupującego.

Dzięki temu platformy po stronie kupującego i sprzedającego mogą wysyłać ważne informacje z urządzenia z powrotem na serwery, aby umożliwić działanie takich funkcji jak budżetowanie w czasie rzeczywistym, aktualizacje modelu określania stawek i dokładne procesy rozliczeniowe. Ta obsługa raportowania wyświetleń uzupełnia interfejs Attribution Reporting API.

Aby obsługiwać raportowanie zdarzeń, musisz wykonać 2 kroki: po stronie sprzedawcy i kupującego kod JavaScript musi zarejestrować, dla jakich zdarzeń ma otrzymywać raporty, a po stronie sprzedawcy trzeba raportować informacje na poziomie zdarzenia.

Protected Audience udostępnia mechanizm subskrybowania przyszłych wydarzeń związanych z wygrywającą aukcją przez rejestrowanie sygnałów. W reportResult()funkcji JavaScriptregisterAdBeacon() sprzedawcy platformy po stronie sprzedaży mogą rejestrować sygnały za pomocą funkcji registerAdBeacon() platformy. Podobnie platformy po stronie kupującego mogą wywoływać metodę registerAdBeacon() z poziomu funkcji JavaScript reportWin().

registerAdBeacon(beacons)

Urządzenie wejściowe:

• event_key: ciąg znaków określający typ interakcji, dla którego ma zostać zarejestrowane zdarzenie. Jest on używany jako klucz do wyszukiwania punktu końcowego, do którego platforma wysyła pingi podczas raportowania wyników aukcji.
• reporting_url: adres URL należący do platformy technologii reklamowej, który służy do obsługi zdarzenia.

Klucze zdarzeń to identyfikatory tekstowe należące do pakietu SDK po stronie sprzedaży, który odpowiada za raportowanie wyników aukcji. Aby można było wykonać wywołanie zwrotne, technologie reklamowe rejestrują sygnały z kluczami, które pasują do kluczy używanych przez platformę sprzedającą do raportowania zdarzeń. Nie muszą być one anonimowe, ale istnieją limity dotyczące liczby i długości kluczy, które można zarejestrować w przypadku określonych odbiorców niestandardowych. Jeśli wywoływana jest funkcja reportEvent(), platformy sprzedające, które przeprowadziły aukcję, zawsze mogą otrzymywać raporty o tych zdarzeniach. Tylko zwycięska platforma po stronie kupującego może otrzymywać te raporty.

Raportowanie po stronie sprzedawcy

Platforma wywołuje funkcję JavaScript reportResult() w kodzie dostarczonym przez platformę po stronie dostawcy, który został pobrany z parametru Decision logic URL sprzedawcy w przypadku interfejsu selectAds() API:

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 w przypadku powodzenia, dowolna inna wartość w przypadku niepowodzenia.
• Adres URL raportowania: platforma wywołuje ten adres URL zwrócony przez funkcję.
• Sygnały dla kupującego: obiekt JSON, który ma zostać przekazany do funkcji reportWinkupującego.

Platforma po stronie sprzedaży może kodować w adresie URL raportowania odpowiednie sygnały, aby uzyskać dodatkowe informacje o aukcji i wygrywającej reklamie. Może to obejmować na przykład te sygnały:

• URL renderowania reklamy
• Wysokość zwycięskiej stawki
• Nazwa aplikacji
• Identyfikatory zapytań
• Sygnały dla kupującego: aby umożliwić udostępnianie danych między platformą po stronie dostawcy a platformą po stronie popytu, platforma przekazuje tę wartość zwracaną jako parametr wejściowy do kodu raportowania po stronie popytu.

Raportowanie po stronie kupującego

Platforma wywołuje funkcję JavaScript w kodzie dostarczonym przez platformę po stronie popytu, który został pobrany z metadanych adresu URL logiki ustalania stawek niestandardowej listy odbiorców powiązanej z aukcją.reportWin()

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 tych danych.
• signals_for_buyer to wynik raportu po stronie sprzedawcy. Dzięki temu platforma SSP może udostępniać dane platformie DSP na potrzeby raportowania.
• contextual_signals zawiera informacje takie jak nazwa aplikacji, a custom_audience_signals zawiera informacje o odbiorcach niestandardowych. Inne informacje mogą zostać dodane w przyszłości.

Dane wyjściowe:

• Stan: 0 w przypadku powodzenia, dowolna inna wartość w przypadku niepowodzenia.
• Adres URL raportowania: platforma wywołuje ten adres URL zwrócony przez funkcję.

Raportowanie zdarzeń

Zgłaszanie zdarzeń raportowania jest możliwe dopiero po zakończeniu raportowania wyświetleń w przypadku aukcji. Pakiet SDK po stronie sprzedawcy odpowiada za raportowanie wszystkich zdarzeń. Platforma udostępnia interfejs API, który przyjmuje ReportEventRequest określający ostatnio przeprowadzoną aukcję, klucz zdarzenia, który jest raportowany, dane powiązane z tym kluczem, informację o tym, czy raport ma być wysyłany do kupującego czy sprzedawcy (lub do obu tych podmiotów), oraz opcjonalne zdarzenie wejściowe dla zdarzeń reklamowych. Klient określa klucz zdarzenia i zbiór 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ć AdSelectionId ostatnio przeprowadzonej aukcji pobraną z AdSelectionOutcome.
• event_key to zdefiniowany przez sprzedawcę ciąg tekstowy opisujący zdarzenie interakcji.
• event_data to ciąg znaków reprezentujący dane powiązane z parametrem event_key
• reporting_destinations to maska bitowa ustawiana za pomocą flag dostarczanych przez platformę. Może to być FLAG_REPORTING_DESTINATION_SELLER lub FLAG_REPORTING_DESTINATION_BUYER albo oba te elementy.
• input_event (opcjonalnie) 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 sekcji Integracja interfejsu Attribution Reporting API.

Gdy pakiet SDK po stronie sprzedawcy wywoła funkcję reportEvent, platforma próbuje dopasować event_key do kluczy zarejestrowanych przez kupujących i sprzedawców w funkcjach JavaScript reportWin i reportResult (w zależności od flagi reporting_destinations). Jeśli wystąpi dopasowanie, platforma wysyła żądanie POST z parametrem event_data do powiązanego reporting_url. content type żądania to zwykły tekst, a treść to event_data. To żądanie jest wysyłane w miarę możliwości i w przypadku błędu sieci, odpowiedzi z błędem serwera lub braku pasujących kluczy nie jest zgłaszany żaden błąd.

Integracja interfejsu Attribution Reporting API

Aby wspierać kupujących, którzy biorą udział w aukcji Protected Audience API, udostępniamy funkcje międzyinterfejsowe w ramach interfejsów Protected Audience API i Attribution Reporting API (ARA). Ta funkcja umożliwia dostawcom technologii reklamowych ocenę skuteczności atrybucji w przypadku różnych taktyk remarketingowych, dzięki czemu mogą oni określić, które typy odbiorców zapewniają najwyższy ROI.

Dzięki tej integracji interfejsów API platformy reklamowe mogą:

• Utwórz mapę par klucz-wartość z identyfikatorami URI, która będzie używana do 1) raportowania interakcji z reklamami i 2) rejestracji źródła.
• uwzględniać dane aukcji Protected Audience w mapowaniu kluczy po stronie źródła na potrzeby raportowania zbiorczego (za pomocą interfejsu Attribution Reporting API). Więcej informacji znajdziesz w projekcie ARA.

Gdy użytkownik zobaczy lub kliknie reklamę:

• Adres URL używany do raportowania interakcji ze zdarzeniami za pomocą Protected Audience API będzie dostarczać kupującemu niezbędne dane, które pozwolą zarejestrować wyświetlenie lub kliknięcie jako kwalifikujące się źródło w Attribution Reporting API.
• Technologia reklamowa może przekazywać wartość CustomAudience (lub inne istotne informacje kontekstowe o reklamie, takie jak miejsce docelowe reklamy lub czas jej wyświetlania) za pomocą tego adresu URL, aby te metadane mogły być przekazywane do raportów zbiorczych, gdy technologia reklamowa sprawdza zbiorczą skuteczność kampanii.

Włączanie rejestracji źródła

reportEvent() będzie akceptować nowy parametr opcjonalny InputEvent. Zwycięscy kupujący, którzy zarejestrują sygnały reklamowe, mogą wybrać, które raporty reportEvent mają być rejestrowane w interfejsach Attribution Reporting API jako zarejestrowane źródło. Nagłówek żądania Attribution-Reporting-Eligible zostanie dodany do wszystkich żądań raportowania zdarzeń wysyłanych z usługi reportEvent(). Wszystkie odpowiedzi z odpowiednimi nagłówkami ARA będą analizowane w taki sam sposób jak każda inna odpowiedź dotycząca rejestracji zwykłego źródła ARA. Więcej informacji o tym, jak zarejestrować adres URL źródła, znajdziesz w wyjaśnieniu interfejsu Attribution Reporting API.

Interfejs ARA na Androidzie obsługuje zdarzenia wyświetlenia i kliknięcia, dlatego InputEvents służą do rozróżniania tych 2 rodzajów zdarzeń. Podobnie jak w przypadku rejestracji źródła ARA, interfejs reportEvent() API zinterpretuje weryfikację platformy InputEvent jako zdarzenie kliknięcia. Jeśli wartość InputEvent jest nieprawidłowa, ma wartość null lub jej brakuje, rejestracja źródła zostanie uznana za wyświetlenie.

Uwaga: parametr eventData po aukcji może zawierać informacje poufne, dlatego platforma usuwa go z przekierowanych żądań rejestracji źródła.eventData

Przykład raportu o zaangażowaniu i konwersjach

W tym przykładzie przyjrzymy się temu z perspektywy kupującego, który jest zainteresowany powiązaniem ze sobą danych z aukcji, wyświetlonej reklamy i aplikacji do konwersji.

W tym przepływie pracy kupujący współpracuje ze sprzedawcą, aby wysłać na aukcję unikalny identyfikator. Podczas aukcji kupujący wysyła ten unikalny identyfikator wraz z danymi aukcji. Podczas renderowania i konwersji dane z wyrenderowanej reklamy są również wysyłane z tym samym unikalnym identyfikatorem. Później można użyć unikalnego identyfikatora, aby powiązać ze sobą te raporty.

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

1. Podczas wykonywania funkcji reportWin kupujący może zarejestrować sygnał reklamy, który będzie wywoływany w czasie renderowania reklamy i w przypadku określonych zdarzeń interakcji (registerAdBeacon()). Aby powiązać sygnały aukcji ze zdarzeniem reklamy, ustaw parametr auctionId jako parametr zapytania w adresie URL sygnału.
2. Podczas renderowania reklamy sygnały zarejestrowane w czasie aukcji mogą być wywoływane lub wzbogacane o dane na poziomie zdarzenia. Sprzedawca musi wywołać reportEvent() i przekazać dane na poziomie zdarzenia. Platforma wyśle ping do zarejestrowanego adresu URL sygnału reklamy kupującego, który jest powiązany z reportEvent(), które zostało wywołane.
3. Kupujący zarejestruje reklamę w interfejsie Attribution Reporting API, odpowiadając na żądania sygnału reklamy za pomocą nagłówka Attribution-Reporting-Register-Source. Aby powiązać sygnały aukcji ze zdarzeniem konwersji, ustaw wartość auctionId w adresie URL rejestracji źródła.

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

Podobny proces dotyczy sprzedawcy, który potrzebuje dostępu do danych o atrybucji. Może on też używać unikalnego identyfikatora do wysyłania z parametrem registerAdBeacon(). Wywołanie reportEvent() zawiera usługę docelową, która może służyć do wysyłania raportu zarówno do kupującego, jak i do sprzedawcy.

Zarządzany przez platformę technologii reklamowych zaufany serwer

Logika wyboru reklam wymaga obecnie informacji w czasie rzeczywistym, takich jak stan wyczerpania budżetu, aby określić, czy kandydaci do reklam powinni zostać wybrani do aukcji. Zarówno platformy po stronie kupującego, jak i po stronie sprzedającego będą mogły uzyskać te informacje z serwerów, które obsługują. Aby zminimalizować wyciek informacji poufnych z tych serwerów, proponujemy wprowadzenie następujących ograniczeń:

• Zachowania tych serwerów, opisane w dalszej części tej sekcji, nie powodują wycieku informacji o użytkownikach.
• Serwery nie będą tworzyć pseudonimowych profili na podstawie widocznych danych, czyli będą musiały być „zaufane”.

Strona kupującego: gdy strona kupującego zainicjuje logikę licytowania po stronie kupującego, platforma pobierze z zaufanego serwera zaufane dane licytowania za pomocą protokołu HTTP. Adres URL jest tworzony przez dołączenie adresu URL i kluczy obecnych w metadanych sygnałów z zaufanego określania stawek przetwarzanej grupy odbiorców niestandardowych. Pobieranie jest wykonywane tylko podczas przetwarzania reklam z list odbiorców niestandardowych na urządzeniu. Na tym etapie platforma kupująca może egzekwować budżety, sprawdzać stan wstrzymania / wznowienia kampanii, stosować kierowanie itp.

To przykładowy adres URL do pobierania danych o ustalaniu stawek na podstawie zaufanych sygnałów, które pochodzą z metadanych sygnałów ustalania stawek na podstawie zaufanych sygnałów z listy odbiorców niestandardowych:

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

Odpowiedź serwera powinna być obiektem JSON, którego klucze to key1, key2 itp., a wartości będą dostępne dla funkcji określania stawek kupującego.

Strona sprzedawcy: podobnie jak w przypadku tego procesu po stronie kupującego, strona sprzedawcy może chcieć pobrać informacje o kreacjach branych pod uwagę na aukcji. Na przykład wydawca może chcieć wymusić, aby określone kreacje nie były wyświetlane w jego aplikacji ze względu na bezpieczeństwo marki. Te informacje można pobrać i udostępnić logice aukcji po stronie sprzedawcy. Podobnie jak w przypadku wyszukiwania zaufanego serwera po stronie kupującego, wyszukiwanie zaufanego serwera po stronie sprzedającego również odbywa się za pomocą pobierania HTTP. Adres URL jest tworzony przez dołączenie adresu URL sygnałów oceny zaufania do adresów URL renderowania kreacji, dla których należy pobrać dane.

Poniżej znajduje się przykładowy adres URL, który umożliwia pobieranie informacji o kreacjach branych pod uwagę w aukcji na podstawie adresów URL renderowania kreacji:

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

Odpowiedź serwera powinna być obiektem JSON, którego klucze są adresami URL renderowania wysłanymi w żądaniu.

Serwery te działałyby w zaufany sposób, zapewniając szereg korzyści w zakresie bezpieczeństwa i prywatności:

• Wartość zwracana przez serwer dla każdego klucza jest wiarygodna i oparta tylko na tym kluczu.
• Serwer nie rejestruje zdarzeń.
• Serwer nie ma innych efektów ubocznych związanych z tymi żądaniami.

Jako mechanizm tymczasowy kupujący i sprzedawca mogą pobierać te sygnały dotyczące określania stawek z dowolnego serwera, w tym z serwera, którym sami zarządzają. W wersji produkcyjnej żądanie będzie jednak wysyłane tylko do zaufanego serwera typu klucz-wartość.

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