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 API.
FLEDGE zostało zmienione na Protected Audience API.
Dodano propozycję przekazywania niestandardowych list odbiorców.
Usunięto wymaganie dotyczące k-anonimowości w codziennej aktualizacji Adres URL.

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

Protected Audience API umożliwia:

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

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

Oś czasu

W najbliższych miesiącach wprowadzimy 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 wersji przedpremierowej dla programistów	Dostępne w wersji beta
Raporty na poziomie zdarzenia	I kw. 2023 roku	III kw. 2023 roku
Zapośredniczenie kaskadowe,	I kw. 2023 roku	IV kw. 2023 roku
Filtrowanie reklam promujących instalacje aplikacji	II kw. 2023 roku	III kw. 2023 roku
Filtrowanie limitów wyświetleń na użytkownika	II kwartał 2023 r.	III kw. 2023 roku
Przekazywanie reklam kontekstowych do procesu wyboru reklamy na potrzeby filtrowania	II kw. 2023 roku	III kw. 2023 roku
Raportowanie interakcji	II kw. 2023 roku	III kwartał 2023 r.
Dołącz do przekazywania dostępu do niestandardowych odbiorców	III kw. 2023 roku	IV kwartał 2023 r.
płatności bez CPM,	III kwartał 2023 r.	IV kw. 2023 roku
Integracja z usługami określania stawek i aukcji	III kw. 2023 roku	IV kw. 2023 roku
Raportowanie debugowania	III kw. 2023 roku	IV kw. 2023 roku
Integracja raportów atrybucji	Nie dotyczy	IV kw. 2023 roku
Zapośredniczenie z Otwartym ustalaniem stawek	IV kw. 2023 roku	IV kw. 2023 roku
Zarządzanie walutami	Q1 '24	II kw. 2024 roku
Integracja k-anon	Nie dotyczy	Q2 24
Integracja raportów zbiorczych	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ą zazwyczaj wdrażane przez udostępnianie informacje o sposobie wyświetlania reklamy (np. nazwa aplikacji) i o tym, jak jest ona prywatna; np. listy odbiorców na platformach technologii reklamowych. Użycie tego informacje, 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ę o podobnych 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. Te informacje mogą służyć do przekazywania informacji, stawki reklamodawcy, a także filtrowanie i renderowanie.
Ad Selection API: zapewnia środowisko, które pozwala administruje platformami technologii reklamowych procesów, które wykorzystują sygnały z urządzenia, określić najlepszy wynik, z uwzględnieniem przechowywanych lokalnie reklam kandydatów dodatkowe przetwarzanie reklam kandydatów, na urządzenie.

Schemat przepływu danych, który pokazuje proces zarządzania listami niestandardowych 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. SportingGoodsApp korzysta z interfejsu Custom Audience API, aby dodać użytkownika do: „produkty w koszyku” listę odbiorców. 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, by 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, okresowo pobieraj w tle zaktualizowane reklamy oparte na odbiorcach. 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).
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. 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 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 oraz inne sygnały z urządzenia. Proces ten można 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 umożliwia raportowanie wyświetleń i wybór reklam wyników. Ta funkcja raportowania jest uzupełniające raporty atrybucji API. Platformy technologii reklamowych mogą dostosować do swoich potrzeb w zakresie raportowania.

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

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

Zarządzanie niestandardowymi odbiorcami

Niestandardowa lista odbiorców

Niestandardowa lista odbiorców to grupa użytkowników określona przez reklamodawcę. o wspólnych zamiarach lub interesach. 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 informacje o odbiorcach lokalnie na urządzeniu i nie ujawnia, do których list odbiorców niestandardowych 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 mogą dołączyć lub opuścić niestandardową grupę odbiorców na podstawie np. użytkownika zaangażowanie w aplikację.

Metadane niestandardowych odbiorców

Każda niestandardowa lista odbiorców 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”. Tego atrybutu można użyć np. jako jednego z kryteriów kierowania w kampaniach reklamowych reklamodawcy albo ciąg zapytania w adresie URL służący do pobierania kod ustalania stawek.
Czas aktywacji i okres ważności: te pola określają godzinę. okres, w którym ta niestandardowa lista odbiorców zacznie działać. Platforma używa tego informacje potrzebne do rezygnacji z członkostwa na liście niestandardowych odbiorców. Data ważności nie może przekroczyć maksymalnego okresu trwania w celu ograniczenia czasu życia 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 informacji znajdziesz w sekcji Pobieranie reklam kandydatów na potrzeby list odbiorców niestandardowych.
Sygnały dotyczące określania stawek przez użytkownika: sygnały specyficzne dla platformy technologii reklamowych w przypadku dowolnych określania stawek reklam remarketingowych. Przykładowe sygnały: przybliżoną lokalizację użytkownika, preferowany region itd.
Zaufane dane dotyczące określania stawek: platformy technologii reklamowych działają w oparciu o dane w czasie rzeczywistym. na potrzeby pobierania i oceniania reklam. Na przykład budżet reklamy może się wyczerpać i trzeba je natychmiast zatrzymać. Technologie reklamowe mogą zdefiniować adres URL punktu końcowego, z którego można pobrać dane w czasie rzeczywistym, oraz zestaw kluczy które należy przeprowadzić 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 reklam.
Reklamy: lista reklam kandydujących do niestandardowej listy odbiorców. Obejmuje to m.in. metadane reklamy związane z konkretną platformą technologii reklamowych oraz adres URL służący do renderowania reklamy. 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 urządzeń mobilnych Ograniczenie liczby reklam, które można przechowywać na niestandardowej liście odbiorców.

Delegowanie niestandardowych list odbiorców

Tradycyjna definicja i konfiguracja odbiorców niestandardowych zwykle zależy technologii i integracji po stronie serwera obsługiwanych przez technologie reklamowe we współpracy klientów i partnerów agencji oraz reklamodawców. Protected Audience API umożliwia definiowanie i konfigurowanie niestandardowych list odbiorców przy jednoczesnej ochronie prywatności użytkowników. Do dołączą do grupy niestandardowych odbiorców – kupujący, którzy korzystają z technologii reklamowych, które nie korzystają z pakietów SDK w aplikacjach muszą współpracować z ekspertami ds. technologii reklamowych, którzy korzystają z urządzeń, np. z reklamodawcą partnerów świadczących usługi pomiarowe (MMP) i platform dostawców (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 ono wywoływanie tworzenia niestandardowych list odbiorców w imieniu kupujących przez wywołujących na urządzeniu. Ten proces nazywamy niestandardowymi odbiorcami . Aby skonfigurować przekazywanie dostępu do niestandardowych list odbiorców, wykonaj te czynności:

Dołącz do grupy niestandardowych odbiorców

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

joinCustomAudience()

Aplikacja lub pakiet SDK może poprosić o dołączenie do niestandardowej listy odbiorców, wywołując joinCustomAudience() po utworzeniu wystąpienia obiektu CustomAudience 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. Do realizacji transakcji używana jest tożsamość kupującego CustomAudience te same testy rejestracji i autoryzacji aplikacji przeprowadzone przez platformę joinCustomAudience() i nie może zostać zmieniona przez odpowiedź pobierania. Właścicielem domeny CustomAudience jest nazwę 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 k-anon. 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 dotyczy to blokad stanu HTTP 429 (Za dużo żądań). żądań z bieżącej aplikacji w zdefiniowanym okresie. 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ącego interfejs API, który odpowiada za ponowne próby z powodu tymczasowych błędów (np. serwer nie odpowiada) lub obsługi trwałych błędów (np. błędy walidacji danych lub inne nieprzemijające błędy komunikacji z serwerem).

Obiekt CustomAudienceFetchRequest pozwala wywołującemu interfejs API zdefiniować za pomocą opcjonalnych właściwości widocznych w w powyższym przykładzie. Jeśli te wartości są ustawione w żądaniu, nie można ich zastąpić przez odpowiedź kupującego otrzymaną przez platformę; 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. Reprezentacja zawartości pola CustomAudience w formacie JSON jako częściowo zdefiniowane przez obiekt wywołujący API jest uwzględniony w żądaniu GET wysyłanym 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 i wykrywać, czy token weryfikacyjny został użyty przez szkodliwą technologię reklamową do tworzyć kilka różnych grup niestandardowych odbiorców.

Uwaga na temat definicji i miejsca na dane 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.

Dodawanie i usuwanie 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 ograniczyć wykorzystanie miejsca na dane i innych zasobów urządzenia, niestandardowe listy odbiorców tracą ważność i są usuwane ze sklepu na urządzeniu po upływie obecnie się znajdujesz. Wartość domyślna jest do ustalenia. 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 istniejące na urządzeniu listy niestandardowe 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 wyraził zgodę poza Piaskownicą prywatności interfejs Protected Audience API kończy się niepowodzeniem.

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. Jednak nie zawsze reklamodawcy i dostawcy technologii reklamowych mogą określać grupy odbiorców, w czasie rzeczywistym podczas korzystania 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 opóźnienia zadanie w tle będzie uruchamiane okresowo i wysyła żądania. ScheduleCustomAudienceUpdateRequest może zawierać te informacje:

UpdateUri: punkt końcowy URI, do którego zostanie wysłane wywołanie GET w celu pobrania aktualizacji. Tożsamość kupującego jest z natury wywnioskowana z domeny eTLD+1 i nie musi jest jawnie podany i nie można go zmienić w odpowiedzi na żądanie aktualizacji. Żądanie GET oczekuje obiektu JSON zawierającego listę obiektów customAudience.
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 wyświetlanie reklam przez pakiety SDK w aplikacji podwójną rolę: od pełnej kontroli do częściowej kontroli nad zarządzaniem odbiorcami niestandardowymi. na podstawie 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 ta opcja jest ustawiona na false i istnieją jeszcze oczekujące żądania aktualizacji dla tego samego kupującego ta sama aplikacja, połączenie z numerem scheduleCustomAudienceUpdate z tym elementem Błąd ScheduleCustomAudienceUpdateRequest. Domyślna wartość to false.

Uprawnienia aplikacji i kontrola nad nimi

Oferta ma zapewnić aplikacjom kontrolę nad niestandardowymi odbiorcami:

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

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 rejestrują się w Piaskownicy prywatności i udostępniają domenę eTLD+1, która dopasowuje wszystkie adresy URL odbiorców niestandardowych.
Techniki reklamowe mogą współpracować z aplikacjami lub pakietami SDK, aby dostarczać tokeny weryfikacyjne, które są służy do weryfikacji utworzonej grupy odbiorców niestandardowych. Po przekazaniu tego procesu do partnera, można skonfigurować tworzenie niestandardowych list odbiorców tak, aby wymagało potwierdzenia w dziedzinie technologii reklamowych.
Technologia reklamowa może dezaktywować połączenia typu joinCustomAudience w jego imieniu i zezwalaj interfejsowi API fetchAndJoinCustomAudience na włączanie wszystkich wywołań niestandardowych odbiorców. Ustawienie można zaktualizować podczas rejestracji w Piaskownicy prywatności. Zwróć uwagę na pozwala wybrać wszystkie technologie reklamowe albo żaden. Ze względu na ograniczenia platformy uprawnienia do przekazywania dostępu nie mogą dotyczyć poszczególnych technologii reklamowych.

Odpowiedź dotycząca reklam i metadanych kandydatów

Reklamy i metadane kandydatów zwracane z platformy po stronie kupującego powinny zawierać parametr tych pól:

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 lokalizację i język.
URL renderowania: punkt końcowy 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

Ta propozycja ma na celu zwiększenie prywatności przez wprowadzenie funkcji wyboru reklam API, który zarządza przebiegiem aukcji na platformach technologii reklamowych.

Obecnie platformy technologii reklamowych zwykle służą wyłącznie do określania stawek i wyboru reklam na swoich serwerach. W ramach tej oferty niestandardowi odbiorcy i inni użytkownicy o charakterze kontrowersyjnym takie jak informacje o zainstalowanym pakiecie, 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 technologii reklamowych mogą rozważyć następujące zmiany w swojej reklamie proces wyboru:

Bez informacji o zainstalowanym pakiecie na serwerze platformy mogą wysyłać do urządzenia wiele reklam kontekstowych, Wywołaj przepływ pracy wyboru reklamy, aby włączyć filtrowanie na podstawie instalacji aplikacji po kolei pod kątem maksymalizacji szans na wyświetlenie trafnej reklamy.
Reklamy remarketingowe są pobierane poza pasmem, dlatego może być konieczne zaktualizowanie bieżących modeli ustalania stawek. 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 aukcji i aukcji po stronie serwera dla danej 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 reklamy administruje wykonywaniem na urządzeniu kod JavaScriptu technologii reklamowych na podstawie w następującej kolejności:

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

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 logiki 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.

Reklamy, które nie korzystają z niestandardowych list odbiorców, są aktywne projektu.

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 SSP, podany zgodnie z aktualizacją eTLD+1 format
Adres URL mechanizmu decyzyjnego: po zainicjowaniu aukcji reklam platforma użyje opcji ten adres URL do pobrania kodu JavaScript z platformy SSP, aby obliczyć zwycięską reklamę.
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 według kupującego: uczestniczące strony popytu mogą używać tego parametru, dostarczają dane wejściowe do aukcji. Na przykład ten parametr może zawierać szczegółowe informacje kontekstowe przydatne przy określaniu stawek.

Ten przykładowy fragment kodu pokazuje, jak pakiet SDK platformy technologii reklamowych inicjuje procesu wyboru reklamy – najpierw zdefiniować AdSelectionConfig, a potem wywołanie metody selectAds, aby uzyskać zwycięską reklamę:

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

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

Logika ustalania stawek po stronie kupującego

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 rezultatów i logiki biznesowej.

Platforma będzie korzystać z ustawienia „Adres URL logiki określania stawek” dla listy odbiorców niestandardowych do pobierz kod JavaScript, który powinien zawierać poniższy podpis funkcji:

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

Metoda generateBid() zwraca obliczoną stawkę. 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 uwzględniana przy użyciu kodu 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. Na przykład ten parametr może zawierać szczegółowe informacje kontekstowe przydatne przy określaniu 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 w kampanii reklamowej mogą skończyć się budżetu i trzeba je natychmiast zatrzymać. 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. 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ą obejmować przybliżoną sygnaturę czasową lub przybliżoną sygnaturę czasową. informacje o lokalizacji czy koszt kliknięcia reklamy.
Sygnały dotyczące użytkowników: mogą one obejmować informacje m.in. o dostępnych instalacjach informacje o przesyłce.

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ść zmiennej adCost jest następnie przekazywana do funkcji contextual_signals w reportWin podczas raportowania wyświetleń.

Logika filtrowania po stronie kupującego

Platformy po stronie kupującego będą mogły filtrować reklamy na podstawie dodatkowych sygnałów na urządzeniu dostępnych na etapie wyboru reklamy. Na przykład platformy technologii reklamowych może zaimplementować ograniczenie liczby wyświetleń. W przypadku wielu dostawców filtrowania, system nie gwarantuje sekwencji wykonywania dostawców usług.

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

Dodatkowo platformy po stronie kupującego będą w stanie zasygnalizować, że dana reklama powinny być filtrowane na podstawie dodatkowych sygnałów na urządzeniu dostępnych dla odbiorców, którzy nie opuszczają urządzenia. Podczas opracowywania dodatkowe zasady filtrowania, platformy po stronie kupującego będą miały tę samą strukturę. aby zasygnalizować, że filtrowanie powinno się odbywać.

Logika oceny sprzedawcy

Zasady dotyczące punktacji są zwykle udostępniane przez platformę SSP. Cel polega na określeniu zwycięskiej reklamy na podstawie danych wyjściowych z określania stawek. Może stosując dodatkową logikę biznesową, aby określić wynik. Jeśli jest wielu dostawców logiki decyzji, system nie gwarantuje kolejności wykonywania wśród 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 uzyskana z funkcji generateBid().
Konfiguracja aukcji: parametr wejściowy metody selectAds().
Zaufane sygnały oceny: platformy technologii reklamowych wykorzystują dane w czasie rzeczywistym do: na potrzeby filtrowania i oceniania reklam. Wydawca aplikacji może na przykład zablokować kampanii reklamowej. Te dane są pobierane z zaufanych sygnały oceny punktowej – parametr URL konfiguracji aukcji. Serwer obsługujący to żądanie powinno być zaufanym serwerem zarządzanym przez technologię reklamową.
Sygnał kontekstowy: może obejmować przybliżoną sygnaturę czasową lub przybliżoną. informacje o lokalizacji.
Sygnalizowanie przez użytkownika: może to obejmować informacje takie jak sklep z aplikacjami, który zainicjował 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.

Środowisko wykonawcze kodu wyboru reklamy

W ramach propozycji system pobiera kod aukcji udostępniony przez platformę technologiczną reklam z punktów końcowych z możliwością konfiguracji 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:

Wykonywanie kodu powinno zakończyć się we wstępnie zdefiniowanym czasie. Ta granica będzie jednak stosowany we wszystkich sieciach reklamowych kupującego. 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.

Celem jest opracowanie rozwiązania w taki sposób, aby informacje o listy niestandardowych odbiorców lub historii zaangażowania w aplikację, których nie można określić aplikacji lub pakietu SDK, podając informacje o zwycięskiej reklamie. (podobnie do propozycje ramek strzeżonych).

Raporty o wyświetleniach i zdarzeniach

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 niestandardowej listy 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 procesów płatności. Raporty tego wyświetlenia jest ona uzupełnieniem interfejsu Attribution Reporting API.

Aby korzystać z raportowania zdarzeń, wymagane są 2 etapy: sprzedaż po stronie sprzedawcy i strona kupującego. JavaScript musi rejestrować zdarzenie, o którym ma otrzymywać raporty o zdarzeniach. strona sprzedająca 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 do wyszukiwania punktu końcowego pingów platformy, gdy raportowanie wyników aukcji.
reporting_url: adres URL należący do platformy adtech, który służy do obsługi zdarzenia.

Klucze zdarzeń to identyfikatory ciągu znaków należące 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ływana jest usługa reportEvent(), platformy SSP, które którzy przeprowadzili aukcję, zawsze mogą otrzymywać te raporty o zdarzeniach. 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 procesu decyzyjnego 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 ma być przekazany do reportWin kupującego. .

Strony podaży mogą zakodować w adresie URL raportowania odpowiednie sygnały, aby uzyskać więcej informacji o aukcji i reklamie zwycięskiej. Na przykład: uwzględnij te sygnały:

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

Raportowanie po stronie kupującego

Platforma wywołuje funkcję JavaScript reportWin() w kodzie po stronie zapytania 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:

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. Dzięki temu platformy SSP, dającą możliwość udostępniania danych na potrzeby raportowania.
contextual_signals zawiera informacje takie jak nazwa aplikacji czy Pole custom_audience_signals zawiera informacje o niestandardowych odbiorcach. Inny powód informacje mogą zostać dodane w przyszłości.

Dane wyjściowe:

Stan: 0 oznacza sukces, dowolna inna wartość oznaczająca niepowodzenie.
Adres URL raportu: platforma wywołuje ten adres URL zwrócony przez funkcję.

Raportowanie zdarzeń

Raportowanie zdarzeń jest możliwe dopiero po raportowaniu wyświetleń w aukcji . Za zgłaszanie zdarzeń odpowiada pakiet SDK po stronie sprzedawcy. platforma udostępnia interfejs API, który przyjmuje obiekt ReportEventRequest, który określa niedawno przeprowadzonej aukcji, raportowany klucz zdarzenia, dane powiązane z niezależnie od tego, czy raport ma zostać wysłany do kupującego czy sprzedawcy (albo i opcjonalne zdarzenie wejściowe 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ć AdSelectionId z niedawno przeprowadzonej aukcji pobranej z poziomu 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ć jeden z tych wartości: FLAG_REPORTING_DESTINATION_SELLER lub FLAG_REPORTING_DESTINATION_BUYER lub oba.
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 znajdziesz w artykule o integracji interfejsu Attribution Reporting API. dotyczące tego parametru.

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 pomóc kupującym, którzy biorą udział w aukcji z Protected Audience API, udostępniające funkcje korzystające z różnych interfejsów API w ramach Protected Audience i Attribution Interfejsy API do raportowania (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 używany do raportowania interakcji z tymi zdarzeniami za pomocą interfejsu Protected Audience API przekaże kupującemu niezbędne dane, które posłużą do zarejestrowania wyświetlenia lub kliknięcia jako kwalifikującego się źródła w interfejsie Attribution Reporting API.
Technologia reklamowa może przekazać CustomAudience (lub inne powiązane dane kontekstowe) informacje o reklamie, takie jak miejsce docelowe reklamy lub czas oglądania), korzystając z tego adresu URL. więc metadane mogą pojawić się w raportach podsumowujących, sprawdzanie łącznej skuteczności kampanii.

Włączanie rejestracji źródła

Funkcja reportEvent() będzie akceptować nowy opcjonalny parametr 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. Żądanie Nagłówek Attribution-Reporting-Eligible” zostanie dodany do wszystkich raportów o zdarzeniach. żądań wysłanych z reportEvent(). Wszystkie odpowiedzi z odpowiednimi nagłówkami ARA będą analizowane w taki sam sposób jak każda inna standardowa rejestracja źródła ARA co można osiągnąć. 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. Podobnie jak w przypadku rejestracji źródeł ARA interfejs API reportEvent() interpretuje InputEvent zweryfikowane przez platformę jako zdarzenie kliknięcia. Jeśli brakuje pola InputEvent, ma on wartość null lub jest nieprawidłowy, rejestracja źródła jest uznawana za widok.

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

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 konwersji.

W ramach tego procesu kupujący kontaktuje się ze sprzedawcą, by przesłać unikalny identyfikator do aukcji. Podczas aukcji kupujący wysyła ten 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.

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. Identyfikatorem może być ustawioną jako zmienną, np. auctionId. Identyfikator jest przekazywany jako perBuyerSignals w auctionConfig i staje się dostępny w logice ustalania stawek kupującego.

Podczas wykonywania reportWin kupujący może zarejestrować beacon reklamowy, 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 auctionId jako parametr zapytania w adresie URL beacona.
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 sprawdzi sygnał ping zarejestrowanym przez kupującego adres URL obrazu typu beacon, który jest powiązany z reportEvent(), które zostało uruchomione.
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 właściwość docelową, której można użyć do wysyłania zarówno kupującemu, jak i sprzedawcy.

Zaufany serwer zarządzany przez platformę technologii reklamowych

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.

Po stronie kupującego: gdy kupujący zainicjuje logikę ustalania stawek po stronie kupującego, platforma pobiera z zaufanego serwera dane dotyczące zaufanych stawek przez HTTP, Adres URL powstaje przez dołączenie adresu URL i kluczy zawartych w funkcji Zaufane określanie stawek sygnalizuje metadane grupy niestandardowych odbiorców, przetworzono. 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ź serwera powinna być obiektem JSON, którego klucze to key1, key2 itd., a wartości będą dostępne dla funkcji określania stawek kupującego.

Strona sprzedająca: podobnie jak w przypadku powyższego procesu po stronie kupującego, strona sprzedająca może chcieć pobierać informacje o kreacjach biorących udział w aukcji. Na przykład wydawca może chcieć wymusić wyświetlanie określonych kreacji w aplikacji na podstawie: obaw związanych z bezpieczeństwem marki. Te informacje można pobrać i udostępnić logice aukcji po stronie sprzedawcy. Podobnie jak w przypadku wyszukiwania zaufanego serwera po stronie kupującego, wyszukiwanie po stronie zaufanego serwera odbywa się również przez pobieranie HTTP. Adres URL jest tworzony przez dołączenie do adresu URL zaufanych sygnałów oceny adresów URL renderowania kreacji, dla 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ź 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 rejestruje zdarzeń na poziomie zdarzenia.
Serwer nie ma żadnych innych efektów ubocznych związanych z tymi żądaniami.

W ramach tymczasowego mechanizmu kupujący i sprzedawca mogą pobierać te stawki z dowolnego serwera, w tym z tego, który działa samodzielnie. 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.