Przewodnik dla programistów interfejsu Protected Audience API

Wersja przedpremierowa dla programistów Wersja beta

Podczas czytania informacji z Piaskownicy prywatności na urządzeniu z Androidem dokumentacji, kliknij przycisk Podgląd dla programistów lub Beta, aby wybrać używanej wersji programu, ponieważ instrukcje mogą się różnić.

---

Prześlij opinię

Interfejs Protected Audience API na Androida (dawniej FLEDGE) obejmuje Custom Audience API i Ad Selection API. Platformy technologii reklamowych i reklamodawcy mogą za pomocą tych interfejsów API wyświetlać reklamy dopasowane na podstawie wcześniejszego zaangażowania w aplikację, ogranicza udostępnianie identyfikatorów między aplikacjami i ogranicza udostępnianie aplikacji użytkownika informacji o interakcjach z innymi firmami.

Interfejs Custom Audience API koncentruje się na „niestandardowych odbiorcach”. abstrakcję, która reprezentuje grupę użytkowników o wspólnych zamiarach. An reklamodawca może zarejestrować użytkownika w niestandardowych odbiorcach i powiązać z nim odpowiednie reklamy z nim. Te informacje są przechowywane lokalnie i mogą zostać wykorzystane do przekazania informacji reklamodawcy stawki, filtrowanie i renderowanie reklam.

Interfejs Ad Selection API zapewnia środowisko umożliwiające wielu deweloperom lokalnie przeprowadzasz aukcję dla niestandardowych odbiorców. W tym celu system Uwzględnia trafne reklamy powiązane z niestandardowymi odbiorcami i skuteczność dodatkowe przetwarzanie reklam, które platforma technologii reklamowych zwraca na urządzenie.

Platformy technologii reklamowych mogą zintegrować te interfejsy API, by wdrożyć remarketing, chronią prywatność użytkownika. Obsługa dodatkowych przypadków użycia, takich jak instalacja aplikacji reklam, są planowane w kolejnych wersjach. Więcej informacji o Protected Audience API API na Androida w propozycji projektu.

Z tego przewodnika dowiesz się, jak korzystać z interfejsu Protected Audience API na Androidzie, aby wykonaj te czynności:

1. Zarządzanie odbiorcami niestandardowymi
2. Konfigurowanie i wyświetlanie wyboru reklam na urządzeniu
3. Raportowanie wyświetleń reklam

Zanim zaczniesz

Zanim zaczniesz, wykonaj te czynności:

1. Skonfiguruj środowisko programistyczne na potrzeby Piaskownicy prywatności na Androida.
2. Zainstaluj obraz systemu na obsługiwanym urządzeniu lub skonfiguruj emulatorowi, który zapewnia obsługę Piaskownicy prywatności na urządzeniach z Androidem.

3. W terminalu włącz dostęp do interfejsu Protected Audience API (wyłączony). domyślnie) za pomocą tego polecenia adb.

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. Dodaj w aplikacji uprawnienie ACCESS_ADSERVICES_CUSTOM_AUDIENCE plik manifestu:

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

5. Odwołaj się do konfiguracji usług reklamowych w elemencie <application> tego elementu Twój plik manifestu:

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

6. 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 dotyczących usług reklamowych i kontrolę dostępu do pakietów SDK.

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

7. Domyślnie interfejs Ad Selection API wymusza limity z maksymalnej ilości pamięci wykorzystywanej w raportach aukcji lub wyświetleń który skrypt może przydzielić. Funkcja ograniczania pamięci wymaga wersji WebView 105.0.5195.58 lub nowsza. Platforma wymusza sprawdzanie wersji i wywołuje funkcję interfejsy API selectAds i reportImpression zawiodą, jeśli zostanie nie jest zadowolony/zadowolona. Możesz to skonfigurować na 2 sposoby:

   • Opcja 1. Uruchom to polecenie adb, aby dezaktywować sprawdzanie:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

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

Dołącz do grupy niestandardowych odbiorców

Niestandardowa lista odbiorców reprezentuje grupę użytkowników o wspólnych zamiarach lub zainteresowań określonych przez aplikację reklamodawcy. Aplikacja lub pakiet SDK może używać niestandardowego atrybutu odbiorców, aby wskazać konkretną grupę odbiorców, np. osobę, która opuściła elementy w koszyku na zakupy. Aby asynchronicznie utworzyć niestandardową listę odbiorców lub dołączyć do niej, wykonaj :

1. Zainicjuj obiekt CustomAudienceManager.
2. Utwórz obiekt CustomAudience, określając kluczowe parametry, takie jak pakiet kupującego i odpowiednia nazwa. Następnie zainicjuj JoinCustomAudienceRequest obiekt z CustomAudience obiektu.
3. Wywołaj asynchroniczne polecenie joinCustomAudience() z JoinCustomAudienceRequest i odpowiednie Executor oraz Obiekty OutcomeReceiver.

Kotlin

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)

Java

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 poniższych parametrów jednoznacznie identyfikuje każdy Obiekt CustomAudience na urządzeniu:

• owner: nazwa pakietu aplikacji właściciela. Domyślnie jest ona ustawiona na nazwa pakietu aplikacji wywołującej.
• buyer: identyfikator sieci reklamowej kupującego, która zarządza reklamami dla tego niestandardowego zamówienia z całego świata.
• name: dowolna nazwa lub identyfikator niestandardowej listy odbiorców.

Wielokrotne wywoływanie aplikacji joinCustomAudience() z innym wystąpieniem CustomAudience aktualizuje wszystkie istniejące CustomAudience przy użyciu pasujące do parametrów owner, buyer i name. Aby chronić prywatność, wynik interfejsu API nie rozróżnia „tworzenia” i „zaktualizuj”.

Dodatkowo CustomAudience musi być utworzony z tymi wymaganymi. parametry:

• URL codziennej aktualizacji: adres URL HTTPS wysyłany codziennie w tle w celu aktualizować sygnały określania stawek przez użytkownika, dane dotyczące zaufanego określania stawek na liście odbiorców niestandardowych renderowania adresów URL i metadanych reklam.
• Adres URL logiki określania stawek: adres URL HTTPS wysłany do użytkownika podczas wyboru reklamy w celu pobrania parametru zasady ustalania stawek za pomocą JavaScriptu przez kupującego. Sprawdź wymagane podpisy funkcji. w tym skrypcie JavaScript.
• Identyfikatory renderowania reklam: dowolny identyfikator ustawiony przez kupującego ds. technologii reklamowych. To jest optymalizacji generowania ładunku dla firmy B&A.

Opcjonalne parametry obiektu CustomAudience mogą obejmować:

• Czas aktywacji: niestandardowe grupy odbiorców mogą uczestniczyć tylko w wyborze reklamy oraz codzienne aktualizacje po aktywacji. Pozwala to na zaangażowanie np. nieaktywnych użytkowników aplikacji.
• Czas ważności: przyszły czas, po którym niestandardowa lista odbiorców zostanie zostały usunięte z urządzenia.
• Sygnały dotyczące określania stawek przez użytkownika: ciąg znaków JSON zawierający sygnały użytkownika, takie jak preferowany język użytkownika, stosowany przez JavaScript logikę ustalania stawek kupującego do generowania stawek w procesie wyboru reklamy. Ten format pomaga technologii reklamowej platformy wykorzystują kod na różnych platformach i ułatwiają jego wykorzystanie w języku JavaScript. funkcji.
• Zaufane dane określania stawek: adres URL HTTPS i lista ciągów znaków użytych podczas proces wyboru reklamy, który pobiera sygnały ustalania stawek z zaufanej pary klucz-wartość posprzedażna.
• Reklamy: lista obiektów AdData odpowiadających reklamom, dla których mają uczestniczyć w wyborze reklamy. Każdy obiekt AdData składa się z tych elementów:
  • URL renderowania: adres URL HTTPS, którego dotyczy zapytanie wyrenderowane w celu wyrenderowania ostatecznej reklamy.
  • Metadane: obiekt JSON zserializowany jako ciąg znaków zawierający informacje do nie są uwzględniane przez logikę ustalania stawek przez kupującego w procesie wyboru reklamy.
  • Filtry reklam: klasa zawierająca wszystkie informacje wymagane do działania aplikacji. zainstalować filtrowanie reklam i ograniczenie liczby wyświetleń podczas ich wyboru.

Uwaga: wartości w polach „Sygnały dotyczące określania stawek przez użytkownika”, „Dane dotyczące zaufanych stawek” i „Reklamy”. łączny rozmiar atrybutów nie powinien przekraczać 10 KB. Te 3 pola muszą być wypełnione do niestandardowych list odbiorców, którzy będą brali udział w procesie wyboru reklamy.

Oto przykład tworzenia instancji obiektu CustomAudience:

Kotlin

// 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()

Java

// 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 JoinCustomAudience()

Asynchroniczna metoda joinCustomAudience() korzysta z metody OutcomeReceiver , aby sygnalizować wynik wywołania interfejsu API.

• Wywołanie zwrotne onResult() oznacza, że lista odbiorców niestandardowych została prawidłowo utworzona. utworzonych lub zaktualizowanych.
• Wywołanie zwrotne onError() wskazuje 2 możliwe warunki.
  • Jeśli JoinCustomAudienceRequest zainicjowano nieprawidłowym kodem argumentów AdServicesException oznacza IllegalArgumentException.
  • Wszystkie inne błędy otrzymują komunikat AdServicesException z atrybutem IllegalStateException.

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

Kotlin

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

Java

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

Opuść grupę odbiorców niestandardowych

Jeśli użytkownik nie spełnia już kryteriów biznesowych dla danego aplikacji lub pakietu SDK, aplikacja lub pakiet SDK może wywołać metodę leaveCustomAudience(), by usunąć niestandardową odbiorców z danego urządzenia. Aby usunąć kolumnę CustomAudience na podstawie jej niepowtarzalnych danych wykonaj te czynności:

1. Zainicjuj obiekt CustomAudienceManager.
2. Zainicjuj pole LeaveCustomAudienceRequest niestandardową listą odbiorców buyer i name. Więcej informacji o tych polach do wprowadzania danych znajdziesz w artykule „Dołącz do grupy niestandardowych odbiorców”.
3. Wywołaj asynchroniczną metodę leaveCustomAudience() za pomocą funkcji LeaveCustomAudienceRequest i odpowiednie Executor oraz Obiekty OutcomeReceiver.

Kotlin

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)

Java

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ływania usługi joinCustomAudience(), sygnały OutcomeReceiver na koniec wywołania interfejsu API. Ze względu na ochronę prywatności wynik błędu odróżniać błędy wewnętrzne od nieprawidłowych argumentów. onResult() wywołanie zwrotne jest wywoływane po zakończeniu wywołania interfejsu API niezależnie od tego, czy usunięto niestandardową listę odbiorców.

Uruchom wybór reklamy

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

1. Zainicjuj obiekt AdSelectionManager.
2. Utwórz obiekt AdSelectionConfig.
3. Wywołaj asynchroniczną metodę selectAds() za pomocą funkcji AdSelectionConfig i odpowiednie Executor oraz Obiekty OutcomeReceiver.

Kotlin

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
)

Java

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 danych wejściowych AdSelectionConfig, gdzie musisz określić następujące wymagane parametry:

• Sprzedawca: identyfikator sieci reklamowej sprzedawcy, która inicjuje wybór reklamy.
• Adres URL mechanizmu decyzyjnego: adres URL HTTPS wysłany w celu uzyskania adresu sieci reklamowej sprzedawcy to logika JavaScriptu.
  • Adres URL HTTPS: wysłano zapytanie o logikę JavaScript sieci reklamowej sprzedawcy. Sprawdź wymagane podpisy funkcji.
  • Gotowe identyfikatory URI: są zgodne z formatem wyboru reklamy FLEDGE. Jeśli nieprawidłowy lub nieprawidłowy format to IllegalArgumentException jest przekazywany gotowy identyfikator URI.
• Kupujący niestandardowych odbiorców: pełna lista identyfikatorów sieci reklamowych kupujących. które sprzedawca może uczestniczyć w procesie wyboru reklam. Te identyfikatory kupujących odpowiadają CustomAudience.getBuyer() z niestandardowych odbiorców.

Opcjonalnie możesz określić te parametry, aby lepiej dostosować reklamę wybór:

• Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający które mają być wykorzystywane przez logikę określania stawek przez kupującego pobieraną z aplikacji JavaScript CustomAudience.getBiddingLogicUrl()
• Sygnały sprzedawcy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały są uwzględniane przez logikę podejmowania decyzji w zakresie JavaScriptu pobieranych przez sprzedawcę z AdSelectionConfig.getDecisionLogicUrl()
• Sygnały według kupującego: mapa obiektów JSON zserializowanych jako ciągi znaków, które zawierają sygnały, które mogą być wykorzystane przez konkretnych kupujących logika określania stawek w JavaScripcie pobrane z tabeli CustomAudience.getBiddingLogicUrl(), które są identyfikowane przez pola kupujących uczestniczących w programie niestandardowych odbiorców.
• Reklamy kontekstowe: zbiór propozycji reklam, które są zbierane bezpośrednio. od kupujących podczas aukcji, która odbywa się poza chronioną listą odbiorców aukcji.

Po wybraniu reklamy wyniki, stawki i sygnały są zachowywane wewnętrznie do raportowania. Wywołanie zwrotne OutcomeReceiver.onResult() zwraca błąd AdSelectionOutcome, który zawiera:

• Wyrenderowany URL zwycięskiej reklamy pobrany z AdData.getRenderUrl().
• Identyfikator wyboru reklamy unikalny dla użytkownika urządzenia. Ten identyfikator jest używany do raportowania wyświetlenie reklamy.

Jeśli nie można dokonać wyboru reklamy z takich powodów: nieprawidłowych argumentów, przekroczenia limitu czasu lub nadmiernego zużycia zasobów, Wywołanie zwrotne OutcomeReceiver.onError() udostępnia parametr AdServicesException z takimi zachowaniami:

• Jeśli wybór reklamy został zainicjowany za pomocą nieprawidłowych argumentów, parametr AdServicesException wskazuje IllegalArgumentException jako przyczyna.
• Wszystkie inne błędy otrzymują komunikat AdServicesException z atrybutem IllegalStateException.

Reklamy kontekstowe

Funkcja Protected Audience API może uwzględniać reklamy kontekstowe w aukcji chronionej. Reklamy kontekstowe muszą być wybrane na serwerze technologii reklam i zwrócone do poza interfejsami Protected Audience API. Można wówczas użyć reklam kontekstowych, w aukcji przy użyciu AdSelectionConfig. W tym momencie funkcja tak samo jak w przypadku reklam na urządzenia, łącznie z możliwością filtrowania wykluczających reklam. Gdy funkcja Aukcja z Protected Audience API została zakończona, musisz wywołać reportImpression() Wywołuje to funkcję reportWin() w zwycięskiej reklamie kontekstowej w: jak w przypadku raportowania wyświetleń, aby otrzymać zwycięską reklamę urządzenia. Każda reklama kontekstowa wymaga kupującego, stawki, linku do funkcji raportowania, wyrenderowany URL i metadane reklamy.

Aby można było wdrożyć w aplikacji reklamy kontekstowe, aplikacja docelowa musi utworzyć ContextualAds obiekt:

Kotlin

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

Java

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

Powstały obiekt ContextualAds można następnie przekazać podczas tworzenia AdSelectionConfig:

Kotlin

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

Java

// 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 instalację aplikacji

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

Pierwszym krokiem w tym procesie jest określenie, którzy reklamodawcy mogą aby filtrować według zainstalowanego pakietu. Musisz to zrobić w aplikacji, której chcesz użyć kierować daną reklamę.

Kotlin

//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)
    }
  })

Java

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

Gdy poprzedni kod zostanie wykonany, przekazani reklamodawcy będą mogli odfiltrowywać zainstalowane aplikacje, które określisz podczas generowania stawek. Jeśli Musisz usunąć reklamodawcę z dostępu do strony, na której można zainstalować tę aplikację stanu, należy uruchomić kod ponownie z usuniętymi informacjami o reklamodawcy.

Następnym krokiem jest skonfigurowanie filtrowania reklam w aplikacji wydawcy. Impreza, wyświetla reklamę w aplikacji wydawcy (najprawdopodobniej jest to pakiet SDK po stronie dostawców). musi zainicjować swój obiekt AdFilters informacjami o tym, które reklamy związane z aplikacjami, które chcą odfiltrować:

Kotlin

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

Java

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

Wydawcy korzystający z usługi DSP mogą też ustawić AdFilter w przypadku reklam znajdujących się w dla niestandardowych odbiorców.

AdFilters można również przekazać podczas tworzenia nowej instancji AdData obiekt:

Kotlin

// 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()

Java

// 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 limitu wyświetleń na użytkownika

Filtrowanie limitu wyświetleń na użytkownika umożliwia technikom reklamowym ograniczenie liczby wyświetleń reklamy wyświetlane. Filtrowanie limitu wyświetleń na użytkownika zmniejsza ryzyko nadmiernej ekspozycji reklamy i optymalizuje wyboru reklamy w danej kampanii reklamowej.

Filtr limitu wyświetleń na użytkownika składa się z 2 głównych elementów: typu zdarzenia reklamowego klucz licznika reklam. Dostępne typy zdarzeń reklamowych:

• Win (już wkrótce): zdarzenie wygranej oznacza, że reklama wygrała aukcję. Zdarzenia wygrane są automatycznie aktualizowane przez interfejs Protected Audience API i nie mogą bezpośrednio przez programistę. Dane o wygranej są widoczne tylko dla reklam w dla danej niestandardowej grupy odbiorców.
• Wyświetlenie: oddzielnie od reportImpression, rozmówcy na urządzeniu (SSP lub MMP) używa updateAdCounterHistogram() do wywoływania zdarzeń wyświetlenia w i wskazywać w wybranym przez siebie kodzie. Zdarzenia wyświetlenia są widoczne dla wszystkich reklam należących do do danej platformy DSP, bez ograniczania się do reklam z tej samej niestandardowej grupy odbiorców.
• Widok: zdarzenie jest wywoływane przez element wywołujący na urządzeniu (SSP lub MMP) w punkcie wybranego przez siebie kodu za pomocą wywołania updateAdCounterHistogram(). Wyświetl zdarzenia są widoczne dla wszystkich reklam należących do danej platformy DSP, a nie tylko do reklam na tej samej platformie Niestandardowi odbiorcy.
• Kliknięcie: zdarzenie jest wywoływane przez element wywołujący na urządzeniu (SSP lub MMP) w punkcie wybranego przez siebie kodu za pomocą wywołania updateAdCounterHistogram(). Zdarzenia kliknięcia są widoczne dla wszystkich reklam należących do danej platformy DSP, a nie tylko dla reklam na platformie tych samych niestandardowych odbiorców.

W aplikacji wydawcy reklama wywoływana jest przez platformę SSP lub MMP widoczną na urządzeniu. zdarzeń. Po wywołaniu funkcji updateAdCounterHistogram() licznik częstotliwości jest zwiększany, tak aby przyszłe aukcje były informacji na temat ekspozycji użytkownika na daną reklamę. Typy zdarzeń reklamowych nie są są powiązane z odpowiednimi działaniami użytkownika i stanowią wskazówki, aby utworzyć strukturę systemu zdarzeń. Aby zwiększyć liczniki reklam w momencie zdarzenie, użytkownik na urządzeniu podaje identyfikator wyboru reklamy zwycięskiej aukcji reklam.

Klucze licznika reklam to dowolne 32-bitowe liczby całkowite ze znakiem i przypisane przez reklamę kupującego i odpowiadają one określonemu zbiorowi reklam zdefiniowanemu przez platformę DSP. Od reklamy są ograniczone tylko do reklam należących do danej platformy DSP, mogą one wybrać bez nakładania się histogramów z innej technologii reklamowej. Licznik reklam klucze są używane do zwiększania liczby identyfikatorów specyficznych dla platformy DSP w reklamach tej platformy lub w jej obrębie dla danej niestandardowej grupy odbiorców, aby odfiltrować reklamy z przyszłych aukcji.

Klucze licznika można wykorzystać do nadania priorytetu reklamom, które z większym prawdopodobieństwem interesująca użytkownika na podstawie jego interakcji z innymi reklamami w danej technologii reklamowej nabywcy. Na przykład reklama, która otrzymała dużą liczbę wyświetleń zaangażowanie pochodzące ze zwycięskich aukcji reklam, obejrzeń i kliknięć, reprezentuje punkt danych. Aby dodatkowo zilustrować ten punkt: reklama kijów golfowych dla leworęcznych może wskazywać, że użytkownik nie jest zainteresowany reklamami dla praworęcznych. O filtr limitu wyświetleń na użytkownika ustawiony dla klawisza licznika przypisanego do reklam leworęcznych może odfiltrowywać reklamy klubów praworęcznych.

Aby używać w aukcji ograniczenia liczby wyświetleń, musisz najpierw utworzyć KeyedFrequencyCap obiektów jak pokazano poniżej:

Kotlin

// 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()

Java

// 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 przekazać je do AdFilters obiekt.

Kotlin

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

Java

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

Gdy obiekt AdFilters jest zapełniany filtrami limitu wyświetleń na użytkownika, może są przekazywane podczas tworzenia listy odbiorców niestandardowych:

Kotlin

// 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()

Java

// 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 zastosujesz filtry limitu wyświetleń na użytkownika w niestandardowej liście odbiorców, platforma SSP może i wywoływanie niezbędnych zdarzeń kliknięcia, obejrzenia lub wyświetlenia.

Kotlin

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

Java

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 ustalony wcześniej limit filtra wyświetleń na użytkownika, są odfiltrowywane aukcji. Filtrowanie następuje przed wykonaniem logiki określania stawek w przypadku aukcji na urządzeniu oraz gdy ładunek jest generowany na potrzeby określania stawek Aukcja pomaga w aukcji usług. Ten zestaw narzędzi zapewnia specjalistom ds. reklamy swobodę korzystania interakcji między użytkownikami a reklamami w ramach niestandardowych list odbiorców w celu skierowania reklamy przy jednoczesnym minimalizowaniu nadmiernej ekspozycji na reklamę.

Filtrowanie reklam kontekstowych bez wywołań sieciowych

Jeśli nie ma popytu na remarketing na danym urządzeniu, możesz wyświetlać reklamy reklam kontekstowych bez wywołań sieciowych. Z gotowymi adresami URI i listą kontekstowych ze stawkami, platforma może pominąć logikę ustalania stawek, sygnały wykorzystywane w ustalaniu stawek i sygnały oceny. Platforma używa gotowego identyfikatora URI do wybierania reklamę kontekstową o najwyższej stawce.

Aby skrócić czas oczekiwania, specjaliści ds. technologii reklamowych mogą uruchomić proces wyboru reklamy obejmujący tylko reklam kontekstowych z funkcją filtrowania reklam bez wywołań sieciowych. To jest Można to osiągnąć za pomocą gotowych identyfikatorów URI do oceny sygnałów. Zajrzyj do sekcji Obsługiwane gotową sekcję przypadków użycia i nazw identyfikatorów URI dla listy scoreAds implementacji.

Aby wyświetlać wybrane reklamy bez wywołań sieciowych:

1. Konfigurowanie filtrowania reklam
2. Tworzenie reklam kontekstowych

3. Utwórz obiekt AdSelectionConfig z tymi elementami:

   1. Pusta lista kupujących.
   2. Gotowy identyfikator URI do wyboru najwyższej stawki
   3. Reklamy kontekstowe
   4. Pusty identyfikator URI sygnałów punktowych. Pusty identyfikator URI może wskazywać, , że nie chcesz korzystać z pobierania zaufanych sygnałów na potrzeby punktacji:

   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 reklamy:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Uruchamiaj własny kod JavaScript do raportowania i używaj gotowych identyfikatorów URI

Obecnie platforma Piaskownicy prywatności ma tylko podstawowy kod JavaScript do raportowania jest dostępna dla gotowych identyfikatorów URI. Jeśli chcesz prowadzić raportowanie JavaScriptu przy jednoczesnym korzystaniu z gotowych identyfikatorów URI na potrzeby reklam o krótkim czasie oczekiwania możesz zastąpić ustawienie DecisionLogicUri między wyborem reklamy raportów.

1. Wykonaj odpowiednie czynności, aby wybrać reklamy na potrzeby reklam kontekstowych za pomocą gotowych identyfikatorów URI.

2. Zanim zaczniesz generować raporty, utwórz kopię raportu 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);
   

Uruchom zapośredniczenie kaskadowe

Zapośredniczenie kaskadowe wymaga korzystania z wielu zewnętrznych pakietów SDK (sieci zewnętrznych) jest prowadzona przez własną sieć zapośredniczenia SDK. Zapośredniczenie kaskadowe to Tak samo niezależnie od tego, czy aukcja miała miejsce na urządzeniu czy Określanie stawek Usługi aukcyjne.

Sieci innych firm

Sieci zewnętrzne muszą zapewnić adapter, który pozwoli sieci zapośredniczeń wywołują metody niezbędne do przeprowadzenia aukcji:

• Uruchom wybór reklamy
• Raportowanie wyświetleń

Oto przykład adaptera sieci zapośredniczeń:

Kotlin

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

Java

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Każdy pakiet SDK ma własnych menedżerów i klientów oraz menedżerów usługi wyboru reklamy. Implementacja za pomocą funkcji selectAds i reportImpressions. Dostawcy pakietów SDK mogą zapoznać się z tymi informacjami: sekcji poświęconej wybieraniu reklam w aukcjach na urządzeniu lub B&A wyjaśnienia dotyczących aukcji B&A. Postępuj zgodnie z instrukcjami zgłaszania reklamy wyświetlenia (po raporcie wyświetleń na jednej platformie SSP dotyczącym i raportowania danych.

Sieć zapośredniczeń

Podobnie jak sieci zewnętrzne, sieci zapośredniczenia muszą mieć te parametry: selectAds oraz reportImpression. Zapoznaj się z sekcjami o wyświetlaniu reklam wyboru reklam i raportowanie wyświetleń reklam.

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

Pobieranie łańcucha zapośredniczenia i minimalnych stawek

Sieć zapośredniczenia jest odpowiedzialna za pobieranie danych własnych. reklam kontekstowych, łańcucha zapośredniczenia i sieci zewnętrznych minimalne stawki (3P). Ten może wystąpić w żądaniu pobrania reklam kontekstowych realizowanych w ramach zapośredniczenia Łańcuch zapośredniczenia określa sposób iteracji w sieciach zewnętrznych, , a stawki minimalne mogą być przekazywane do procesu aukcji jako adSelectionSignals.

Miejsca docelowe w sieci w łańcuchu zapośredniczenia

Pakiet SDK zapośredniczenia może umieścić się w łańcuchu zapośredniczenia na podstawie aktualnego eCPM własnych stawek. W interfejsie Protected Audience API stawki reklamowe są nieprzezroczyste. Mediacja Aby porównać dane własne, pakiet SDK powinien używać parametru AdSelectionFromOutcomesConfig stawki reklamy do stawki minimalnej w kolejnej sieci zewnętrznej w łańcuchu. Jeśli stawka własna wynosi wyższy od minimalnej stawki, oznacza to, że pakiet SDK zapośredniczenia jest umieszczony przed sieci zewnętrznej.

Uruchom wybór reklamy

Aby pobrać kandydaturę do reklamy własnej, sieć zapośredniczenia może uruchomić żądanie na urządzeniu aukcji, postępuj zgodnie z instrukcjami z sekcji Uruchom wybór reklamy. Generuje Własna kandydująca reklama, stawka i AdSelectionId używane w zapośredniczeniu proces tworzenia konta.

Tworzenie obiektu AdSelectionFromResultsConfig

Pole AdSelectionFromOutcomesConfig umożliwia sieci zapośredniczenia przekazywanie listy z AdSelectionIds (wyniki poprzednich aukcji), sygnały wyboru reklamy oraz identyfikator URI umożliwiający pobranie kodu JavaScriptu, który wybiera reklamę spośród kilku kandydatów. Lista identyfikatorów AdSelectionId wraz ze stawkami, a sygnały są przekazywane do JavaScript, który może zwrócić jeden z tych elementów (AdSelectionIds), jeśli przebije stawkę ceny minimalnej lub brak, jeśli łańcuch zapośredniczenia ma być kontynuowany.

Sieci zapośredniczenia tworzą AdSelectionFromOutcomesConfig na podstawie danych własnych AdSelectionId z poprzedniej sekcji oraz minimalną stawkę dla sieci zewnętrznej są brane pod uwagę. Należy utworzyć nowy element AdSelectionFromOutcomesConfig dla każdego etapu łańcucha zapośredniczenia.

Kotlin

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

Java

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 przypadku zapośredniczenia kaskadowego wymaga parametru Pole wejściowe AdSelectionFromOutcomesConfig, gdzie należy określić wymagane parametry:

• Sprzedawca: identyfikator sieci reklamowej sprzedawcy, która inicjuje wybór reklamy.
• AdSelectionIds: pojedyncza lista poprzednich uruchomień selectAds() dla danych własnych. reklama.
• Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający które mają być używane przez logikę ustalania stawek przez kupującego. W takim przypadku uwzględnij minimalną stawkę. pobranych dla danej sieci zewnętrznej.
• Identyfikator URI logiki wyboru: adres URL HTTPS wysłany do użytkownika podczas wyboru reklamy w celu pobrania JavaScript sieci zapośredniczenia do wyboru zwycięskiej reklamy. Zobacz wymagane podpisy funkcji w tym skrypcie JavaScript. JavaScript powinien zwrócić parametr Reklama innej firmy, jeśli stawka jest wyższa niż minimalna stawka lub z innego powodu zwraca null. Dzięki temu pakiet SDK zapośredniczenia może skrócić łańcuch zapośredniczenia, gdy zwycięzca .

Po utworzeniu obiektu AdSelectionOutcomesConfig wywołaj metodę selectAds() sieć innej firmy, która jest pierwsza w łańcuchu.

Kotlin

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)

Java

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

Administrowanie zapośredniczeniem kaskadowym

Oto kolejność działań przez mediację proces tworzenia konta.

1. Wygeneruj własną reklamę.
2. Wykonanie iteracji w łańcuchu zapośredniczenia W przypadku każdej sieci zewnętrznej wykonaj te czynności:
   1. Kompilacja AdSelectionFromOutcomeConfig, w tym własne outcomeId oraz Minimalna stawka pakietu SDK firmy zewnętrznej.
   2. Wywołaj funkcję selectAds() z konfiguracją z poprzedniego kroku.
   3. Jeśli wynik nie jest pusty, zwróć reklamę.
   4. Wywołaj metodę selectAds() obecnego adaptera sieci SDK. Jeśli wynik jest pusty, zwraca reklamę.
3. Jeśli w łańcuchu nie uda się znaleźć zwycięzcy, zwróć reklamę własną.

Kotlin

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

Java

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) { ... }
}

Raportowanie wyświetleń reklam

Raportowanie wyświetlenia reklamy odbywa się na 2 sposoby, w zależności od tego, jak aukcja przed uruchomieniem. Jeśli korzystasz z pojedynczej platformy SSP przeprowadzającej aukcję, przejdź do tej sekcji. Jeśli zamierzasz wdrożyć zapośredniczenie kaskadowe, wykonaj czynności opisane na .

Raportowanie wyświetleń w ramach pojedynczej platformy SSP

Po wybraniu zwycięskiej reklamy z procedury wyboru reklamy można ją zgłaszanie wyświetlenia z powrotem do platform po stronie kupującego i sprzedawcy; za pomocą metody AdSelectionManager.reportImpression(). Aby zgłosić reklamę wyświetlenie:

1. Zainicjuj obiekt AdSelectionManager.
2. Utwórz obiekt ReportImpressionRequest z identyfikatorem wyboru reklamy.
3. Wywołaj asynchroniczną metodę reportImpression() za pomocą funkcji ReportImpressionRequest i odpowiednie Executor oraz Obiekty OutcomeReceiver.

Java

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

Kotlin

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)

Zainicjuj ReportImpressionRequest, używając tych wymaganych elementów parametry:

• Identyfikator wyboru reklamy: niepowtarzalny identyfikator tylko dla użytkownika urządzenia, który identyfikuje pomyślnego wyboru reklamy.
• Konfiguracja wyboru reklamy: ta sama konfiguracja co w tabeli selectAds(). zgodnie z podanym identyfikatorem wyboru reklamy.

Asynchroniczna metoda reportImpression() korzysta z metody OutcomeReceiver , aby sygnalizować wynik wywołania interfejsu API.

• Wywołanie zwrotne onResult() wskazuje, czy adresy URL raportowania wyświetleń zostały a żądanie zostało zaplanowane.
• Wywołanie zwrotne onError() wskazuje te możliwe warunki:
  • Jeśli wywołanie zostanie zainicjowane z nieprawidłowym argumentem wejściowym, funkcja AdServicesException oznacza IllegalArgumentException jako przyczyna.
  • Wszystkie inne błędy otrzymują komunikat AdServicesException z atrybutem IllegalStateException.

Kaskadowe raportowanie wyświetleń w ramach zapośredniczenia

Pakiet zapośredniczenia SDK musi śledzić zwycięski pakiet SDK, aby aktywować procesów raportowania. Pakiety SDK uczestniczące w łańcuchu zapośredniczenia powinny przekazywać do wywołania przez mediatora własnego przepływu raportowania. Pakiet SDK biorąc udział w aukcji zapośredniczonej, wykonaj powyższe czynności, aby zaimplementować własne raporty.

Platformy SSP mogą wykorzystać ten przykładowy kod pakietu SDK firmy zewnętrznej jako prototyp procesu dołączania Procesy zapośredniczenia:

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 do raportowania wyświetleń wysyła żądania HTTPS GET do punktów końcowych dostarczanych przez platformę SSP i zwycięską platformę po stronie kupującego:

Punkt końcowy platformy po stronie kupującego:

• Interfejs API korzysta z adresu URL mechanizmu ustalania stawek określonego w liście odbiorców niestandardowych, aby pobiera kod JavaScript dostarczony przez kupującego, który zawiera funkcje logiczne zwracające adresu URL raportowania wyświetleń.
• Wywołaj funkcję JavaScript reportWin(), która powinna zwrócić adresu URL raportowania wyświetleń kupującego.

Punkt końcowy platformy sprzedażowej:

• Użyj adresu URL logiki decyzyjnej podanego w AdSelectionConfig pobierze kod JavaScript oparty na logice decyzji sprzedawcy.
• Wywołaj funkcję JavaScript reportResult(), która powinna zwrócić błąd adres URL raportowania wyświetleń sprzedawcy.

Określanie stawek Raporty dotyczące usług aukcyjnych

Aukcja przeprowadzona na podstawie określania stawek Usługi aukcyjne będą zawierać wszystkie niezbędne raportowanie informacji, w tym adresy URL wygenerowane na potrzeby raportowania interakcji z reklamami, zawarte w zaszyfrowanej odpowiedzi z aukcji po stronie serwera. Gdy gdy odpowiedź zostanie odszyfrowana, na platformie zostaną zarejestrowane odpowiednie adresy URL, aby generować raporty o reklamach i wyświetleniach, wykonując te same czynności co powyżej.

Raporty wyświetleń w ramach najlepszych starań

Metoda reportImpression() została zaprojektowana tak, aby umożliwić z najlepszym wykonaniem i raportowania danych.

Uwaga:

• Jeśli interfejs API nie może określić adresów URL raportowania wyświetleń z parametru JavaScriptu, zwróci on błąd.
• Jeśli wywołanie adresów URL nie powiedzie się, bieżąca wersja przedpremierowa dla programistów tak nie spowoduje żadnych błędów. Logika ponawiania w przypadku tymczasowych awarii to zaplanowano na przyszłe wydania.
• Wiele połączeń z tym samym numerem reportImpression() mogą spowodować, że wyniki wyboru reklamy będą raportowane wiele razy razy.

Raportowanie interakcji z reklamami

Protected Audience API umożliwia tworzenie bardziej szczegółowych raportów o interakcjach po wyrenderowaniu reklamy. Mogą to być interakcje takie jak czas wyświetlenia, kliknięcia, najechanie kursorem, lub inne przydatne dane, które można zebrać. Proces ich otrzymywania wymaga wykonania dwóch czynności. Po pierwsze, kupujący i sprzedawcy muszą się zarejestrować, w kodzie JavaScriptu. Następnie klient musi i je zgłaszać.

Rejestracja w celu otrzymywania zdarzeń interakcji

Rejestrowanie na zdarzenia interakcji odbywa się w reportWin() oraz funkcji JavaScript sprzedawcy reportResult() za pomocą funkcji JavaScript udostępnione przez platformę: registerAdBeacon. Aby zarejestrować się i otrzymać w raporcie zdarzeń, wystarczy wywołać funkcję JavaScript platformy JavaScriptu. Ten fragment kodu używa właściwości reportWin() kupującego, ale tej samej dotyczy metody reportResult().

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri
    registerAdBeacon("click", clickUri)
    registerAdBeacon("view", viewUri)
    registerAdBeacon("hover", hoverUri)

    return reportingUrl;
}

Uwaga: ciągi kluczowe interakcji muszą być zgodne z danymi w raportach sprzedawcy. i otrzymywać raporty.

Raportowanie zdarzeń interakcji

Po zgłoszeniu wyświetlenia klienci mogą zgłaszać interakcje do firmy wcześniej zarejestrowane, wygrywające platformy po stronie kupującego i sprzedaży Metoda AdSelectionManager.reportInteraction(). Aby zgłosić zdarzenie reklamowe:

1. Zainicjuj obiekt AdSelectionManager.
2. Utwórz obiekt ReportInteractionRequest z identyfikatorem wyboru reklamy. klucz interakcji, dane interakcji i miejsce docelowe raportowania.
3. Wywoływanie asynchronicznej metody reportInteraction() za pomocą obiektu request i odpowiednie obiekty 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);

Zainicjuj ReportInteractionRequest, używając tych wymaganych elementów parametry:

• Identyfikator wyboru reklamy: identyfikator wyboru reklamy pobrany ze zwróconego wcześniej AdSelectionOutcome
• Klucz interakcji: klucz ciągu zdefiniowany przez klienta i opisujący działanie. są zgłaszane. Musi on być zgodny z kluczem zarejestrowanym przez sprzedawcę lub w funkcjach JavaScriptu do raportowania.
• Dane interakcji: ciąg znaków zawierający dane, które zostaną uwzględnione w zdarzeniu. który ma zostać przesłany z powrotem do serwerów raportowania za pomocą metody POST.
• Miejsca docelowe raportowania: maska bitowa określająca, czy zdarzenia powinny być nabywcy, sprzedawcy lub obu tych stronom. Flagi te są udostępniane przez platformy i końcowej maski miejsca docelowego można utworzyć za pomocą metody bitowej operacji. Aby zgłosić problem do jednego miejsca docelowego, możesz użyć flagi dostarczonej przez bezpośrednio na platformie. Aby wygenerować raport do wielu miejsc docelowych, możesz użyć LUB (|), aby połączyć wartości flag.

Asynchroniczna metoda reportInteraction() korzysta z metody OutcomeReceiver , aby sygnalizować wynik wywołania interfejsu API.

• Wywołanie zwrotne onResult() wskazuje, że wywołanie interakcji w raporcie jest prawidłowe.
• Wywołanie zwrotne onError() wskazuje te możliwe warunki:
  • Jeśli połączenie jest wykonywane w czasie, gdy aplikacja działa w tle, Zwracany jest element IllegalStateException z opisem błędu.
  • Jeśli dostęp klienta do funkcji reportInteraction() zostanie zablokowany, Wartość LimitExceededException jest zwracana.
  • Jeśli pakiet nie jest zarejestrowany do wywoływania interfejsów Privacy PreServing API, Zwracana jest wartość SecurityException().
  • Jeśli interakcje w raportowaniu aplikacji różnią się od interakcji z aplikacją, która wywołała selectAds(), zwracany jest IllegalStateException.
• Jeśli użytkownik nie wyraził zgody na włączenie interfejsów API Piaskownicy prywatności, wywołanie dyskretnie się nie powiodły.

Uwaga: brak błędów nie oznacza, że wystąpiły błędy. Zamiast tego to gwarantuje, że Protected Audience API będzie próbowała raportować interakcje na stronie

Punkty końcowe raportowania interakcji

Interfejs API interakcji z raportami wysyła żądania HTTPS POST do punktów końcowych dostarczanych przez między platformą sprzedaży i zwycięską platformą kupna. Protected Audience API dopasuje klucze interakcji do identyfikatorów URI zadeklarowanych w kodzie JavaScript służącym do raportowania i wysyłaj żądanie POST do każdego punktu końcowego dla każdej zgłaszanej interakcji. Typ treści żądania to zwykły tekst, którego treść jest Dane dotyczące interakcji.

Raportowanie interakcji w ramach najlepszych starań

reportInteraction() zaprojektowano tak, aby jak najdokładniej wykonywać za pomocą metody HTTP POST.

Codzienna aktualizacja tła

Gdy tworzysz grupę odbiorców niestandardowych, aplikacja lub pakiet SDK może ją zainicjować metadanych. Dodatkowo platforma może aktualizować następujące elementy niestandardowych z metadanymi odbiorców z codzienną aktualizacją w tle.

• Sygnały dotyczące określania stawek przez użytkownika
• Dane dotyczące zaufanego określania stawek
• AdData lista

Ten proces wysyła zapytania do adresu URL codziennej aktualizacji zdefiniowanego w niestandardowych listach odbiorców. i URL może zwrócić odpowiedź JSON.

• Odpowiedź JSON może zawierać dowolne z obsługiwanych pól metadanych, które wymaga do zaktualizowania.
• Każde pole JSON jest sprawdzane niezależnie. Klient ignoruje wszystkie nieprawidłowych pól, które nie powodują aktualizacji danych w danym polu odpowiedź.
• Pusta odpowiedź HTTP lub pusty obiekt JSON „{}” w wyniku nie aktualizacji metadanych.
• Rozmiar wiadomości z odpowiedzią musi być ograniczony do 10 KB.
• Do korzystania z HTTPS są wymagane wszystkie identyfikatory URI.
• Domena trusted_bidding_uri musi mieć tę samą wartość ETLD+1 co kupujący.

Przykład: odpowiedź JSON z codzienną aktualizacją w tle

{
    "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 reklamy administruje wykonaniem kreacji przesłanych przez kupującego JavaScript dostępny przez sprzedawcę.

Kod JavaScript dostarczony przez kupującego jest pobierany z adresu URL logiki ustalania stawek podanego w polu niestandardowych odbiorców. Zwrócony kod JavaScript powinien zawierać te funkcje:

• generateBid()
• reportWin()

Kod JavaScript dostarczony przez sprzedawcę jest pobierany z adresu URL procesu decyzyjnego określonego w polu parametr AdSelectionConfig interfejsu Ad Selection API. Zwrócone wartości 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 w formacie var ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals: obiekty JSON określone w aukcji. obiekt konfiguracji

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

  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 tekstowe pobrane z właściwości z parametrem ta sama nazwa listy niestandardowych odbiorców uwzględnionych w wyborze reklamy;
  • activation_time i expiration_time to moment aktywacji oraz wygaśnięcia niestandardowej listy odbiorców, wyrażony w sekundach od czasu utworzenia systemu uniksowego epoka
  • ca_user_bidding_signals to ciąg znaków JSON określony w Pole userBiddingSignals obiektu CustomAudience w momencie utworzenia
  • trusted_bidding_signals, contextual_signals i user_signals są zapisane w formacie JSON obiektów. Są one przekazywane jako puste obiekty i zostaną wypełnione kolejnych wersji. Ich format nie jest wymuszany przez platformę i jest zarządzany. w dziedzinie technologii reklamowych.

Efekt:

• ad: reklama, której dotyczy stawka. Skrypt może zwrócić kopię otrzymaną reklamę z różnymi metadanymi. Właściwość render_url elementu reklama powinna pozostać niezmieniona.
• bid: wartość zmiennoprzecinkowa reprezentująca wartość stawki dla tej reklamy.
• status: liczba całkowita, która może być:
  • 0: oznacza pomyślne wykonanie.
  • 1: (lub dowolna wartość różna od 0) na wypadek, gdyby którykolwiek z sygnałów wejściowych był nieprawidłowy. W Jeśli funkcja Wygeneruj stawkę zwraca wartość inną niż zero, proces licytacji unieważniona dla 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: wyświetl dokumentację generateBid
• bid: wartość stawki za reklamę.

• ad_selection_config: obiekt JSON reprezentujący klucz Parametr AdSelectionConfig interfejsu API selectAds. Format to:

  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 sellerSignals Parametr interfejsu API AdSelectionConfig

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

• contextual_signals, user_signals: obiekty JSON. Obecnie są przekazywane jako puste obiekty i zostaną wypełnione w kolejnych wersjach. Ich format nie jest jest egzekwowana przez platformę i zarządzana przez technologię reklamową.

• per_buyer_signals: obiekt JSON odczytany z mapy perBuyerSignal w Parametr interfejsu API AdSelectionConfig używany jako klucz bieżącego parametru niestandardowego Kupujący będący odbiorcami. Puste, jeśli mapa nie zawiera żadnych wpisów dla danego kupującego.

Dane wyjściowe:

• score: wartość zmiennoprzecinkowa określająca wartość wyniku tej reklamy.
• status: liczba całkowita, która może być:
  • 0: oznacza pomyślne wykonanie
  • 1: na wypadek, gdyby customAudienceSignals były nieprawidłowe
  • 2: jeśli AdSelectionConfig jest nieprawidłowy
  • 3. Jeśli inne sygnały są nieprawidłowe
  • Każda wartość różna od 0 powoduje niepowodzenie procesu; wartość określa typ zgłoszonego 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. obiekt

Dane wyjściowe:

• status: 0 oznacza sukces, wartość inna niż 0 w przypadku niepowodzenia
• result: jeden z przekazanych 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: wyświetl dokumentację scoreAds
• render_url: wyrenderowany URL zwycięskiej reklamy.
• bid: stawka zaoferowana za zwycięską reklamę.
• contextual_signals: wyświetl dokumentację generateBid

Dane wyjściowe:

• status: 0 oznacza sukces i wartość inna niż 0 w przypadku niepowodzenia
• results: obiekty JSON zawierające:
  • signals_for_buyer: obiekt JSON przekazywany do metody reportWin funkcja
  • reporting_url: adres URL używany przez platformę do powiadamiania wyświetlenie reklamy kupującemu.

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ą usługi scoreAd
• signals_for_buyer: obiekt JSON zwrócony przez funkcję reportResult
• contextual_signals, custom_audience_signals: zapoznaj się z dokumentacją usługi generateBid

Dane wyjściowe:

• status: 0 oznacza sukces i wartość inna niż 0 w przypadku niepowodzenia
• results: obiekt JSON zawierający:
  • reporting_url: adres URL używany przez platformę do powiadamiania wyświetlenie reklamy sprzedawcy

registerAdBeacon()

Uwaga: ta opcja jest udostępniana przez platformę Androida i nie powinna być wdrażana przez technologii reklamowej.

function registerAdBeacon(
  interaction_key,
  reporting_uri
)

Parametry wejściowe:

• interaction_key: ciąg znaków reprezentujący zdarzenie. Jest ona używana przez później podczas raportowania interakcji ze zdarzeniami, aby wyszukać reporting_uri, które należy powiadomić. Ten klucz musi pasować do tego, w których rejestruje się kupujący lub sprzedawca, i to, co raportuje sprzedawca.
• reporting_uri: identyfikator URI do otrzymywania raportów o zdarzeniach. Powinna być związana z typ zgłaszanego zdarzenia. Musi zaakceptować żądanie POST do obsługi przesyłane razem ze zdarzeniem.

Gotowe identyfikatory URI funkcji wyboru reklamy

Gotowe identyfikatory URI umożliwiają specjalistom ds. technologii reklamowych wybór funkcji JavaScriptu na potrzeby reklamy logika wyboru w systemach AdSelectionConfig oraz AdSelectionFromOutcomesConfig zajęć. Gotowe identyfikatory URI nie wymagają sieci w celu pobrania odpowiedniego JavaScriptu. Technologie reklamowe mogą używać gotowych identyfikatorów URI bez konieczności konfigurowania zarejestrowanej domeny do hostowania JavaScriptu.

Gotowy identyfikator URI jest tworzony w tym formacie:

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

Platforma Piaskownicy prywatności udostępnia kod JavaScript, wykorzystując informacje z tej Identyfikator URI w środowisku wykonawczym.

IllegalArgumentException jest zgłaszany, jeśli:

• w identyfikatorze URI nie ma żadnego z wymaganych parametrów
• identyfikator URI zawiera nierozpoznane parametry

Obsługiwane przypadki użycia i nazwy gotowych identyfikatorów URI

Przykład zastosowania 1: wybór reklamy

Gotowe identyfikatory URI według przypadku użycia ad-selection są obsługiwane w Proces selectAds(AdSelectionConfig).

Nazwa gotowego identyfikatora URI: highest-bid-wins

Ten gotowy identyfikator URI udostępnia kod JavaScript, który wybiera reklamę o najwyższej stawce po ustaleniu stawek. Udostępnia też podstawową funkcję raportowania do raportowania render_uri i bid zwycięzcy.

Parametry wymagane

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

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

Wykorzystanie

Jeśli podstawowy adres URL raportowania to https://www.ssp.com/reporting, Identyfikator URI będzie miał postać:

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

Przykład zastosowania 2: wybór reklamy z wyników

Gotowe identyfikatory URI w ramach przypadku użycia ad-selection-from-outcomes obsługują selectAds(AdSelectionFromOutcomesConfig) – przepływ pracy.

Nazwa gotowego identyfikatora URI: waterfall-mediation-truncation

Gotowy identyfikator URI waterfall-mediation-truncation udostępnia kod JavaScript, który implementuje logikę obcinania zapośredniczenia kaskadowego, gdzie kod JavaScript zwraca własną reklamę, jeśli wartość bid jest większa od wartości bid floor lub jej równa oraz w przeciwnym razie zwraca null.

Parametry wymagane

bidFloor: klucz wartości minimalnej stawki przekazywanej w parametrze getSelectionSignals(). w porównaniu z reklamą z pakietu zapośredniczenia.

Wykorzystanie

Jeśli sygnały wyboru reklam mają postać {"bid_floor": 10}, wynikowy wynik Gotowy identyfikator URI wygląda tak:

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

Testowanie

Aby ułatwić Ci rozpoczęcie pracy z interfejsem Protected Audience API, przygotowaliśmy przykładowy w języku Kotlin i Javie, które znajdziesz na GitHub.

Wymagania wstępne

Interfejs Protected Audience API wymaga JavaScriptu podczas wyboru reklamy w raportach wyświetleń. Istnieją dwie metody dostarczania tego kodu JavaScript w środowisko testowe:

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

Każda z tych metod wymaga skonfigurowania punktu końcowego HTTPS do obsługi wyświetleń i raportowania danych.

Punkty końcowe HTTPS

Aby przetestować wybór reklam i raportowanie wyświetleń, musisz skonfigurować 7 punkty końcowe, do których urządzenie testowe lub emulator ma dostęp:

1. Punkt końcowy kupującego, który udostępnia logikę ustalania stawek w JavaScript.
2. Punkt końcowy, który udostępnia sygnały ustalania stawek.
3. Punkt końcowy sprzedawcy, który udostępnia kod JavaScript do podejmowania decyzji.
4. Punkt końcowy, który udostępnia sygnały oceny.
5. Punkt końcowy raportowania wyświetleń zwycięskiego kupującego.
6. Punkt końcowy raportowania wyświetleń sprzedawcy.
7. Punkt końcowy, w którym będą przesyłane codzienne aktualizacje dla niestandardowej grupy odbiorców.

Repozytorium GitHub udostępnia dla Twojej wygody podstawowy kod JavaScript do testowania w celach informacyjnych. Zawiera również definicje usług OpenAPI, które można wdrożyć w za pomocą obsługiwanej platformy testowej czy mikroserwisów. Aby dowiedzieć się więcej, zapoznaj się z projektem README.

Zastąp zdalne pobieranie JavaScriptu

Ta funkcja jest przeznaczona do kompleksowego testowania. Zastąpienie pilota aplikacja musi działać w trybie debugowania z włączonymi opcjami programisty.

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

<application
  android:debuggable="true">

Uwaga: pamiętaj, aby usunąć android:debuggable="true przed wysłaniem i aplikacji.

Przykłady korzystania z tych zastąpień znajdziesz w Przykładowa aplikacja Audience API na GitHubie.

Musisz dodać własny, niestandardowy kod JavaScript, by obsługiwać procedury wyboru reklamy, takie jak takich jak określanie stawek, decyzje dotyczące punktacji i raportowanie. Podstawowy kod JavaScript które obsługują wszystkie wymagane żądania w repozytorium GitHub. Przykładowa aplikacja interfejsu Protected Audience API pokazuje, jak odczytywać kod ten plik i przygotować go do użycia jako zastąpienia.

Można zastąpić pobieranie JavaScriptu po stronie sprzedającego i kupującego. niezależnie od siebie, ale do obsługi kodu JavaScript potrzebny jest punkt końcowy HTTPS dla których nie stosujesz zastąpień. Zapoznaj się z materiałami README dotyczącymi gdzie znajdziesz informacje o tym, jak skonfigurować serwer, który będzie obsługiwał takie przypadki.

Pobieranie JavaScriptu można zastąpić tylko w przypadku niestandardowych odbiorców, którzy należą do pakietu.

Zastąp kod JavaScript po stronie sprzedawcy

Aby skonfigurować zastępowanie kodu JavaScript po stronie sprzedawcy, wykonaj te czynności zgodnie z przykładem w tym przykładowym kodzie:

1. Zainicjuj obiekt AdSelectionManager.
2. Uzyskaj odniesienie do: TestAdSelectionManager z AdSelectionManager obiekt.
3. Utwórz obiekt AdSelectionConfig.
4. Utwórz AddAdSelectionOverrideRequest z obiekt AdSelectionConfig i obiekt String reprezentujący kod JavaScript. których chcesz użyć jako zastąpienia.
5. Wywołaj asynchroniczną metodę overrideAdSelectionConfigRemoteInfo() za pomocą funkcji AddAdSelectionOverrideRequest obiekt i odpowiednie Executor i OutcomeReceiver.

Kotlin

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)

Java

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

W sekcji Wybór reklam znajdziesz więcej informacji o tym, jakie reprezentowane przez pola w AdSelectionConfig. Główna różnica polega na tym, że parametr decisionLogicUrl może być ustawiony na wartość zmiennej, zignorowano.

Aby zastąpić kod JavaScript użyty podczas wybierania reklamy, komponent Pole decisionLogicJs musi zawierać prawidłowe podpisy funkcji po stronie sprzedawcy. Przykład odczytywania pliku JavaScript jako ciągu znaków znajdziesz w Przykładowa aplikacja Protected Audience API na GitHubie.

Asynchroniczna metoda overrideAdSelectionConfigRemoteInfo() korzysta z metody OutcomeReceiver obiekt sygnalizujący wynik wywołania interfejsu API.

Wywołanie zwrotne onResult() oznacza, że zastąpienie zostało zastosowane. W przyszłości połączenia z numerem selectAds() będą używane niezależnie od decyzji i raportów które zostały przesłane jako zastąpienie.

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

• Jeśli zostanie podjęta próba zastąpienia za pomocą nieprawidłowych argumentów, w funkcji AdServiceException wskazuje IllegalArgumentException jako przyczyna.
• Jeśli próba zastąpienia zostanie zastąpiona, gdy aplikacja nie działa w trybie debugowania z parametrem włączone opcje programisty, ikona AdServiceException wskazuje, IllegalStateException.

Zresetuj zastąpienia po stronie sprzedawcy

W tej sekcji zakładamy, że masz zastąpiony kod JavaScript używany do sprzedaży i masz odwołanie do: TestAdSelectionManager oraz Wartość AdSelectionConfig została użyta w poprzedniej sekcji.

Aby zresetować zastąpienia dla wszystkich AdSelectionConfigs:

1. Wywoływanie asynchronicznej metody resetAllAdSelectionConfigRemoteOverrides() z odpowiednim obiektem OutcomeReceiver.

Kotlin

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

Java

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

Po zresetowaniu zastąpień po stronie sprzedawcy połączenia do selectAds() będą używać dowolnych Parametr decisionLogicUrl jest przechowywany w AdSelectionConfig, aby podjąć próbę pobierz wymagany JavaScript.

Jeśli wywołanie resetAllAdSelectionConfigRemoteOverrides() nie powiedzie się, Wywołanie zwrotne OutComeReceiver.onError() udostępnia wartość AdServiceException. Jeśli zostanie podjęta próba usunięcia zastąpień, gdy aplikacja nie będzie uruchomiona w trybie debugowania z włączonymi opcjami programisty, AdServiceException oznacza IllegalStateException.

Zastąp JavaScript po stronie kupującego

1. Postępuj zgodnie z instrukcjami, aby dołączyć do grupy niestandardowych odbiorców.
2. Tworzenie AddCustomAudienceOverrideRequest z kupującym i nazwę listy odbiorców niestandardowych, której ustawienia chcesz zastąpić. reguły określania stawek i dane, których chcesz użyć jako zastąpień.
3. Wywołaj asynchroniczną metodę overrideCustomAudienceRemoteInfo() za pomocą funkcji AddCustomAudienceOverrideRequest obiekt i trafny Obiekty Executor i OutcomeReceiver

Kotlin

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)

Java

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 atrybutów buyer i name są takie same jak użyte do utworzenia. grupę niestandardowych odbiorców. Więcej informacji o tych polach

Możesz też podać dwa dodatkowe parametry:

• biddingLogicJs: kod JavaScript zawierający logikę kupującego, która jest używana. podczas wyboru reklamy. Wymagane podpisy funkcji znajdziesz w tym artykule JavaScriptu.
• trustedBiddingSignals: sygnały służące do określania stawek, które mają być używane podczas wyboru reklamy. Do celów testowych może to być pusty ciąg znaków.

Asynchroniczna metoda overrideCustomAudienceRemoteInfo() korzysta z metody OutcomeReceiver sygnalizujący wynik wywołania interfejsu API.

Wywołanie zwrotne onResult() oznacza, że zastąpienie zostało zastosowane. Kolejne wywołania funkcji selectAds() używają dowolnej logiki określania stawek i raportowania który został przekazany jako zastąpienie.

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

• Jeśli zostanie podjęta próba zastąpienia za pomocą nieprawidłowych argumentów, w funkcji AdServiceException wskazuje IllegalArgumentException jako przyczyna.
• Jeśli próba zastąpienia zostanie zastąpiona, gdy aplikacja nie działa w trybie debugowania z parametrem włączone opcje programisty, ikona AdServiceException wskazuje, IllegalStateException.

Zresetuj zastąpienia po stronie kupującego

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

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

1. Wywołaj asynchroniczną metodę resetAllCustomAudienceOverrides() za pomocą funkcji odpowiednie obiekty Executor i OutcomeReceiver.

Kotlin

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

Java

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

Po zresetowaniu zastąpień po stronie zakupu kolejne wywołania selectAds() używaj dowolnych biddingLogicUrl i trustedBiddingData przechowywane w CustomAudience, aby spróbować pobrać wymagane JavaScriptu.

Jeśli wywołanie resetCustomAudienceRemoteInfoOverride() nie powiedzie się, Wywołanie zwrotne OutComeReceiver.onError() udostępnia wartość AdServiceException. Jeśli zostanie podjęta próba usunięcia zastąpień, gdy aplikacja nie będzie uruchomiona w trybie debugowania z włączoną opcją programisty, ikona AdServiceException oznacza IllegalStateException.

Skonfiguruj serwer raportowania

Jeśli używasz zastąpień zdalnego pobierania, nadal musisz skonfigurować serwer które urządzenie lub emulator może sięgać, aby reagować na zgłaszane zdarzenia. Prosta który zwraca wartość 200, wystarczy do przeprowadzenia testów. Repozytorium GitHub zawiera: Definicje usług OpenAPI, które można wdrożyć w obsługiwanej wersji makiety lub platformy mikroserwisów. Aby dowiedzieć się więcej, zapoznaj się z projektem README.

Gdy szukasz definicji OpenAPI, znajdź plik Reporting-server.json. Ten plik zawiera prosty punkt końcowy, który zwraca kod 200, reprezentujący protokół HTTP kodu odpowiedzi. Ten punkt końcowy jest używany podczas: selectAds() i sygnalizuje: interfejsu Protected Audience API.

Funkcje do przetestowania

• Ćwicz, dołączając do grupy lub ją opuszczając i konfigurując niestandardową grupę odbiorców na podstawie wcześniejszych działań użytkownika.
• Uruchamiaj wybór reklam na urządzeniu za pomocą hostowanych skryptów JavaScript zdalnie.
• Obserwuj, jak powiązanie aplikacji z ustawieniami niestandardowych odbiorców może wpłynąć na reklamę wyniki wyboru.
• Raporty wyświetleń ćwiczenia po wybraniu reklamy.

Ograniczenia

W tabeli poniżej znajdziesz ograniczenia przetwarzania przez interfejs Protected Audience API. Przedstawione limity mogą ulec zmianie w zależności od opinii użytkowników. Dla: są w trakcie opracowywania, zapoznaj się z informacjami o wersji.

Komponent	Opis limitu	Wartość limitu
Niestandardowi odbiorcy (CA)	Maksymalna liczba reklam na urząd certyfikacji	100
	Maksymalna liczba urzędów certyfikacji na aplikację	1000
	Maksymalna liczba aplikacji, które mogą utworzyć urząd certyfikacji	1000
	Maksymalne opóźnienie czasu aktywacji urzędu certyfikacji od momentu jego utworzenia	60 dni
	Maksymalny czas wygaśnięcia urzędu certyfikacji od momentu aktywacji	60 dni
	Maksymalna liczba urzędów certyfikacji na urządzeniu	4000
	Maksymalny rozmiar nazwy urzędu certyfikacji	200 bajtów
	Maksymalny rozmiar identyfikatora URI pobierania dziennie	400 bajtów
	Maksymalny rozmiar identyfikatora URI logiki ustalania stawek	400 bajtów
	Maksymalny rozmiar danych dotyczących zaufanych stawek	10 KB
	Maksymalny rozmiar sygnałów dotyczących określania stawek przez użytkownika	10 KB
	Maksymalna liczba połączeń za leaveCustomAudience na kupującego	1 na sekundę
	Maksymalna liczba połączeń za joinCustomAudience na kupującego	1 na sekundę
Pobieranie informacji w tle z Kalifornii	Przekroczenie limitu czasu oczekiwania na połączenie	5 sekund
	Upłynął limit czasu odczytu HTTP	30 sekund
	Maksymalny łączny rozmiar pobierania	10 KB
	Maksymalny czas trwania iteracji pobierania	5 minut
	Maksymalna liczba urzędów certyfikacji aktualizowanych na zadanie	1000
Wybór reklamy	Maksymalna liczba kupujących	Do ustalenia
	Maksymalna liczba urzędów certyfikacji na kupującego	Do ustalenia
	Maksymalna liczba reklam w aukcji	Do ustalenia
	Limit czasu połączenia początkowego	5 sekund
	Upłynął limit czasu odczytu połączenia	5 sekund
	Maksymalny czas wykonania ogólnego zasobu AdSelection	10 sekund
	Maksymalny czas wykonywania określania stawek na urząd certyfikacji w AdSelection	5 sekund
	Maksymalny czas wykonania punktacji w AdSelection	5 sekund
	Maksymalny czas realizacji na kupującego w AdSelection	Do ustalenia
	Maksymalny rozmiar sygnałów wyboru reklamy/sprzedawcy/na kupującego	Do ustalenia
	Maksymalny rozmiar skryptów sprzedawcy/kupującego	Do ustalenia
	Maksymalna częstotliwość połączeń (selectAds)	1 QPS
Raporty wyświetleń	Minimalny czas przed usunięciem wybranej reklamy z trwałości	24 godz.
	Maksymalna liczba wybranych reklam pamięci masowej	Do ustalenia
	Maksymalny rozmiar wyjściowego adresu URL raportowania	Do ustalenia
	Maksymalny czas raportowania wyświetleń	Do ustalenia
	Maksymalna liczba ponownych prób w przypadku połączeń z powiadomieniami	Do ustalenia
	Limit czasu połączenia	5 sekund
	Maksymalny ogólny czas wykonywania dla reguły reportImpression	2 sekundy
	Maksymalna częstotliwość połączeń (reportImpressions)	1 QPS
Raporty o zdarzeniach	Maksymalna liczba beaconów na kupującego na aukcję	10
	Maksymalna liczba beaconów na sprzedawcę na aukcję	10
	Maksymalny rozmiar klucza zdarzenia	40 bajtów
	Maksymalny rozmiar danych zdarzenia	64KB
Reklamy	Maksymalny rozmiar listy reklam	10 KB udostępniane przez wszystkich AdData w jednym urzędu certyfikacji na potrzeby kontekstu
Adresy URL	Maksymalna długość dowolnego ciągu adresu URL uznawanego za dane wejściowe	Do ustalenia
JavaScript	Maksymalny czas wykonania	1 sekunda na określanie stawek i punktowanie na potrzeby raportowania wyświetleń
	Maksymalna używana pamięć	10 MB

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

Twoja opinia jest kluczowym elementem Piaskownicy prywatności na Androida. Daj nam znać żadnych problemów lub pomysłów na ulepszenie Piaskownicy prywatności na Androida.