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

bookmark_border Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Ostatnie aktualizacje

• Dodaliśmy informacje o harmonogramie aktualizacji niestandardowych list odbiorców.
• Dodano integrację raportowania atrybucji z Protected Audiences.
• Opublikowano oś czasu funkcji Protected Audience.
• Interfejs FLEDGE zmienił nazwę na Protected Audience API.
• Dodano propozycję dotyczącą delegowania niestandardowych list odbiorców.
• Usunęliśmy wymóg k-anonimowości w adresie URL dziennej aktualizacji.

Protected Audience jest w wersji beta i dostępny do testowania na urządzeniach publicznych.

Dzięki odbiorcom chronionym możesz:

• Zarządzaj grupami odbiorców niestandardowych na podstawie wcześniejszych działań użytkowników.
• Rozpoczynanie aukcji na urządzeniu z obsługą pojedynczego sprzedawcy lub pośrednictwa kaskadowego.
• Raportowanie wyświetleń ćwiczeń po wybraniu reklamy.

Aby zacząć, przeczytaj przewodnik dla programistów dotyczący Protected Audience. Bardzo cenimy Twoją opinię, ponieważ stale ulepszamy usługę Protected Audience.

Oś czasu

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

Omówienie

W reklamach mobilnych reklamodawcy często muszą wyświetlać reklamy potencjalnie zainteresowanym użytkownikom na podstawie ich wcześniejszego zaangażowania w aplikację reklamodawcy. Na przykład deweloper aplikacji SportingGoodsApp może wyświetlać reklamy użytkownikom, którzy mają produkty w koszyku, aby przypomnieć im o konieczności dokończenia zakupu. W branży powszechnie używa się takich ogólnych określeń jak „remarketing” i „kierowanie na niestandardową listę odbiorców”.

Obecnie te przypadki użycia są zwykle wdrażane przez udostępnianie platformom technologii reklamowych informacji kontekstowych o sposobie wyświetlania reklamy (np. nazwie aplikacji) oraz informacji prywatnych, takich jak listy odbiorców. Dzięki tym informacjom reklamodawcy mogą wybierać na swoich serwerach odpowiednie reklamy.

Interfejs Protected Audience API na Androida (wcześniej FLEDGE) obejmuje te interfejsy API dla platform reklamowych i reklamodawców, aby obsługiwać typowe przypadki użycia oparte na interakcji w sposób, który ogranicza udostępnianie identyfikatorów w aplikacjach i informacji o interakcji użytkownika z aplikacją w sposób, który ogranicza udostępnianie identyfikatorów w aplikacjach i informacji o interakcji użytkownika z aplikacją:

1. Custom Audience API: ten interfejs koncentruje się na abstrakcji „listy niestandardowych odbiorców”, która reprezentuje listę odbiorców z podobnymi zamiarami wyznaczoną przez reklamodawcę. Informacje o odbiorcach są przechowywane na urządzeniu i mogą być powiązane z odpowiednimi reklamami kandydatów dla danej grupy odbiorców oraz dowolnymi metadanymi, np. sygnałami dotyczącymi określania stawek. Informacje te mogą służyć do określania stawek reklamodawców, filtrowania reklam i ich renderowania.
2. Interfejs Ad Selection API: zapewnia on ramy, które koordynują przepływy pracy platform technologii reklamowych, wykorzystując sygnały z urządzenia do określania „zwycięskiej” reklamy przez analizowanie reklam kandydatów przechowywanych lokalnie i przeprowadzanie dodatkowego przetwarzania reklam kandydatów, które platforma technologii reklamowych zwraca na urządzenie.

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

1. SportingGoodsApp chce przypominać użytkownikom o zakupie produktów, które pozostały w koszyku, jeśli nie dokonali zakupu w ciągu 2 dni. Aplikacja SportingGoodsApp używa interfejsu API Custom Audience do dodawania użytkownika do listy odbiorców „produkty w koszyku”. Platforma zarządza tą listą odbiorców i przechowuje ją na urządzeniu, co ogranicza możliwość udostępniania jej osobom trzecim. SportingGoodsApp współpracuje z platformą technologii reklamowych, aby wyświetlać reklamy użytkownikom na liście odbiorców. Platforma technologii reklamowych zarządza metadanymi list odbiorców i udostępnia reklamy docelowe, które są dostępne do rozważenia w ramach procesu wyboru reklam. Platformę można skonfigurować tak, aby okresowo pobierała zaktualizowane reklamy na podstawie odbiorców w tle. Pomaga to w utrzymywaniu aktualnej listy reklam kandydatów opartych na danych o odbiorcach i nieskorelowanych z żądaniami wysłanymi do zewnętrznych serwerów reklamowych podczas okazji reklamowej (np. żądania reklamy kontekstowej).

2. Gdy użytkownik gra w FrisbeeGame na tym samym urządzeniu, może zobaczyć reklamę przypominającą o dokończeniu zakupu produktów w koszyku w aplikacji SportingGoodsApp. Może to osiągnąć, gdy FrisbeeGame (z integrowanym pakietem SDK reklam) wywoła interfejs Ad Selection API, aby wybrać reklamę dla użytkownika na podstawie dowolnej listy odbiorców, do której należy (w tym przykładzie lista odbiorców „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 listami odbiorców niestandardowych i innymi sygnałami na urządzeniu. Proces ten może też zostać dostosowany przez platformę adtech i pakiet SDK reklam za pomocą niestandardowej logiki ustalania stawek i punktacji, aby osiągać odpowiednie cele reklamowe. Dzięki temu dane o interesach użytkownika lub interakcjach z aplikacją mogą służyć do wyboru reklam, a jednocześnie ograniczać udostępnianie tych danych innym podmiotom.

3. Pakiet SDK aplikacji wyświetlającej reklamy lub platformy reklamowej renderuje wybraną reklamę.

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

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

Platformy adtech muszą się zarejestrować, aby uzyskać dostęp do interfejsu Protected Audience API. Więcej informacji znajdziesz w artykule Rejestracja na konto w Piaskownicy prywatności.

Zarządzanie niestandardową listą odbiorców

Niestandardowa lista odbiorców

Odbiorcy niestandardowi to grupa użytkowników o określonych zamiarach lub zainteresowaniach. Aplikacja lub pakiet SDK może używać niestandardowej grupy odbiorców, aby wskazać konkretną grupę odbiorców, np. osoby, 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 list odbiorców należy użytkownik. Listy niestandardowych odbiorców różnią się od grup zainteresowań w Chrome z Protected Audience API i nie można ich udostępniać w internecie ani aplikacjach. Pomaga to ograniczyć udostępnianie informacji o użytkownikach.

Aplikacja reklamodawcy lub zintegrowany pakiet SDK może dołączyć do listy odbiorców niestandardowych lub opuścić tę listę na podstawie np. zaangażowania użytkowników w aplikację.

Metadane niestandardowych odbiorców

Każda lista niestandardowa zawiera te metadane:

• Właściciel: nazwa pakietu aplikacji właściciela. Jest ona domyślnie ustawiana na nazwę pakietu aplikacji wywołującej.
• Kupujący: sieć reklamowa kupującego, która zarządza reklamami dla tej listy odbiorców niestandardowych. Kupujący reprezentuje też stronę, która może uzyskać dostęp do niestandardowych odbiorców i pobrać odpowiednie informacje o reklamach. Kupujący jest określany w formacie eTLD+1.
• Nazwa: dowolna nazwa lub identyfikator listy odbiorców niestandardowych, np. „użytkownicy, którzy porzucili 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 do pobierania kodu ustalania stawek.
• Czas aktywacji i czas wygaśnięcia: te pola określają przedział czasu, w którym ta lista niestandardowych odbiorców będzie aktywna. Platforma wykorzystuje te informacje do usuwania użytkowników z listy odbiorców niestandardowych. Czas wygaśnięcia nie może przekraczać maksymalnego czasu trwania, aby ograniczyć czas istnienia listy odbiorców niestandardowych.
• Adres URL aktualizacji codziennej: adres URL, którego platforma używa do regularnego pobierania reklam i innych metadanych zdefiniowanych w polach „Sygnały ustalania stawek przez użytkownika” i „Zaufane sygnały ustalania stawek”. Więcej informacji znajdziesz w sekcji Pobieranie reklam kandydatów na potrzeby list odbiorców niestandardowych.
• Sygnały dotyczące określania stawek przez użytkowników: sygnały specyficzne dla platformy technologicznej reklamowej dotyczące określania stawek za reklamy remarketingowe. Przykłady sygnałów to m.in. przybliżona lokalizacja użytkownika, preferowana lokalizacja itp.
• Zaufane dane do określania stawek: platformy technologiczne korzystają z danych w czasie rzeczywistym, aby pobierać i ocenić reklamy. Może się np. zdarzyć, że reklama wyczerpie budżet i należy natychmiast zatrzymać jej wyświetlanie. Usługa Ad-tech może zdefiniować punkt końcowy URL, z którego można pobierać 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ę technologiczną reklam.
• Adres URL kodu ustalania stawek: adres URL, którego platforma używa do pobierania kodu ustalania stawek z platformy po stronie zamawiającego. Platforma wykonuje ten krok, gdy rozpoczyna się aukcja reklamowa.
• Reklamy: lista reklam kandydatów na potrzeby listy niestandardowej odbiorców. Obejmuje to metadane reklamy specyficzne dla platformy reklamowej i adres URL do jej wyświetlenia. Gdy rozpocznie się aukcja dla listy odbiorców niestandardowych, zostanie uwzględniona ta lista metadanych reklam. Ta lista reklam będzie odświeżana za pomocą punktu końcowego z adresem URL do codziennego aktualizowania, o ile to możliwe. Ze względu na ograniczenia zasobów na urządzeniach mobilnych liczba reklam, które można przechowywać w listach niestandardowych odbiorców, jest ograniczona.

Delegowanie niestandardowej listy odbiorców

Tradycyjne definiowanie i konfigurowanie list odbiorców niestandardowych zwykle polega na korzystaniu z technologii po stronie serwera oraz integracji obsługiwanych przez technologie reklamowe we współpracy z klientem i partnerami w zakresie reklamy. Interfejs Protected Audience API umożliwia definiowanie i konfigurowanie niestandardowych list odbiorców, a zarazem zapewnia ochronę prywatności użytkowników. Aby korzystać z list odbiorców niestandardowych, dostawcy technologii reklamowych, którzy nie mają pakietu SDK w aplikacjach, muszą współpracować z dostawcami technologii reklamowych, którzy mają dostęp do urządzeń, np. z partnerami ds. pomiarów mobilnych (MMP) i platformami dostawców reklam (SSP). Interfejs Protected Audience API ma obsługiwać te pakiety SDK, zapewniając elastyczne rozwiązania do zarządzania niestandardowymi listami odbiorców. Umożliwia on wywoływanie tworzenia niestandardowych list odbiorców w imieniu kupujących przez wywołujących na urządzeniu. Ten proces nazywa się delegowaniem list odbiorców niestandardowych. Aby skonfigurować delegowanie list niestandardowych odbiorców:

Dołączanie do grupy odbiorców niestandardowych

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

joinCustomAudience()

Aplikacja lub pakiet SDK może poprosić o dołączenie do listy niestandardowych odbiorców, wywołując funkcję joinCustomAudience() po uruchomieniu 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ć żądanie dołączenia do listy niestandardowych odbiorców w imieniu dostawcy technologii reklamowych, który nie jest obecny na urządzeniu. W tym celu wywołuje 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 należący do kupującego zwraca obiekt JSON CustomAudience w ciele odpowiedzi. Pola kupującego i właściciela niestandardowych odbiorców są ignorowane (i automatycznie wypełniane przez interfejs API). Interfejs API narzuca też, aby adres URL codziennego odświeżania był 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 API fetchAndJoinCustomAudience() określa tożsamość kupującego na podstawie eTLD+1 fetchUri. Tożsamość kupującego CustomAudience jest używana do przeprowadzania tych samych kontroli rejestracji i autoryzacji aplikacji, które są przeprowadzane przez joinCustomAudience(). Nie może być zmieniana przez odpowiedź na żądanie. Właścicielem CustomAudience jest nazwa pakietu aplikacji wywołującej. fetchUri nie jest weryfikowana w żaden inny sposób niż przez sprawdzenie eTLD + 1. W szczególności nie jest sprawdzana poprawność w k-anon. Interfejs API fetchAndJoinCustomAudience() wysyła żądanie HTTP GET do interfejsu fetchUri i oczekuje obiektu JSON reprezentującego grupę odbiorców niestandardowych. W odpowiedzi są stosowane te same ograniczenia obowiązkowe, opcjonalne i wartości domyślne, które dotyczą pól niestandardowych obiektów list odbiorców. Więcej informacji o aktualnych wymaganiach i ograniczeniach znajdziesz w Przewodniku dla programistów.

Każda odpowiedź HTTP z błędem od kupującego powoduje, że fetchAndJoinCustomAudience zakończy się niepowodzeniem. W szczególności kod stanu HTTP 429 (Za dużo żądań) blokuje żądania z bieżącej aplikacji przez zdefiniowany okres. Wywołanie interfejsu API również zakończy się niepowodzeniem, jeśli odpowiedź kupującego będzie miała nieprawidłowy format. Błędy są zgłaszane do wywołującego interfejs API, który odpowiada za ponowne próby z powodu tymczasowych błędów (np. nie odpowiadający serwer) lub obsługi trwałych błędów (np. błędy walidacji danych lub inne nieprzemijające błędy komunikacji z serwerem).

Obiekt CustomAudienceFetchRequest umożliwia wywołującemu interfejs API zdefiniowanie niektórych informacji o niestandardowej liście odbiorców za pomocą opcjonalnych właściwości pokazanych w przykładzie powyżej. Jeśli wartości są ustawione w żądaniu, nie mogą zostać zastąpione przez odpowiedź kupującego otrzymaną przez platformę. Interfejs Protected Audience API ignoruje pola w odpowiedzi. Jeśli nie są ustawione w żądaniu, muszą być ustawione w odpowiedzi, ponieważ te pola są wymagane do utworzenia listy odbiorców niestandardowych. W żądaniu GET do adresu fetchUri w specjalnym nagłówku X-CUSTOM-AUDIENCE-DATA jest zawarta reprezentacja w formacie JSON treści obiektu CustomAudience częściowo zdefiniowanego przez wywołującego interfejs API. Rozmiar serializowanej postaci danych określonych dla listy niestandardowych odbiorców jest ograniczony do 8 KB. Jeśli rozmiar przekracza limit, fetchAndJoinCustomAudience wywołanie interfejsu API się nie powiedzie.

Brak sprawdzania k-anon pozwala używać fetchUri do weryfikacji kupującego i udostępniania informacji między kupującym a pakietem SDK. Aby ułatwić weryfikację listy odbiorców niestandardowych, kupujący może podać token weryfikacyjny. Pakiet SDK na urządzeniu powinien zawierać ten token w fetchUri, aby punkt końcowy hostowany przez kupującego mógł pobrać zawartość listy niestandardowych odbiorców i użyć tokena weryfikacyjnego do sprawdzenia, czy operacja fetchAndJoinCustomAudience() odpowiada kupującemu i pochodzi od zaufanej strony partnera na urządzeniu. Aby udostępnić informacje, kupujący może uzgodnić z uzytkownikiem na urządzeniu, że niektóre informacje służące do tworzenia niestandardowych list odbiorców zostaną dodane jako parametry zapytania do fetchUri. Dzięki temu kupujący może sprawdzić wywołania i sprawdzić, czy złośliwa technologia reklamowa nie użyła tokena weryfikacyjnego do utworzenia kilku różnych list odbiorców niestandardowych.

Uwaga na temat definicji i przechowywania tokena weryfikacyjnego

• Token weryfikacji 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 potwierdzić, że tworzone przez niego listy odbiorców są tworzone w jego imieniu.
  • Propozycja interfejsu Protected Audience API nie określa ani formatu tokena weryfikacyjnego, ani sposobu przekazywania przez kupującego tokena weryfikacyjnego do wywołującego. Na przykład token weryfikacyjny może być wstępnie załadowany w SDK lub na zapleczu właściciela lub może być pobierany w czasie rzeczywistym przez SDK właściciela z serwera kupującego.

Dodawanie i usuwanie odbiorców niestandardowych

Właściciel listy niestandardowej może ją opuścić, 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 urządzeniu i inne zasoby, listy niestandardowe wygasają i są usuwane z magazynu na urządzeniu po upływie określonego czasu. Wartość domyślna zostanie określona w przyszłości. Właściciel może zastąpić tę domyślną wartość.

Kontrola użytkownika

• Propozycja ma na celu umożliwienie użytkownikom wyświetlania listy zainstalowanych aplikacji, które utworzyły co najmniej 1 listę odbiorców niestandardowych.
• Użytkownicy mogą usuwać aplikacje z tej listy. Usunięcie spowoduje wyczyszczenie wszystkich niestandardowych list odbiorców powiązanych z tymi aplikacjami i uniemożliwi dołączenie ich do nowych niestandardowych list odbiorców.
• Użytkownicy mogą całkowicie zresetować Protected Audience API. Gdy tak się stanie, wszystkie istniejące na urządzeniu listy niestandardowe zostaną usunięte.
• Użytkownicy mogą całkowicie zrezygnować z używania Piaskownicy prywatności na Androidzie, w tym interfejsu Protected Audience API. Jeśli użytkownik zrezygnował z używania Piaskownicy prywatności, interfejs Protected Audience API nie zgłasza błędu.

Projektowanie tej funkcji jest w toku, 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, oraz aby przekazywały pełne właściwości listy docelowej, bezpośrednio lub za pomocą delegowania. Reklamodawcy i dostawcy technologii reklamowych nie zawsze mogą jednak określić, do których list odbiorców należy użytkownik, w czasie korzystania z aplikacji.

Aby ułatwić to zadanie, firmy technologiczne mogą wywoływać interfejs API scheduleCustomAudienceUpdate(). Ten interfejs API umożliwia wywołującemu określenie opóźnienia wywołania interfejsu API, dzięki czemu dostawca technologii reklamowej może mieć więcej czasu na przetworzenie zdarzeń na poziomie aplikacji i ustalenie, do których list odbiorców chronionych powinien dołączyć użytkownik 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;
  }
}

Plik ScheduleCustomAudienceUpdateRequest zawiera informacje potrzebne do zarejestrowania opóźnionego zadania do wykonania na platformie. Po upływie określonego czasu zadanie w tle będzie okresowo wysyłać żądania. ScheduleCustomAudienceUpdateRequest może zawierać te informacje:

• UpdateUri: identyfikator URI punktu końcowego, do którego zostanie wysłane wywołanie GET w celu pobrania aktualizacji. Tożsamość kupującego jest z zasady wywnioskowana z eTLD+1 i nie musi być podawana w zbieranych odpowiedziach. Nie można jej też zmienić w odpowiedzi na prośbę o aktualizację. Żądanie GET oczekuje obiektu JSON zawierającego listę obiektów customAudience.
• DelayTime: czas oznaczający opóźnienie od momentu wykonania wywołania interfejsu API scheduleCustomAudienceUpdate() do zaplanowania aktualizacji.

• PartialCustomAudience interfejs API umożliwia też pakietowi SDK na urządzeniu wysyłanie listy częściowo utworzonych list odbiorców niestandardowych. Umożliwia to pakietom SDK w aplikacji pełnienie podwójnej roli, od pełnej do częściowej kontroli nad zarządzaniem grupami odbiorców niestandardowych w zależności od ich współpracy z platformami DSP.

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

• ShouldReplacePendingUpdates: wartość logiczna określająca, czy oczekujące zaplanowane aktualizacje mają zostać anulowane i zastąpione aktualizacją podaną w bieżącym ScheduleCustomAudienceUpdateRequest. Jeśli to ustawienie jest ustawione na false, a w przypadku tego samego kupującego w tej samej aplikacji są nadal oczekujące aktualizacje, wywołanie funkcji scheduleCustomAudienceUpdate z tą wartością ScheduleCustomAudienceUpdateRequest zakończy się niepowodzeniem. Domyślna wartość to false.

Uprawnienia i kontrola aplikacji

Proponowane zmiany mają zapewnić aplikacjom kontrolę nad listami niestandardowych odbiorców:

• Aplikacja może zarządzać powiązaniami z listami niestandardowych odbiorców.
• Aplikacja może przyznać zewnętrznym platformom reklamowym uprawnienia do zarządzania w jej imieniu listami odbiorców niestandardowych.

Projektowanie tej funkcji jest w toku, a szczegóły zostaną podane w późniejszej aktualizacji.

Ustawienia platformy reklamowej

W tej propozycji opisujemy sposoby, w jakie dostawcy technologii reklamowych mogą kontrolować listy niestandardowych odbiorców:

• Technologie reklamowe muszą zarejestrować się w Piaskownicy prywatności i podać domenę eTLD+1, która pasuje do wszystkich adresów URL dla niestandardowej listy odbiorców.
• Firmy technologiczne zajmujące się reklamami mogą współpracować z aplikacjami lub pakietami SDK, aby udostępniać tokeny weryfikacyjne, które służą do weryfikacji tworzenia niestandardowych list odbiorców. Gdy ten proces jest delegowany do partnera, utworzenie listy niestandardowych odbiorców może być skonfigurowane tak, aby wymagało potwierdzenia przez technologię reklamową.
• Firma zajmująca się technologiami reklamowymi może dezaktywować wywołania joinCustomAudience w jej imieniu i zezwolić interfejsowi API fetchAndJoinCustomAudience na aktywowanie wszystkich wywołań dotyczących niestandardowych list odbiorców. Ustawienia można zaktualizować podczas rejestracji w Piaskownicy prywatności. Pamiętaj, że ta kontrola umożliwia korzystanie ze wszystkich technologii reklamowych lub z żadnej. Ze względu na ograniczenia platformy uprawnienia delegowania nie mogą być przyznawane na podstawie poszczególnych platform reklamowych.

Odpowiedź na „Kandydat na reklamę” i metadane

Reklamy i metadane zwracane przez platformę zakupową powinny zawierać te pola:

• Metadane:metadane reklam po stronie kupującego dotyczące reklam i technologii reklamowych. Mogą to być na przykład informacje o kampanii reklamowej i kryteriach kierowania, takie jak lokalizacja i język.
• URL renderowania: punkt końcowy do renderowania kreacji reklamy.
• Filtr: opcjonalne informacje potrzebne interfejsowi Protected Audience API do filtrowania reklam na podstawie danych na urządzeniu. Więcej informacji znajdziesz w sekcji o logika filtrowania po stronie kupującego.

Proces wyboru reklamy

Celem tej propozycji jest poprawa prywatności poprzez wprowadzenie interfejsu Ad Selection API, który koordynuje wykonywanie aukcji na platformach technologicznych reklam.

Platformy technologii reklamowych zwykle określają stawki i wybierają reklamy wyłącznie na swoich serwerach. W ramach tej propozycji listy niestandardowe i inne poufne sygnały użytkowników, takie jak informacje o dostępnych zainstalowanych pakietach, będą dostępne tylko za pomocą interfejsu Ad Selection API. Dodatkowo w przypadku użycia remarketingu reklamy docelowe będą pobierane poza pasmem (czyli nie w kontekście, w którym będą wyświetlane). Platformy technologiczne reklamowe będą musiały przygotować się do wdrożenia i wykonania na urządzeniu niektórych części logiki bieżącej aukcji i wyboru reklam. Platformy reklamowe mogą wprowadzić w swoim procesie wyboru reklam te zmiany:

• Bez informacji o zainstalowanych pakietach dostępnych na serwerze platformy technologiczne związane z reklamami mogą wysyłać na urządzenie wiele reklam kontekstowych i uruchamiać proces wyboru reklamy, aby umożliwić filtrowanie na podstawie instalacji aplikacji i maksymalizację szans na wyświetlenie trafnej reklamy.
• Reklamy remarketingowe są pobierane poza pasmem, dlatego może być konieczne zaktualizowanie bieżących modeli ustalania stawek. Platformy technologiczne związane z reklamami mogą tworzyć podmodele określania stawek (ich implementacja może być oparta na modelu zwanym modelem 2-wieżowy), które mogą działać osobno na funkcjach reklam i sygnałach kontekstowych oraz łączyć wyniki podmodeli na urządzeniu, aby przewidywać stawki. Może to przynieść korzyści zarówno w przypadku aukcji po stronie serwera, jak i aukcji dla danej możliwości wyświetlenia reklamy.

Dzięki temu dane o interakcjach użytkownika z aplikacją mogą być wykorzystywane do wyboru reklam, a jednocześnie ogranicza się udostępnianie tych danych osobom trzecim.

Ten proces wyboru reklam steruje wykonywaniem na urządzeniu kodu JavaScript dostarczonego przez technologię reklamową zgodnie z tą sekwencją:

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 selekcji reklam, które obejmują listy niestandardowych odbiorców, platforma pobiera kod JavaScript podany przez stronę kupującego na podstawie publicznego punktu końcowego adresu URL zdefiniowanego przez metadane „Adres URL reguł ustalania stawek” listy niestandardowych odbiorców. Adres URL punktu końcowego kodu decyzji po stronie sprzedawcy będzie też przekazywany jako dane wejściowe do zainicjowania przepływu pracy dotyczącego wyboru reklamy.

Projektowanie selekcji reklam, które nie obejmują list odbiorców niestandardowych, jest w trakcie aktywnego opracowywania.

Uruchamianie procesu wyboru reklamy

Gdy aplikacja musi wyświetlić reklamę, pakiet SDK platformy reklamowej może zainicjować proces wyboru reklamy przez wywołanie metody selectAds() po uruchomieniu obiektu AdSelectionConfig z oczekiwanymi parametrami:

• Sprzedawca: identyfikator platformy reklamowej po stronie sprzedawcy w formacie eTLD+1.
• URL reguły podejmowania decyzji: gdy rozpocznie się aukcja reklamowa, platforma użyje tego adresu URL do pobrania kodu JavaScript z platformy po stronie sprzedawcy, aby określić wynik reklamy zwycięskiej.
• Kupujący korzystający z list odbiorców niestandardowych: lista platform reklamowych z niestandardowymi zasobami reklamowymi opartymi na odbiorcach, która jest dostępna na potrzeby tej aukcji w formacie eTLD+1.
• Sygnały wyboru reklamy: informacje o aukcji (np. rozmiar reklamy, format reklamy).
• Sygnały sprzedawcy: sygnały specyficzne dla platformy po stronie sprzedawcy.
• Zaufane sygnały oceny URL: adres URL punktu końcowego zaufanych sygnałów po stronie sprzedawcy, z którego można pobierać informacje o konkretnym kreacji w czasie rzeczywistym.
• Sygnały od kupujących: uczestnicy popytu mogą używać tego parametru do podawania danych wejściowych do aukcji. Ten parametr może na przykład zawierać obszerne informacje kontekstowe przydatne do określania stawek.

Ten przykładowy fragment kodu pokazuje, jak pakiet SDK platformy adtech inicjuje proces wyboru reklamy. Najpierw definiuje on AdSelectionConfig, a potem wywołuje funkcję selectAds, aby uzyskać reklamę zwycięską:

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);

Zasady ustalania stawek po stronie kupującego

Logika określania stawek jest zwykle dostarczana przez platformy do zakupu reklam. Celem kodu jest określenie stawek dla reklam kandydatów. Może ona stosować dodatkową logikę biznesową do określenia wyniku.

Platforma użyje metadanych „Adres URL reguł ustalania stawek” listy niestandardowych odbiorców, aby pobrać kod JavaScript, który powinien zawierać poniższą 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ą stawkę. Platforma będzie wywoływać tę funkcję w przypadku wszystkich reklam (kontekstowych lub remarketingowych) kolejno. Jeśli jest wielu dostawców logiki ustalania stawek, system nie gwarantuje kolejności ich działania.

Funkcja oczekuje tych parametrów:

• Reklama: reklama brana pod uwagę przez kod ustalania stawek po stronie kupującego. Będzie to reklama z kwalifikującej się niestandardowej listy odbiorców.
• Sygnały aukcji: sygnały po stronie sprzedawcy, specyficzne dla platformy.
• Sygnały od kupujących: uczestnicy popytu mogą używać tego parametru do podawania danych wejściowych do aukcji. Ten parametr może na przykład zawierać obszerne informacje kontekstowe przydatne do określania stawek.
• Zaufane sygnały dotyczące określania stawek: platformy technologiczne korzystają z danych w czasie rzeczywistym, aby pobierać reklamy i przypisywać im punkty. Na przykład kampania reklamowa może wyczerpać budżet i należy natychmiast zatrzymać jej wyświetlanie. Technologia reklamowa może zdefiniować punkt końcowy URL, z którego można pobrać te dane w czasie rzeczywistym, oraz zestaw kluczy, dla których należy przeprowadzić wyszukiwanie w czasie rzeczywistym. Serwer zarządzany przez platformę adtech, który obsługuje to żądanie, będzie zaufanym serwerem zarządzanym przez tę platformę.
• Sygnały kontekstowe: mogą one obejmować przybliżony sygnaturę czasową lub przybliżone informacje o lokalizacji albo koszt kliknięcia reklamy.
• Sygnały użytkownika: mogą one obejmować informacje o dostępnych zainstalowanych pakietach.

Koszt reklamy

Oprócz stawki platformy po stronie kupującego mogą zwracać koszt kliknięcia w ramach 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 jest zwycięska, wartość adCost jest okrągławiana losowo do 8 bitów ze względu na ochronę prywatności. Zaokrąglona wartość adCost jest następnie przekazywana do parametru contextual_signals w reportWin podczas raportowania wyświetleń.

Zasady 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. Na przykład platformy technologiczne związane z reklamami mogą tu stosować ograniczenia liczby wyświetleń. Jeśli jest wielu dostawców filtrów, system nie gwarantuje kolejności wykonywania przez nich zadań.

Logika filtrowania po stronie kupującego może być implementowana w ramach logiki ustalania stawek przez zwracanie wartości stawki 0 dla danej reklamy.

Platformy po stronie kupującego będą mogły sygnalizować, że dana reklama powinna zostać odfiltrowana na podstawie dodatkowych sygnałów na urządzeniu dostępnych dla Protected Audience, które nie opuszczą urządzenia. Gdy ustabilizujemy projekty dodatkowej logiki filtrowania, platformy po stronie kupującego będą używać tej samej struktury, aby sygnalizować, że filtrowanie powinno zostać przeprowadzone.

Logika oceniania po stronie sprzedawcy

Logika punktacji jest zwykle dostarczana przez platformę po stronie sprzedającego. Celem kodu jest określenie reklamy zwycięskiej na podstawie wyników reguł ustalania stawek. Może ona stosować dodatkową logikę biznesową do określenia wyniku. Jeśli jest wielu dostawców logiki decyzji, system nie gwarantuje kolejności wykonywania działań przez tych dostawców. Platforma użyje parametru wejściowego „Adres URL logiki decyzji” interfejsu API selectAds(), aby pobrać kod JavaScript, który powinien zawierać 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, która jest oceniana; dane wyjściowe funkcji generateBid().
• Stawka: wartość stawki zwracana przez funkcję generateBid().
• Konfiguracja aukcji: parametr wejściowy do metody selectAds().
• Zaufane sygnały dotyczące oceny: platformy technologiczne reklamowe korzystają z danych w czasie rzeczywistym, aby filtrować reklamy i przypisywać im oceny. Na przykład wydawca aplikacji może zablokować wyświetlanie reklam w aplikacji w ramach kampanii reklamowej. Dane te są pobierane z zaufanych parametrów adresu URL sygnałów oceny w konfiguracji aukcji. Serwer obsługujący to żądanie powinien być zarządzany przez zaufany serwer 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, w którym rozpoczęto instalację aplikacji.
• Sygnał dotyczący listy odbiorców niestandardowych: jeśli reklama, której wynik jest obliczany, pochodzi z listy odbiorców niestandardowych na urządzeniu, zawiera ona informacje takie jak czytnik i nazwa listy odbiorców niestandardowych.

Czas wykonywania kodu wyboru reklam

W ramach propozycji system pobiera kod aukcji udostępniony przez platformę technologiczną reklam z konfigurowalnych punktów końcowych adresów URL i wykonuje 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ć działanie w określonym czasie. Te ograniczenia będą stosowane równomiernie w przypadku wszystkich sieci reklamowych kupujących. Szczegóły dotyczące tego ograniczenia zostaną podane w następnym e-mailu.
• Kod musi być samodzielny i nie może mieć żadnych zewnętrznych zależności.

Ponieważ kod aukcji, np. logika określania stawek, może wymagać dostępu do prywatnych danych użytkownika, takich jak źródła instalacji aplikacji, środowisko uruchomieniowe nie udostępnia dostępu do sieci ani pamięci masowej.

Język programowania

Kod aukcji udostępniony przez platformę AdTech powinien być napisany w języku JavaScript. Umożliwiłoby to platformom technologii reklamowych udostępnianie kodu określania stawek na różnych platformach obsługujących Piaskownicę prywatności.

Wygrywające renderowanie reklam

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

Planujemy udoskonalić rozwiązanie, aby aplikacja ani pakiet SDK nie mogły określić informacji o przynależności do listy niestandardowych odbiorców ani historii zaangażowania w aplikację na podstawie informacji o reklamie zwycięskiej (podobnie jak w przypadku ramek ograniczonych treści w Chrome).

Raportowanie wyświetleń i zdarzeń

Po wyrenderowaniu reklamy zwycięskie wyświetlenie może zostać zgłoszone do platform po stronie kupującego i sprzedającego, które biorą udział w programie. Dzięki temu kupujący i sprzedający mogą uwzględniać w raporcie o wyświetleniach z wygraną stawką informacje z aukcji, np. stawkę lub nazwę listy odbiorców niestandardowych. Dodatkowo platforma po stronie sprzedającego i wygrywająca platforma po stronie kupującego mogą otrzymywać dodatkowe raporty na poziomie zdarzenia dotyczące reklamy, która wygrała. Umożliwia to uwzględnianie informacji o aukcji (stawka, nazwa niestandardowych odbiorców itp.) w przypadku kliknięć, wyświetleń i innych zdarzeń reklamowych. 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 na serwery, aby umożliwić takie funkcje jak budżetowanie w czasie rzeczywistym, aktualizacje modelu ustalania stawek i dokładne procesy rozliczeniowe. Ta obsługa raportowania wyświetleń uzupełnia interfejs Attribution Reporting API.

Aby obsługiwać raportowanie zdarzeń, należy wykonać 2 działania: po stronie sprzedawcy i po stronie kupującego. JavaScript musi zarejestrować, jakie zdarzenia powinny otrzymywać raporty zdarzeń, a sprzedawca odpowiada za raportowanie informacji na poziomie zdarzenia.

Protected Audience udostępnia mechanizm, który umożliwia subskrybowanie przyszłych zdarzeń związanych z wygrywającą aukcją przez rejestrowanie beaconów. W funkcji JavaScript reportResult() sprzedawcy platformy po stronie sprzedawcy mogą rejestrować beacony 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 do zarejestrowania. Jest on używany jako klucz do wyszukiwania punktu końcowego, który platforma wywołuje podczas raportowania wyników aukcji.
• reporting_url: adres URL należący do platformy adtech, który służy do obsługi zdarzenia.

Klucze zdarzeń to ciągi znaków będące własnością pakietu SDK po stronie sprzedawcy, który odpowiada za raportowanie wyników aukcji. Aby wywołanie zwrotne mogło się odbyć, technologie reklamowe rejestrują beacony za pomocą kluczy, które pasują do kluczy używanych przez stronę sprzedającą podczas raportowania zdarzeń. Nie muszą być k-anonimiczne, ale są ograniczenia dotyczące liczby i długości kluczy, które można zarejestrować na danej liście odbiorców niestandardowych. Jeśli wywołana zostanie funkcja reportEvent(), platformy po stronie sprzedawcy, które przeprowadziły aukcję, zawsze mogą otrzymywać te raporty zdarzeń. Tylko platforma do zakupu reklam, która wygrała aukcję, może otrzymywać te raporty.

Raportowanie po stronie sprzedawcy

Platforma wywołuje funkcję JavaScript reportResult() w kodzie po stronie dostawcy pobranym z adresu URL logiki decyzji sprzedawcy w przypadku interfejsu 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 w przypadku powodzenia, dowolna inna wartość w przypadku niepowodzenia.
• Adres URL raportowania: platforma wywołuje ten adres URL zwracany przez funkcję.
• Sygnały dla kupującego: obiekt JSON, który zostanie przekazany do funkcji reportWin kupującego.

Usługodawca może zakodować w adresie URL raportowania odpowiednie sygnały, aby uzyskać więcej informacji o aukcji i reklamie zwycięskiej. Może ona na przykład obejmować te sygnały:

• Adres URL renderowania reklamy
• Wysokość zwycięskiej stawki
• Nazwa aplikacji
• Identyfikatory zapytań
• sygnały dla kupującego: aby umożliwić udostępnianie danych po stronie podaży i 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 reportWin() w kodzie po stronie popytu pobranym z metadanych adresu URL logiki ustalania stawek listy niestandardowych odbiorców powiązanej 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:

• Wartości auction_signals i per_buyer_signals są pobierane z AuctionConfig. Wszystkie informacje, które platforma po stronie kupującego musi przekazać do adresu URL raportowania, mogą pochodzić z tego źródła danych.
• signals_for_buyer to wynik funkcji reportResult po stronie sprzedawcy. Umożliwia to platformie SSP udostępnianie danych platformie DSP na potrzeby raportowania.
• contextual_signals zawiera informacje takie jak nazwa aplikacji, a custom_audience_signals zawiera informacje o listach niestandardowych odbiorców. W przyszłości możemy dodać inne informacje.

Dane wyjściowe:

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

Raportowanie zdarzeń

Raportowanie zdarzeń jest możliwe dopiero po zakończeniu raportowania wyświetleń w ramach aukcji. Pakiet SDK po stronie sprzedawcy odpowiada za raportowanie zdarzeń. Platforma udostępnia interfejs API, który przyjmuje parametr ReportEventRequest określający niedawno przeprowadzoną aukcję, klucz zdarzenia, które jest zgłaszane, dane powiązane z tym kluczem, informacje o tym, czy raport ma być wysyłany do kupującego, sprzedającego (lub do obu) oraz opcjonalne zdarzenie wejściowe dotyczące zdarzeń reklamowych. Klient definiuje klucz zdarzenia i zbiór danych, które mają być raportowane.

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 z niedawno przeprowadzonej aukcji pobranej z poziomu AdSelectionOutcome.
• event_key to ciąg znaków zdefiniowany po stronie sprzedawcy, opisujący zdarzenie interakcji.
• event_data to ciąg znaków reprezentujący dane powiązane z elementem event_key.
• reporting_destinations to maska bitowa ustawiona za pomocą flag dostarczonych przez platformę. Może to być wartość FLAG_REPORTING_DESTINATION_SELLER lub FLAG_REPORTING_DESTINATION_BUYER albo obie te wartości.
• input_event (opcjonalnie) służy do integracji z interfejsem Attribution Reporting API. Jest to obiekt InputEvent (w przypadku zdarzenia kliknięcia) lub 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łuje funkcję reportEvent, platforma próbuje dopasować parametr event_key do kluczy zarejestrowanych przez kupujących i sprzedających w funkcjach JavaScript reportWin i reportResult.reporting_destinations Jeśli występuje dopasowanie, platforma wysyła event_data do powiązanego reporting_url. Typ treści żądania to zwykły tekst, a jego treść to event_data. Żądanie to jest wysyłane w ramach podejmowania przez Google wszelkich możliwych starań i w przypadku błędu sieci lub serwera lub braku pasujących kluczy nie powoduje żadnego błędu.

Integracja z interfejsem Attribution Reporting API

Aby ułatwić kupującym udział w aukcji Protected Audience, udostępniamy funkcje interfejsów Protected Audience API i Attribution Reporting API (ARA). Ta funkcja umożliwia specjalistom ds. technologii reklamowych ocenianie skuteczności atrybucji w różnych taktykach remarketingowych, dzięki czemu mogą oni dowiedzieć się, które typy odbiorców zapewniają najwyższy ROI.

Dzięki tej integracji interfejsów API firmy z branży adtech mogą:

• Utwórz mapę par klucz-wartość identyfikatorów URI, która będzie używana do: 1) raportowania interakcji z reklamą i 2) rejestracji źródła.
• Uwzględnij dane aukcji z aukcji chronionych odbiorców w mapowaniu kluczy po stronie źródła na potrzeby raportowania zbiorczego (za pomocą interfejsu Attribution Reporting API). Więcej informacji znajdziesz w propozycji dotyczącej interfejsu ARA.

Gdy użytkownik widzi lub klika reklamę:

• Adres URL używany do raportowania interakcji z tymi zdarzeniami za pomocą interfejsu Protected Audience API udostępnia kupującemu niezbędne dane, które są wykorzystywane do rejestrowania wyświetleń lub kliknięć jako kwalifikujących się źródeł w interfejsie Attribution Reporting API.
• Technologia reklamowa może przekazać CustomAudience (lub inne odpowiednie informacje kontekstowe o reklamie, np. o miejscu jej umieszczenia lub czasie wyświetlania) za pomocą tego adresu URL, aby te metadane mogły być propagowane do raportów zbiorczych, gdy technologia reklamowa będzie sprawdzać łączną skuteczność kampanii.

Włączanie rejestrowania źródeł

reportEvent() będzie przyjmować nowy opcjonalny parametr InputEvent. Zwycięskie oferty kupujących, którzy rejestrują sygnały reklamowe, mogą wybierać, które raporty o zdarzeniach są rejestrowane w interfejsach Attribution Reporting API jako zarejestrowane źródło. Do wszystkich żądań raportowania zdarzeń wysyłanych z adresu reportEvent() zostanie dodany nagłówek żądania Attribution-Reporting-Eligible. Odpowiedzi z odpowiednimi nagłówkami ARA będą analizowane tak samo jak inne zwykłe odpowiedzi ARA. Aby dowiedzieć się, jak zarejestrować źródłowy adres URL, zapoznaj się z objaśnieniami dotyczącymi interfejsu Attribution Reporting API.

Ponieważ ARA na Androida obsługuje zdarzenia wyświetlenia i kliknięcia, do rozróżniania tych 2 typów służą InputEvents. Podobnie jak w przypadku rejestracji źródeł ARA interfejs reportEvent() API interpretuje zweryfikowane przez platformę zdarzenie InputEvent jako zdarzenie kliknięcia. Jeśli wartość InputEvent jest nieprawidłowa, pusta lub nieobecna, rejestracja źródła zostanie uznana za wyświetlenie.

Pamiętaj, że dane eventData po aukcji mogą zawierać informacje poufne, dlatego platforma usuwa je w przekierowanych żądaniach rejestracji źródeł.eventData

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 uzgadnia z sprzedawcą, aby wysłać do aukcji unikalny identyfikator. Podczas aukcji kupujący wysyła ten unikalny identyfikator wraz z danymi aukcji. Podczas renderowania i konwersji dane z wyrenderowanej reklamy są też wysyłane z tym samym unikalnym identyfikatorem. Później można użyć tego identyfikatora do powiązania tych raportów.

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

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

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

Podobna procedura dotyczy sprzedawcy, jeśli potrzebuje on dostępu do danych atrybucji. Sprzedawca może też wysyłać niepowtarzalny identyfikator za pomocą registerAdBeacon(). Wywołanie reportEvent() zawiera usługę docelową, której można użyć do wysłania raportu zarówno do kupującego, jak i sprzedawcy.

Zaufany serwer zarządzany przez platformę technologiczną reklam

Logika wyboru reklam wymaga obecnie informacji w czasie rzeczywistym, takich jak stan wyczerpania budżetu, aby określić, czy reklamy kandydatów powinny być wybrane do udziału w 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ć ryzyko wycieku informacji poufnych na tych serwerach, proponujemy wprowadzić następujące ograniczenia:

• Działania tych serwerów, opisane w dalszej części tej sekcji, nie prowadzą do wycieku informacji o użytkownikach.
• Serwery nie będą tworzyć profili pseudonimowych na podstawie danych, które widzą. Muszą być one „zaufane”.

Strona kupującego: gdy strona kupującego inicjuje logikę określania stawek, platforma pobiera dane z usług wiarygodnego określania stawek za pomocą protokołu HTTP z usług wiarygodnego określania stawek. Adres URL jest tworzony przez dołączenie adresu URL i kluczy obecnych w metadanych Signali zaufanych stawek dotyczących przetwarzanej niestandardowej grupy odbiorców. Pobieranie odbywa się tylko podczas przetwarzania reklam z uwzględnieniem niestandardowych list odbiorców na urządzeniu. Na tym etapie strona kupująca może narzucać budżety, sprawdzać stan wstrzymania / wznowienia kampanii, stosować kierowanie itp.

Poniżej podano przykładowy adres URL służący do pobierania danych z zaufanego ustalania stawek na podstawie metadanych sygnału zaufanego ustalania stawek z listy niestandardowej:

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

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

Strona sprzedawcy: podobnie jak w przypadku procesu po stronie kupującego opisanego powyżej, strona sprzedawcy może chcieć pobrać informacje o kreacjach uwzględnionych w aukcji. Na przykład wydawca może chcieć, aby w jego aplikacji nie wyświetlały się określone kreacje 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 zaufanych serwerów po stronie kupującego, wyszukiwanie zaufanych serwerów po stronie sprzedającego również odbywa się za pomocą pobierania HTTP. Adres URL jest tworzony przez dołączenie do adresu URL zaufanych sygnałów oceny adresów URL renderowania kreacji, z których mają zostać pobrane dane.

Poniżej znajduje się przykładowy adres URL do pobierania informacji o kreacjach uwzględnianych 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 to adresy URL renderowania wysłane w żądaniu.

Serwery te działałyby w zaufany sposób, zapewniając kilka korzyści związanych z bezpieczeństwem i prywatnością:

• Wartość zwracana przez serwer dla każdego klucza jest obliczana tylko na podstawie tego klucza.
• Serwer nie wykonuje rejestrowania na poziomie zdarzenia.
• Serwer nie ma żadnych innych efektów ubocznych związanych z tymi żądaniami.

Jako tymczasowy mechanizm kupujący i sprzedający mogą pobierać te sygnały dotyczące określania stawek z dowolnego serwera, w tym z serwera, który sami obsługują. W wersji produkcyjnej żądanie zostanie jednak wysłane tylko do zaufanej serwera typu klucz-wartość.

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