Przewodnik dla deweloperów dotyczący Protected Audience API

Podczas czytania dokumentacji dotyczącej Piaskownicy prywatności na Androida użyj przycisku Podgląd dla deweloperów lub Beta, aby wybrać wersję programu, z którą pracujesz, ponieważ instrukcje mogą się różnić.

Interfejs Protected Audience API na Androida (wcześniej FLEDGE) obejmuje interfejsy Custom Audience API i Ad Selection API. Platformy technologii reklamowych i reklamodawcy mogą używać tych interfejsów API do wyświetlania reklam spersonalizowanych na podstawie wcześniejszego zaangażowania w aplikację, co ogranicza udostępnianie identyfikatorów w aplikacjach i udzielanie informacji o interakcjach użytkownika z aplikacją osobom trzecim.

Interfejs Custom Audience API koncentruje się na abstrakcji „niestandardowej listy odbiorców”, która reprezentuje grupę użytkowników o wspólnych zamiarach. Reklamodawca może zarejestrować użytkownika na liście odbiorców niestandardowych i związać z nią odpowiednie reklamy. Te informacje są przechowywane lokalnie i mogą być wykorzystywane do określania stawek reklamodawców, filtrowania reklam i ich renderowania.

Interfejs Ad Selection API zapewnia środowisko, które umożliwia wielu deweloperom prowadzenie aukcji lokalnie na potrzeby niestandardowych list odbiorców. Aby to osiągnąć, system bierze pod uwagę odpowiednie reklamy powiązane z listą niestandardowych odbiorców i przeprowadza dodatkowe przetwarzanie reklam, które platforma technologii reklamowej zwraca na urządzenie.

Platformy technologii reklamowych mogą zintegrować te interfejsy API, aby wdrażać remarketing, który chroni prywatność użytkowników. Obsługa dodatkowych przypadków użycia, w tym reklam w celu zachęcania do instalowania aplikacji, jest planowana na przyszłe wersje. Więcej informacji o interfejsie Protected Audience API na Androida znajdziesz w propozycji projektu.

Z tego przewodnika dowiesz się, jak korzystać z interfejsu Protected Audience API na urządzeniu z Androidem, aby:

1. Zarządzanie niestandardowymi odbiorcami
2. Konfigurowanie i uruchamianie selekcji reklam na urządzeniu
3. Zgłaszanie wyświetleń reklamy

Zanim zaczniesz

Zanim zaczniesz, wykonaj te czynności:

1. Skonfiguruj środowisko programistyczne do korzystania z Piaskownicy prywatności na Androida.
2. Zainstaluj obraz systemu na obsługiwanym urządzeniu lub skonfiguruj emulator, który obsługuje Piaskownicę prywatności na Androidzie.

3. W terminalu zezwól na dostęp do interfejsu Protected Audience API (domyślnie wyłączonego) za pomocą tego polecenia adb.

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. W terminalu włącz raportowanie sygnałów beacon za pomocą tych poleceń adb.

    adb shell device_config put adservices fledge_beacon_reporting_metrics_enabled true
    adb shell device_config put adservices fledge_register_ad_beacon_enabled true
   

5. Dodaj uprawnienia ACCESS_ADSERVICES_CUSTOM_AUDIENCE do pliku manifestu aplikacji:

     <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
   

6. Odwołuj się do konfiguracji usług reklamowych w elemencie <application> w pliku manifestu:

     <property android:name="android.adservices.AD_SERVICES_CONFIG"
               android:resource="@xml/ad_services_config" />
   

7. Określ zasób XML usług reklamowych, do którego odwołuje się plik manifestu, np. res/xml/ad_services_config.xml. Więcej informacji o uprawnieniach usług reklamowych i kontroli dostępu do pakietu SDK

     <ad-services-config>
       <custom-audiences allowAllToAccess="true" />
     </ad-services-config>
   

8. Domyślnie interfejs Ad Selection API narzuca limity maksymalnej ilości pamięci, jaką może przydzielić skrypt obsługujący aukcję lub raportowanie wyświetleń. Funkcja ograniczenia pamięci wymaga wersji WebView 105.0.5195.58 lub nowszej. Platforma wymusza sprawdzanie wersji i wywołania interfejsów selectAds i reportImpression kończą się niepowodzeniem, jeśli nie spełniają tego warunku. Dostępne są 2 opcje konfiguracji:

   • Opcja 1. Aby dezaktywować tę kontrolę, uruchom to polecenie adb:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • Opcja 2. Zainstaluj WebView Beta ze Sklepu Google Play. Musi być równa lub wyższa niż wersja podana wcześniej.

Dołączanie do grupy odbiorców niestandardowych

Lista niestandardowych odbiorców to grupa użytkowników o wspólnych zamiarach lub zainteresowaniach, jaką określa aplikacja reklamodawcy. Aplikacja lub pakiet SDK może używać listy niestandardowych odbiorców, aby wskazać konkretną grupę odbiorców, np. osoby, które porzuciły produkty w koszyku. Aby asynchronicznie utworzyć niestandardową listę odbiorców lub dołączyć do niej, wykonaj te czynności:

1. Inicjuje obiekt CustomAudienceManager.
2. Utwórz obiekt CustomAudience, podając kluczowe parametry, takie jak pakiet kupującego i odpowiednia nazwa. Następnie zainicjuj obiekt JoinCustomAudienceRequest za pomocą obiektu CustomAudience.
3. Wywołaj asynchroniczną funkcję joinCustomAudience() za pomocą obiektu JoinCustomAudienceRequest oraz odpowiednich obiektów Executor i OutcomeReceiver.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

Kombinacja tych parametrów jednoznacznie identyfikuje każdy obiekt CustomAudience na urządzeniu:

• owner: nazwa pakietu aplikacji właściciela. Jest ona domyślnie ustawiana na nazwę pakietu aplikacji wywołującej.
• buyer: identyfikator sieci reklamowej kupującego, która zarządza reklamami dla tej listy odbiorców niestandardowych.
• name: dowolna nazwa lub identyfikator listy niestandardowej.

Powtarzające się wywołanie funkcji joinCustomAudience() z inną instancją funkcji CustomAudience aktualizuje wszystkie istniejące obiekty CustomAudience z odpowiednimi parametrami owner, buyer i name. Aby chronić prywatność, interfejs API nie rozróżnia działań „tworzenie” i „aktualizowanie”.

Dodatkowo musisz utworzyć CustomAudience z tymi wymaganymi parametrami:

• URL do codziennej aktualizacji: adres URL HTTPS, który jest codziennie wywoływany w tle, aby aktualizować sygnały licytowania użytkowników w listach niestandardowych, dane zaufanej licytacji oraz renderować adresy URL i metadane reklam.
• URL logiki ustalania stawek: adres URL HTTPS zapytany podczas wyboru reklamy w celu pobrania logiki ustalania stawek w kodzie JavaScript kupującego. W tym kodzie JavaScript znajdziesz wymagane nazwy funkcji.
• Identyfikatory renderowania reklam: dowolny identyfikator ustawiony przez technologię reklamową kupującego. Jest to optymalizacja służąca do generowania danych dla B&A.

Opcjonalne parametry obiektu CustomAudience:

• Czas aktywacji: lista odbiorców niestandardowych może uczestniczyć w wybieraniu reklam i ich codziennych aktualizacjach dopiero po jej aktywacji. Może to być przydatne np. do ponownego zaangażowania użytkowników, którzy przestali korzystać z aplikacji.
• Czas wygaśnięcia: przyszły czas, po którym lista niestandardowych odbiorców zostanie usunięta z urządzenia.
• Sygnały określania stawek przez użytkownika: ciąg tekstowy JSON zawierający sygnały użytkownika, np. preferowaną przez niego lokalizację, które są wykorzystywane przez logikę JavaScript kupującego do generowania stawek podczas procesu wyboru reklamy. Ten format pomaga platformom reklamowym w ponownym wykorzystywaniu kodu na różnych platformach i ułatwia jego wykorzystanie w funkcjach JavaScript.
• Zaufane dane określania stawek: adres URL HTTPS i lista ciągów znaków używanych podczas procesu wyboru reklam, które pobierają sygnały określania stawek z zaufanego usługi klucz-wartość.
• Reklamy: lista obiektów AdData odpowiadających reklamom, które biorą udział w wybieraniu reklam. Każdy obiekt AdData składa się z tych elementów:
  • URL renderowania: adres URL HTTPS, który jest wyszukiwany w celu renderowania ostatecznej reklamy.
  • Metadane: obiekt JSON zserializowany jako ciąg znaków zawierający informacje, które są wykorzystywane przez logikę określania stawek przez kupującego podczas procesu wyboru reklamy.
  • Filtry reklam: klasa zawierająca wszystkie informacje potrzebne do filtrowania reklam w celu instalacji aplikacji i określania limitu wyświetleń na użytkownika podczas wyboru reklam.

Oto przykład utworzenia obiektu CustomAudience:

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

Obsługa wyników funkcji joinCustomAudience()

Asymetryczna metoda joinCustomAudience() używa obiektu OutcomeReceiver do sygnalizowania wyniku wywołania interfejsu API.

• Wywołanie zwrotne onResult() oznacza, że lista niestandardowa została utworzona lub zaktualizowana.
• Wywołanie onError() oznacza 2 możliwe warunki.
  • Jeśli funkcja JoinCustomAudienceRequest zostanie zainicjowana z nieprawidłowymi argumentami, funkcja AdServicesException wskaże jako przyczynę błąd IllegalArgumentException.
  • Wszystkie pozostałe błędy mają wartość AdServicesException z przyczyną IllegalStateException.

Oto przykład obsługi wyniku funkcji joinCustomAudience():

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

Dodawanie i usuwanie odbiorców niestandardowych

Jeśli użytkownik przestanie spełniać kryteria biznesowe określone dla danej listy odbiorców niestandardowych, aplikacja lub pakiet SDK może wywołać funkcję leaveCustomAudience(), aby usunąć tę listę z urządzenia. Aby usunąć CustomAudience na podstawie jego unikalnych parametrów:

1. Inicjuje obiekt CustomAudienceManager.
2. Inicjalizacja LeaveCustomAudienceRequest z użyciem wartości buyer i name z listy niestandardowych odbiorców. Więcej informacji o tych polach znajdziesz w artykule Łączenie z listą niestandardowych odbiorców.
3. Wywołaj asynchroniczną metodę leaveCustomAudience() z obiektem LeaveCustomAudienceRequest oraz odpowiednimi obiektami Executor i OutcomeReceiver.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

Podobnie jak w przypadku wywołania joinCustomAudience(), OutcomeReceiver sygnalizuje koniec wywołania interfejsu API. Aby chronić prywatność, wynik błędu nie rozróżnia błędów wewnętrznych od nieprawidłowych argumentów. Funkcja onResult() zostaje wywołana po zakończeniu wywołania interfejsu API, niezależnie od tego, czy udało się usunąć pasującą listę odbiorców.

Wybór reklamy

Aby używać interfejsu Protected Audience API do wybierania reklam, wywołaj metodę selectAds():

1. Inicjuje obiekt AdSelectionManager.
2. Utwórz obiekt AdSelectionConfig.
3. Wywołaj asynchroniczną metodę selectAds() z obiektem AdSelectionConfig oraz odpowiednimi obiektami Executor i OutcomeReceiver.

val adSelectionManager: AdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
  AdSelectionConfig.Builder().setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(
        contextualAds.getBuyer(), contextualAds
      )
    ).build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
  adSelectionConfig, executor, outcomeReceiver
)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
    )
    .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(adSelectionConfig, executor, outcomeReceiver);

Metoda selectAds() wymaga wejścia AdSelectionConfig, w którym musisz podać te wymagane parametry:

• Sprzedawca: identyfikator sieci reklamowej sprzedawcy, który inicjuje wybór reklamy.
• URL logiki decyzji: adres URL HTTPS, który jest zapytaniem o logikę JavaScript sieci reklamowej sprzedawcy.
  • Adres URL HTTPS: zapytanie służy do uzyskania logiki JavaScript sieci reklamowej sprzedawcy. Sprawdź wymagane funkcje podpisów.
  • Wstępnie utworzony identyfikator URI: odpowiada formatowi wyboru reklamy FLEDGE. IllegalArgumentException jest rzucany, jeśli podany nieobsługiwany lub źle sformatowany wstępnie utworzony identyfikator URI.
• Kupujący korzystający z list odbiorców niestandardowych: pełna lista identyfikatorów sieci reklamowych kupujących, które mogą uczestniczyć w procesie wyboru reklamy. Te identyfikatory kupujących odpowiadają CustomAudience.getBuyer()uczestniczących niestandardowych list odbiorców.

Aby dostosować wyświetlanie reklam, możesz opcjonalnie podać te parametry:

• Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków, zawierający sygnały, które mają być używane przez logikę licytowania kupującego w JavaScript pobrane z CustomAudience.getBiddingLogicUrl().
• Sygnały sprzedawcy: obiekt JSON zserializowany jako ciąg znaków, zawierający sygnały wykorzystywane przez logikę podejmowania decyzji w JavaScriptzie pobrane z pliku AdSelectionConfig.getDecisionLogicUrl().
• Sygnały poszczególnych kupujących: mapa obiektów JSON zserializowanych jako ciągi tekstowe, zawierająca sygnały wykorzystywane przez logikę określania stawek w JavaScriptzie w przypadku konkretnych kupujących, pobierane z pliku CustomAudience.getBiddingLogicUrl() i identyfikowane przez pola kupujących w przypadku uczestniczących list odbiorców niestandardowych.
• Reklamy kontekstowe: zbiór kandydatów na reklamy zbieranych bezpośrednio od kupujących podczas aukcji, która odbywa się poza aukcją chronionych odbiorców.

Po wybraniu reklamy wyniki, stawki i sygnały są przechowywane wewnętrznie na potrzeby raportowania. Wywołanie zwrotne OutcomeReceiver.onResult() zwraca obiekt AdSelectionOutcome, który zawiera:

• Adres URL renderowania zwycięskiej reklamy uzyskany z AdData.getRenderUrl().
• Unikalny identyfikator wyboru reklamy dla użytkownika urządzenia. Ten identyfikator jest używany do raportowania wyświetleń reklamy.

Jeśli nie uda się wybrać reklamy z powodu nieprawidłowych argumentów, przekroczenia limitu czasu lub nadmiernego zużycia zasobów, wywołanie OutcomeReceiver.onError() zwraca wartość AdServicesExceptionz tymi zachowaniami:

• Jeśli wybór reklamy jest inicjowany za pomocą nieprawidłowych argumentów, AdServicesException wskazuje jako przyczynę błąd IllegalArgumentException.
• Wszystkie pozostałe błędy mają wartość AdServicesException z przyczyną IllegalStateException.

Reklamy kontekstowe

Protected Audience może uwzględniać reklamy kontekstowe w ramach aukcji chronionej. Reklamy kontekstowe muszą być wybierane na serwerze technologii reklamowych i zwracane na urządzenie poza interfejsami Protected Audience API. Reklamy kontekstowe można następnie uwzględniać w aukcji za pomocą AdSelectionConfig. W tym momencie działają one tak samo jak reklamy na urządzeniu, w tym pod kątem kwalifikowania się do filtrowania reklam. Po zakończeniu aukcji dla chronionych odbiorców musisz wywołać funkcję reportImpression(). W wygrywającej reklamie kontekstowej wywołuje to parametr reportWin() w tym samym wzorze co raportowanie wyświetleń, aby wyświetlić tę reklamę na urządzeniu. Każda reklama kontekstowa wymaga kupującego, stawki, linku do logiki raportowania, adresu URL renderowania i metadanych reklamy.

Aby wdrażać reklamy kontekstowe w aplikacji, aplikacja docelowa musi utworzyć obiekt ContextualAds:

val contextualAds: ContextualAds =
  Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
    //Pass in your valid app install ads
    .setDecisionLogicUri(mContextualLogicUri)
    .setAdsWithBid(appInstallAd)
    .build()

ContextualAds contextualAds = new ContextualAds.Builder()
  .setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
  .setDecisionLogicUri(mContextualLogicUri)
  //Pass in your valid app install ads
  .setAdsWithBid(appInstallAd)
  .build();

Utworzony obiekt ContextualAds można następnie przekazać podczas tworzenia AdSelectionConfig:

// Create a new ad
val noFilterAd: AdData = Builder()
  .setMetadata(JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)

// Create a new ad
AdData noFilterAd = new AdData.Builder()
  .setMetadata(new JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);

Filtrowanie reklam promujących instalacje aplikacji

Filtrowanie reklam promujących instalację aplikacji pomaga filtrować reklamy promujące instalację aplikacji, które są już zainstalowane na urządzeniu.

Pierwszym krokiem w tym procesie jest określenie, którzy reklamodawcy mają możliwość filtrowania według zainstalowanego pakietu. Musi się to odbywać w aplikacji, którą chcesz uwzględnić w kierowaniu reklamy.

//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  object : OutcomeReceiver<Any?, Exception?>() {
    fun onResult(@NonNull ignoredResult: Any?) {
      Log.v("[your tag]", "Updated app install advertisers")
    }

    fun onError(@NonNull error: Exception?) {
      Log.e("[your tag]", "Failed to update app install advertisers", error)
    }
  })

//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  new OutcomeReceiver<Object, Exception>() {
    @Override
    public void onResult(@NonNull Object ignoredResult) {
      Log.v("[your tag]", "Updated app install advertisers");
    }

    @Override
    public void onError(@NonNull Exception error) {
      Log.e("[your tag]", "Failed to update app install advertisers", error);
    }
  });

Po wykonaniu powyższego kodu podani reklamodawcy mogą odfiltrowywać zainstalowane aplikacje, które określisz podczas generowania stawek. Jeśli chcesz zablokować dostęp reklamodawcy do informacji o stanie instalacji tej aplikacji, uruchom ten kod ponownie, ale bez informacji o reklamodawcy.

Następnym krokiem jest skonfigurowanie filtrowania reklam w aplikacji wydawcy. Strona, która wyświetla reklamę w aplikacji wydawcy (najprawdopodobniej pakiet SDK po stronie dostawcy), musi zainicjować obiekt AdFilters z informacjami o tym, które reklamy związane z aplikacją chce odfiltrować:

// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
    Builder().setPackageNames(setOf("example.target.app")).build()
  ).build()

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

Wydawcy po stronie popytu mogą też ustawiać AdFilter dla reklam, które znajdują się w ich listach odbiorców niestandardowych.

AdFilters można też przekazać w miejscu tworzenia nowego obiektu AdData:

// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
  Builder().setMetadata("{ ... }") // Valid JSON string
    .setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters).build()

// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters)
    .build();

Filtrowanie według limitu wyświetleń na użytkownika

Filtrowanie według limitu wyświetleń umożliwia ograniczenie liczby wyświetleń reklamy. Filtrowanie na podstawie ograniczenia liczby wyświetleń zmniejsza nadmierne wyświetlanie reklam i optymalizuje wybór reklam alternatywnych w danej kampanii reklamowej.

Filtr ograniczający częstotliwość wyświetlania reklam składa się z 2 głównych elementów: typu zdarzenia reklamowego i klucza licznika reklam. Dostępne typy zdarzeń reklamowych:

• Wygrana: zdarzenie wygrana wskazuje, że reklama wygrała aukcję. Zdarzenia wygranej są automatycznie aktualizowane przez interfejs Protected Audience API i nie mogą być wywoływane bezpośrednio przez dewelopera. Dane o wygrywaniu są widoczne tylko dla reklam w danej grupie niestandardowej.
• Wyświetlenie: niezależnie od reportImpression, wywołujący na urządzeniu (SSP lub MMP) używa updateAdCounterHistogram() do wywoływania zdarzeń wyświetlenia w wybranym przez siebie miejscu w kodzie. Zdarzenia wyświetleń są widoczne dla wszystkich reklam należących do danej platformy DSP i nie są ograniczone do reklam w tej samej grupie odbiorców niestandardowych.
• Wyświetlanie: wywołanie zdarzenia przez wywołującego na urządzeniu (SSP lub MMP) w wybranym przez niego miejscu kodu za pomocą wywołania updateAdCounterHistogram(). Zdarzenia wyświetleń są widoczne dla wszystkich reklam należących do danej platformy DSP i nie są ograniczone do reklam na tej samej liście odbiorców niestandardowej.
• Kliknięcie: wywołanie zdarzenia przez wywołującego na urządzeniu (SSP lub MMP) w wybranym przez niego miejscu kodu za pomocą wywołania updateAdCounterHistogram(). Zdarzenia kliknięcia są widoczne dla wszystkich reklam należących do danej platformy DSP i nie są ograniczone do reklam na tej samej liście odbiorców niestandardowych.

W aplikacji wydawcy dostawca SSP lub MMP obecny na urządzeniu wywołuje zdarzenia reklamowe. Gdy wywoływana jest funkcja updateAdCounterHistogram(), licznik filtra ograniczenia liczby wyświetleń jest zwiększany, aby przyszłe aukcje zawierały aktualne informacje o wyświetleniu danej reklamy przez użytkownika. Typy zdarzeń reklam nie są ściśle powiązane z odpowiednimi działaniami użytkownika i stanowią wskazówki, które pomagają wywołującym sformatować system zdarzeń. Aby zwiększyć liczniki reklam w momencie wystąpienia zdarzenia, podmiot na urządzeniu przekazuje identyfikator wyboru reklamy z wygrywającej aukcji reklamowej.

Klucze licznika reklam to dowolne 32-bitowe liczby całkowite ze znakiem przypisane przez technologię reklamową kupującego. Odpowiadają one danemu zbiorowi reklam zdefiniowanemu przez platformę DSP. Klucze licznika reklam są ograniczone tylko do reklam należących do danego DSP, dlatego można je wybierać bez nakładania się z histogramami z innych technologii reklamowych. Klucze licznika reklam służą do zwiększania identyfikatorów specyficznych dla DSP w reklamach w DSP lub w danej grupie odbiorców niestandardowych, aby wykluczać reklamy z przyszłych aukcji.

Klucze licznika można wykorzystać do nadawania priorytetów reklamom, które są bardziej prawdopodobne, że zainteresują danego użytkownika na podstawie jego interakcji z innymi reklamami danego dostawcy technologii reklamowych. Na przykład reklama, która uzyskała wysoki poziom zaangażowania dzięki wygranym aukcjom reklamowym, wyświetleniom i kliknięciom, stanowi wywnioskowany punkt danych. Aby to zilustrować, podajmy przykład reklamy kijów golfowych dla leworęcznych. Może to oznaczać, że użytkownik nie jest zainteresowany kijami dla praworęcznych. Filtr limitu wyświetleń ustawiony dla klucza licznika przypisanego do reklam dla leworęcznych może odfiltrowywać reklamy dla osób praworęcznych.

Aby używać w aukcji limitu wyświetleń na użytkownika, musisz najpierw utworzyć obiekty KeyedFrequencyCap:

// Value used when incrementing frequency counter
val adCounterKey = 123

// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 2, Duration.ofSeconds(10)
).build()

// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 1, Duration.ofSeconds(10)
).build()

// Value used when incrementing frequency counter
int adCounterKey = 123;

// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 2, Duration.ofSeconds(10)
  ).build();

// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 1, Duration.ofSeconds(10)
  ).build();

Po utworzeniu obiektów KeyedFrequencyCap możesz je przekazać do obiektu AdFilters.

val filters: AdFilters = Builder()
  .setFrequencyCapFilters(
    Builder()
      .setKeyedFrequencyCapsForImpressionEvents(
        ImmutableObject.of(keyedFrequencyCapForImpression)
      )
      .setKeyedFrequencyCapsForClickEvents(
        ImmutableObject.of(keyedFrequencyCapForClick)
      )
  ).build()

AdFilters filters = new AdFilters.Builder()
    .setFrequencyCapFilters(new FrequencyCapFilters.Builder()
        .setKeyedFrequencyCapsForImpressionEvents(
            ImmutableObject.of(keyedFrequencyCapForImpression)
        )
        .setKeyedFrequencyCapsForClickEvents(
            ImmutableObject.of(keyedFrequencyCapForClick)
        )
    ).build();

Gdy obiekt AdFilters jest wypełniony filtrami ograniczania liczby wyświetleń, można go przekazać podczas tworzenia listy odbiorców niestandardowej:

// Initialize a custom audience.
val audience: CustomAudience = Builder()
  .setBuyer(buyer)
  .setName(name)
  .setAds(
    listOf(
      Builder()
        .setRenderUri(renderUri)
        .setMetadata(JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()
    )
  ).build()

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setAds(Collections.singletonList(new AdData.Builder()
        .setRenderUri(renderUri)
        .setMetadata(new JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()))
    .build();

Gdy filtry limitu częstotliwości są stosowane w przypadku listy niestandardowej, SSP może wywołać odpowiednie zdarzenia kliknięcia, wyświetlenia lub wyświetlenia.

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

val request: UpdateAdCounterHistogramRequest = Builder(
  adSelectionId,
  FrequencyCapFilters.AD_EVENT_TYPE_CLICK,  //CLICK, VIEW, or IMPRESSION
  callerAdTech
).build()

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

UpdateAdCounterHistogramRequest request =
  new UpdateAdCounterHistogramRequest.Builder(
      adSelectionId,
      FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
      callerAdTech
).build();

Reklamy, które osiągnęły ustawione wcześniej limity filtra ograniczeń liczby wyświetleń, są odfiltrowywane z aukcji. Filtrowanie odbywa się przed wykonaniem logiki ustalania stawek w przypadku aukcji na urządzeniu i podczas generowania ładunku w przypadku aukcji usług ustalania stawek. Ten zestaw narzędzi daje specjalistom ds. technologii reklamowych elastyczność w korzystaniu z interakcji użytkowników z reklamami w ramach ich list odbiorców niestandardowych, aby ukierunkować kierowanie reklam, minimalizując jednocześnie ich nadmierną ekspozycję.

Filtrowanie reklam kontekstowych bez wywołań sieciowych

Jeśli na urządzeniu nie ma zapotrzebowania na remarketing, możesz uruchamiać wybór reklam w przypadku reklam kontekstowych bez wywołań sieci. Dzięki gotowym identyfikatorom URI i liście reklam kontekstowych ze stawkami platforma może pominąć pobieranie logiki ustalania stawek, sygnałów dotyczących stawek i sygnałów punktacji. Platforma używa gotowego identyfikatora URI do wybrania reklamy kontekstowej z najwyższą stawką.

Aby skrócić czas oczekiwania, firmy technologiczne zajmujące się reklamami mogą uruchamiać proces wyboru reklam, który obejmuje tylko reklamy kontekstowe z funkcją filtrowania reklam bez wywołań sieciowych. Osiąga się to, używając gotowych identyfikatorów URI do punktowania sygnałów. Aby poznać listę obsługiwanych implementacji scoreAds, zapoznaj się z sekcją z przypadkami użycia gotowych identyfikatorów URI i ich nazwami.

Aby uruchomić wybór reklam bez wywołań sieci:

1. Konfigurowanie filtrowania reklam
2. Tworzenie reklam kontekstowych

3. Utwórz obiekt AdSelectionConfig z tymi właściwościami:

   1. pusta lista kupujących;
   2. Wstępnie utworzony identyfikator URI do wybierania najwyższej stawki
   3. Reklamy kontekstowe
   4. Pusty identyfikator URI dla sygnałów oceny. Pusty identyfikator URI jest dozwolony, aby wskazać, że nie chcesz używać pobierania zaufanych sygnałów do obliczania wyniku:

   Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting");
   // Initialize AdSelectionConfig
   AdSelectionConfig adSelectionConfig =
     new AdSelectionConfig.Builder()
       .setSeller(seller)
       .setDecisionLogicUri(prebuiltURIScoringUri)
       .setCustomAudienceBuyers(Collections.emptyList())
       .setAdSelectionSignals(adSelectionSignals)
       .setSellerSignals(sellerSignals)
       .setPerBuyerSignals(perBuyerSignals)
       .setBuyerContextualAds(buyerContextualAds)
       .setTrustedScoringSignalsUri(Uri.EMPTY)
       .build();
   

4. Uruchom wybór reklam:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Uruchamianie własnego kodu JavaScript do raportowania przy użyciu gotowych identyfikatorów URI

Obecnie platforma Piaskownica prywatności udostępnia tylko podstawową implementację JavaScriptu do raportowania w przypadku gotowych adresów URI. Jeśli chcesz uruchomić własny kod JavaScript do raportowania, nadal korzystając z wstępnie utworzonych identyfikatorów URI w celu uzyskania reklam o niskiej latencji, możesz zastąpić parametr DecisionLogicUri między wyborem reklamy a uruchomieniem raportowania.

1. Wykonaj czynności w celu uruchomienia selekcji reklam w przypadku reklam kontekstowych z użyciem gotowych adresów URI

2. Zanim uruchomisz raportowanie, utwórz kopię AdSelectionConfig.

   adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder()
     // Replace <urlToFetchYourReportingJS> with your own URL:
     .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>))
     .build();
   

3. Generowanie raportów o wyświetleniach

   // adSelectionId is from the result of the previous selectAds run
   ReportImpressionRequest request = new ReportImpressionRequest(
     adSelectionId,
     adSelectionConfigWithYourReportingJS);
   adSelectionManager.reportImpression(
     request,
     executor,
     outcomeReceiver);
   

Uruchamianie zapośredniczenia kaskadowego

Zapośredniczenie kaskadowe wymaga skoordynowania przez sieć zapośredniczenia pakietów SDK firm zewnętrznych. Pośrednictwo w schemacie kaskadowym działa tak samo niezależnie od tego, czy aukcja miała miejsce na urządzeniu, czy w usłudze licytowania i przeprowadzania aukcji (L&A).

Sieci 3P

Sieci zewnętrzne muszą udostępnić adapter, który umożliwia sieci pośredniczącej wywołanie niezbędnych metod do przeprowadzania aukcji:

• Wybór reklamy
• Raportowanie wyświetleń

Oto przykład adaptera sieci pośredniczącej:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

    init {
        adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
    }

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

    public NetworkAdaptor() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Każdy pakiet SDK ma swoich menedżerów i klientów usługi doboru reklam oraz własne implementacje selectAds i reportImpressions. Dostawcy pakietów SDK mogą zapoznać się z sekcjami dotyczącymi wyboru reklam w przypadku aukcji na urządzeniu lub z objaśnieniami dotyczącymi aukcji B&A. Dowiedz się, jak zgłaszać wyświetlenia reklam (wykonując raportowanie wyświetleń w pojedynczym SSP).

Sieć zapośredniczeń

Podobnie jak w przypadku sieci innych firm, sieci zapośredniczenia wymagają implementacji selectAds i reportImpression. Więcej informacji znajdziesz w sekcji o wybieraniu reklam i raportowaniu wyświetleń reklam.

Sieci zapośredniczenia odpowiadają za prowadzenie łańcucha zapośredniczenia i umieszczanie się w łańcuchu zapośredniczenia. W następnej sekcji opisujemy, jak skonfigurować i przeprowadzić ten proces.

Pobieranie łańcucha zapośredniczenia i podpór stawek

Sieć pośrednicząca odpowiada za pobieranie reklam kontekstowych własnych (1P), łańcucha pośrednictwa i stawek minimalnych sieci zewnętrznych (3P). Może się to zdarzyć w przypadku żądania pobierania reklam kontekstowych wykonywanego przez sieć zapośredniczoną. Łańcuch zapośredniczenia określa sposób przechodzenia przez sieci zewnętrzne, a minimalne stawki mogą być przekazywane do procesu aukcji jako adSelectionSignals.

Miejsce sieci w łańcuchu zapośredniczenia

Pakiet SDK zapośredniczenia może się umieścić w łańcuchu zapośredniczenia na podstawie bieżącej wartości eCPM stawek reklam własnych. W interfejsie Protected Audience API stawki reklam są nieprzejrzyste. SDK zapośredniczenia powinien używać AdSelectionFromOutcomesConfig, aby można było porównać stawkę danej reklamy w ramach sieci reklamowej 1P ze stawką minimalną następnej sieci reklamowej 3P w łańcuchu. Jeśli stawka własna jest wyższa niż minimalna stawka, oznacza to, że pakiet SDK zapośredniczenia jest umieszczony przed siecią zewnętrzną.

Wybór reklamy

Aby pobrać kandydata reklamy własnej, sieć zapośredniczenia może przeprowadzić aukcję na urządzeniu zgodnie z instrukcjami podanymi w sekcji wybór reklamy. Generuje to kandydata do wyświetlenia reklamy z domeny własnej, stawkę i AdSelectionId, które są używane w procesie zapośredniczenia.

Tworzenie obiektu AdSelectionFromOutcomesConfig

AdSelectionFromOutcomesConfig pozwala sieci pośredniczącej przekazać listę AdSelectionIds (wyniki z poprzednich aukcji), sygnałów wyboru reklamy oraz identyfikator URI do pobierania kodu JavaScript, który wybiera reklamę spośród wielu kandydatów. Lista identyfikatorów AdSelectionId wraz z ich stawkami i sygnałami jest przekazywana do kodu JavaScript, który może zwrócić jedną z wartości AdSelectionIds, jeśli jest wyższa od stawki minimalnej, lub żadną, jeśli łańcuch zapośredniczenia ma być kontynuowany.

Sieci pośredniczące tworzą AdSelectionFromOutcomesConfig, korzystając z wartości AdSelectionId z poprzedniej sekcji i wartości minimalnej stawki dla sieci zewnętrznej, która jest rozpatrywana. Dla każdego etapu łańcucha zapośredniczenia należy utworzyć nowe AdSelectionFromOutcomesConfig.

fun  runSelectOutcome(
    adSelectionClient : AdSelectionClient,
    outcome1p : AdSelectionOutcome,
    network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
    val config = AdSelectionFromOutcomesConfig.Builder()
        .setSeller(seller)
        .setAdSelectionIds(listOf(outcome1p))
        .setSelectionSignals({"bid_floor": bid_floor})
        .setSelectionLogicUri(selectionLogicUri)
        .build()
    return adSelectionClient.selectAds(config)
}

public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) {
    AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .build();

    return adSelectionClient.selectAds(config){}
}

Zastąpienie metody selectAds() w ramach pośrednictwa w modelu kaskadowym wymaga parametru AdSelectionFromOutcomesConfig, w którym musisz podać te wymagane parametry:

• Sprzedawca: identyfikator sieci reklamowej sprzedawcy, który inicjuje wybór reklamy.
• AdSelectionIds: lista zawierająca pojedynczy element z poprzedniego wywołania funkcji selectAds() dla reklamy własnej.
• Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały, których używa logika określania stawek przez kupującego. W takim przypadku uwzględnij minimalną stawkę wygenerowaną dla danej sieci zewnętrznej.
• URI logiki wyboru: identyfikator URI adresu HTTPS zapytany podczas wyboru reklamy w celu pobrania kodu JavaScript sieci reklamowej do wyboru reklamy zwycięskiej. W tym kodzie JavaScriptu znajdziesz wymagane nazwy funkcji. Kod JavaScript powinien zwracać reklamę zewnętrzną, jeśli stawka jest wyższa niż minimalna stawka, lub zwracać null. Umożliwia to pakietowi SDK zapośredniczenia skrócenie łańcucha zapośredniczenia po znalezieniu zwycięzcy.

Po utworzeniu AdSelectionOutcomesConfig wywołaj metodę selectAds() sieci zewnętrznej, która jest pierwsza w łańcuchu.

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
  AdSelectionFromOutcomesConfig.Builder()
    .setSeller(seller)
    .setAdSelectionIds(listof(outcome1p))
    .setSelectionSignals({"bid_floor": bid_floor})
    .setSelectionLogicUri(selectionLogicUri)
    .setAdSelectionIds(outcomeIds)
    .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
        new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .setAdSelectionIds(outcomeIds)
            .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver);

Organizowanie zapośredniczenia kaskadowego

Poniżej znajdziesz kolejność operacji w ramach procesu zapośredniczenia.

1. Wykonaj selekcję reklam własnych.
2. Przejdź przez łańcuch zapośredniczenia. W przypadku każdej sieci zewnętrznej:
   1. Utwórz AdSelectionFromOutcomeConfig, w tym outcomeId własnego dostawcy i podstawową stawkę 3 poziomowego pakietu SDK.
   2. Wywołaj selectAds() z konfiguracją z poprzedniego kroku.
   3. Jeśli wynik nie jest pusty, zwracaj reklamę.
   4. Wywołaj metodę selectAds() w bieżącym adapterze sieci pakietu SDK. Jeśli wynik nie jest pusty, zwraca reklamę.
3. Jeśli w łańcuchu nie zostanie znaleziony zwycięzca, zwracaj reklamę własną.

fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
  : Pair<AdSelectionOutcome, NetworkAdapter> {
    val outcome1p = runAdSelection()

    var outcome : AdSelectionOutcome
    for(network3p in mediationChain) {
      outcome = runSelectOutcome(outcome1p, network3p)
      if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
          return Pair(outcome, this)
      }

      outcome = network3p.runAdSelection()
      if(outcome.hasOutcome()) {
          return Pair(outcome, network3p)
      }
    }
  return Pair(outcome1p, this)
}

class MediationNetwork {
    AdSelectionManager adSelectionManager;

    public MediationNetwork() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void runAdSelection() {...}

    public void reportImpressions() {...}

    public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
            List<NetworkAdapter> mediationChain) {
        AdSelectionOutcome outcome1p = runAdSelection();

        AdSelectionOutcome outcome;
        for(NetworkAdapter network3p: mediationChain) {
            if (outcome1p.hasOutcome() &&
              (outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
                return new Pair<>(outcome, this);
            }

            if((outcome = network3p.runAdSelection()).hasOutcome()) {
                return new Pair<>(outcome, network3p);
            }
        }
        return new Pair<>(outcome1p, this);
    }

    /* Runs comparison by creating an AdSelectionFromOutcomesConfig */
    public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) { ... }
}

Zgłaszanie wyświetleń reklam

Występują 2 sposoby raportowania wyświetleń reklamy w zależności od tego, jak przebiega aukcja. Jeśli jesteś pojedynczym SSP, który przeprowadza aukcję, przeczytaj tę sekcję. Jeśli chcesz wdrożyć zapośredniczenie kaskadowe, wykonaj czynności opisane w sekcji Raportowanie wyświetleń zapośredniczenia kaskadowego.

Raportowanie wyświetleń w pojedynczym SSP

Po wybraniu reklamy zwycięskiej z ram łańcucha procesu wyboru reklamy możesz zgłosić wyświetlenie do platform uczestniczących po stronie kupującego i sprzedającego za pomocą metody AdSelectionManager.reportImpression(). Aby zgłosić wyświetlenie reklamy:

1. Inicjuje obiekt AdSelectionManager.
2. Utwórz obiekt ReportImpressionRequest z identyfikatorem selekcji reklamy.
3. Wywołaj asynchroniczną metodę reportImpression() z obiektem ReportImpressionRequest oraz odpowiednimi obiektami Executor i OutcomeReceiver.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig)
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig)
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

Inicjalizacja ReportImpressionRequest z tymi wymaganymi parametrami:

• Identyfikator wyboru reklamy: identyfikator, który jest unikalny dla użytkownika urządzenia i identyfikuje pomyślny wybór reklamy.
• Konfiguracja wyboru reklamy: ta sama konfiguracja, która została użyta w wywołaniu selectAds(), zidentyfikowanym przez podany identyfikator wyboru reklamy.

Asymetryczna metoda reportImpression() używa obiektu OutcomeReceiver do sygnalizowania wyniku wywołania interfejsu API.

• W wywołaniu onResult() zostanie wskazane, czy adresy URL raportowania wyświetleń zostały utworzone i czy żądanie zostało zaplanowane.
• Wywołanie onError() wskazuje te możliwe warunki:
  • Jeśli wywołanie jest inicjowane nieprawidłowym argumentem wejściowym, AdServicesException wskazuje jako przyczynę błąd IllegalArgumentException.
  • Wszystkie pozostałe błędy mają wartość AdServicesException z przyczyną IllegalStateException.

Raporty o wyświetleniach w przypadku zapośredniczenia kaskadowego

Pakiet SDK do zapośredniczenia musi śledzić zwycięski pakiet SDK, aby uruchamiać procesy raportowania. Pakiety SDK uczestniczące w łańcuchu zapośredniczenia powinny udostępniać pośrednikowi metodę wywołania, która uruchamia ich własny proces raportowania. Pakiet SDK uczestniczący w aukcji pośredniczącej może zaimplementować własne raportowanie, wykonując powyższe czynności.

SSP-y mogą wykorzystać ten przykład kodu pakietu SDK firmy zewnętrznej jako prototyp dołączania do procesów pośrednictwa:

Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
         mediationSdk.orchestrateMediation(mediationChain);

if (winner.first.hasOutcome()) {
      winner.second.reportImpressions(winner.first.getAdSelectionId());

Punkty końcowe raportowania wyświetleń

Interfejs API raportowania wyświetleń wysyła żądania HTTPS GET do punktów końcowych udostępnionych przez platformę reklamową strony sprzedaży i wygrywającą platformę strony kupna:

Punkt końcowy platformy po stronie kupującego:

• Interfejs API używa adresu URL reguły ustalania stawek określonego w przypadku listy niestandardowych odbiorców, aby pobrać kod JavaScript dostarczony przez kupującego, który zawiera regułę zwracania adresu URL raportowania wyświetleń.
• Wywołaj funkcję JavaScriptu reportWin(), która powinna zwrócić adres URL raportu wyświetleń kupującego.

Punkt końcowy platformy SSP:

• Aby pobrać logikę decyzyjną sprzedawcy w formie kodu JavaScript, użyj adresu URL logiki decyzyjnej określonego w obiekcie AdSelectionConfig.
• Wywołaj funkcję JavaScriptu reportResult(), która powinna zwrócić adres URL raportu wyświetleń sprzedawcy.

Raportowanie usług określania stawek i aukcji

Aukcja przeprowadzona w ramach usług Określanie stawek i Aukcji będzie zawierać wszystkie niezbędne informacje do raportowania, w tym wygenerowane adresy URL do raportowania interakcji z reklamą, uwzględnione w zaszyfrowanej odpowiedzi z aukcji po stronie serwera. Gdy odpowiedź zostanie odszyfrowana, odpowiednie adresy URL zostaną zarejestrowane na platformie, dzięki czemu raportowanie reklam i wyświetleń będzie przebiegać w taki sam sposób.

Możliwie najlepsza obsługa raportowania wyświetleń

Metoda reportImpression() została zaprojektowana tak, aby zapewnić jak największą dokładność raportowania.

Zgłaszanie interakcji z reklamami

Protected Audience umożliwia raportowanie bardziej szczegółowych interakcji z wyświetlanymi reklamami. Mogą to być interakcje takie jak czas wyświetlania, kliknięcia, najechanie kursorem myszy lub inne przydatne dane, które można zbierać. Aby otrzymać te raporty, musisz wykonać 2 kroki. Po pierwsze, kupujący i sprzedający muszą się zarejestrować, aby otrzymywać te raporty w swoim kodzie JavaScript do raportowania. Następnie klient musi zgłosić te zdarzenia.

Rejestrowanie się w celu otrzymywania zdarzeń interakcji

Rejestrowanie zdarzeń interakcji odbywa się w funkcjach JavaScript reportWin() kupującego i reportResult() sprzedawcy za pomocą funkcji JavaScript udostępnianej przez platformę: registerAdBeacon. Aby zarejestrować się w celu otrzymywania raportu o wydarzeniu, wywołaj funkcję JavaScript platformy z Twojego kodu JavaScript do raportowania. Ten fragment kodu używa funkcji reportWin() kupującego, ale ta sama metoda dotyczy też funkcji reportResult().

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri

    registerAdBeacon({"click": clickUri, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

Raportowanie zdarzeń interakcji

Po zgłoszeniu wyświetlenia klienci mogą zgłaszać interakcje z poprzednio zarejestrowanymi zwycięskimi platformami po stronie kupującego i sprzedającego za pomocą metody AdSelectionManager.reportInteraction(). Aby zgłosić zdarzenie reklamowe:

1. Inicjuje obiekt AdSelectionManager.
2. Utwórz obiekt ReportInteractionRequest z identyfikatorem selekcji reklamy, kluczem interakcji, danymi interakcji i miejscem docelowym raportowania.
3. Wywołaj asynchroniczną metodę reportInteraction() z obiektem request oraz odpowiednimi obiektami Executor i OutcomeReceiver.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
  new ReportInteractionRequest.Builder()
    .setAdSelectionId(adSelectionId)
    .setInteractionKey("view")
    .setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
    .setReportingDestinations(
      FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
    )
    .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportInteraction(
  reportImpressionRequest,
  executor,
  outcomeReceiver);

Inicjalizacja ReportInteractionRequest z tymi wymaganymi parametrami:

• Identyfikator wyboru reklamy: identyfikator wyboru reklamy pobrany z poprzednio zwróconego zapytaniaAdSelectionOutcome.
• Klucz interakcji: klucz ciągu znaków zdefiniowany przez klienta, opisujący rejestrowane działanie. Musi on być zgodny z kluczem zarejestrowanym przez sprzedawcę lub kupującego w funkcjach JavaScript do raportowania.
• Dane interakcji: ciąg tekstowy zawierający dane, które mają zostać uwzględnione w raporcie zdarzenia, aby można je było przesłać z powrotem na serwery raportowania.
• Docelowe miejsca raportowania: maska bitowa określająca, czy zdarzenia mają być raportowane do kupującego, sprzedającego czy do obu. Te flagi są dostarczane przez platformę, a ostateczną maskę miejsca docelowego można utworzyć za pomocą operacji bitowych. Aby przesłać raport do jednego miejsca docelowego, możesz użyć flagi udostępnionej bezpośrednio przez platformę. Aby wysyłać raporty do wielu miejsc docelowych, możesz użyć operatora logicznego OR (|) do łączenia wartości flagi.

Asymetryczna metoda reportInteraction() używa obiektu OutcomeReceiver do sygnalizowania wyniku wywołania interfejsu API.

• Wywołanie onResult() wskazuje, że wywołanie raportu interakcji jest prawidłowe.
• Wywołanie onError() wskazuje te możliwe warunki:
  • Jeśli wywołanie zostanie wykonane, gdy aplikacja działa w tle, zwrócony zostanie kodIllegalStateException z opisem błędu.
  • Jeśli klient jest ograniczony w wywoływaniu funkcji reportInteraction(), zwracana jest wartość LimitExceededException.
  • Jeśli pakiet nie jest zarejestrowany do wywoływania interfejsów API chroniących prywatność, zwracana jest wartośćSecurityException().
  • Jeśli aplikacja zgłaszająca interakcje jest inna niż aplikacja, która wywołała funkcję selectAds(), zwracana jest wartość IllegalStateException.
• Jeśli użytkownik nie wyraził zgody na włączenie interfejsów API Piaskownicy prywatności, wywołanie zakończy się niepowodzeniem.

Punkty końcowe raportowania interakcji

Interfejs API interakcji z raportami wysyła żądania HTTPS POST do punktów końcowych udostępnionych przez platformę po stronie sprzedawcy i wygrywającą platformę po stronie kupującego. Protected Audience porówna klucze interakcji z adresami URI określonymi w raportującym kodzie JavaScript, a następnie wyśle żądanie POST do każdego punktu końcowego w przypadku każdej raportowanej interakcji. Content-Type żądania to zwykły tekst, a jego treść to dane interakcji.

Możliwie najlepsza obsługa raportowania interakcji

Interfejs reportInteraction() ma na celu zapewnienie możliwie najlepszego raportowania za pomocą metody HTTP POST.

Codzienna aktualizacja w tle

Podczas tworzenia listy niestandardowych odbiorców aplikacja lub pakiet SDK może zainicjować metadane dotyczące listy niestandardowych odbiorców. Dodatkowo platforma może codziennie aktualizować te elementy niestandardowych metadanych dotyczących list odbiorców w ramach procesu aktualizacji w tle.

• Sygnały dotyczące ustalania stawek przez użytkownika
• Zaufane dane dotyczące określania stawek
• AdData lista

Ten proces wykonuje zapytania do adresu URL z codziennie aktualizowanym plikiem danych zdefiniowanego w listie niestandardowych odbiorców. Adres URL może zwracać odpowiedź w formacie JSON.

• Odpowiedź w formacie JSON może zawierać dowolne obsługiwane pola metadanych, które należy zaktualizować.
• Każde pole JSON jest sprawdzane niezależnie. Klient ignoruje źle sformatowane pola, co powoduje brak aktualizacji w odpowiednich polach w odpowiedzi.
• Pusty komunikat HTTP lub pusty obiekt JSON „{}” powoduje brak aktualizacji metadanych.
• Rozmiar wiadomości z odpowiedzią musi być ograniczony do 10 KB.
• W przypadku wszystkich identyfikatorów URI musi być używany protokół HTTPS.
• trusted_bidding_uri musi mieć ten sam identyfikator ETLD+1 co kupujący.

Przykład: odpowiedź JSON dla dziennego powiadomienia tła

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

Kod JavaScript do wyboru reklamy

Proces wyboru reklam steruje wykonywaniem kodu JavaScript dostarczonego przez kupującego i sprzedawcę.

Kod JavaScriptu przesłany przez kupującego jest pobierany z adresu URL logiki ustalania stawek określonego w sekcji „Lista niestandardowych odbiorców”. Zwrócony kod JavaScript powinien zawierać te funkcje:

• generateBid()
• reportWin()

Kod JavaScript dostarczony przez sprzedawcę jest pobierany z adresu URL logiki decyzji określonego w parametrze AdSelectionConfig interfejsu AdServices Ad Selection API. Zwrócony kod JavaScript powinien zawierać te funkcje:

• scoreAd()
• reportResult()

generateBid()

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_bidding_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

Parametry wejściowe:

• ad: obiekt JSON o formacie var ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals: obiekty JSON określone w obiekcie konfiguracji aukcji

• custom_audience_bidding_signals: obiekt JSON wygenerowany przez platformę. Format tego obiektu JSON:

  var custom_audience_signals = {
    "owner":"ca_owner",
    "buyer":"ca_buyer",
    "name":"ca_name",
    "activation_time":"ca_activation_time_epoch_ms",
    "expiration_time":"ca_expiration_time_epoch_ms",
    "user_bidding_signals":"ca_user_bidding_signals"
  }
  

  gdzie:

  • owner, buyer i name to ciągi znaków pochodzące z usług o tej samej nazwie, które należą do niestandardowej listy odbiorców biorącej udział w wybieraniu reklam.
  • activation_time i expiration_time to czas aktywacji i wygaśnięcia listy niestandardowych odbiorców wyrażony w sekundach od epoki uniksowej.
  • ca_user_bidding_signals to ciąg JSON określony w polu userBiddingSignals obiektu CustomAudience w momencie jego utworzenia.
  • trusted_bidding_signals, contextual_signals i user_signals to obiekty JSON. Są one przekazywane jako puste obiekty i będą wypełniane w przyszłych wersjach. Ich format nie jest narzucany przez platformę i jest zarządzany przez technologię reklamową.

Efekt:

• ad: to reklama, do której odnosi się stawka. Skrypt może zwrócić kopię otrzymanej reklamy z innymi metadanymi. Właściwość render_url w ad powinna pozostać niezmieniona.
• bid: wartość typu float, która określa wartość stawki dla tej reklamy.
• status: wartość całkowita, która może być:
  • 0: dla prawidłowego wykonania
  • 1: (lub dowolna wartość niezerowa) w przypadku, gdy którykolwiek z sygnałów wejściowych jest nieprawidłowy. Jeśli funkcja generate-bid zwróci wartość inną niż 0, proces ustalania stawek zostanie unieważniony w przypadku wszystkich reklam CA.

scoreAd()

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

Parametry wejściowe:

• ad: zapoznaj się z dokumentacją generateBid
• bid: wartość stawki reklamy

• ad_selection_config: obiekt JSON reprezentujący parametr AdSelectionConfig interfejsu API selectAds. Format:

  var ad_selection_config = {
    'seller': 'seller',
    'decision_logic_url': 'url_of_decision_logic',
    'custom_audience_buyers': ['buyer1', 'buyer2'],
    'auction_signals': auction_signals,
    'per_buyer_signals': per_buyer_signals,
    'contextual_ads': [ad1, ad2]
  }
  

• seller_signals: obiekty JSON odczytane z parametru interfejsu API sellerSignals AdSelectionConfig

• trusted_scoring_signal: odczyt z pola adSelectionSignals w parametrze interfejsu API AdSelectionConfig

• contextual_signals, user_signals: obiekty JSON. Są one przekazywane jako puste obiekty i będą wypełniane w kolejnych wersjach. Ich format nie jest narzucany przez platformę, a zarządza nim dostawca technologii reklamowych.

• per_buyer_signals: obiekt JSON odczytywany z mapy perBuyerSignal w parametrze interfejsu API AdSelectionConfig, który ma jako klucz bieżącego kupującego listy niestandardowe. Pusty, jeśli mapa nie zawiera żadnych wpisów dla danego kupującego.

Dane wyjściowe:

• score: wartość zmiennoprzecinkowa reprezentująca wartość wyniku tej reklamy
• status: wartość całkowita, która może być:
  • 0: oznacza prawidłowe wykonanie.
  • 1: jeśli customAudienceSignals są nieprawidłowe,
  • 2: jeśli parametr AdSelectionConfig jest nieprawidłowy.
  • 3: gdy którykolwiek z innych sygnałów jest nieprawidłowy.
  • Każda wartość niezerowa powoduje niepowodzenie procesu, a wartość określa typ zgłaszanego wyjątku.

selectOutcome()

function selectOutcome(
  outcomes,
  selection_signals) {
    return {'status': 0, 'result': null};
}

Parametry wejściowe:

• outcomes: obiekt JSON {"id": id_string, "bid": bid_double}
• selection_signals: obiekty JSON określone w konfiguracji aukcji.

Dane wyjściowe:

• status: 0 w przypadku powodzenia, wartość niezerową w przypadku niepowodzenia
• result: jeden z podanych wyników lub wartość null

reportResult()

function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
   return {
      'status': status,
      'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
   };
}

Parametry wejściowe:

• ad_selection_config: zobacz dokumentację scoreAds
• render_url: adres URL renderowania reklamy zwycięskiej
• bid: stawka za reklamę, która wygrała aukcję
• contextual_signals: zobacz dokumentację generateBid

Dane wyjściowe:

• status: 0 w przypadku powodzenia i wartość niezerową w przypadku niepowodzenia.
• results: obiekty JSON zawierające:
  • signals_for_buyer: obiekt JSON przekazywany funkcji reportWin
  • reporting_url: adres URL używany przez platformę do powiadamiania kupującego o wyświetleniu

reportWin()

function reportWin(
   ad_selection_signals,
   per_buyer_signals,
   signals_for_buyer,
   contextual_signals,
   custom_audience_signals) {
   return {'status': 0, 'results': {'reporting_url': reporting_url } };
}

Parametry wejściowe:

• ad_selection_signals, per_buyer_signals: zapoznaj się z dokumentacją scoreAd
• signals_for_buyer: obiekt JSON zwracany przez funkcję reportResult
• contextual_signals, custom_audience_signals: zapoznaj się z dokumentacją dotyczącą generateBid

Dane wyjściowe:

• status: 0 w przypadku powodzenia i wartość niezerową w przypadku niepowodzenia.
• results: obiekt JSON zawierający:
  • reporting_url: adres URL używany przez platformę do powiadamiania sprzedawcy o wyświetleniu

registerAdBeacon()

function registerAdBeacon(
  beacons
)

Parametry wejściowe:

• beacons: obiekt zawierający pary klucz-wartość kluczy interakcji i identyfikatorów URI raportowania. Format:

  let beacons = {
    'interaction_key': 'reporting_uri',
    'interaction_key': 'reporting_uri',
    ...
  }
  

  • interaction_key: ciąg tekstowy reprezentujący zdarzenie. Platforma używa tego parametru później, gdy zgłasza interakcje ze zdarzeniami, aby sprawdzić, do którego reporting_uri powinna wysłać powiadomienie. Ten klucz musi być zgodny z tym, co kupujący lub sprzedający rejestruje, i tym, co sprzedający zgłasza.
  • reporting_uri: identyfikator URI do otrzymywania raportów o zdarzeniach. Powinien on dotyczyć konkretnego typu zdarzenia. Musi ono akceptować żądania POST, aby obsługiwać wszelkie dane zgłaszane wraz ze zdarzeniem.

  Na przykład:

    let beacons = {
      'click': 'https://reporting.example.com/click_event',
      'view': 'https://reporting.example.com/view_event'
    }
  

Wstępnie utworzone identyfikatory URI selekcji reklam

Wstępnie utworzone adresy URI umożliwiają dostawcom technologii reklamowych wyznaczanie funkcji JavaScript na potrzeby logiki decyzji o wybieraniu reklam w klasach AdSelectionConfig i AdSelectionFromOutcomesConfig. Wstępnie utworzone identyfikatory URI nie wymagają wywołań sieci do pobrania odpowiedniego kodu JavaScript. Firmy zajmujące się technologiami reklamowymi mogą używać gotowych identyfikatorów URI bez konieczności konfigurowania zarejestrowanej domeny, która będzie hostować kod JavaScript.

Gotowy identyfikator URI jest tworzony w tym formacie:

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

Platforma Piaskownica prywatności udostępnia JavaScript za pomocą informacji z tego URI w czasie wykonywania.

Wyjątek IllegalArgumentException jest zgłaszany, jeśli:

• w identyfikatorze URI nie ma wymaganych parametrów;
• w identyfikatorze URI znajdują się nierozpoznane parametry

Obsługiwane wstępnie zdefiniowane przypadki użycia i nazwy identyfikatorów URI

Przypadek użycia 1: wybór reklamy

W ramach procesu selectAds(AdSelectionConfig) obsługiwane są wstępnie utworzone identyfikatory URI w ramach przypadku użycia ad-selection.

Wstępnie utworzona nazwa identyfikatora URI: highest-bid-wins

Ten gotowy adres URI udostępnia kod JavaScript, który po ustaleniu stawek wybiera reklamę z najwyższą stawką. Udostępnia też podstawową funkcję raportowania, która umożliwia raportowanie wartości render_uri i bid zwycięzcy.

Parametry wymagane

reportingUrl: podstawowy adres URL raportowania z parametrami render_uri i bid reklamy zwycięskiej:

<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>

Wykorzystanie

Jeśli podstawowy adres URL raportowania to https://www.ssp.com/reporting, gotowy identyfikator URI będzie wyglądał tak:

`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`

Przypadek użycia 2: ad-selection-from-outcomes

W przypadku użycia ad-selection-from-outcomes obsługiwane są wstępnie utworzone identyfikatory URI w ramach procesu selectAds(AdSelectionFromOutcomesConfig).

Wstępnie utworzona nazwa identyfikatora URI: waterfall-mediation-truncation

Wstępnie utworzony identyfikator URI waterfall-mediation-truncation udostępnia kod JavaScript, który implementuje logikę zapośredniczenia kaskadowego. Kod JavaScript zwraca reklamę wewnętrzną, jeśli wartość bid jest większa lub równa wartości bid floor, a w przeciwnym razie zwraca wartość null.

Parametry wymagane

bidFloor: klucz wartości minimalnej stawki przekazanej w parametry getSelectionSignals(), który jest porównywany z reklamą w zapośredniczeniu za pomocą pakietu SDK.

Wykorzystanie

Jeśli sygnały wyboru reklamy wyglądają tak: {"bid_floor": 10}, wynikowy gotowy identyfikator URI będzie wyglądał tak:

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

Testowanie

Aby ułatwić Ci rozpoczęcie korzystania z interfejsu Protected Audience API, opracowaliśmy przykładowe aplikacje w językach Kotlin i Java, które znajdziesz na GitHub.

Wymagania wstępne

Interfejs Protected Audience API wymaga użycia kodu JavaScript podczas selekcji reklam i raportowania wyświetleń. W środowisku testowym można podać ten kod JavaScriptu na 2 sposoby:

• Uruchom serwer z wymaganymi punktami końcowymi HTTPS, który zwraca kod JavaScript.
• Zastąp pobieranie z dalsza, podając niezbędny kod ze źródła lokalnego

Oba podejścia wymagają skonfigurowania punktu końcowego HTTPS do obsługi raportowania wyświetleń.

Punkty końcowe HTTPS

Aby przetestować wybór reklam i raportowanie wyświetleń, musisz skonfigurować 7 punktów końcowych HTTPS, do których może uzyskać dostęp urządzenie testowe lub emulator:

1. Punkt końcowy kupującego, który obsługuje skrypt JavaScript logiki określania stawek.
2. Punkt końcowy, który udostępnia sygnały określania stawek.
3. Punkt końcowy sprzedawcy, który obsługuje logikę decyzyjną w języku JavaScript.
4. Punkt końcowy, który udostępnia sygnały punktacji.
5. Punkt końcowy raportowania wyświetleń dla kupującego, który wygrał.
6. Punkt końcowy raportowania wyświetleń sprzedawcy.
7. Punkt końcowy do wyświetlania codziennych aktualizacji dla niestandardowej grupy odbiorców.

Dla wygody repozytorium GitHub zawiera podstawowy kod JavaScript do celów testowania. Zawiera on też definicje usług OpenAPI, które można wdrożyć na obsługiwanej platformie mock lub mikroserwisów. Więcej informacji znajdziesz w pliku README projektu.

Zastępowanie pobierania kodu JavaScript z dalu

Ta funkcja jest przeznaczona do kompleksowego testowania. Aby zastąpić pobieranie z usług zdalnych, aplikacja musi działać w trybie debugowania z włączonymi opcjami programisty.

Aby włączyć tryb debugowania w aplikacji, dodaj ten wiersz do atrybutu application w pliku AndroidManifest.xml:

<application
  android:debuggable="true">

Przykład użycia tych zastąpień znajdziesz w aplikacji Protected Audience API na GitHub.

Aby obsługiwać rutynowe czynności związane z wybieraniem reklam, takie jak ustalanie stawek, podejmowanie decyzji na podstawie wyników i raportowanie, musisz dodać własny niestandardowy kod JavaScript. Podstawowe przykłady kodu JavaScript, który obsługuje wszystkie wymagane żądania, znajdziesz w repozytorium GitHub. Przykładowa aplikacja Protected Audience API pokazuje, jak odczytać kod z tego pliku i przygotować go do użycia jako zastąpienia.

Zastąpienie pobierania kodu JavaScript po stronie sprzedawcy i kupującego jest możliwe niezależnie, ale do wyświetlania kodu JavaScript, dla którego nie udostępniasz zastąpienia, potrzebujesz punktu końcowego HTTPS. Aby dowiedzieć się, jak skonfigurować serwer, który obsługuje te przypadki, zapoznaj się z README.

Zastąpienie pobierania kodu JavaScript można zastosować tylko w przypadku list odbiorców niestandardowych, które są własnością Twojego pakietu.

Zastępowanie kodu JavaScript po stronie sprzedawcy

Aby skonfigurować zastąpienie kodu JavaScript po stronie sprzedawcy, wykonaj te czynności zgodnie z przykładem kodu:

1. Inicjuje obiekt AdSelectionManager.
2. Pobierz odwołanie do obiektu TestAdSelectionManager z obiektu AdSelectionManager.
3. Utwórz obiekt AdSelectionConfig.
4. Utwórz obiekt AddAdSelectionOverrideRequest z obiektem AdSelectionConfig i obiektem String reprezentującym kod JavaScript, którego chcesz użyć jako zastąpienia.
5. Wywołaj asynchroniczną metodę overrideAdSelectionConfigRemoteInfo() z obiektem AddAdSelectionOverrideRequest oraz odpowiednimi obiektami Executor i OutcomeReceiver.

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

Więcej informacji o tym, co oznaczają poszczególne pola w sekcji AdSelectionConfig, znajdziesz w sekcji Uruchomienie procesu wyboru reklamy. Główna różnica polega na tym, że w decisionLogicUrl możesz ustawić wartość zastępczą, ponieważ zostanie ona zignorowana.

Aby zastąpić kod JavaScript używany podczas wyboru reklam, element decisionLogicJs musi zawierać odpowiednie signatury funkcji po stronie sprzedawcy. Przykład odczytania pliku JavaScript jako ciągu znaków znajdziesz w przykładowej aplikacji Protected Audience API na GitHub.

Asymetryczna metoda overrideAdSelectionConfigRemoteInfo() używa obiektu OutcomeReceiver do sygnalizowania wyniku wywołania interfejsu API.

Funkcja onResult() zwraca wartość true, gdy zastąpienie zostało zastosowane. Przyszłe wywołania funkcji selectAds() będą używać decyzji i logiki raportowania, które zostały przekazane jako zastąpienie.

Wywołanie onError() oznacza 2 możliwe stany:

• Jeśli próba zastąpienia zostanie podjęta z nieprawidłowymi argumentami, AdServiceException wskaże jako przyczynę IllegalArgumentException.
• Jeśli próba zastąpienia zostanie podjęta w przypadku aplikacji, która nie działa w trybie debugowania z włączonymi opcjami dla deweloperów, AdServiceException wskazuje na przyczynę IllegalStateException.

Resetowanie zastąpień po stronie sprzedawcy

W tej sekcji zakładamy, że masz zastąpiony kod JavaScript po stronie sprzedawcy i masz odwołanie do funkcji TestAdSelectionManager i AdSelectionConfig użytych w poprzedniej sekcji.

Aby zresetować zastąpienia dla wszystkich AdSelectionConfigs:

1. Wywołaj asynchroniczną metodę resetAllAdSelectionConfigRemoteOverrides() z odpowiednim obiektem OutcomeReceiver.

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

Po zresetowaniu zastąpień po stronie sprzedawcy wywołania funkcji selectAds() używają dowolnej wartości decisionLogicUrl, która jest przechowywana w AdSelectionConfig, aby spróbować pobrać wymagany kod JavaScript.

Jeśli wywołanie funkcji resetAllAdSelectionConfigRemoteOverrides() zakończy się niepowodzeniem, wywołanie funkcji OutComeReceiver.onError() zwróci wartość AdServiceException. Jeśli próba usunięcia zastąpień zostanie podjęta w aplikacji, która nie działa w trybie debugowania z włączonymi opcjami dla deweloperów, AdServiceException wskazuje, że przyczyną jest IllegalStateException.

Zastępowanie kodu JavaScript po stronie kupującego

1. Aby dołączyć do listy niestandardowych odbiorców, wykonaj te czynności.
2. Utwórz AddCustomAudienceOverrideRequest z kupującym i nazwą listy niestandardowej, którą chcesz zastąpić, a także z logiką ustalania stawek i danymi, których chcesz użyć jako zastąpienia.
3. Wywołaj asynchroniczną metodę overrideCustomAudienceRemoteInfo() z obiektem AddCustomAudienceOverrideRequest oraz odpowiednimi obiektami Executor i OutcomeReceiver.

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

Wartości pól buyer i name są takie same jak te użyte do utworzenia niestandardowej listy odbiorców. Więcej informacji o tych polach

Możesz też podać 2 dodatkowe parametry:

• biddingLogicJs: kod JavaScript zawierający logikę kupującego, która jest używana podczas wyboru reklamy. W tym kodzie JavaScript znajdziesz wymagane funkcje.
• trustedBiddingSignals: sygnały ustalania stawek, które mają być używane podczas wyboru reklamy. Na potrzeby testowania może to być pusty ciąg znaków.

Asymetryczna metoda overrideCustomAudienceRemoteInfo() używa obiektu OutcomeReceiver do sygnalizowania wyniku wywołania interfejsu API.

Funkcja onResult() zwraca wartość true, gdy zastąpienie zostało zastosowane. Kolejne wywołania funkcji selectAds() używają logiki określania stawek i raportowania, którą podano jako zastąpienie.

Wywołanie onError() oznacza 2 możliwe warunki.

• Jeśli próba zastąpienia zostanie podjęta z nieprawidłowymi argumentami, AdServiceException wskaże jako przyczynę IllegalArgumentException.
• Jeśli próba zastąpienia zostanie podjęta w przypadku aplikacji, która nie działa w trybie debugowania z włączonymi opcjami dla deweloperów, AdServiceException wskazuje na przyczynę IllegalStateException.

Resetowanie zastąpień po stronie kupującego

W tej sekcji zakładamy, że masz zastąpiony kod JavaScript po stronie kupującego i masz odwołanie do TestCustomAudienceManager użyte w poprzedniej sekcji.

Aby zresetować zastąpienia dla wszystkich list niestandardowych odbiorców:

1. Wywołaj asynchroniczną metodę resetAllCustomAudienceOverrides() z odpowiednimi obiektami Executor i OutcomeReceiver.

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

Po zresetowaniu zastąpień po stronie kupującego kolejne wywołania funkcji selectAds() będą używać wartości biddingLogicUrl i trustedBiddingData zapisanych w CustomAudience, aby spróbować pobrać wymagany kod JavaScript.

Jeśli wywołanie funkcji resetCustomAudienceRemoteInfoOverride() zakończy się niepowodzeniem, wywołanie funkcji OutComeReceiver.onError() zwróci wartość AdServiceException. Jeśli próba usunięcia zastąpień zostanie podjęta w przypadku aplikacji, która nie działa w trybie debugowania z włączonymi opcjami dewelopera, AdServiceException wskazuje, że przyczyną jest IllegalStateException.

Konfigurowanie serwera raportów

Jeśli używasz zastąpień pobierania z dalsza, musisz też skonfigurować serwer, do którego urządzenie lub emulator może się łączyć, aby odpowiadać na zdarzenia raportowania. Do testowania wystarczy punkt końcowy zwracający kod 200. Repozytorium GitHub zawiera definicje usług OpenAPI, które można wdrożyć na obsługiwanej platformie mock lub mikrousług. Więcej informacji znajdziesz w pliku README projektu.

Szukaj definicji OpenAPI w pliku reporting-server.json. Ten plik zawiera punkt końcowy, który zwraca kod 200, czyli kod odpowiedzi HTTP. Ten punkt końcowy jest używany podczas selectAds() i informuje Protected Audience API o pomyślnym zakończeniu raportowania wyświetleń.

Funkcje do przetestowania

• Ćwiczenie dołączania do listy lub opuszczania jej i konfigurowania listy niestandardowych odbiorców na podstawie wcześniejszych działań użytkownika.
• inicjowanie wyboru reklamy na urządzeniu za pomocą kodu JavaScript hostowanego zdalnie;
• Obserwuj, jak powiązanie aplikacji z ustawieniami niestandardowych list odbiorców może wpływać na wyniki selekcji reklam.
• Raportowanie wyświetleń ćwiczeń po wybraniu reklamy.

Ograniczenia

W tabeli poniżej znajdziesz ograniczenia dotyczące przetwarzania Protected Audience API. Podane limity mogą ulec zmianie na podstawie opinii. Aby dowiedzieć się więcej o funkcjach w trakcie opracowywania, przeczytaj informacje o wersji.

Zgłaszanie błędów i problemów

Twoja opinia jest bardzo ważna dla Piaskownicy prywatności na Androida. Poinformuj nas o problemach, które zauważysz, lub o swoich pomysłach na udoskonalenie Piaskownicy prywatności na Androida.