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

Przesłać opinię

Ostatnie aktualizacje

Funkcja Protected Audience jest w wersji beta i można ją testować na urządzeniach publicznych.

Dzięki Protected Audience możesz:

  • zarządzać odbiorcami niestandardowymi na podstawie wcześniejszych działań użytkowników.
  • Inicjowanie aukcji na urządzeniu z pomocą zapośredniczenia pojedynczego sprzedawcy lub zapośredniczenia kaskadowego.
  • Ćwiczenie raportowania wyświetleń po wybraniu reklamy.

Na początek przeczytaj przewodnik dla programistów dotyczący funkcji Protected Audience API. Chętnie poznamy Twoją opinię, ponieważ pracujemy nad rozwojem Protected Audience.

Oś czasu

W najbliższych miesiącach udostępnimy nowe funkcje. Dokładne daty premiery będą się różnić w zależności od funkcji. Gdy tylko będzie ona dostępna, zaktualizujemy tę tabelę o linki do dokumentacji.

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 limitu wyświetleń na użytkownika II kw. 2023 roku III kw. 2023 roku
Przekazywanie reklam kontekstowych do procesu wyboru reklamy na potrzeby filtrowania II kw. 2023 roku III kw. 2023 roku
Raportowanie interakcji II kw. 2023 roku III kw. 2023 roku
Przekazywanie dostępu do niestandardowych list odbiorców III kw. 2023 roku IV kw. 2023 roku
płatności inne niż CPM, III kw. 2023 roku IV kw. 2023 roku
Integracja z określaniem stawek i usługami aukcji III kw. 2023 roku IV kw. 2023 roku
Raportowanie debugowania III kw. 2023 roku IV kw. 2023 roku
Integracja raportowania atrybucji Nie dotyczy IV kw. 2023 roku
Zapośredniczenie z otwartym ustalaniem stawek IV kw. 2023 roku IV kw. 2023 roku
Zarządzanie walutami I kw. 2024 roku II kw. 2024 roku
Integracja K-anon Nie dotyczy II kw. 2024 roku
Integracja raportów zbiorczych III kw. 2024 roku IV kw. 2024 roku

Przegląd

W przypadku reklam mobilnych reklamodawcy zwykle muszą wyświetlać reklamy potencjalnie zainteresowanym użytkownikom na podstawie ich wcześniejszych interakcji z aplikacją. Na przykład deweloper aplikacji SportingGoodsApp może wyświetlać reklamy użytkownikom, którzy mają jeszcze produkty w koszyku, wyświetlając reklamy przypominające użytkownikom o dokończeniu zakupu. W branży jest to ogólne rozwiązanie, np. „remarketing” i „kierowanie na odbiorców”.

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

Protected Audience API na Androida (dawniej FLEDGE) obejmuje następujące interfejsy API dla platform technologii reklamowych i reklamodawców, które obsługują typowe przypadki użycia oparte na interakcjach w sposób ograniczający udostępnianie zarówno identyfikatorów między aplikacjami, jak i informacji o interakcjach użytkownika z aplikacjami firmom zewnętrznym:

  1. Custom Audience API: koncentruje się na pojęciu „niestandardowi odbiorcy”, który reprezentuje grupę odbiorców o podobnych zamiarach. Informacje o odbiorcach są przechowywane na urządzeniu i można je powiązać z reklamami kandydującymi, które pasują do danej listy odbiorców, oraz z dowolnymi metadanymi, np. z sygnałami określania stawek. Te informacje mogą służyć do ustalania stawek reklamodawców, filtrowania reklam i renderowania.
  2. Ad Selection API: zapewnia platformę, która zarządza przepływami pracy platform technologii reklamowych, które wykorzystują sygnały z urządzenia do określenia „zwycięskiej” reklamy. W tym celu bierzemy pod uwagę reklamy kandydujące zapisane lokalnie i przetwarzamy dodatkowe reklamy kandydujące, które platforma technologii reklamowych zwraca na urządzenie.
Wykres blokowy przedstawiający proces wyboru reklam i zarządzania odbiorcami w Piaskownicy prywatności na urządzeniach z Androidem.

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

  1. Firma SportingGoodsApp chce przypomnieć użytkownikom o możliwości zakupu gadżetów, które znajdują się w koszyku, jeśli nie dokonają oni zakupu w ciągu 2 dni. SportingGoodsApp używa interfejsu Custom Audience API, aby dodać użytkownika do listy odbiorców „Produkty w koszyku”. Platforma zarządza tą listą odbiorców i przechowuje ją na urządzeniu, co ogranicza możliwość udostępniania jej osobom trzecim. Firma SportingGoodsApp współpracuje z platformą technologii reklamowej, aby wyświetlać reklamy użytkownikom z jej listy odbiorców. Platforma technologii reklamowych zarządza metadanymi list odbiorców i udostępnia reklamy kandydujące, które są udostępniane procesowi wyboru reklam do rozpatrzenia. Platformę można skonfigurować tak, aby okresowo pobierała w tle zaktualizowane reklamy na podstawie odbiorców. Dzięki temu lista kandydatów na podstawie odbiorców będzie aktualna i niezwiązana z żądaniami wysyłanymi do zewnętrznych serwerów reklamowych w trakcie możliwości reklamowej (tj. w ramach kontekstowych żądań reklamy).

  2. Użytkownik, który gra w FrisbeeGame na tym samym urządzeniu, może zobaczyć reklamę z prośbą o dokończenie zakupu rzeczy znajdujących się w koszyku w aplikacji SportingGoodsApp. Można to osiągnąć, wywołując FrisbeeGame (ze zintegrowanym pakietem SDK do wyświetlania reklam) interfejs Ad Selection API, by wybrać najlepszą reklamę dla użytkownika na podstawie dowolnej listy odbiorców, do której może on należeć (w tym przykładzie jest to niestandardowa lista odbiorców „produkty w koszyku” utworzona przez SportingGoodsApp). Proces wyboru reklam można tak skonfigurować, aby uwzględniał reklamy pobierane z serwerów platform technologii reklamowych, a także reklamy na urządzeniu powiązane z niestandardowymi odbiorcami oraz inne sygnały z urządzenia. Przepływ pracy można też dostosować za pomocą platformy technologii reklamowych i pakietu SDK do wyświetlania reklam za pomocą logiki ustalania stawek niestandardowych i punktacji, aby osiągnąć odpowiednie cele reklamowe. Dzięki temu dane o zainteresowaniach i interakcjach użytkownika z aplikacją mogą ułatwiać wybór reklam, a jednocześnie ograniczać udostępnianie ich osobom trzecim.

  3. Pakiet SDK aplikacji do wyświetlania reklam lub pakietu SDK platformy technologii reklamowych renderuje wybraną reklamę.

  4. Platforma ta ułatwia raportowanie wyświetleń i wyników wyboru reklamy. Ta funkcja raportowania stanowi uzupełnienie interfejsu Attribution Reporting API. Platformy z branży technologii reklamowych mogą dostosowywać się do swoich potrzeb w zakresie raportowania.

Dostęp do Protected Audience API w interfejsach API Androida

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

Zarządzanie odbiorcami niestandardowymi

Niestandardowa lista odbiorców

Niestandardowa lista odbiorców to grupa użytkowników określonych przez reklamodawcę o wspólnych zamiarach lub zainteresowaniach. Aplikacja lub pakiet SDK może korzystać z niestandardowych list odbiorców, by wskazać konkretną grupę odbiorców, np. „użytkowników, którzy zostawili produkty w koszyku” lub „zakończyli poziom podstawowy” w grze. Platforma przechowuje i przechowuje informacje o odbiorcach lokalnie na urządzeniu i nie określa, do jakich niestandardowych list odbiorców należy użytkownik. Niestandardowe listy odbiorców różnią się od grup zainteresowań w ChromeOS i nie można ich udostępniać w internecie ani aplikacjach. Pomaga to ograniczyć udostępnianie informacji o użytkowniku.

Aplikacja reklamodawcy lub zintegrowany pakiet SDK może join lub opuścić niestandardową listę odbiorców na podstawie np. zaangażowania użytkownika w aplikację.

Niestandardowe metadane odbiorców

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

  • Właściciel: nazwa pakietu aplikacji właściciela. Jest ona domyślnie ustawiona na nazwę pakietu aplikacji wywołującej.
  • Kupujący: sieć reklamowa kupującego, która zarządza reklamami tej grupy niestandardowych odbiorców. Kupujący reprezentuje też stronę, która może uzyskać dostęp do niestandardowej listy odbiorców i pobierać istotne informacje o reklamie. Kupujący jest określony w formacie eTLD+1.
  • Nazwa:dowolna nazwa lub identyfikator niestandardowej listy odbiorców, np. „użytkownicy, którzy porzucili koszyk”. Możesz go użyć jako na przykład jednego z kryteriów kierowania w kampaniach reklamowych reklamodawcy lub ciągu zapytania w adresie URL do pobierania kodu ustalania stawek.
  • Czas aktywacji i daty ważności: te pola określają przedział czasu, w którym ta niestandardowa lista odbiorców będzie obowiązywać. Platforma wykorzystuje te informacje, aby wycofać członkostwo z grupy niestandardowej. Okres ważności nie może przekraczać maksymalnego okresu, aby ograniczyć czas życia listy odbiorców niestandardowej.
  • Adres URL codziennej aktualizacji: cykliczny adres URL używany przez platformę do pobierania reklam kandydujących i innych metadanych zdefiniowanych w polach „Sygnały dotyczące określania stawek przez użytkowników” i „Zaufane sygnały dotyczące określania stawek”. Więcej informacji znajdziesz w sekcji poświęconej pobieraniu reklam kandydujących do kierowania na odbiorców niestandardowych.
  • Sygnały dotyczące określania stawek przez użytkowników: sygnały z platformy technologii reklamowych używane do ustalania stawek za reklamy remarketingowe. Przykładowe sygnały to m.in. przybliżona lokalizacja użytkownika i preferowany język.
  • Dane dotyczące zaufanego określania stawek: platformy technologii reklamowych używają danych w czasie rzeczywistym do określania stawek i pobierania reklam. Na przykład budżet reklamy może się wyczerpać i musi zostać natychmiast wstrzymany. Technologia reklamowa może zdefiniować punkt końcowy adresu URL, z którego w czasie rzeczywistym można pobrać dane, oraz zestaw kluczy, których ma dotyczyć wyszukiwanie w czasie rzeczywistym. Serwerem obsługującym to żądanie będzie zaufany serwer zarządzany przez platformę technologii reklamowych.
  • Adres URL mechanizmu ustalania stawek: adres URL używany przez platformę do pobierania kodu ustalania stawek z platformy DSP. Platforma wykonuje ten krok, gdy rozpoczyna się aukcja reklam.
  • Reklamy: lista reklam kandydujących do umieszczenia na liście niestandardowych odbiorców. Obejmuje to metadane reklamy związane z konkretną platformą technologii reklamowych oraz adres URL, pod którym reklama ma być renderowana. Gdy rozpoczyna się aukcję dla listy niestandardowych odbiorców, uwzględniana jest ta lista metadanych reklamy. Ta lista reklam będzie w miarę możliwości odświeżana za pomocą punktu końcowego aktualizowanego codziennie adresu URL. Liczba reklam, które można przechowywać na niestandardowej liście odbiorców, jest ograniczona ze względu na ograniczenia zasobów urządzeń mobilnych.

Przekazywanie dostępu do niestandardowych list odbiorców

Tradycyjna definicja i konfiguracja niestandardowych grup odbiorców opiera się zwykle na technologiach po stronie serwera oraz integracji opartych na technologii reklamowych we współpracy z klientami i partnerami agencji oraz reklamodawców. Protected Audience API umożliwia określanie i konfigurowanie niestandardowej listy odbiorców, chroniąc jednocześnie prywatność użytkowników. Aby dołączyć do listy niestandardowych odbiorców, kupujący, którzy nie korzystają z pakietu SDK w aplikacjach, muszą współpracować z technologiami reklamowymi działającymi na urządzeniu – takimi jak mobilni partnerzy świadczący usługi pomiarowe (MMP) i platformy dostawców reklam (SSP). Interfejs Protected Audience API ma na celu obsługę tych pakietów SDK przez zapewnienie elastycznych rozwiązań do zarządzania niestandardowymi odbiorcami przez włączenie w wywołaniach urządzeń wywoływania niestandardowych list odbiorców w imieniu kupujących. Nazywamy to przekazywaniem dostępu do niestandardowych list odbiorców. Aby skonfigurować przekazywanie dostępu do list niestandardowych odbiorców, wykonaj te czynności:

Dołącz do niestandardowej listy odbiorców

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

joinCustomAudience()

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

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

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

fetchAndJoinCustomAudience()

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

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

fetchAndJoinCustomAudience(fetchRequest);

Punkt końcowy URL, który należy do kupującego, odpowiada obiektowi JSON CustomAudience w treści odpowiedzi. Pola dotyczące kupującego i właściciela niestandardowej listy odbiorców są ignorowane (i automatycznie wypełniane przez interfejs API). Interfejs API wymaga też, aby adres URL codziennej aktualizacji był zgodny z adresem eTLD + 1 kupującego.

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

Interfejs fetchAndJoinCustomAudience() API określa tożsamość kupującego na podstawie parametru eTLD + 1 w elemencie fetchUri. Tożsamość kupującego CustomAudience jest używana do przeprowadzania tych samych testów rejestracji i autoryzacji aplikacji, które przeprowadza joinCustomAudience(). Nie można jej zmienić przez odpowiedź pobrania. Właściciel CustomAudience to nazwa pakietu aplikacji wywołującej. Nie ma innego sposobu weryfikacji fetchUri poza sprawdzaniem eTLD + 1, a w szczególności nie ma kontroli k-anoncheck. Interfejs fetchAndJoinCustomAudience() API wysyła żądanie HTTP GET do fetchUri i oczekuje obiektu JSON reprezentującego niestandardową listę odbiorców. W odpowiedzi są stosowane te same obowiązkowe, opcjonalne ograniczenia i wartości domyślne pól niestandardowych obiektów odbiorców. Więcej informacji o aktualnych wymaganiach i ograniczeniach znajdziesz w przewodniku dla programistów.

Każda odpowiedź o błędzie HTTP od kupującego powoduje niepowodzenie fetchAndJoinCustomAudience. W szczególności odpowiedź stanu HTTP 429 (Za dużo żądań) blokuje żądania z bieżącej aplikacji przez określony czas. Wywołanie interfejsu API kończy się też niepowodzeniem, jeśli odpowiedź od kupującego ma nieprawidłowy format. Błędy są zgłaszane do elementu wywołującego API odpowiedzialnego za ponawianie próby spowodowane tymczasowymi problemami (np. brak odpowiedzi serwera) lub obsługą stałych błędów (takich jak błędy weryfikacji danych lub inne trwałe błędy podczas komunikacji z serwerem).

Obiekt CustomAudienceFetchRequest umożliwia wywołanie interfejsu API definiowania informacji na potrzeby niestandardowej listy odbiorców za pomocą opcjonalnych właściwości pokazanych w przykładzie powyżej. Jeśli ustawisz te wartości w żądaniu, odpowiedź kupującego nie będzie możliwa. Interfejs Protected Audience API ignoruje pola w odpowiedzi. Jeśli nie określisz ich w żądaniu, musisz je podać w odpowiedzi, ponieważ te pola są wymagane do utworzenia niestandardowej listy odbiorców. Reprezentacja w formacie JSON zawartości CustomAudience, która jest częściowo zdefiniowana przez element wywołujący interfejs API, jest zawarta w żądaniu GET do fetchUri w specjalnym nagłówku X-CUSTOM-AUDIENCE-DATA. Rozmiar zserializowanych danych określonych na potrzeby listy odbiorców niestandardowej jest ograniczony do 8 KB. Jeśli rozmiar przekracza ten rozmiar, wywołanie interfejsu API fetchAndJoinCustomAudience kończy się niepowodzeniem.

Brak takiej weryfikacji umożliwia weryfikację kupującego i pakiet SDK za pomocą usługi fetchUri. Aby ułatwić niestandardową weryfikację odbiorców, kupujący może udostępnić token weryfikacyjny. Pakiet SDK na urządzeniu powinien zawierać ten token w elemencie fetchUri, aby punkt końcowy hostowany przez kupującego mógł pobierać zawartość niestandardowej listy odbiorców i używać tokena weryfikacyjnego do sprawdzania, czy operacja fetchAndJoinCustomAudience() odpowiada kupującemu i pochodzi od zaufanego partnera na urządzeniu. Aby udostępnić informacje, kupujący może wyrazić zgodę z wywołaniem na urządzeniu, że niektóre informacje używane do utworzenia listy niestandardowych odbiorców zostaną dodane jako parametry zapytania do funkcji fetchUri. Dzięki temu kupujący może kontrolować wywołania i wykrywać, czy szkodliwa technologia reklamowa wykorzystała token weryfikacyjny do utworzenia kilku różnych grup odbiorców niestandardowych.

Uwaga dotycząca definicji i przechowywania tokena weryfikacyjnego

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

    • Kupujący może użyć tokena weryfikacyjnego, aby sprawdzić, czy tworzone listy odbiorców są tworzone w jego imieniu.
    • Oferta pakietowa Protected Audience API nie określa formatu tokena weryfikacyjnego ani sposobu, w jaki kupujący przekazuje token weryfikacyjny do wywołania. Na przykład token weryfikacyjny może być wstępnie wczytany do pakietu SDK lub backendu właściciela albo może zostać pobrany w czasie rzeczywistym przez jego pakiet SDK z serwera kupującego.

Opuszczanie grupy odbiorców niestandardowych

Właściciel niestandardowej listy odbiorców może ją opuścić, dzwoniąc pod numer leaveCustomAudience(). Możesz to zobaczyć na przykładowym fragmencie kodu poniżej:

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

Aby oszczędzać miejsce na dane i inne zasoby urządzenia, niestandardowe listy odbiorców tracą ważność i są usuwane ze sklepu na urządzeniu po ustalonym czasie. Wartość domyślna jest określana. Właściciel może zastąpić tę wartość domyślną.

Kontrola użytkowników

  • Ta oferta ma na celu zapewnienie użytkownikom wglądu w listę zainstalowanych aplikacji, które utworzyły co najmniej 1 niestandardową listę odbiorców
  • Użytkownicy mogą usuwać aplikacje z tej listy. Spowoduje to usunięcie wszystkich niestandardowych list odbiorców powiązanych z aplikacjami i uniemożliwienie, aby aplikacje te nie dołączały do nowych.
  • Użytkownicy mogą całkowicie zresetować interfejs Protected Audience API. Gdy tak się stanie, wszystkie niestandardowe listy odbiorców utworzone na urządzeniu zostaną wyczyszczone.
  • Użytkownicy mogą zrezygnować z Piaskownicy prywatności na Androidzie, w tym z Protected Audience API. Jeśli użytkownik zrezygnował z Piaskownicy prywatności, interfejs Protected Audience API nie powiedzie się.

Pracujemy nad rozwijaniem tej funkcji. Szczegóły podamy w jednej z późniejszych aktualizacji.

Uprawnienia aplikacji i kontrola nad nimi

Celem oferty pakietowej jest zapewnienie aplikacji kontroli nad niestandardowymi odbiorcami:

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

Pracujemy nad rozwijaniem tej funkcji. Szczegóły podamy w jednej z późniejszych aktualizacji.

Kontrola platformy technologii reklamowych

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

  • Technologie reklamowe rejestrują się w Piaskownicy prywatności i udostępniają domenę eTLD + 1, która dopasowuje wszystkie adresy URL w przypadku niestandardowej grupy odbiorców.
  • Technologie reklamowe mogą współpracować z aplikacjami lub pakietami SDK, aby dostarczać tokeny weryfikacyjne używane do weryfikowania tworzenia list niestandardowych odbiorców. Jeśli proces zostanie przekazany do partnera, można skonfigurować tworzenie odbiorców niestandardowych w taki sposób, aby wymagały potwierdzenia od technologii reklamowej.
  • Specjalista z branży reklamowej może dezaktywować wywołania joinCustomAudience w ich imieniu i zezwolić tylko interfejsowi API fetchAndJoinCustomAudience na włączanie wszystkich niestandardowych list odbiorców wywołań. Ustawienia można zmienić podczas rejestracji w Piaskownicy prywatności. Pamiętaj, że opcja sterowania dopuszcza albo wszystkich, albo żadne z technologii reklamowych. Ze względu na ograniczenia platformy nie można przekazywać uprawnień dostępu do poszczególnych technologii reklamowych.

Reklamy kandydujące i odpowiedź z metadanymi

Reklamy i metadane kandydatów zwracane z platformy zakupowej powinny zawierać te pola:

  • Metadane: po stronie kupującego metadane reklam dotyczące technologii reklamowych. Może to np. obejmować informacje o kampanii reklamowej i kryteria kierowania, takie jak lokalizacja i język.
  • URL renderowania: punkt końcowy renderowania kreacji reklamy.
  • Filtrowanie: opcjonalne informacje niezbędne do działania interfejsu Protected Audience API w celu filtrowania reklam na podstawie danych z urządzenia. Więcej informacji znajdziesz w sekcji poświęconej regułom filtrowania po stronie zakupu.

Proces wyboru reklamy

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

Obecnie platformy technologii reklamowych ustalają stawki i wybierają reklamy tylko na swoich serwerach. Dzięki tej ofercie niestandardowe listy odbiorców i inne poufne sygnały użytkownika, takie jak dostępne informacje o zainstalowanym pakiecie, będą dostępne tylko przez interfejs Ad Selection API. Dodatkowo na potrzeby remarketingu reklamy kandydujące będą pobierane niezgodnie z wymaganiami (tj. nie w kontekście, w którym będą wyświetlane reklamy). Platformy technologii reklamowych będą musiały przygotować się na wdrożenie i wykonanie na urządzeniu niektórych części bieżących działań logicznych aukcji i wyboru reklam. Platformy z branży technologii reklamowych mogą uwzględnić te zmiany w procesie wyboru reklam:

  • Jeśli na serwerze nie są dostępne informacje o zainstalowanych pakietach, platformy technologii reklamowych mogą chcieć odesłać wiele reklam kontekstowych z powrotem na urządzenie i wywołać proces wyboru reklamy, aby umożliwić filtrowanie na podstawie instalacji aplikacji. Pozwoli to zwiększyć szanse na wyświetlenie trafnej reklamy.
  • Reklamy remarketingowe są pobierane niewłaściwie, więc może być konieczne zaktualizowanie bieżących modeli ustalania stawek. Platformy z branży technologii reklamowych mogą tworzyć podmodele ustalania stawek (implementacja może opierać się na wzorcu nazywanym modelem 2 wieży), który może oddzielnie pracować z funkcjami reklam i sygnałami kontekstowymi oraz łączyć dane wyjściowe z podmodelu na urządzeniu, aby prognozować stawki. Może to przynieść korzyści zarówno w przypadku aukcji po stronie serwera, jak i aukcji.

Takie podejście umożliwia wybór reklam na podstawie danych o interakcjach użytkownika z aplikacją, a jednocześnie ogranicza udostępnianie tych danych osobom trzecim.

Wykres blokowy pokazujący rozpoczęcie procesu wyboru reklamy.

Proces wyboru reklamy administruje wykonywaniem na urządzeniu kodu JavaScript dostarczonego przez technologie reklamowe w następującej kolejności:

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

W przypadku wyboru reklam, które obejmują odbiorców niestandardowych, platforma pobierze kod JavaScript udostępniony przez klienta, który kupuje kod JavaScriptu na podstawie publicznego punktu końcowego adresu URL zdefiniowanego przez metadane niestandardowych odbiorców w sekcji „Adres URL mechanizmu określania stawek”. Punkt końcowy adresu URL na potrzeby kodu decyzji po stronie sprzedaży także będzie przekazywany jako dane wejściowe w celu zainicjowania procesu wyboru reklamy.

Ustawienia reklam, które nie obejmują niestandardowych odbiorców, są w fazie aktywnego projektowania.

Rozpocznij proces wyboru reklamy

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

  • Sprzedawca: identyfikator platformy reklamowej w formacie eTLD + 1
  • URL logiki decyzji: po rozpoczęciu aukcji reklam platforma użyje tego adresu URL do pobrania kodu JavaScript z platformy sprzedawcy, aby ocenić zwycięską reklamę.
  • Kupujący na liście niestandardowych odbiorców: lista platform po stronie zakupu, które obsługują w danej aukcji niestandardowych ofert reklamowych opartych na odbiorcach, w formacie eTLD + 1.
  • Sygnały wyboru reklamy: informacje o aukcji (rozmiar i format reklamy itp.).
  • Sygnały sprzedawcy: sygnały specyficzne dla platformy dostawców.
  • Adres URL zaufanych sygnałów wyników: punkt końcowy adresu URL zaufanego sygnału sprzedawcy, z którego w czasie rzeczywistym mogą pobierać konkretne informacje dotyczące kreacji.
  • Sygnały dotyczące kupującego: uczestniczące strony popytu mogą używać tego parametru do dostarczania danych wejściowych do aukcji. Może on np. zawierać wyczerpujące informacje kontekstowe przydatne przy ustalaniu stawek.

Poniższy przykładowy fragment kodu przedstawia pakiet SDK platformy technologii reklamowych inicjujący proces wyboru reklamy przez zdefiniowanie obiektu AdSelectionConfig, a następnie wywołanie metody selectAds, co pozwoli 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 dostarczana przez platformy po stronie zakupu. Służy on do określania stawek za reklamy kandydujące. Określenie wyniku może wymagać zastosowania dodatkowej logiki biznesowej.

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

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

Metoda generateBid() zwraca obliczoną kwotę stawki. Platforma będzie kolejno wywoływać tę funkcję dla wszystkich reklam (kontekstowych lub remarketingowych). Jeśli istnieje wielu dostawców logiki ustalania stawek, system nie gwarantuje kolejności wykonywania poszczególnych czynności.

Funkcja wymaga tych parametrów:

  • Reklama: reklama uwzględniana przez kod ustalania stawek po stronie zakupu. To będzie reklama od kwalifikującej się niestandardowej grupy odbiorców,
  • Sygnały z aukcji: sygnały powiązane z platformą sprzedażową.
  • Sygnały dotyczące kupującego: uczestniczące strony popytu mogą używać tego parametru do dostarczania danych wejściowych do aukcji. Może on np. zawierać wyczerpujące informacje kontekstowe przydatne przy ustalaniu stawek.
  • Zaufane sygnały określania stawek: platformy technologii reklamowych używają danych w czasie rzeczywistym do pobierania i oceniania reklam. Na przykład budżet kampanii reklamowej może się wyczerpać i trzeba natychmiast zatrzymać wyświetlanie reklam. Technologia reklamowa może zdefiniować punkt końcowy adresu URL, z którego można pobierać dane w czasie rzeczywistym, oraz zbiór kluczy, których ma dotyczyć wyszukiwanie w czasie rzeczywistym. Zarządzany przez nią serwer platformy reklamowej, który obsługuje to żądanie, będzie zaufanym serwerem zarządzanym przez tę platformę.
  • Sygnały kontekstowe: mogą to być przybliżone sygnatury czasowe, przybliżone informacje o lokalizacji lub koszt kliknięcia reklamy.
  • Sygnały użytkownika: mogą to być informacje takie jak dostępne informacje o zainstalowanych pakietach.

Koszt reklamy

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

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

Jeśli reklama wygra, parametr adCost jest stochatycznie zaokrąglany do 8 bitów ze względu na ochronę prywatności. Zaokrąglona wartość adCost jest następnie przekazywana do parametru contextual_signals w reportWin podczas raportowania wyświetleń.

Logika filtrowania po stronie kupującego

Platformy po stronie kupujących 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 mogą wdrażać funkcje ograniczenia liczby wyświetleń. Jeśli jest wielu dostawców filtrów, system nie gwarantuje kolejności wykonania ich zadań.

Logikę filtrowania po stronie kupującego można wdrożyć w ramach logiki ustalania stawek, zwracając wartość stawki 0 za daną reklamę.

Dodatkowo platformy po stronie zakupu będą mogły zasygnalizować, że dana reklama powinna być filtrowana na podstawie dodatkowych sygnałów z urządzenia dostępnych w ramach Protected Audience API, które nie opuszczają urządzenia. W trakcie opracowywania dodatkowej logiki filtrowania platformy po stronie zakupu będą korzystać z tej samej struktury, sygnalizując, że powinno nastąpić odfiltrowywanie.

Logika punktowa po stronie sprzedawcy

Logika punktacji jest zwykle tworzona przez platformę handlową. Celem tego kodu jest wyłonienie zwycięskiej reklamy na podstawie wyników logiki ustalania stawek. Do określenia wyniku można zastosować dodatkową logikę biznesową. Jeśli jest wielu dostawców logiki podejmowania decyzji, system nie gwarantuje kolejności wykonania u wszystkich dostawców. Platforma użyje parametru wejściowego „Decision logic URL” interfejsu API selectAds() do pobrania kodu JavaScript, który powinien zawierać poniższy podpis funkcji:

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

Funkcja wymaga tych parametrów:

  • Reklama: oceniana reklama; wynik z funkcji generateBid().
  • Stawka: kwota stawki uzyskana z funkcji generateBid().
  • Konfiguracja aukcji: parametr wejściowy do metody selectAds().
  • Zaufane sygnały wyników: platformy technologii reklamowych używają danych w czasie rzeczywistym do filtrowania i oceniania reklam. Wydawca aplikacji może na przykład zablokować wyświetlanie reklam z kampanii w aplikacji. Dane te są pobierane z parametru adresu URL zaufanych sygnałów punktowych w konfiguracji aukcji. Serwer obsługujący to żądanie powinien być zaufanym serwerem zarządzanym przez technologię reklamową.
  • Sygnał kontekstowy: może to być przybliżona sygnatura czasowa lub informacje o przybliżonej lokalizacji.
  • Sygnał użytkownika: może to obejmować informacje takie jak sklep z aplikacjami, z którego instalacja została zainicjowana.
  • Niestandardowy sygnał dotyczący odbiorców: jeśli oceniana reklama pochodzi z niestandardowej listy odbiorców na urządzeniu, będzie ona zawierać takie informacje jak czytelnik i nazwa tej listy.

Czas działania kodu wyboru reklamy

W ramach oferty pakietowej system pobierze kod aukcji udostępniony na platformie reklamowej z konfigurowalnych punktów końcowych URL i wykona na urządzeniu. Ze względu na ograniczenia zasobów dotyczące urządzeń mobilnych kod aukcji powinien być zgodny z tymi wytycznymi:

  • Kod powinien zakończyć wykonywanie kodu w ustalonym wcześniej czasie. Ta wartość będzie stosowana jednakowo do wszystkich sieci reklamowych kupujących. Szczegóły tej wartości poznamy w późniejszej aktualizacji.
  • Kod musi być samodzielny i nie może mieć żadnych zależności zewnętrznych.

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

Język programowania

Kod aukcji udostępniany przez platformę technologii reklamowych powinien być napisany w języku JavaScript. Dzięki temu platformy technologii reklamowych będą na przykład udostępniać kod określania stawek różnym platformom obsługującym Piaskownicę prywatności.

Najlepsze renderowanie reklam

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

Planujemy rozwinąć rozwiązanie tak, aby aplikacja lub pakiet SDK nie mogła określać informacji o niestandardowych odbiorcach ani historii zaangażowania użytkownika na podstawie informacji o zwycięskiej reklamie (podobnie jak w przypadku oferty ramek ogrodzonych w Chrome).

Raporty o wyświetleniach i zdarzeniach

Po wyrenderowaniu reklamy wygrane wyświetlenie można przesłać z powrotem do uczestniczących platform po stronie kupującego i sprzedawcy. Dzięki temu kupujący i sprzedawcy mogą uwzględnić w raporcie o zwycięskich wyświetleniach informacje z aukcji, np. stawkę lub niestandardową nazwę odbiorców. Dodatkowo platforma po stronie sprzedawcy i kupująca po stronie kupującego może otrzymywać dodatkowe raporty na poziomie zdarzenia dotyczące zwycięskiej reklamy. Dzięki temu możesz dołączyć informacje o aukcji (stawka, niestandardowa nazwa grupy odbiorców itp.) z kliknięciami, wyświetleniami i innymi zdarzeniami reklamowymi. Platforma wywołuje logikę raportowania w tej kolejności:

  1. Raportowanie po stronie sprzedawców.
  2. Raportowanie po stronie kupującego.

Daje to platformom zarówno po stronie kupujących, jak i sprzedawców możliwość wysyłania ważnych informacji z urządzenia z powrotem do serwerów. Dzięki temu można korzystać z takich funkcji jak określanie budżetu w czasie rzeczywistym, aktualizowanie modelu ustalania stawek i dokładne procesy płatności. Raportowanie wyświetleń stanowi uzupełnienie interfejsu Attribution Reporting API.

Aby korzystać z raportowania zdarzeń, musisz wykonać 2 czynności: kod JavaScript po stronie sprzedawcy i po stronie zakupu musi rejestrować, o którym zdarzeniu ma otrzymywać raporty o zdarzeniach, a zespół sprzedaży odpowiada za raportowanie informacji na poziomie zdarzenia.

Protected Audience umożliwia rejestrowanie kolejnych zdarzeń związanych z wygraną aukcję przez rejestrowanie obrazów typu beacon. W funkcji JavaScriptu reportResult() sprzedawcy za pomocą funkcji registerAdBeacon() platformy mogą rejestrować obrazy typu beacon. Podobnie platformy po stronie zakupu mogą wywoływać metodę registerAdBeacon() z funkcji reportWin() JavaScriptu.

registerAdBeacon(beacons)

Urządzenie wejściowe:

  • event_key: ciąg znaków określający typ interakcji, w której przypadku chcesz zarejestrować działanie. Służą one jako klucz do wyszukiwania punktu końcowego, który wysyła pingi przez platformę podczas raportowania wyników aukcji.
  • reporting_url: adres URL należący do platformy technologii reklamowych służący do obsługi zdarzenia.

Klucze zdarzeń to identyfikatory w postaci ciągu znaków należące do pakietu SDK platformy sprzedaży, który odpowiada za raportowanie wyników aukcji. Aby wykonać wywołanie zwrotne, specjaliści ds. technologii reklamowych rejestrują beacony z kluczami pasującymi do kluczy używanych przez sprzedawcę podczas raportowania zdarzeń. Nie muszą one być k-anonimowe, ale obowiązują ograniczenia dotyczące liczby i długości kluczy, które można zarejestrować na potrzeby danej niestandardowej listy odbiorców. Jeśli wywołujesz reportEvent(), platformy sprzedaży, które uczestniczyły w aukcji, zawsze mogą otrzymywać te raporty o zdarzeniach. Takie raporty może otrzymywać tylko zwycięska platforma po stronie kupującego.

Raporty dla sprzedawców

Platforma wywołuje funkcję JavaScript reportResult() w kodzie udostępnionym po stronie dostawców pobranym z parametru Decision logic URL sprzedawcy 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 – powodzenie, inna wartość błędu.
  • URL raportowania: platforma wywołuje ten adres URL zwrócony przez funkcję.
  • Sygnały dla kupującego: obiekt JSON przekazywany do funkcji reportWin kupującego.

Po stronie dostawców reklam można zakodować odpowiednie sygnały w adresie URL raportu, aby uzyskać dokładniejsze informacje o aukcji i wygranej reklamie. Może zawierać na przykład 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 dostawcą a popytem, platforma przekazuje tę wartość jako parametr wejściowy do kodu raportowania DSP.

Raportowanie po stronie kupującego

Platforma wywołuje funkcję JavaScript reportWin() w kodzie udostępnianym po stronie popytu pobranego z metadanych adresu URL mechanizmu określania stawek niestandardowej listy 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:

  • Parametry auction_signals i per_buyer_signals są pobierane z: AuctionConfig. Mogą z niego pochodzić wszystkie informacje, które platforma zakupowa musi przekazać do adresu URL służącego do raportowania.
  • signals_for_buyer to wynik z raportu o sprzedaży. Dzięki temu platforma sprzedawcy może udostępniać dane tej platformie na potrzeby raportowania.
  • Pole contextual_signals zawiera informacje, takie jak nazwa aplikacji, a custom_audience_signals zawiera informacje o niestandardowych odbiorcach. W przyszłości możemy dodać więcej informacji.

Dane wyjściowe:

  • Stan: 0 – powodzenie, inna wartość błędu.
  • URL raportowania: platforma wywołuje ten adres URL zwrócony przez funkcję.

Raportowanie zdarzeń

Raportowanie zdarzeń jest możliwe dopiero po zakończeniu raportowania wyświetleń w aukcji. Za raportowanie wszystkich zdarzeń odpowiada pakiet SDK sprzedawcy. Platforma udostępnia interfejs API, który pobiera parametr ReportEventRequest określający ostatnio przeprowadzaną aukcję, raportowany klucz zdarzenia, dane powiązane z tym kluczem, informację o tym, czy raport ma zostać wysłany do kupującego, czy do sprzedawcy (albo obu), i opcjonalne zdarzenie wejściowe dotyczące zdarzeń reklamowych. Klient określa klucz zdarzenia i zbiór danych, które mają być raportowane.

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

reportEvent(request)

Urządzenie wejściowe:

  • ad_selection_id musi mieć wartość AdSelectionId z ostatnio przeprowadzonej aukcji pobranej z AdSelectionOutcome.
  • event_key to zdefiniowany po stronie sprzedawcy ciąg tekstowy opisujący zdarzenie interakcji.
  • event_data to ciąg znaków reprezentujący dane powiązane z: event_key
  • reporting_destinations to maska bitowa ustawiona przy użyciu flag dostarczanych przez platformę. Możliwe wartości to FLAG_REPORTING_DESTINATION_SELLER, FLAG_REPORTING_DESTINATION_BUYER lub oba.
  • Parametr input_event (opcjonalny) jest używany do integracji z interfejsem Attribution Reporting API. Jest to obiekt InputEvent (w przypadku zdarzenia kliknięcia) lub wartość null (w przypadku zdarzenia obejrzenia). Więcej informacji o tym parametrze znajdziesz w artykule o integracji interfejsu Attribution Reporting API.

Po tym, jak pakiet SSP wywoła metodę reportEvent i w zależności od flagi reporting_destinations platforma próbuje dopasować event_key do kluczy zarejestrowanych przez kupujących i sprzedawców w ich funkcjach JavaScript reportWin i reportResult. Jeśli występuje dopasowanie, platforma wysyła żądanie event_data do powiązanego elementu reporting_url. Typ treści żądania to zwykły tekst, którego treść to event_data. Żądanie jest wykonywane z wykorzystaniem najlepszych starań i w przypadku błędu sieci, odpowiedzi błędu serwera lub braku pasujących kluczy nie zostanie wysłane po cichu.

Integracja interfejsu Attribution Reporting API

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

Dzięki tej integracji między interfejsami API technologie reklamowe mogą:

  • Utwórz mapę par klucz-wartość identyfikatorów URI, które będą używane na potrzeby: 1) raportowania interakcji z reklamą i 2) rejestracji źródła.
  • Uwzględnianie danych aukcji z aukcji Protected Audience w mapowaniu klucza po stronie źródła na potrzeby zbiorczego raportowania podsumowującego (za pomocą interfejsu Attribution Reporting API). Więcej informacji znajdziesz w propozycji projektu interfejsu ARA.

Gdy użytkownik widzi lub klika reklamę:

  • Adres URL używany do raportowania tych interakcji z użyciem Protected Audience API będzie dostarczać kupującemu dane niezbędne do zarejestrowania obejrzenia lub kliknięcia jako kwalifikującego się źródła za pomocą interfejsu Attribution Reporting API.
  • Korzystając z tego adresu URL, technologia reklamowa może przekazywać CustomAudience (lub inne istotne informacje kontekstowe dotyczące reklamy, takie jak miejsce docelowe reklamy czy czas oglądania) na potrzeby ich rozpowszechniania w raportach podsumowujących podczas sprawdzania łącznej skuteczności kampanii.

Włączanie rejestracji źródła

reportEvent() będzie akceptować nowy opcjonalny parametr InputEvent. Zwycięzcy kupujący, którzy rejestrują beacony reklamowe, mogą wybrać, które raporty do raportów o zdarzeniach mają być rejestrowane w interfejsach Attribution Reporting API jako zarejestrowane źródło. Nagłówek żądania „Attribution-Reporting-Eligible” będzie dodawany do wszystkich żądań raportowania o zdarzeniach wysyłanych z interfejsu reportEvent(). Wszystkie odpowiedzi z odpowiednimi nagłówkami ARA będą analizowane tak samo jak wszystkie inne odpowiedzi związane z rejestracją w źródle ARA. Informacje o tym, jak zarejestrować źródłowy adres URL znajdziesz w artykule z wyjaśnieniem interfejsu Attribution Reporting API.

ARA na Androidzie obsługuje zdarzenia wyświetlenia i kliknięcia, więc do rozróżniania tych 2 typów zdarzeń służą InputEvents. Tak jak w przypadku rejestracji źródeł ARA, interfejs API reportEvent() zinterpretuje InputEvent zweryfikowaną na platformie jako zdarzenie kliknięcia. Jeśli brakuje parametru InputEvent, ma on wartość null lub jest nieprawidłowy, rejestracja w źródle będzie uznawana za wyświetlenie.

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

Przykład raportowania zaangażowania i konwersji

W tym przykładzie przyjrzymy się temu z perspektywy kupującego, który jest zainteresowany powiązaniem danych z aukcji, wyrenderowanej reklamy i aplikacji, która generuje konwersję.

W tym procesie kupujący współpracuje ze sprzedawcą, by przesłać do aukcji unikalny identyfikator. Podczas aukcji kupujący wysyła ten unikalny identyfikator razem z danymi z tej aukcji. Podczas renderowania i konwersji dane z renderowanej reklamy są też wysyłane z tym samym unikalnym identyfikatorem. Później możesz powiązać te raporty ze sobą za pomocą unikalnego identyfikatora.

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 funkcji auctionConfig i staje się dostępny w mechanizmie ustalania stawek kupującego.

  1. Podczas wykonywania kodu reportWin kupujący może zarejestrować beacon, który ma być wywoływany w czasie renderowania reklamy i w przypadku określonych zdarzeń interakcji (registerAdBeacon()). Aby powiązać sygnały aukcji z konkretnym zdarzeniem reklamowym, ustaw auctionId jako parametr zapytania adresu URL obrazu typu beacon.
  2. Podczas renderowania reklamy beacony zarejestrowane w czasie aukcji mogą być wywoływane lub ulepszone za pomocą danych na poziomie zdarzenia. Sprzedawca musi aktywować zdarzenie reportEvent() i przekazywać dane na poziomie zdarzenia. Platforma wyśle ping do adresu URL zarejestrowanego przez kupującego obrazu typu beacon, który jest powiązany z wywołanym przez kupującego elementem reportEvent().
  3. Kupujący zarejestruje reklamę w Attribution Reporting API, odpowiadając na żądania beaconów z nagłówkiem Attribution-Reporting-Register-Source. Aby powiązać sygnały z aukcji ze zdarzeniem konwersji, ustaw auctionId w rejestrowanym źródłowym adresie URL.

Gdy to zrobisz, kupujący otrzyma raport z aukcji, raport interakcji i raport konwersji, które możesz powiązać za pomocą unikalnego identyfikatora, który można wykorzystać do powiązania.

Podobny przepływ pracy ma sprzedawca, który potrzebuje dostępu do danych atrybucji. Może też użyć unikalnego identyfikatora, aby przesłać żądanie za pomocą funkcji registerAdBeacon(). Wywołanie reportEvent() zawiera właściwość miejsca docelowego, która może służyć do wysyłania raportu zarówno do kupującego, jak i do sprzedawcy.

Zarządzany zaufany serwer platformy reklamowej

Logika wyboru reklamy wymaga obecnie dostępu do informacji w czasie rzeczywistym, takich jak stan wyczerpania budżetu, aby określić, czy kandydaci na aukcję powinni wziąć udział w aukcji. Obie platformy po stronie kupującego i sprzedawcy będą mogły uzyskać te informacje z obsługiwanych przez siebie serwerów. Aby zminimalizować wyciek informacji poufnych przez te serwery, oferta pakietowa wprowadza następujące ograniczenia:

  • Sposób działania tych serwerów, opisany w dalszej części tej sekcji, nie ujawniłby informacji o użytkownikach.
  • Serwery nie utworzą pseudonimizowanych profili na podstawie napotkanych danych, tzn. muszą zostać oznaczone jako „zaufane”.

Strona kupującego: gdy strona kupującego inicjuje logikę ustalania stawek po stronie kupującego, platforma wykonuje pobieranie przez HTTP zaufanych danych ustalania stawek z zaufanego serwera. URL składa się z adresu URL i kluczy zawartych w metadanych sygnałów zaufanego określania stawek przetwarzanych odbiorców niestandardowych. Pobieranie następuje tylko podczas przetwarzania reklam pochodzących od niestandardowych odbiorców na urządzeniu. Na tym etapie kupujący może egzekwować budżety, sprawdzać stan wstrzymania i wznawiania kampanii, prowadzić kierowanie itp.

Poniżej znajduje się przykładowy adres URL umożliwiający pobieranie danych dotyczących zaufanego określania stawek na podstawie metadanych zaufanych sygnałów ustalania stawek z grupy niestandardowych odbiorców:

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

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

Sprzedawca: podobnie jak w opisie powyżej, strona sprzedająca może chcieć pobrać informacje o kreacjach branych pod uwagę w aukcji. Na przykład wydawca może chcieć, by pewne kreacje nie wyświetlały się w aplikacji, ze względu na kwestie związane z bezpieczeństwem marki. Informacje te można pobierać i udostępniać do mechanizmu aukcji po stronie sprzedawcy. Podobnie jak w przypadku wyszukiwania zaufanego serwera po stronie kupującego, wyszukiwanie takiego serwera odbywa się również przy użyciu pobierania HTTP. Aby go utworzyć, należy dołączyć adres URL zaufanych sygnałów wyników do adresów URL renderowania kreacji, dla których mają zostać pobrane dane.

Poniżej znajdziesz przykładowy URL do pobierania informacji o kreacjach uwzględnionych w aukcji na podstawie adresów URL renderowania:

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

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

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

  • Można uznać, że wartość zwracana przez serwer dla każdego klucza jest oparta wyłącznie na tym kluczu.
  • Serwer nie rejestruje na poziomie zdarzenia.
  • Serwer nie ma żadnych innych skutków ubocznych na podstawie tych żądań.

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

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