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

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

Ostatnie aktualizacje

Dodaliśmy informacje o harmonogramie aktualizacji niestandardowych list odbiorców.
Dodaliśmy integrację raportów atrybucji z Protected Audience API
Opublikowano oś czasu funkcji Protected Audience.
FLEDGE zostało zmienione na Protected Audience API.
Dodano propozycję przekazywania niestandardowych list odbiorców.
Usunęliśmy wymóg k-anonimowości w adresie URL dziennej aktualizacji.

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

Dzięki odbiorcom chronionym możesz:

Zarządzanie odbiorcami niestandardowymi na podstawie wcześniejszych działań użytkowników.
Rozpoczynanie aukcji na urządzeniu z obsługą pojedynczego sprzedawcy lub pośrednictwa kaskadowego.
Raporty wyświetleń ćwiczenia po wybraniu reklamy.

Na początek przeczytaj przewodnik dla programistów dotyczący Protected Audience API. Twoje opinie są dla nas cenne, bo cały czas rozwijamy Protected Audience API.

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 do niej.

Funkcja	Dostępne w podglądzie dla programistów	Dostępne w wersji beta
Raporty na poziomie zdarzenia	I kw. 2023 roku	III kw. 2023 roku
Zapośredniczenie kaskadowe,	Q1 23	IV kw. 2023 roku
Filtrowanie reklam promujących instalacje aplikacji	II kwartał 2023 r.	III kw. 2023 roku
Filtrowanie według ograniczenia liczby wyświetleń	II kwartał 2023 r.	III kw. 2023 roku
Przesyłanie reklam kontekstowych do procesu wyboru reklam w celu filtrowania	II kwartał 2023 r.	III kw. 2023 roku
Raporty o interakcjach	II kw. 2023 roku	III kwartał 2023 r.
Dołączanie do niestandardowych grup odbiorców	III kwartał 2023 r.	IV kwartał 2023 r.
płatności inne niż CPM	III kwartał 2023 r.	IV kwartał 2023 r.
Integracja ustalania stawek z usługami aukcyjnymi	III kw. 2023 roku	IV kwartał 2023 r.
Raportowanie błędów	III kw. 2023 roku	IV kwartał 2023 r.
Integracja raportów atrybucji	Nie dotyczy	IV kwartał 2023 r.
Zapośredniczenie w ramach Otwartego ustalania stawek	IV kwartał 2023 r.	IV kwartał 2023 r.
Zarządzanie walutą	I kw. 2024 roku	II kw. 2024 roku
Integracja k-anon	Nie dotyczy	II kw. 2024 roku
Integracja raportowania zbiorczego	Q3 24	IV kw. 2024 roku

Omówienie

W przypadku reklam mobilnych reklamodawcy zwykle muszą wyświetlać reklamy potencjalnie zainteresowanych użytkowników, na podstawie ich wcześniejszych interakcji do aplikacji reklamodawcy. Na przykład deweloper aplikacji SportingGoodsApp może chcieć: wyświetlać reklamy użytkownikom, którzy mają jeszcze produkty w koszyku, przypomnij użytkownikom o dokończeniu zakupu. Branża często opisuje tę sytuację ogólne pomysły w rodzaju „remarketing”, i „niestandardowe kierowanie na 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 (dawniej FLEDGE) obejmuje te interfejsy API dla platform technologii reklamowych i reklamodawców do obsługi typowych przypadki użycia związane z interakcjami, które ograniczają udostępnianie obu identyfikatorów między aplikacjami i informacjami o interakcjach użytkownika w aplikacji z innymi firmami:

Custom Audience API: koncentruje się na „niestandardowi odbiorcy” abstrakcja, która reprezentuje wyznaczoną przez reklamodawcę i odbiorców o wspólnych zamiarach. Informacje o odbiorcach są przechowywane na urządzeniu oraz można powiązać z odpowiednimi reklamami kandydującymi do danej grupy odbiorców metadanych, np. sygnały dotyczące określania stawek. Informacje te mogą służyć do określania stawek reklamodawców, filtrowania reklam i ich renderowania.
Interfejs Ad Selection API: zapewnia on ramy, które koordynują przepływy pracy platform technologicznych reklamowych, wykorzystując sygnały z urządzenia do określania „zwycięskiej” reklamy. Dokonuje tego, biorąc pod uwagę reklamy docelowe zapisane lokalnie i przeprowadzając dodatkowe przetwarzanie reklam docelowych, które platforma technologiczna reklamowa zwraca na urządzenie.

Schemat przepływu danych, który pokazuje proces zarządzania niestandardowymi listami odbiorców i wybierania reklam w Piaskownicy prywatności na urządzeniach z Androidem.

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

SportingGoodsApp chce przypomnieć swoim użytkownikom o konieczności zakupu pozostałych gadżetów w koszyku, jeśli nie dokona zakupu w ciągu 2 dni. Aplikacja SportingGoodsApp używa interfejsu API Custom Audience API, aby dodać użytkownika do listy odbiorców „produkty w koszyku”. Platforma zarządza tymi informacjami i je przechowuje listę odbiorców na urządzeniu, ograniczając udostępnianie plików osobom trzecim. SportingGoodsApp współpracuje z platformą technologii reklamowej, aby wyświetlać reklamy użytkownikom na liście odbiorców. Platforma technologii reklamowych zarządza metadanymi odbiorców tworzy listy i wyświetla reklamy kandydatów, które są udostępniane reklamie i uwzględniania ich w procesie wyboru. Platformę można skonfigurować tak, aby okresowo pobierała zaktualizowane reklamy na podstawie odbiorców w tle. Ten pomaga zachować aktualność i nieskorygowanie listy reklam kandydatów opartych na odbiorcach z żądaniami wysyłanymi do serwerów reklamowych firm zewnętrznych w momencie wystąpienia możliwości wyświetlenia reklamy (tj. kontekstowe żądanie reklamy).
Gdy użytkownik gra w FrisbeeGame na tym samym urządzeniu, może zobaczyć reklamę z przypomnieniem, by dokończyć zakup produktów pozostałych w aplikacji SportingGoodsApp koszyka na zakupy. Jest to możliwe dzięki FrisbeeGame (z reklamami zintegrowanymi) SDK), wywołując interfejs Ad Selection API, by wybrać zwycięską reklamę. użytkownika, na podstawie dowolnej listy odbiorców, do której należy (w tym przypadku np. „produkty w koszyku”, niestandardową listę odbiorców utworzoną przez SportingGoodsApp). Proces wyboru reklamy można skonfigurować tak, aby uwzględniał reklamy pobierane z reklamy platform technologicznych z serwerów Google, a także z reklam wyświetlanych na urządzeniu odbiorców oraz innych sygnałów na urządzeniu. Procedura może być też dostosowane przez platformę technologii reklamowych i pakietu SDK do wyświetlania reklam przy użyciu ustalania stawek niestandardowych logikę punktową do osiągnięcia odpowiednich celów reklamowych. Takie podejście umożliwia dane o zainteresowaniach użytkownika lub dane o interakcjach z aplikacją w celu podejmowania decyzji o wyborze reklam; ograniczając udostępnianie tych danych osobom trzecim.
Aplikacja do wyświetlania reklam lub pakiet SDK platformy technologii reklamowych renderuje wybraną reklamę.
Platforma ułatwia raportowanie wyświetleń i wyników wyboru reklam. Ta funkcja raportowania uzupełnia interfejs Attribution Reporting API. Platformy technologii reklamowych mogą dostosować do swoich potrzeb w zakresie raportowania.

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

Platformy technologii reklamowych muszą się zarejestrować, aby uzyskać dostęp do interfejsu Protected Audience API. Zobacz Aby uzyskać więcej informacji, załóż konto Piaskownicy prywatności.

Zarządzanie listami niestandardowych 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 listy odbiorców, aby: wskazywać konkretną grupę odbiorców, na przykład osobę, która ma „porzucone elementy” koszyk na zakupy lub „ukończył poziom dla początkujących” danej gry. Platforma przechowuje i przechowuje informacje o odbiorcach lokalnie na urządzeniu i nie przechowuje do których niestandardowych 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. Domyślnie jest ona ustawiona na nazwa pakietu aplikacji wywołującej.
Kupujący: sieć reklamowa kupującego, która zarządza reklamami dla tej niestandardowej grupy odbiorców. Kupujący reprezentuje również stronę, która może uzyskiwać dostęp do niestandardowej listy odbiorców i pobierać istotne informacje o reklamie. Kupujący jest określony zgodnie z formatem eTLD+1.
Nazwa:dowolna nazwa lub identyfikator niestandardowych odbiorców, np. „osoby, które porzuciły koszyk”. Ten atrybut może być używany np. jako jedno z kryteriów kierowania w kampaniach reklamowych reklamodawcy lub jako ciąg znaków zapytania w adresie URL służącym 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 niestandardowej listy odbiorców. Data ważności nie może przekroczyć maksymalnego okresu trwania w celu ograniczenia okresu ważności niestandardowego elementu z całego świata.
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 Więcej informacji znajdziesz w sekcji o pobieraniu reklam kandydujących do kierowania na odbiorców.
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ładowe sygnały: przybliżoną lokalizację użytkownika, preferowany region itd.
Zaufane dane do określania stawek: platformy technologiczne korzystają z danych w czasie rzeczywistym, aby pobierać i ocenić reklamy. Na przykład budżet reklamy może się wyczerpać i trzeba je natychmiast zatrzymać. 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 tę żądanie zostanie zaufane serwer zarządzany przez platformy technologii reklamowych.
Adres URL logiki określania stawek: adres URL, którego platforma używa do pobierania danych o stawkach. z platformy DSP. 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 renderowania. Gdy dla odbiorców niestandardowych zostanie zainicjowana aukcja, ta lista metadanych reklamy będzie które wzięto pod uwagę. 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 ograniczone zasoby na urządzeniach mobilnych liczba reklam, które można przechowywać na liście odbiorców niestandardowych, jest ograniczona.

Przekazywanie niestandardowych list 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. Protected Audience API umożliwia definiowanie i konfigurowanie niestandardowych list odbiorców przy jednoczesnej ochronie prywatności użytkowników. Aby dołączyć do listy odbiorców niestandardowych, technologie reklamowe kupujących, które nie mają pakietu SDK w aplikacjach, muszą współpracować z technologiami reklamowymi, które 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łącz do grupy niestandardowych odbiorców

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

joinCustomAudience()

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

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

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

fetchAndJoinCustomAudience()

Aplikacja lub pakiet SDK może poprosić o dołączenie do niestandardowej listy odbiorców w imieniu technika reklamowego, który nie ma obecności na urządzeniu, dzwoniąc pod 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 w pliku JSON CustomAudience w treści odpowiedzi. Pola kupującego i właściciela listy odbiorców niestandardowych to: ignorowanych (i automatycznie uzupełnianych przez interfejs API). Interfejs API narzuca też, aby adres URL codziennego odświeżania pasował do 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", ...
         ]
       }
     }
   },
   ...
 ]
}

fetchAndJoinCustomAudience() określa tożsamość kupującego na podstawie eTLD+1 z 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. Nie ma innego sposobu weryfikacji fetchUri oprócz sprawdzenia eTLD+1, a w szczególności o braku k-anon sprawdzić. Interfejs API fetchAndJoinCustomAudience() wysyła żądanie HTTP GET do fetchUri i oczekuje obiektu JSON reprezentującego niestandardową listę odbiorców. Ta sama obowiązkowe, opcjonalne ograniczenia i wartości domyślne odbiorców niestandardowych pola obiektów są stosowane do odpowiedzi. Więcej informacji o bieżącym wymaganiach i ograniczeniach znajdziesz w naszym przewodniku dla programistów.

Każda odpowiedź błędu HTTP od kupującego powoduje, że fetchAndJoinCustomAudience niepowodzenie. 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 nie powiedzie się również wtedy, gdy odpowiedź kupującego będzie nieprawidłowa. Błędy są zgłaszane do: wywołujący interfejs API odpowiedzialny za ponawianie próby z powodu tymczasowych błędów (np. serwer nie odpowiada) lub obsługa trwałych awarii (np. sprawdzanie poprawności danych). lub inne trwałe błędy w 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 powyższym przykładzie. 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ą one określone w żądaniu, muszą trzeba ustawić w odpowiedzi, bo są one wymagane do utworzenia z całego świata. Treść CustomAudience w postaci reprezentacji JSON jest częściowo zdefiniowana przez wywołującego interfejs API i jest dołączona do żądania GET do fetchUri w specjalnym nagłówku X-CUSTOM-AUDIENCE-DATA. Rozmiar serializowanej postaci wielkość danych dla niestandardowych odbiorców jest ograniczona do 8 KB. Jeśli rozmiar to przekroczono liczbę niepowodzeń wywołania interfejsu API fetchAndJoinCustomAudience.

Brak weryfikacji k-an pozwala na weryfikację kupującego za pomocą fetchUri oraz włączyć wymianę informacji między kupującym a pakietem SDK. Aby ułatwić niestandardowe weryfikację odbiorców, kupujący może token. Pakiet SDK na urządzeniu powinien zawierać ten token w elemencie fetchUri, tak aby hostowany przez kupującego punkt końcowy może pobierać zawartość listy niestandardowych odbiorców oraz użyj tokena weryfikacyjnego, by sprawdzić, czy fetchAndJoinCustomAudience() odpowiada kupującemu i pochodzi z zaufanego partnera. Aby udostępnić informacje, kupujący może zgodzić się z rozmówcą na urządzeniu informacje, które posłużą do utworzenia listy niestandardowych odbiorców, dodano jako parametry zapytania do tabeli fetchUri. Dzięki temu kupujący może sprawdzać wywołania i wykrywać, czy złośliwa technologia reklamowa nie użyła tokena weryfikacyjnego do utworzenia kilku różnych list niestandardowych odbiorców.

Uwaga na temat definicji i przechowywania tokena weryfikacyjnego

Token weryfikacyjny nie jest używany do żadnych celów przez Protected Audience API. API i jest opcjonalna.
- Kupujący może użyć tokena weryfikacyjnego, aby sprawdzić, czy odbiorcy tworzone w ich imieniu.
- Propozycja interfejsu Protected Audience API nie określa ani formatu elementu ani sposobu przenoszenia go przez kupującego do . 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.

Opuść grupę odbiorców niestandardowych

Właściciel grupy odbiorców niestandardowych może ją opuścić, nawiązując połączenie leaveCustomAudience() zgodnie z poniższym przykładowym fragmentem 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ę wartość domyślną.

Kontrola użytkowników

Propozycja ma na celu zapewnienie użytkownikom widoczności listy zainstalowanych aplikacji z którymi utworzono co najmniej 1 listę odbiorców niestandardowych
Użytkownicy mogą usuwać aplikacje z tej listy. Usunięcie spowoduje wyczyszczenie wszystkich ustawień odbiorców powiązanych z aplikacjami i uniemożliwiać aplikacjom dołączanie do nowych, niestandardowych odbiorców.
Użytkownicy mogą całkowicie zresetować Protected Audience API. W takim przypadku wszystkie dotychczasowe listy odbiorców niestandardowych na urządzeniu zostaną usunięte.
Użytkownicy mają możliwość całkowitej rezygnacji z Piaskownicy prywatności na Android, który obejmuje interfejs Protected Audience API. Jeśli użytkownik zrezygnował z używania Piaskownicy prywatności, interfejs Protected Audience API nie zgłasza błędu.

Prace nad tą funkcją wciąż trwają, a jej szczegóły zostaną zostaną uwzględnione w kolejnej aktualizacji.

Zaplanowane aktualizacje

Opisane wcześniej rozwiązania wymagają, aby pakiet SDK aplikacji lub AdTech SDK wywołał interfejsów API, gdy aplikacja działa na pierwszym planie, i przekazują pełne właściwości bezpośrednio lub za pomocą przekazywania dostępu. Reklamodawcy i dostawcy technologii reklamowych nie zawsze mogą jednak określić, do których list odbiorców należy użytkownik, w czasie korzystania przez niego z aplikacji.

Aby to ułatwić, technologie reklamowe mogą nazywać Interfejs API scheduleCustomAudienceUpdate(). Ten interfejs API umożliwia wywołującemu określenie opóźnienie w wywołaniu interfejsu API, co zapewni dodatkowy czas technologii reklamowej do przetwarzania zdarzeń na poziomie aplikacji i określania, Chronionych odbiorców, do których 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: rejestracji opóźnionego zadania, które ma zostać uruchomione na platformie. Po upływie określonego czasu zadanie w tle będzie okresowo wysyłać żądania. ScheduleCustomAudienceUpdateRequest może zawierać te informacje:

UpdateUri: punkt końcowy identyfikatora URI, do którego wysyłane jest wywołanie GET w celu pobrania aktualizacji. Tożsamość kupującego jest 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ę. GET wymaga obiektu JSON zawierającego listę obiektów customAudience w .
DelayTime: czas wskazujący opóźnienie od momentu utworzenia scheduleCustomAudienceUpdate() Wywołanie interfejsu API w celu zaplanowania aktualizacji.

PartialCustomAudience: interfejs API umożliwia też pakietowi SDK na urządzeniu wysyłanie listy. częściowo utworzonych niestandardowych list odbiorców. Umożliwia to pakietom SDK w aplikacji pełnienie podwójnej roli, od pełnej do częściowej kontroli nad zarządzaniem listami odbiorców, w zależności od współpracy z platformami DSP.
- Zapewnia to również zgodność tego interfejsu API z fetchAndJoinCustomAudience() Interfejs API, który umożliwia udostępnianie podobnych informacji.
ShouldReplacePendingUpdates: wartość logiczna wskazująca, czy są jakieś oczekujące aktualizacje. zaplanowane aktualizacje należy anulować i zastąpić aktualizacją wyszczególnioną w obecna wartość 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 aplikacji i kontrola

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.

Prace nad tą funkcją wciąż trwają, a jej szczegóły zostaną zostaną uwzględnione w kolejnej aktualizacji.

Ustawienia platformy reklamowej

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

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 weryfikowania 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 swoim imieniu i zezwolić interfejsowi API fetchAndJoinCustomAudience na aktywowanie wszystkich wywołań dotyczących niestandardowych list odbiorców. Ustawienie 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 do przekazywania dostępu nie mogą dotyczyć poszczególnych technologii reklamowych.

Odpowiedź na „Kandydat na reklamy i metadane”

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

Metadane: metadane reklam po stronie kupującego dotyczące reklam i technologii reklamowych. Na przykład: zawierać informacje o kampanii reklamowej i kryteriach kierowania, takich jak lokalizacji i języka.
URL renderowania: punkt końcowy do renderowania kreacji reklamy.
Filtrowanie: opcjonalne informacje niezbędne do tego, aby interfejs Protected Audience API mógł filtrować reklamy na podstawie danych z urządzenia. Więcej szczegółowych informacji znajdziesz w sekcji na temat kupowania z reguły filtrowania bocznego.

Proces wyboru reklamy

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

Obecnie platformy technologii reklamowych zwykle służą wyłącznie do określania stawek i wyboru reklam 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 remarketingu reklamy kandydujące będą pobierane poza zakres (tj. nie w kontekście, w którym reklamy ). Platformy technologii reklamowych będą musiały przygotować się na takie części wdrożoną i przeprowadzoną urządzenia. Platformy reklamowe mogą wprowadzić następujące zmiany w procesie wyboru reklam:

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 zakres, więc obecne modele ustalania stawek mogą wymagają aktualizacji. Platformy technologii reklamowych mogą chcieć utworzyć podmodele ustalania stawek (implementacja może opierać się na wzorcu o nazwie model z 2 wieżami) który może osobno pracować nad funkcjami reklam i sygnałami kontekstowymi, a potem łączyć danych wyjściowych modelu podrzędnego na urządzeniu w celu prognozowania stawek. 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 z aplikacją są uwzględniane przy wyborze reklam a jednocześnie ograniczać udostępnianie tych danych osobom trzecim.

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

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

Realizacja logiki ustalania stawek po stronie kupującego
Filtrowanie i przetwarzanie reklam po stronie kupującego
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. Punkt końcowy adresu URL dla jako dane wejściowe zainicjowane zostaną również kod decyzji po stronie sprzedawcy proces wyboru reklamy.

Projektowanie grup reklamowych, które nie obejmują list odbiorców niestandardowych, jest obecnie aktywnie rozwijane.

Rozpocznij proces wyboru reklamy

Gdy aplikacja musi wyświetlić reklamę, pakiet SDK platformy technologii reklamowych może zainicjować reklamę. przepływ pracy wyboru przez wywołanie metody selectAds() po utworzeniu instancji obiekt AdSelectionConfig z oczekiwanymi parametrami:

Sprzedawca: identyfikator platformy reklamowej po stronie sprzedawcy w formacie eTLD+1.
URL reguły decyzyjnej: 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.
Nabywcy niestandardowych list odbiorców: lista platform po stronie kupującego z niestandardowymi atrybutami na podstawie odbiorców w tej aukcji, zgodnie z formatem eTLD+1.
Sygnały dotyczące wyboru reklamy: informacje o aukcji (rozmiar i format reklamy). itp.).
Sygnały dla sprzedawców: sygnały specyficzne dla platformy dostawców.
URL zaufanego sygnału punktowego: adres URL punktu końcowego zaufanego sygnału po stronie sprzedawcy z której można pobrać w czasie rzeczywistym informacje o konkretnej kreacji.
Sygnały od kupujących: strony popytu mogą używać tego parametru do podawania danych 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 parametr 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);

Logika ustalania stawek po stronie kupującego

Logika ustalania stawek jest zwykle udostępniana przez platformy po stronie kupującego. Jego zadaniem jest określanie stawek dla reklam kandydatów. Może to obejmować dodatkowe do określania wyników.

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ą kwotę stawki. Platforma Wywołuj tę funkcję po kolei dla wszystkich reklam (kontekstowych lub remarketingowych). Jeśli jest wielu dostawców logiki określania stawek, system nie gwarantuje, między dostawcami.

Funkcja oczekuje tych parametrów:

Reklama: reklama brana pod uwagę przez kod ustalania stawek po stronie kupującego. Będzie to:
Sygnały z aukcji: sygnały dotyczące sprzedaży i konkretnej platformy.
Sygnały według kupującego: uczestniczące strony popytu mogą używać tego parametru, dostarczają dane wejściowe 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 adresu URL, z którego można pobrać dane w czasie rzeczywistym, oraz zestaw kluczy które należy sprawdzić w czasie rzeczywistym. Metody platformy technologii reklamowych zarządzany serwer, który obsługuje to żądanie, będzie zaufanym serwerem zarządzanym przez z platformy technologii reklamowych.
Sygnały kontekstowe: mogą obejmować przybliżoną sygnaturę czasową lub przybliżoną sygnaturę czasową. informacje o lokalizacji czy 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 okaże się zwycięska, parametr adCost jest zaokrąglony stochastycznie do 8 bitów w przypadku 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 według dodatkowych dostępnych na etapie wyboru reklamy. Na przykład platformy technologii reklamowych może zaimplementować ograniczenie liczby wyświetleń. Jeśli jest wielu dostawców filtrów, system nie gwarantuje kolejności wykonywania zadań przez tych dostawców.

Logikę filtrowania po stronie kupującego można wdrożyć w ramach reguły ustalania stawek, zwracając wartość 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. Podczas opracowywania dodatkowe zasady filtrowania, platformy po stronie kupującego będą miały tę samą strukturę. zasygnalizuje konieczność filtrowania.

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 logiki określania 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 wartości „Decision Logic URL” (Adres URL funkcji decyzyjnej). dane wejściowe selectAds() API do pobierania kodu JavaScript, który powinien uwzględnij podpis funkcji poniżej:

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

Funkcja oczekuje tych parametrów:

Reklama: reklama, która jest oceniana; dane wyjściowe funkcji generateBid().
Stawka: wartość stawki zwracana przez funkcję generateBid().
Konfiguracja aukcji: parametr wejściowy metody selectAds().
Zaufane sygnały o punktacji: platformy technologiczne korzystają z danych w czasie rzeczywistym, aby filtrować reklamy i przypisywać im punkty. 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żoną. informacje o lokalizacji.
Sygnał użytkownika: mogą one obejmować informacje, np. o sklepie z aplikacjami, rozpoczął instalację aplikacji.
Niestandardowy sygnał dotyczący odbiorców: jeśli ocena reklamy pochodzi z urządzenia. grupa odbiorców niestandardowych, będzie zawierać takie informacje, jak czytelnik i nazwa grupę niestandardowych odbiorców.

Środowisko wykonawcze kodu wyboru reklamy

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. Biorąc pod uwagę zasób ograniczeń na urządzeniach mobilnych, kod aukcji powinien być zgodny z tymi wytycznymi:

Wykonanie kodu powinno się zakończyć we wcześniej zdefiniowanym czasie. Te ograniczenia będą stosowane w taki sam sposób we wszystkich sieciach reklamowych kupujących. Szczegóły tej granicy będą udostępnione w późniejszej aktualizacji.
Kod musi być autonomiczny i nie może mieć żadnych zależności zewnętrznych.

Ponieważ kod aukcji, taki jak reguły ustalania stawek mogą wymagać dostępu do użytkownika prywatnego takich jak źródła instalacji aplikacji, środowisko wykonawcze nie udostępnia sieci ani dostępu do pamięci masowej.

Język programowania

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

Zwycięskie renderowanie reklam

Reklama z najwyższym wynikiem jest uznawana za zwycięzcę aukcji. W tym zwycięska reklama 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 użytkownika do listy niestandardowych odbiorców ani historii zaangażowania w aplikację na podstawie informacji o reklamie, która wygrała aukcję (podobnie jak w przypadku ramek ograniczonych treści w Chrome).

Raportowanie wyświetleń i zdarzeń

Po wyrenderowaniu reklamy zwycięskie wyświetlenie można zgłosić do na platformie SSP. Dzięki temu kupujący i sprzedawcy Uwzględnij informacje z aukcji, np. stawkę lub niestandardową listę odbiorców z raportem na temat zwycięskich wyświetleń. Ponadto platformy SSP zwycięska platforma po stronie kupującego może otrzymywać dodatkowe w raportach dotyczących zwycięskiej reklamy. 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:

Raporty sprzedażowe
Raportowanie po stronie kupującego.

Dzięki temu platformy po stronie kupującego i sprzedającego mogą przesyłać ważne dane informacji z powrotem do serwerów, aby umożliwić działanie takich funkcji jak określanie budżetu w czasie rzeczywistym, aktualizacji modeli określania stawek i dokładności przepływów pracy związanych z płatnościami. 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 o zdarzeniach, a strona sprzedawcy 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 reportResult() sprzedawcy JavaScript, platformy SSP mogą rejestrować beacony za pomocą funkcji registerAdBeacon() platformy. Platformy po stronie kupującego mogą też wywoływać funkcję metody registerAdBeacon() z funkcji JavaScript reportWin().

registerAdBeacon(beacons)

Urządzenie wejściowe:

event_key: ciąg tekstowy wskazujący typ interakcji, który ma zostać zarejestrowany. Służy on jako klucz do wyszukiwania punktu końcowego, który jest wywoływany przez pingi platformy raportowanie wyników aukcji.
reporting_url: adres URL należący do platformy AdTech do obsługi zdarzenia.

Klucze zdarzeń to identyfikatory ciągu znaków, które należą do pakietu SDK platformy sprzedażowej odpowiedzialnej za raportowanie wyników aukcji. Aby wywołanie zwrotne mogło się odbyć, firmy technologiczne zajmujące się reklamami rejestrują sygnały za pomocą kluczy, które pasują do kluczy używanych przez stronę sprzedającą podczas raportowania zdarzeń. Nie muszą one być k-anonimowe, chociaż można ograniczeń liczby i długości kluczy, które można zarejestrować na dla danej niestandardowej grupy odbiorców. Jeśli wywołana jest funkcja reportEvent(), platformy po stronie sprzedawcy, które przeprowadziły aukcję, zawsze mogą otrzymywać te raporty zdarzeń. Tylko wybrana platforma do zakupu reklam może otrzymywać te raporty.

Raporty sprzedażowe

Platforma wywołuje funkcję JavaScript reportResult() w zasobie kod umieszczony z boku strony pobrany z adresu URL logiki decyzyjnej sprzedawcy parametr dla 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.
URL raportowania: platforma wywołuje ten adres URL zwrócony z funkcji.
Sygnały dla kupującego: obiekt JSON, który zostanie przekazany do funkcji reportWin kupującego.

Dostawca może kodować odpowiednie sygnały w adresie URL raportowania, aby ułatwić uzyskać więcej informacji na temat aukcji i zwycięskiej reklamy. Na przykład: uwzględnij te sygnały:

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

Raportowanie po stronie kupującego

Platforma wywołuje funkcję JavaScript reportWin() w żądaniu kodu dostarczonego z boku strony pobranego z metadanych adresu URL mechanizmu ustalania stawek zbioru danych niestandardową listę odbiorców powiązaną z aukcją.

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

Urządzenie wejściowe:

Dane auction_signals i per_buyer_signals są pobierane z AuctionConfig Wszelkie informacje, które platforma po stronie kupującego musi przekazać URL raportowania może pochodzić z tego punktu odniesienia.
signals_for_buyer to wynik raportu o stronach sprzedających. Umożliwia to platformie SSP udostępnianie danych platformie SSP na potrzeby raportowania.
contextual_signals zawiera informacje takie jak nazwa aplikacji, a custom_audience_signals zawiera informacje o listach niestandardowych odbiorców. Inny powód informacje mogą zostać dodane w przyszłości.

Dane wyjściowe:

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

Raportowanie zdarzeń

Raportowanie zdarzeń jest możliwe dopiero po zakończeniu raportowania wyświetleń 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óry jest zgłaszany, 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 zdarzenie klucz i zbieranie danych do raportowania.

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

reportEvent(request)

Urządzenie wejściowe:

Wartość „ad_selection_id” musi być wartością AdSelectionId w przypadku ostatnio przeprowadzonej aukcji pobrane z AdSelectionOutcome.
event_key to ciąg znaków zdefiniowany przez klienta, który opisuje interakcję .
event_data to ciąg znaków reprezentujący dane powiązane z parametrem event_key
reporting_destinations to maska bitowa ustawiona za pomocą flag dostarczanych przez platformy. Może to być wartość FLAG_REPORTING_DESTINATION_SELLER lub FLAG_REPORTING_DESTINATION_BUYER albo obie te wartości.
Interfejs input_event (opcjonalny) służy do integracji z raportowaniem atrybucji API. Jest to obiekt InputEvent (w przypadku zdarzenia kliknięcia) lub wartość null (w przypadku zdarzenia wyświetlenia). Więcej informacji o tym parametrze znajdziesz w artykule Integracja interfejsu Attribution Reporting API.

Po wywołaniu przez pakiet SDK po stronie sprzedawcy reportEvent oraz, w zależności od reporting_destinations, platforma próbuje dopasować event_key do kluczy zarejestrowanych przez kupujących i sprzedawców w ich reportWin i reportResult funkcji JavaScript. W przypadku dopasowania platforma wysyła żądanie POST event_data do powiązanego elementu reporting_url. Typ treści żądania to zwykły tekst, a jego treść to event_data. To żądanie jest przesyłane z najlepszymi wysiłek, który kończy się niepowodzeniem w przypadku błędu sieci lub błędu serwera. lub nie znaleziono pasujących kluczy.

Integracja interfejsu 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 ocenę skuteczności atrybucji w różnych taktykach remarketingowych, dzięki czemu mogą oni zrozumieć, które typy odbiorców zapewniają najwyższy ROI.

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

Utwórz mapę klucz-wartość identyfikatorów URI, która będzie używana w obu tych miejscach 1) raportowanie interakcji z reklamą oraz 2) rejestracja źródła.
Uwzględnianie danych aukcji z aukcji z Protected Audience API po stronie źródła mapowanie kluczy do zbiorczych raportów z podsumowaniem (za pomocą raportów atrybucji API) Więcej informacji znajdziesz w propozycji projektu ARA.

Gdy użytkownik zobaczy lub kliknie reklamę:

Adres URL służący do zgłaszania tych interakcji ze zdarzeniami za pomocą Protected Audience API będzie Dostarczają kupującemu niezbędne dane, które posłużą do zarejestrowania wyświetlenia lub kliknięcia jako kwalifikujące się źródło przy użyciu interfejsu 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ć zbiorczą skuteczność kampanii.

Włączanie rejestracji źródła

reportEvent() będzie przyjmować nowy parametr opcjonalny InputEvent. Zwycięskie kupujący, którzy zarejestrują beacon, mogą wybrać, które raporty zdarzeń zarejestrowane 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. Zapoznaj się z wyjaśnieniem dotyczącym Attribution Reporting API, z których dowiesz się, jak rejestrować URL źródła.

ARA na Androidzie obsługuje zdarzenia wyświetlania i kliknięć, więc InputEvents pozwalają odróżnić te 2 typy. Tak samo jak w źródle ARA lub rejestracji, interfejs API reportEvent() zinterpretuje InputEvent jako zdarzenie kliknięcia. Jeśli InputEvent jest nieprawidłowy, nieprawidłowy lub nieprawidłowy, rejestracja źródła zostanie uznana za wyświetlenie.

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

Przykład raportowania zaangażowania i konwersji

W tym przykładzie przyjrzymy się temu z perspektywy kupującego, powiązywanie danych z aukcji, renderowanej reklamy i aplikacji do konwersji razem.

W tym przepływie pracy kupujący kontaktuje się ze sprzedawcą, by przesłać unikalny identyfikator do aukcji. Podczas aukcji kupujący wysyła ten unikalny identyfikator wraz z danymi aukcji. Podczas renderowania i konwersji dane z renderowanej reklamy z tym samym unikalnym identyfikatorem. Później można użyć tego identyfikatora do powiązania tych raportów.

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

Podczas wykonywania metody reportWin kupujący może zarejestrować beacon dla reklam, wywoływane podczas renderowania reklamy i w przypadku określonych zdarzeń interakcji (registerAdBeacon()). Aby powiązać sygnały aukcji dla zdarzenia reklamowego, jako: auctionId jako parametr zapytania adresu URL obrazu typu beacon.
Podczas renderowania reklamy beacony zarejestrowane w czasie aukcji mogą być uruchamianych lub wzbogaconych o dane na poziomie zdarzenia. Sprzedawca musi aktywować reportEvent() i przekazywać 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.
Kupujący zarejestruje reklamę za pomocą Attribution Reporting API do odpowiada na żądania obrazu typu beacon za pomocą Nagłówek Attribution-Reporting-Register-Source. Aby powiązać sygnały aukcji dla zdarzenia konwersji ustaw auctionId w polu Zarejestruj źródłowy adres URL.

Po zakończeniu tego procesu kupujący otrzyma raport z aukcji, interakcji, jak i konwersji, które można dopasować za pomocą – unikalny identyfikator, który można ze sobą powiązać.

Podobny proces ma zastosowanie w przypadku sprzedawcy, który potrzebuje dostępu do danych atrybucji. sprzedawca może też użyć unikalnego identyfikatora, aby wysłać zamówienie za pomocą registerAdBeacon(). Wywołanie reportEvent() zawiera 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, np. o wyczerpaniu budżetu określa, czy kandydaci reklam powinni zostać wybrani do aukcji. Obie opcje platformy po stronie kupującego i platformy SSP będą mogły uzyskiwać te informacje obsługiwanych serwerów. W celu zminimalizowania wycieku informacji poufnych na tych serwerach, z którymi wiąże się oferta pakietowa, wiąże się z następującymi ograniczeniami:

Działanie tych serwerów, opisane w dalszej części tej sekcji, nie spowodowałoby wyciek informacji o użytkownikach.
Serwery nie tworzą pseudonimów na podstawie dostępnych danych. czyli musi być zaufany.

Strona kupującego: gdy strona kupującego inicjuje logikę określania stawek, platforma pobiera dane o wiarygodnym określaniu stawek z usług wiarygodnego serwera za pomocą protokołu HTTP. 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 niestandardowych ustawień na urządzeniu odbiorców. Na tym etapie kupujący może wymuszać budżety, sprawdzać kampanie Wstrzymanie / wznowienie, kierowanie reklam itp.

Poniżej znajdziesz przykładowy adres URL do pobierania danych dotyczących zaufanego określania stawek na podstawie zaufanego określania stawek metadane sygnału z grupy niestandardowych odbiorców:

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

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

Strona sprzedawcy: podobnie jak w procesie po stronie kupującego opisanym powyżej, strona sprzedawcy może chcieć pobrać informacje o kreacjach uwzględnionych w aukcji. Na przykład wydawca może chcieć zablokować wyświetlanie w aplikacji określonych kreacji 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 składa się dołączając adres URL zaufanego wskaźnika oceny do adresów URL renderowania kreacji. w której przypadku trzeba pobrać dane.

Poniżej znajduje się przykładowy adres URL służący do pobierania informacji o kreacjach uwzględnionych w na podstawie adresów URL renderowania kreacji:

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

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

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

Zwracana przez serwer wartość każdego klucza może być godna zaufania, że zależy wyłącznie od wartości ten klucz.
Serwer nie wykonuje rejestrowania na poziomie zdarzenia.
Serwer nie ma żadnych innych efektów ubocznych związanych z tymi żądaniami.

Jako mechanizm tymczasowy, kupujący i sprzedawca mogą pobierać te stawki sygnałów z dowolnego serwera, w tym z tego, który jest przez niego obsługiwany. W wersji produkcyjnej żądanie zostanie jednak wysłane tylko do zaufanej serwera typu klucz-wartość.

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