Przewodnik dla programistów interfejsu Protected Audience API

Wersja przedpremierowa dla programistów Beta

Podczas czytania dokumentacji Piaskownicy prywatności na Androida wybierz odpowiednią wersję programu, korzystając z przycisku Podgląd dla programistów lub Beta. Instrukcje mogą się różnić.

---

Przesłać opinię

Interfejs Protected Audience API na Androida (dawniej FLEDGE) obejmuje interfejsy Custom Audience API i Ad Selection API. Reklamodawcy i platformy z branży technologii reklamowych mogą używać tych interfejsów API do wyświetlania reklam dopasowanych na podstawie wcześniejszego zaangażowania w aplikację. Ogranicza to udostępnianie identyfikatorów między aplikacjami i ogranicza udostępnianie firmom zewnętrznym informacji o interakcji z aplikacjami.

Interfejs Custom Audience API koncentruje się na grupie „niestandardowych odbiorców”, czyli grupie użytkowników o podobnych zamiarach. Reklamodawca może zarejestrować użytkownika na niestandardowej liście odbiorców i powiązać z nią odpowiednie reklamy. Informacje te są przechowywane lokalnie i mogą służyć do ustalania stawek reklamodawców oraz ich filtrowania i renderowania.

Interfejs Ad Selection API umożliwia wielu deweloperom przeprowadzanie lokalnych aukcji dla niestandardowych odbiorców. Aby to osiągnąć, system uwzględnia trafne reklamy powiązane z niestandardową listą odbiorców i dodatkowo przetwarza reklamy, które platforma technologii reklamowych zwraca na urządzenie.

Platformy z branży technologii reklamowych mogą integrować te interfejsy API, aby wdrażać remarketing chroniący prywatność użytkowników. W kolejnych wersjach planujemy wprowadzić obsługę dodatkowych przypadków użycia, w tym reklam promujących instalacje aplikacji. Więcej informacji o interfejsie Protected Audience API na Androida znajdziesz w ofercie pakietowej.

Z tego przewodnika dowiesz się, jak korzystać z interfejsu Protected Audience API na Androidzie, aby:

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

Zanim zaczniesz

Przed rozpoczęciem wykonaj te czynności:

1. Skonfiguruj środowisko programistyczne Piaskownicy prywatności na Androida.
2. Zainstaluj obraz systemu na obsługiwanym urządzeniu lub skonfiguruj emulator obsługujący Piaskownicę prywatności na urządzeniach z Androidem.

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

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. Dodaj do pliku manifestu aplikacji uprawnienie ACCESS_ADSERVICES_CUSTOM_AUDIENCE:

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

5. Utwórz odniesienie do konfiguracji usług reklamowych w elemencie <application> pliku 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ę Twój plik manifestu, np. res/xml/ad_services_config.xml. Dowiedz się więcej o uprawnieniach do usług reklamowych i kontroli dostępu do pakietów SDK

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

7. Domyślnie interfejs Ad Selection API egzekwuje limity maksymalnej ilości pamięci, którą może przydzielić skrypt raportowania aukcji lub wyświetleń. Funkcja ograniczenia pamięci wymaga WebView w wersji 105.0.5195.58 lub nowszej. Platforma wymusza sprawdzanie wersji, a wywołania interfejsów API selectAds i reportImpression kończą się niepowodzeniem, jeśli są one niezgodne z zasadami. Możesz to zrobić na 2 sposoby:

   • Opcja 1. Aby dezaktywować 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. Ta wartość musi być równa lub wyższa od wersji podanej wcześniej.

Dołącz do niestandardowej listy odbiorców

Niestandardowa lista odbiorców to grupa użytkowników o wspólnych zamiarach lub zainteresowaniach, zgodnie z ustawieniami aplikacji reklamodawcy. Aplikacja lub pakiet SDK może używać tej listy do wskazywania konkretnej grupy odbiorców, np. osoby, która zostawiła produkty w koszyku. Aby asynchronicznie utworzyć niestandardową listę odbiorców lub dołączyć do niej:

1. Zainicjuj obiekt CustomAudienceManager.
2. Utwórz obiekt CustomAudience, określając kluczowe parametry, np. pakiet kupującego i odpowiednią nazwę. Następnie zainicjuj obiekt JoinCustomAudienceRequest za pomocą obiektu CustomAudience.
3. Wywołaj asynchroniczny joinCustomAudience() z obiektem JoinCustomAudienceRequest i odpowiednimi obiektami Executor i 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 tych parametrów jednoznacznie identyfikuje każdy obiekt CustomAudience na urządzeniu:

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

Wywoływanie funkcji joinCustomAudience() wielokrotnie z innym wystąpieniem obiektu CustomAudience aktualizuje istniejące już CustomAudience o pasujące parametry owner, buyer i name. Aby chronić prywatność, wynik działania interfejsu API nie rozróżnia „tworzenia” i „aktualizacji”.

Dodatkowo należy utworzyć CustomAudience z tymi wymaganymi parametrami:

• Adres URL z codzienną aktualizacją: adres URL HTTPS wysyłany codziennie w tle w celu aktualizowania sygnałów dotyczących określania stawek przez użytkowników i zaufanych danych dotyczących określania stawek w przypadku niestandardowej listy odbiorców oraz renderowania adresów URL i metadanych reklam na potrzeby reklam.
• Adres URL logiki określania stawek: adres URL HTTPS, którego kliknięcie jest wysyłane podczas wyboru reklamy w celu pobrania logiki ustalania stawek JavaScriptu przez kupującego. Zobacz wymagane podpisy funkcji w tym JavaScripcie.
• Identyfikatory renderowania reklam: dowolny identyfikator ustawiany przez technologię reklamową kupującego. Jest to optymalizacja generowania ładunku na potrzeby B&A.

Opcjonalne parametry obiektu CustomAudience mogą obejmować:

• Czas aktywacji: niestandardowa grupa odbiorców może uczestniczyć w wyborze reklam i codziennych aktualizacjach po upływie czasu aktywacji. Pomaga to na przykład zaangażować nieaktywnych użytkowników aplikacji.
• Data ważności: czas, po którym niestandardowa lista odbiorców jest usuwana z urządzenia.
• Sygnały dotyczące określania stawek przez użytkowników: ciąg znaków JSON zawierający sygnały użytkownika, np. preferowany język użytkownika, których JavaScript używa do generowania stawek podczas procesu wyboru reklamy. Format ten ułatwia platformy technologii reklamowych ponowne używanie kodu na różnych platformach i ułatwia wykorzystanie kodu w funkcjach JavaScript.
• Dane dotyczące zaufanego określania stawek: adres URL HTTPS i lista ciągów znaków używanych podczas procesu wyboru reklamy, które pobierają sygnały dotyczące określania stawek z zaufanej usługi klucz-wartość.
• Reklamy: lista obiektów AdData odpowiadających reklamom, które uczestniczą w wyborze. Każdy obiekt AdData składa się z:
  • URL renderowania: adres URL HTTPS, do którego jest wysyłane zapytanie o wyrenderowanie ostatecznej reklamy.
  • Metadane: obiekt JSON zserializowany jako ciąg znaków zawierający informacje, które ma wykorzystać logika ustalania stawek przez kupującego podczas procesu wyboru reklamy.
  • Filtry reklam: klasa zawierająca wszystkie informacje niezbędne do filtrowania reklam promujących instalacje aplikacji i ograniczania liczby wyświetleń podczas wyboru reklamy.

Uwaga: suma wartości atrybutów „Sygnały dotyczące stawek przez użytkowników”, „Zaufane dane ustalania stawek” i „Reklamy” nie powinna przekraczać 10 KB. Aby grupa niestandardowych odbiorców mogła uczestniczyć w wyborze reklamy, trzeba wypełnić te 3 pola.

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(), używa obiektu OutcomeReceiver do sygnalizowania wyniku wywołania interfejsu API.

• Wywołanie zwrotne onResult() oznacza, że niestandardowa lista odbiorców została utworzona lub zaktualizowana.
• Wywołanie zwrotne onError() oznacza 2 możliwe warunki.
  • Jeśli JoinCustomAudienceRequest został zainicjowany z nieprawidłowymi argumentami, AdServicesException wskazuje jako przyczynę IllegalArgumentException.
  • W przypadku pozostałych błędów wyświetlany jest AdServicesException z przyczyną IllegalStateException.

Oto przykład postępowania z wynikiem 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);
    }
};

Opuszczanie grupy odbiorców niestandardowych

Jeśli użytkownik nie spełnia już kryteriów biznesowych danej niestandardowej listy odbiorców, aplikacja lub pakiet SDK może wywołać metodę leaveCustomAudience(), aby usunąć tę listę z urządzenia. Aby usunąć element CustomAudience związany z jego unikalnymi parametrami, wykonaj te czynności:

1. Zainicjuj obiekt CustomAudienceManager.
2. Zainicjuj LeaveCustomAudienceRequest, używając listy niestandardowych odbiorców: buyer i name. Więcej informacji o tych polach znajdziesz w artykule „Dołączanie do grupy odbiorców niestandardowych”.
3. Wywołaj asynchroniczną metodę leaveCustomAudience() z obiektem LeaveCustomAudienceRequest oraz odpowiednimi obiektami Executor i 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 wywołanie joinCustomAudience(), OutcomeReceiver sygnalizuje zakończenie wywołania interfejsu API. Z myślą o ochronie prywatności wynik błędu nie odróżnia błędów wewnętrznych od nieprawidłowych argumentów. Wywołanie zwrotne onResult() jest wywoływane po zakończeniu wywołania interfejsu API niezależnie od tego, czy pasująca niestandardowa lista odbiorców została usunięta.

Uruchom wybór reklamy

Aby wybrać reklamy za pomocą interfejsu Protected Audience API, wywołaj metodę selectAds():

1. Zainicjuj obiekt AdSelectionManager.
2. Utwórz obiekt AdSelectionConfig.
3. Wywołaj asynchroniczną metodę selectAds() z obiektem AdSelectionConfig oraz odpowiednimi obiektami Executor i 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, w których musisz podać te wymagane parametry:

• Sprzedawca: identyfikator sieci reklamowej sprzedawcy, która inicjuje wybór reklamy.
• URL logiki decyzji: adres URL HTTPS używany w celu uzyskania logiki JavaScript sieci reklamowej sprzedawcy.
  • Adres URL HTTPS: przesłany w celu uzyskania logiki JavaScript sieci reklamowej sprzedawcy. Zobacz wymagane podpisy funkcji.
  • Gotowy identyfikator URI zgodny z formatem wyboru reklam FLEDGE. W przypadku przesłania nieobsługiwanego lub nieprawidłowo utworzonego identyfikatora URI zgłaszany jest IllegalArgumentException.
• Kupujący na liście niestandardowych odbiorców: pełna lista identyfikatorów sieci reklamowych kupujących, którzy mogą uczestniczyć w procesie wyboru reklamy. Te identyfikatory kupujących odpowiadają CustomAudience.getBuyer() listom odbiorców niestandardowych, które uczestniczą w programie.

Aby trafniej dobierać reklamy, możesz opcjonalnie określić te parametry:

• Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały do wykorzystania przez logikę określania stawek przez kupującego, pobrany z CustomAudience.getBiddingLogicUrl().
• Sygnały sprzedawcy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały używane przez pobraną przez sprzedawcę logikę decyzji JavaScriptu pobranej z AdSelectionConfig.getDecisionLogicUrl().
• Sygnały dla kupującego: mapa obiektów JSON, zserializowanych jako ciągi znaków, zawierających sygnały do wykorzystania przez logikę ustalania stawek konkretnych kupujących pobrany z CustomAudience.getBiddingLogicUrl(). Są one identyfikowane przez pola kupującego na listach niestandardowych odbiorców, które uczestniczą w programie.
• Reklamy kontekstowe: zbiór kandydatów reklam pozyskiwanych bezpośrednio od kupujących podczas aukcji prowadzonej poza aukcją w ramach Protected Audience API.

Po wybraniu reklamy wyniki, stawki i sygnały są zapisywane wewnętrznie na potrzeby raportów. Wywołanie zwrotne OutcomeReceiver.onResult() zwraca wartość AdSelectionOutcome, która zawiera:

• URL renderowania zwycięskiej reklamy uzyskany z pliku AdData.getRenderUrl().
• Unikalny identyfikator wyboru reklamy dla użytkownika urządzenia. Służy on do raportowania wyświetlenia reklamy.

Jeśli nie można wybrać reklamy z powodu nieprawidłowych argumentów, przekroczenia limitu czasu lub nadmiernego zużycia zasobów, wywołanie zwrotne OutcomeReceiver.onError() powoduje wywołanie funkcji AdServicesException o tych zachowaniach:

• Jeśli wybór reklamy został zainicjowany przy użyciu nieprawidłowych argumentów, AdServicesException wskazuje jako przyczynę IllegalArgumentException.
• W przypadku pozostałych błędów wyświetlany jest AdServicesException z przyczyną IllegalStateException.

Reklamy kontekstowe

W ramach Protected Audience API reklamy kontekstowe mogą być włączane do aukcji chronionej. Reklamy kontekstowe muszą być wybierane na serwerze technologii reklamowej i zwracane na urządzenie poza interfejsami Protected Audience API. Reklamy kontekstowe mogą być wtedy uwzględniane w aukcji za pomocą elementu AdSelectionConfig. Dzięki temu działają tak samo jak reklamy na urządzeniu, w tym spełniają kryteria filtrowania reklam wykluczających. Po zakończeniu aukcji Protected Audience API musisz wywołać reportImpression(). Wywołuje to zdarzenie reportWin() w zwycięskiej reklamie kontekstowej (tak samo jak w przypadku raportowania wyświetleń) w celu otrzymania na urządzeniu zwycięskiej reklamy. Każda reklama kontekstowa wymaga kupującego, stawki, linku do logiki raportowania, adresu URL renderowania i metadanych reklamy.

Aby wdrożyć reklamy kontekstowe w aplikacji, aplikacja docelowa musi utworzyć obiekt ContextualAds:

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

Otrzymany obiekt ContextualAds możesz 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 instalacje aplikacji

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

Pierwszym krokiem w tym procesie jest określenie, którzy reklamodawcy mogą filtrować zainstalowany pakiet. Musi to nastąpić w aplikacji, na którą chcesz kierować 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 uruchomiony, przekazani reklamodawcy mogą odfiltrowywać zainstalowane aplikacje określone przez Ciebie podczas generowania stawek. Jeśli chcesz zablokować reklamodawcy dostęp do stanu instalacji tej aplikacji, uruchom ten kod ponownie z usuniętymi informacjami o nim.

Następnym krokiem jest skonfigurowanie filtrowania reklam w aplikacji wydawcy. Firma, która wyświetla reklamę w aplikacji wydawcy (najprawdopodobniej to pakiet SDK po stronie dostawców), musi zainicjować obiekt AdFilters, podając informacje o tym, które reklamy związane z aplikacjami chce odfiltrowywać:

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 DSP mogą też ustawić AdFilter w przypadku reklam, które występują w grupach niestandardowych odbiorców.

AdFilters można też przekazać w momencie tworzenia wystąpienia nowego obiektu AdData:

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 pozwala technikom reklamowym ograniczać liczbę wyświetleń reklamy. Filtrowanie limitu wyświetleń na użytkownika ogranicza nadmierne wyświetlanie reklam i optymalizuje wybór reklam zastępczych w przypadku danej kampanii reklamowej.

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

• Wygrana (już wkrótce): zdarzenie wygranej oznacza, że reklama wygrała aukcję. Zdarzenia wygranych są automatycznie aktualizowane przez Protected Audience API i deweloper nie może ich wywoływać bezpośrednio. Dane wygranych są widoczne tylko dla reklam na danej niestandardowej liście odbiorców.
• Wyświetlenie: niezależnie od reportImpression element wywołujący na urządzeniu (SSP lub MMP) używa updateAdCounterHistogram() do wywoływania zdarzeń wyświetlenia w wybranym punkcie kodu. Zdarzenia wyświetlenia są widoczne dla wszystkich reklam należących do danej platformy DSP, nie tylko w przypadku reklam na tej samej niestandardowej liście odbiorców.
• Widok: zdarzenie jest wywoływane przez element wywołujący na urządzeniu (SSP lub MMP) w wybranym przez niego punkcie kodu za pomocą wywołania updateAdCounterHistogram(). Zdarzenia widoku danych są widoczne dla wszystkich reklam należących do danej platformy DSP, nie tylko w przypadku reklam z tej samej niestandardowej listy odbiorców.
• Kliknięcie: zdarzenie jest wywoływane przez element wywołujący na urządzeniu (SSP lub MMP) w wybranym przez niego punkcie kodu za pomocą wywołania updateAdCounterHistogram(). Zdarzenia kliknięcia są widoczne dla wszystkich reklam należących do danej platformy DSP, nie tylko w przypadku reklam należących do tej samej niestandardowej listy odbiorców.

Zdarzenia reklamowe w aplikacji wydawcy wywoływane są przez platformę SSP lub MMP, która istnieje na urządzeniu. Po wywołaniu funkcji updateAdCounterHistogram() licznik filtra limitu wyświetleń jest zwiększany, aby w przyszłych aukcjach uzyskać aktualne informacje o ekspozycji użytkownika na daną reklamę. Typy zdarzeń reklamowych nie są na stałe powiązane z odpowiadającymi im działaniami użytkownika. Są to wskazówki, które mają pomóc dzwoniącym w utworzeniu struktury systemu zdarzeń. Aby zwiększyć liczbę liczników reklam w momencie wystąpienia zdarzenia, użytkownik na urządzeniu podaje identyfikator wyboru reklamy zwycięskiej z aukcji.

Klucze licznika reklam to dowolne 32-bitowe liczby całkowite podpisane przez kupującego, które odpowiadają danemu zestawowi reklam zdefiniowanym przez platformę DSP. Klucze licznika reklam są ograniczone tylko do reklam należących do danej platformy DSP, więc można je wybrać bez pokrywania się z histogramami innych technologii reklamowych. Klucze licznika reklam służą do zwiększania liczby identyfikatorów DSP w reklamach platformy DSP lub w obrębie określonej niestandardowej listy odbiorców w celu odfiltrowywania reklam z przyszłych aukcji.

Klucze licznika można wykorzystać do nadawania priorytetu reklamom, które z większym prawdopodobieństwem będą interesujące dla danego użytkownika, na podstawie jego interakcji z innymi reklamami danej technologii reklamowej danego kupującego. Na przykład wywnioskowanym punktem danych jest reklama, która w dużym stopniu zaangażowała się w wygraną aukcję reklam, wyświetlenia i kliknięcia. Aby jeszcze lepiej wyjaśnić tę kwestię: reklama kijów golfowych dla leworęcznych może wskazywać, że użytkownik nie jest zainteresowany kijami praworęcznymi. Ustawiono filtr limitu wyświetleń na użytkownika dla klucza licznika przypisanego do reklam leworęcznych, aby odfiltrowywać reklamy kijów praworęcznych.

Aby użyć ograniczenia liczby wyświetleń w aukcji, musisz najpierw utworzyć obiekty (KeyedFrequencyCap), 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 je przekazać do obiektu AdFilters.

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 wypełniony filtrami limitu wyświetleń na użytkownika, może być przekazywany podczas tworzenia listy odbiorców niestandardowej:

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

Po zaimplementowaniu filtrów limitu wyświetleń na użytkownika na niestandardowej liście odbiorców platforma SSP może wywoływać niezbędne zdarzenia kliknięcia, wyświetlenia 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 wstępnie ustawiony limit filtra limitu wyświetleń na użytkownika, są odfiltrowywane z aukcji. Filtrowanie następuje przed uruchomieniem logiki ustalania stawek w przypadku aukcji na urządzeniu oraz w trakcie generowania ładunku na potrzeby aukcji ustalania stawek i usług aukcyjnych.Ten zestaw narzędzi zapewnia technikom reklamowym elastyczność w wykorzystywaniu interakcji między użytkownikami a reklamami w grupach niestandardowych, aby skupić się na kierowaniu reklam i zminimalizować ryzyko ich nadmiernej ekspozycji.

Filtrowanie reklam kontekstowych bez wywołań sieciowych

Jeśli na urządzeniu nie ma żądań remarketingu, możesz wyświetlać reklamy kontekstowe bez połączeń sieciowych. Dzięki gotowym identyfikatorom URI i liście reklam kontekstowych ze stawkami platforma może pominąć pobieranie logiki ustalania stawek, sygnałów ustalania stawek i sygnałów punktowych. Platforma używa gotowego identyfikatora URI, aby wybrać reklamę kontekstową z najwyższą stawką.

Aby skrócić czas oczekiwania, specjaliści ds. technologii reklamowych mogą przeprowadzać proces wyboru reklamy obejmujący tylko reklamy kontekstowe z funkcją filtrowania reklam bez wywołań sieciowych. Można to osiągnąć za pomocą gotowych identyfikatorów URI do określania wartości sygnałów. Listę obsługiwanych implementacji scoreAds znajdziesz w sekcji na temat obsługiwanych gotowych identyfikatorów URI.

Aby wyświetlać wybór reklam bez połączeń sieciowych:

1. Konfigurowanie filtrowania reklam
2. Tworzenie reklam kontekstowych

3. Utwórz obiekt AdSelectionConfig z tą instrukcją:

   1. Pusta lista kupujących
   2. Gotowy identyfikator URI służący do wybierania najwyższej stawki
   3. Reklamy kontekstowe
   4. Pusty identyfikator URI dla sygnałów punktowych. Pusty identyfikator URI może wskazać, że nie chcesz korzystać z pobierania zaufanych sygnałów do oceny:

   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, korzystając z gotowych identyfikatorów URI

Obecnie platforma Piaskownicy prywatności obsługuje tylko podstawowe implementacje JavaScript służące do raportowania w przypadku gotowych identyfikatorów URI. Jeśli chcesz uruchamiać własny kod JavaScript do raportowania, jednocześnie korzystając z gotowych identyfikatorów URI do wyboru reklam z krótkim czasem oczekiwania, możesz zastąpić parametr DecisionLogicUri między wyborem reklamy a generowaniem raportów.

1. Wykonaj odpowiednie czynności, by korzystać z wyboru reklam kontekstowych przy użyciu gotowych identyfikatorów URI.

2. Zanim uruchomisz raportowanie, 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 organizacji wielu zewnętrznych pakietów SDK (sieci zewnętrznych) przez sieć zapośredniczenia SDK. Zapośredniczenie kaskadowe odbywa się w ten sam sposób niezależnie od tego, czy aukcja odbywała się na urządzeniu czy w usługach określania stawek i aukcji.

Sieci innych firm

Sieci zewnętrzne muszą dostarczyć adapter, który umożliwia sieci zapośredniczeń wywoływanie metod niezbędnych do przeprowadzenia aukcji:

• Uruchom wybór reklamy
• Raportuj wyświetlenia

Oto przykład adaptera sieci zapośredniczenia:

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 usługi wyboru reklamy oraz własną implementację selectAds i reportImpressions. Dostawcy pakietów SDK mogą zapoznać się z sekcjami dotyczącymi wyboru reklam w przypadku aukcji na urządzeniu lub skorzystać z objaśnienia na temat aukcji B&A (w języku angielskim). Postępuj zgodnie z instrukcjami tworzenia raportów o wyświetleniach reklam (zgodnie z raportem wyświetleń pojedynczej platformy SSP na potrzeby raportowania).

Sieć zapośredniczeń

Podobnie jak sieci zewnętrzne, sieci zapośredniczenia potrzebują implementacji selectAds i reportImpression. Więcej informacji znajdziesz w sekcjach dotyczących wybierania reklam i raportowania wyświetleń reklam.

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

Pobieranie łańcucha zapośredniczenia i minimalnych stawek

Sieć zapośredniczenia odpowiada za pobieranie własnych reklam kontekstowych, łańcucha zapośredniczenia i minimalnych stawek z sieci zewnętrznych. Może się to zdarzyć w żądaniu pobrania reklam kontekstowych wykonanych przez sieć zapośredniczenia. Łańcuch zapośredniczenia określa sposób iteracji w sieciach zewnętrznych, a minimalne stawki mogą być przekazywane do procesu aukcji jako adSelectionSignals.

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

Pakiet SDK zapośredniczenia może umieścić się w łańcuchu zapośredniczenia na podstawie rzeczywistego eCPM własnych stawek reklam. W interfejsie Protected Audience API stawki za reklamy są nieprzejrzyste. Pakiet SDK zapośredniczenia powinien używać parametru AdSelectionFromOutcomesConfig, aby móc porównywać stawkę za daną reklamę własnej reklamy ze stawką minimalną następnej sieci zewnętrznej w łańcuchu. Jeśli stawka własna jest wyższa niż minimalna stawka, oznacza to, że pakiet SDK zapośredniczenia jest umieszczony przed daną siecią zewnętrzną.

Uruchom wybór reklamy

Aby pobrać propozycję reklamy własnej, sieć zapośredniczenia może przeprowadzić aukcję na urządzeniu zgodnie z instrukcjami w sekcji Uruchom wybór reklamy. W ten sposób wygenerujemy własną kandydaturę, stawkę i AdSelectionId, które będą używane w procesie zapośredniczenia.

Tworzenie konfiguracji AdSelectionFromResultsConfig

Element AdSelectionFromOutcomesConfig umożliwia sieci zapośredniczeń przekazanie listy AdSelectionIds (wyników z poprzednich aukcji), sygnałów wyboru reklamy oraz identyfikatora URI do pobrania 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 przekroczy dolny limit stawki, lub żaden, jeśli łańcuch zapośredniczenia powinien kontynuować działanie.

Sieci zapośredniczenia tworzą AdSelectionFromOutcomesConfig, korzystając z własnego elementu (AdSelectionId) z poprzedniej sekcji oraz minimalnej stawki dla danej sieci zewnętrznej. Dla każdego kroku łańcucha zapośredniczenia należy utworzyć nowy obiekt AdSelectionFromOutcomesConfig.

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ępowanie metody selectAds() w przypadku zapośredniczenia kaskadowego wymaga podania danych wejściowych AdSelectionFromOutcomesConfig, w których musisz podać te wymagane parametry:

• Sprzedawca: identyfikator sieci reklamowej sprzedawcy, która inicjuje wybór reklamy.
• AdSelectionIds: lista pojedynczych wartości z poprzedniego uruchomienia selectAds() dla reklamy własnej.
• Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały do wykorzystania przez logikę ustalania stawek przez kupującego. W takim przypadku uwzględnij minimalną stawkę pobraną dla danej sieci zewnętrznej.
• Identyfikator URI usługi Selection Logic: adres URL HTTPS wysłany podczas wyboru reklamy w celu pobrania kodu JavaScript sieci zapośredniczenia na potrzeby wyboru zwycięskiej reklamy. Zobacz wymagane podpisy funkcji w tym JavaScripcie. Kod JavaScript powinien zwrócić reklamę firmy zewnętrznej, jeśli stawka jest wyższa niż dolna stawka lub w inny sposób zwróci wartość null. Dzięki temu pakiet SDK zapośredniczenia może skrócić łańcuch zapośredniczenia po znalezieniu zwycięzcy.

Po utworzeniu AdSelectionOutcomesConfig wywołaj metodę selectAds() sieci zewnętrznej, 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

Poniżej przedstawiono kolejność działań, które mają zostać przeprowadzone w ramach procesu zapośredniczenia.

1. Uruchom wybór własnej reklamy.
2. Powtórzenie w łańcuchu zapośredniczenia. W przypadku każdej sieci 3P wykonaj te czynności:
   1. Kompilacja AdSelectionFromOutcomeConfig z własnym elementem outcomeId oraz minimalną stawką z pakietu SDK firmy zewnętrznej.
   2. Wywołaj funkcję selectAds(), używając konfiguracji z poprzedniego kroku.
   3. Jeśli wynik nie jest pusty, zwraca reklamę.
   4. Wywołaj metodę selectAds() obecnego adaptera sieci SDK. Jeśli wynik nie jest pusty, zwracaj reklamę.
3. Jeśli w łańcuchu nie zostanie znalezionego 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) { ... }
}

Zgłaszanie wyświetleń reklam

Istnieją 2 procesy raportowania wyświetlenia reklamy w zależności od sposobu przeprowadzania aukcji. Jeśli prowadzisz jedną aukcję SSP, postępuj zgodnie z instrukcjami podanymi w tej sekcji. Jeśli zamierzasz wdrożyć zapośredniczenie kaskadowe, wykonaj czynności opisane w sekcji raportowania wyświetleń zapośredniczenia kaskadowego.

Raportowanie wyświetleń pojedynczej platformy SSP

Gdy zwycięska reklama zostanie wybrana w ramach procesu wyboru reklamy, możesz za pomocą metody AdSelectionManager.reportImpression() generować raporty o wyświetleniach na uczestniczących w nich platformach po stronie kupujących i sprzedawców. Aby zgłosić wyświetlenie reklamy:

1. Zainicjuj obiekt AdSelectionManager.
2. Utwórz obiekt ReportImpressionRequest z identyfikatorem wyboru reklamy.
3. Wywołaj asynchroniczną metodę reportImpression() z obiektem ReportImpressionRequest oraz odpowiednimi obiektami Executor i 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 tymi wymaganymi parametrami:

• Identyfikator wyboru reklamy: unikalny identyfikator przypisany wyłącznie do użytkownika urządzenia, który pozwala wybrać reklamę.
• Konfiguracja wyboru reklamy: ta sama konfiguracja użyta w wywołaniu selectAds() określona przez podany identyfikator wyboru reklamy.

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

• Wywołanie zwrotne onResult() wskazuje, czy adresy URL do raportowania wyświetleń zostały utworzone, a żądanie zostało zaplanowane.
• Wywołanie zwrotne onError() wskazuje te możliwe warunki:
  • Jeśli wywołanie zostało zainicjowane przy użyciu nieprawidłowego argumentu wejściowego, AdServicesException wskazuje jako przyczynę IllegalArgumentException.
  • W przypadku pozostałych błędów wyświetlany jest AdServicesException z przyczyną IllegalStateException.

Raportowanie wyświetleń zapośredniczenia kaskadowego

Pakiet SDK zapośredniczenia musi śledzić zwycięski pakiet SDK, aby aktywować procesy raportowania. Pakiety SDK, które należą do łańcucha zapośredniczenia, powinny udostępniać metodę wywoływania funkcji mediatorowi, która uruchamia własny proces raportowania. Pakiet SDK uczestniczący w aukcji zapośredniczonej może wykonać powyższe czynności, aby wdrożyć własne raportowanie.

Platformy SSP mogą użyć tego przykładowego kodu zewnętrznego pakietu SDK jako prototypu sposobu łączenia w procesach 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 wyświetleń raportu wysyła żądania HTTPS GET do punktów końcowych dostarczanych przez platformę sprzedawcy i wygrywającą platformę kupującego:

Punkt końcowy platformy po stronie kupującego:

• Interfejs API korzysta z adresu URL logiki ustalania stawek określonego w sekcji niestandardowej listy odbiorców do pobrania udostępnionego przez kupującego kodu JavaScriptu, który zawiera kod JavaScript zwracający adres URL do raportowania wyświetleń.
• Wywołaj funkcję JavaScript reportWin(), która powinna zwracać adres URL raportowania wyświetleń kupującego.

Punkt końcowy platformy po stronie sprzedawcy:

• Użyj adresu URL logiki decyzji określonego w obiekcie AdSelectionConfig, aby pobrać kod JavaScript logiki decyzji sprzedawcy.
• Wywołaj funkcję JavaScript reportResult(), która powinna zwracać adres URL raportowania wyświetleń kupującego.

Raporty dotyczące ustalania stawek i usług aukcyjnych

Aukcja prowadzona w ramach usług określania stawek i aukcji będzie zawierać wszystkie niezbędne informacje raportowania, w tym wygenerowane adresy URL na potrzeby raportowania interakcji z reklamą, w zaszyfrowanej odpowiedzi z aukcji po stronie serwera. Po odszyfrowaniu odpowiedzi odpowiednie adresy URL są rejestrowane na platformie, więc raportowanie reklam i wyświetleń wymaga wykonania tych samych czynności, które opisaliśmy powyżej.

Raporty wyświetleń

Metoda reportImpression() została zaprojektowana z myślą o możliwości pełnego raportowania.

Uwaga:

• Jeśli interfejs API nie może określić adresów URL raportowania wyświetleń za pomocą funkcji JavaScript, zwróci błąd.
• Jeśli wywołanie tych adresów URL nie powiedzie się, bieżąca wersja przedpremierowa dla programistów nie spowoduje żadnych błędów. W przyszłych wersjach planujemy korzystać z logiki ponawiania w przypadku tymczasowych awarii.
• Wielokrotne wywołania funkcji reportImpression() z tymi samymi parametrami mogą spowodować wielokrotne raportowanie wyników wyboru reklamy.

Raportuj interakcje z reklamami

Protected Audience umożliwia raportowanie bardziej szczegółowych interakcji z renderowaną reklamą. Mogą to być interakcje takie jak czas oglądania, kliknięcia, najechanie kursorem i inne przydatne dane, które można gromadzić. Procedura otrzymywania tych raportów składa się z dwóch etapów. Po pierwsze kupujący i sprzedawcy muszą się zarejestrować, aby otrzymywać te raporty w swoim kodzie JavaScript. Następnie klient musi zgłosić te zdarzenia.

Rejestracja w celu otrzymywania zdarzeń interakcji

Rejestrowanie zdarzeń interakcji odbywa się w funkcjach JavaScript kupującego (reportWin()) i w funkcjach reportResult() sprzedawcy przy użyciu funkcji JavaScript udostępnianej przez platformę: registerAdBeacon. Aby zarejestrować się w celu otrzymywania raportu o zdarzeniach, wystarczy wywołać funkcję JavaScript platformy z poziomu kodu JavaScript raportowania. Ten fragment kodu korzysta z elementu reportWin() kupującego, ale to samo podejście dotyczy 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: aby otrzymywać raporty, ciągi kluczy interakcji muszą odpowiadać danym sprzedawcy.

Raportowanie zdarzeń interakcji

Po zgłoszeniu wyświetlenia klienci mogą raportować interakcje na wcześniej zarejestrowanych zwycięskich platformach po stronie kupujących i sprzedawców za pomocą metody AdSelectionManager.reportInteraction(). Aby zgłosić zdarzenie reklamowe:

1. Zainicjuj obiekt AdSelectionManager.
2. Utwórz obiekt ReportInteractionRequest z identyfikatorem wyboru reklamy, kluczem interakcji, danymi dotyczącymi interakcji i miejscem docelowym raportowania.
3. Wywołaj asynchroniczną metodę reportInteraction() z obiektem request i 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);

Zainicjuj ReportInteractionRequest tymi wymaganymi parametrami:

• Ad Selection ID (Identyfikator wyboru reklamy): identyfikator wyboru reklamy pobrany z zwróconego wcześniej AdSelectionOutcome.
• Klucz interakcji: zdefiniowany przez klienta klucz tekstowy opisujący zgłaszane działanie. Musi on być zgodny z kluczem zarejestrowanym przez sprzedawcę lub kupującego w funkcjach JavaScript służących do raportowania.
• Dane interakcji: ciąg znaków zawierający dane, które zostaną dołączone do raportu o zdarzeniach i wysłane z powrotem na serwery raportowania.
• Miejsca docelowe raportowania: maska określająca, czy zdarzenia powinny być raportowane do kupującego, sprzedawcy czy do obu tych elementów. Te flagi są dostarczane przez platformę, a końcową maskę docelową można utworzyć za pomocą operacji bitowych. Aby zgłosić problem do jednego miejsca docelowego, możesz użyć flagi dostarczonej bezpośrednio przez platformę. Aby tworzyć raporty dla wielu miejsc docelowych, możesz użyć operatora bitowego LUB (|) do połączenia wartości flag.

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

• Wywołanie zwrotne onResult() wskazuje, że wywołanie interakcji z raportem jest prawidłowe.
• Wywołanie zwrotne onError() wskazuje te możliwe warunki:
  • Jeśli wywołanie jest wykonywane, gdy aplikacja działa w tle, zwracany jest błąd IllegalStateException z opisem błędu.
  • Jeśli klient ma ograniczone możliwości wywoływania funkcji reportInteraction(), zwracany jest kod LimitExceededException.
  • Jeśli pakiet nie jest zarejestrowany do wywoływania interfejsów API zachowywania prywatności, zwracany jest błąd SecurityException().
  • Jeśli interakcje z raportowaniem w aplikacji różnią się od aplikacji, która wywołuje selectAds(), zwracana jest wartość IllegalStateException.
• Jeśli użytkownik nie wyrazi zgody na włączenie interfejsów API Piaskownicy prywatności, wywołanie nie powiedzie się po cichu.

Uwaga: brak błędów nie oznacza, że raportowanie miało miejsce. Daje to jednak gwarancję, że w pewnym momencie w ramach Protected Audience API będziemy próbowali zgłosić interakcje.

Punkty końcowe raportowania interakcji

Interfejs API interakcji w raportach wysyła żądania HTTPS POST do punktów końcowych dostarczonych przez platformę sprzedawcy i wygrywającą platformę kupującego. Protected Audience dopasowuje klucze interakcji do identyfikatorów URI zadeklarowanych w przypadku raportowania JavaScriptu i w przypadku każdej zgłaszanej interakcji wysyła do każdego punktu końcowego żądanie POST. Typ treści żądania to zwykły tekst, a treścią są dane interakcji.

Raporty interakcji

Interfejs reportInteraction() został zaprojektowany z myślą o jak najwygodniejszym wypełnianiu raportów za pomocą metody HTTP POST.

Codzienna aktualizacja w tle

Podczas tworzenia niestandardowej listy odbiorców aplikacja lub pakiet SDK może zainicjować niestandardowe metadane odbiorców. Dodatkowo platforma może w ramach codziennego procesu aktualizacji w tle aktualizować podane niżej niestandardowe metadane odbiorców.

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

Spowoduje to przetwarzanie zapytań wysyłanych do adresu URL aktualizacji dziennej zdefiniowanej w niestandardowych grupach odbiorców, a adres URL może zwrócić odpowiedź JSON.

• Odpowiedź JSON może zawierać dowolne obsługiwane pola metadanych, które trzeba zaktualizować.
• Każde pole JSON jest sprawdzane niezależnie. Klient ignoruje wszystkie nieprawidłowe pola, które nie powodują żadnych aktualizacji tego konkretnego pola w odpowiedzi.
• Pusta odpowiedź HTTP lub pusty obiekt JSON „{}” nie powodują aktualizacji metadanych.
• Rozmiar wiadomości z odpowiedzią musi być ograniczony do 10 KB.
• Do korzystania z HTTPS wymagane są wszystkie identyfikatory URI.
• trusted_bidding_uri musi mieć ten sam identyfikator ETLD + 1 co kupujący.

Przykład: odpowiedź JSON dotycząca codziennej aktualizacji 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
        },
        ...
    ]
}

JavaScript do wyboru reklamy

Proces wyboru reklamy administruje wykonywaniem kodu JavaScript dostarczonego przez kupującego i sprzedawcy.

Kod JavaScript dostarczony przez kupującego jest pobierany z adresu URL logiki ustalania stawek określonego w sekcji niestandardowej na liście odbiorców. Zwracany kod JavaScript powinien zawierać następujące funkcje:

• generateBid()
• reportWin()

Kod JavaScript udostępniony przez sprzedawcę jest pobierany z adresu URL opartego na logice decyzji określonego w parametrze AdSelectionConfig interfejsu API wyboru reklamy. Zwracany JavaScript powinien zawierać te funkcje:

• scoreAd()
• reportResult()

wygenerujesz_stawkę()

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 obiekcie konfiguracji aukcji

• 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ąg znaków pochodzący z właściwości o tej samej nazwie grupy niestandardowych odbiorców, która uczestniczy w wyborze reklamy.
  • activation_time i expiration_time to czas aktywacji i wygaśnięcia niestandardowej listy odbiorców wyrażony w sekundach od epoki uniksowej.
  • ca_user_bidding_signals to ciąg znaków JSON określony w polu userBiddingSignals w CustomAudience podczas tworzenia
  • trusted_bidding_signals, contextual_signals i user_signals to obiekty JSON. Są one przekazywane jako puste obiekty i zostaną wypełnione w kolejnych wersjach. Ich format nie jest egzekwowany przez platformę i jest zarządzany przez technologię reklamową.

Efekt:

• ad: to reklama, której dotyczy stawka. Skrypt może zwrócić kopię otrzymanej reklamy z innymi metadanymi. Właściwość render_url reklamy powinna pozostać niezmieniona.
• bid: liczba zmiennoprzecinkowa odpowiadająca wartości stawki za tę reklamę.
• status: liczba całkowita, którą może być:
  • 0: skuteczne wykonanie
  • 1: (lub dowolna wartość inna niż 0), jeśli którykolwiek z sygnałów wejściowych jest nieprawidłowy. Jeśli w procesie ustalania stawek zostanie zwrócona wartość inna niż 0, proces ustalania stawek zostanie unieważniony w przypadku wszystkich reklam z Kanady.

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: patrz dokumentację generateBid
• bid: wartość stawki za reklamę.

• ad_selection_config: obiekt JSON reprezentujący parametr AdSelectionConfig interfejsu selectAds API. 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 odczytywane z parametru interfejsu API sellerSignals AdSelectionConfig

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

• contextual_signals, user_signals: obiekty JSON. Obecnie są one przekazywane jako puste obiekty i będą wypełniane w kolejnych wersjach. Ich format nie jest egzekwowany przez platformę i jest zarządzany przez technologię reklamową.

• per_buyer_signals: obiekt JSON odczytywany z mapy perBuyerSignal w parametrze interfejsu API AdSelectionConfig przy użyciu klucza bieżącego kupującego na liście odbiorców niestandardowych. Pusta, jeśli mapa nie zawiera żadnych wpisów dotyczących danego kupującego.

Dane wyjściowe:

• score: wartość zmiennoprzecinkowa reprezentująca wynik danej reklamy.
• status: liczba całkowita, którą może być:
  • 0: skuteczne wykonanie
  • 1: jeśli pola customAudienceSignals są nieprawidłowe
  • 2: jeśli AdSelectionConfig jest nieprawidłowy
  • 3: na wypadek, gdyby którykolwiek z pozostałych sygnałów jest nieprawidłowy
  • Każda wartość różna od zera powoduje błąd procesu – ta wartość określa rodzaj 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 obiekcie konfiguracji aukcji

Dane wyjściowe:

• status: 0 oznacza sukces, wartość inna niż 0 oznacza niepowodzenie
• result: jeden z wyników przekazanych lub 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: URL renderowania zwycięskiej reklamy;
• bid: stawka zaoferowana dla zwycięskiej reklamy.
• contextual_signals: wyświetl dokumentację generateBid

Dane wyjściowe:

• status: 0 oznacza sukces, inne niż 0 w przypadku niepowodzenia
• results: obiekty JSON zawierające:
  • signals_for_buyer: obiekt JSON przekazywany do funkcji reportWin.
  • reporting_url: adres URL używany przez platformę do wysyłania powiadomień o wyświetleniu dla kupującego.

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: wyświetl dokumentację scoreAd
• signals_for_buyer: obiekt JSON zwrócony przez reportResult
• contextual_signals, custom_audience_signals: wyświetl dokumentację generateBid

Dane wyjściowe:

• status: 0 oznacza sukces, inne niż 0 w przypadku niepowodzenia
• results: obiekt JSON zawierający:
  • reporting_url: adres URL używany przez platformę do powiadamiania sprzedawcy o wyświetleniach.

registerAdBeacon()

Uwaga: ta funkcja jest dostarczana przez platformę Androida i nie powinna być wdrażana przez technologie reklamowe.

function registerAdBeacon(
  interaction_key,
  reporting_uri
)

Parametry wejściowe:

• interaction_key: ciąg znaków reprezentujący zdarzenie. Będzie ona później używana przez platformę podczas raportowania interakcji ze zdarzeniami, aby wyszukać element reporting_uri, który ma zostać powiadomiony. Klucz ten musi odpowiadać temu, co rejestruje kupujący lub sprzedawca, a danymi przez sprzedawcę.
• reporting_uri: identyfikator URI służący do otrzymywania raportów o zdarzeniach. To ustawienie powinno być związane z typem zgłaszanego zdarzenia. Musi zaakceptować żądanie POST, aby obsługiwać wszelkie dane zgłoszone w związku ze zdarzeniem.

Gotowe identyfikatory URI dotyczące wyboru reklamy

Gotowe identyfikatory URI dają technikom reklamowym możliwość wyznaczenia funkcji JavaScript na potrzeby logiki decyzji o wyborze reklamy w klasach AdSelectionConfig i AdSelectionFromOutcomesConfig. Gotowe identyfikatory URI nie wymagają wywołań sieciowych w celu pobrania odpowiedniego kodu JavaScript. Technologie reklamowe mogą używać gotowych identyfikatorów URI bez konieczności konfigurowania zarejestrowanej domeny do hostowania kodu JavaScript.

Gotowy identyfikator URI powstaje w tym formacie:

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

Platforma Piaskownicy prywatności udostępnia kod JavaScript w czasie działania, korzystając z informacji z tego identyfikatora URI.

Obiekt IllegalArgumentException jest zwracany, jeśli:

• Identyfikator URI nie zawiera dowolnego z wymaganych parametrów
• identyfikator URI zawiera nierozpoznane parametry

Obsługiwane gotowe zastosowania i nazwy identyfikatorów URI

Przypadek użycia 1: wybór reklamy

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

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

Ten gotowy identyfikator URI zawiera kod JavaScript, który po określeniu stawki wybiera reklamę z najwyższą stawką. Zapewnia też podstawową funkcję raportowania, która pozwala zgłosić render_uri i bid zwycięzcy.

Parametry wymagane

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

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

Wykorzystanie

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

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

Przypadek użycia 2: wybór reklamy z wyników

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

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

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

Parametry wymagane

bidFloor: klucz do wartości minimalnej stawki przekazywanej w elemencie getSelectionSignals(), która jest porównywana z reklamą z pakietu SDK zapośredniczenia.

Wykorzystanie

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

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

Testowanie

Aby pomóc Ci zacząć korzystać z interfejsu Protected Audience API, utworzyliśmy przykładowe aplikacje w języku Kotlin i Javie, które znajdziesz na GitHub.

Wymagania wstępne

Protected Audience API wymaga obsługi JavaScriptu podczas wyboru reklamy i raportowania wyświetleń. Kod JavaScriptu w środowisku testowym można udostępniać na 2 sposoby:

• Uruchomić serwer z wymaganymi punktami końcowymi HTTPS, które zwracają kod JavaScript.
• Zastąp pobieranie zdalne, podając niezbędny kod ze źródła lokalnego

Oba sposoby wymagają skonfigurowania punktu końcowego HTTPS do obsługi raportów o wyświetleniach.

Punkty końcowe HTTPS

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

1. Punkt końcowy kupującego, który obsługuje kod JavaScript określania stawek.
2. Punkt końcowy, który obsługuje sygnały związane z ustalaniem stawek.
3. Punkt końcowy sprzedawcy, który obsługuje kod JavaScript logiczny decyzji.
4. Punkt końcowy, który obsługuje sygnały punktowe.
5. Punkt końcowy raportowania wyświetleń zwycięskiego kupującego.
6. Punkt końcowy raportowania wyświetleń przez sprzedawcę.
7. Punkt końcowy do wysyłania codziennych aktualizacji w przypadku niestandardowej listy odbiorców.

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

Zastępowanie zdalnego pobierania kodu JavaScript

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

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

<application
  android:debuggable="true">

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

Przykład wykorzystania tych zastąpień znajdziesz w przykładowej aplikacji interfejsu Protected Audience API na GitHubie.

Aby obsługiwać procedury wyboru reklamy, takie jak ustalanie stawek, podejmowanie decyzji dotyczących punktacji i raportowanie, musisz dodać własny niestandardowy kod JavaScript. Podstawowe przykłady kodu JavaScript, które obsługują 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.

Możesz niezależnie zastępować pobieranie JavaScript po stronie sprzedawcy i po stronie kupującego, ale potrzebujesz punktu końcowego HTTPS do obsługi kodu JavaScript, w przypadku którego nie udostępniasz zastąpień. Informacje o konfigurowaniu serwera do obsługi takich przypadków znajdziesz w README.

Pobieranie za pomocą JavaScriptu można zastąpić tylko w przypadku niestandardowych list odbiorców, które należą do Twojego pakietu.

Zastąp kod JavaScript dostępny dla sprzedawców

Aby skonfigurować zastąpienie kodu JavaScript przeznaczonego do sprzedaży, wykonaj te czynności w sposób pokazany poniżej:

1. Zainicjuj obiekt AdSelectionManager.
2. Uzyskaj odniesienie do obiektu TestAdSelectionManager z obiektu AdSelectionManager.
3. Utwórz obiekt AdSelectionConfig.
4. Utwórz AddAdSelectionOverrideRequest z obiektem AdSelectionConfig oraz String reprezentującą 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.

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

Więcej informacji o tym, co reprezentują poszczególne pola w AdSelectionConfig, znajdziesz w sekcji Uruchom wybór reklamy. Główna różnica polega na tym, że parametr decisionLogicUrl może zostać ustawiony na wartość zmiennej, ponieważ będzie ona ignorowana.

Aby zastąpić JavaScript używany podczas wyboru reklamy, decisionLogicJs musi zawierać odpowiednie podpisy funkcji po stronie sprzedawcy. Informacje o tym, jak odczytać plik JavaScript pod postacią ciągu znaków, znajdziesz w przykładowej aplikacji Protected Audience API w GitHubie.

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

Wywołanie zwrotne onResult() oznacza, że zastąpienie zostało zastosowane. Przyszłe wywołania funkcji selectAds() będą używać dowolnej decyzji i logiki raportowania przekazanej jako zastąpienie.

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

• Jeśli zostanie podjęta próba zastąpienia przy użyciu nieprawidłowych argumentów, AdServiceException wskazuje jako przyczynę IllegalArgumentException.
• Jeśli zostanie podjęta próba zastąpienia przy aplikacji, która nie jest uruchomiona w trybie debugowania z włączonymi opcjami programisty, AdServiceException wskazuje IllegalStateException jako przyczynę.

Zresetuj zastąpienia po stronie sprzedawcy

W tej sekcji zakładamy, że zastąpisz kod JavaScript sprzedawcy i że stosujesz odwołanie do metod TestAdSelectionManager i AdSelectionConfig użytych w poprzedniej sekcji.

Aby zresetować zastąpienia dla wszystkich AdSelectionConfigs:

1. Wywołaj asynchroniczną metodę resetAllAdSelectionConfigRemoteOverrides() za pomocą odpowiedniego obiektu 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 wywołania selectAds() używają dowolnego parametru decisionLogicUrl zapisanego w pliku AdSelectionConfig, aby pobrać wymagany kod JavaScript.

Jeśli wywołanie resetAllAdSelectionConfigRemoteOverrides() nie powiedzie się, wywołanie zwrotne OutComeReceiver.onError() zwróci metodę AdServiceException. Jeśli spróbujesz usunąć zastąpienia, gdy aplikacja nie jest uruchomiona w trybie debugowania z włączonymi opcjami programisty, AdServiceException wskazuje jako przyczynę IllegalStateException.

Zastąp kod JavaScript po stronie kupującego

1. Aby dołączyć do grupy odbiorców niestandardowych:
2. Utwórz element AddCustomAudienceOverrideRequest z kupującym i nazwą niestandardowej listy odbiorców, której ustawienia chcesz zastąpić, oraz 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.

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 parametrów kupujący i name są takie same jak podczas tworzenia listy niestandardowych odbiorców. Więcej informacji o tych polach

Można też określić 2 dodatkowe parametry:

• biddingLogicJs: kod JavaScript, który przechowuje logikę kupującego i używany podczas wyboru reklamy. Zobacz wymagane podpisy funkcji w tym JavaScript.
• trustedBiddingSignals: sygnały dotyczące ustalania 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(), używa obiektu OutcomeReceiver do sygnalizowania wyniku 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óra została podana jako zastąpienie.

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

• Jeśli zostanie podjęta próba zastąpienia przy użyciu nieprawidłowych argumentów, AdServiceException wskazuje jako przyczynę IllegalArgumentException.
• Jeśli zostanie podjęta próba zastąpienia przy aplikacji, która nie jest uruchomiona w trybie debugowania z włączonymi opcjami programisty, AdServiceException wskazuje IllegalStateException jako przyczynę.

Zresetuj zastąpienia po stronie kupującego

W tej sekcji zakładamy, że JavaScript po stronie zakupu został zastąpiony i że odwołujesz się do TestCustomAudienceManager użytego w poprzedniej sekcji.

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

1. Wywołaj asynchroniczną metodę resetAllCustomAudienceOverrides() z odpowiednimi obiektami 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 kupującego kolejne wywołania selectAds() wykorzystują biddingLogicUrl i trustedBiddingData przechowywane w CustomAudience, aby pobrać wymagany kod JavaScript.

Jeśli wywołanie resetCustomAudienceRemoteInfoOverride() nie powiedzie się, wywołanie zwrotne OutComeReceiver.onError() zwróci metodę AdServiceException. Jeśli spróbujesz usunąć zastąpienia, gdy aplikacja nie jest uruchomiona w trybie debugowania z włączonymi opcjami programisty, AdServiceException wskazuje jako przyczynę IllegalStateException.

Skonfiguruj serwer raportowania

Gdy używasz zastąpień pobierania zdalnego, nadal musisz skonfigurować serwer, z którym urządzenie lub emulator będzie mogło odpowiadać na zdarzenia raportowania. Do testowania wystarczy prosty punkt końcowy, który zwraca wartość 200. Repozytorium GitHub zawiera definicje usług OpenAPI, które można wdrożyć na obsługiwanej platformie testowej lub na obsługiwanej platformie mikroserwisów. Więcej informacji znajdziesz w pliku README projektu.

Szukając definicji OpenAPI, szukaj pliku Reporting-server.json. Ten plik zawiera prosty punkt końcowy, który zwraca kod 200, reprezentujący kod odpowiedzi HTTP. Ten punkt końcowy jest używany w czasie selectAds() i informuje interfejs Protected Audience API, że raportowanie wyświetleń zakończyło się powodzeniem.

Testowane funkcje

• Ćwiczenie polegające na dołączaniu lub opuszczaniu i konfigurowaniu niestandardowych grup odbiorców na podstawie wcześniejszych działań użytkownika.
• Rozpocznij proces wyboru reklam na urządzeniu za pomocą hostowanych zdalnie skryptów JavaScript.
• Obserwuj, jak powiązanie aplikacji z niestandardowymi ustawieniami odbiorców może wpływać na wybór reklamy.
• Ćwiczenie raportowania wyświetleń po wybraniu reklamy.

Ograniczenia

W tabeli poniżej znajdziesz informacje o ograniczeniach dotyczących przetwarzania przez interfejs Protected Audience API. Pokazane limity mogą ulec zmianie w zależności od otrzymanych opinii. Informacje o funkcjach w toku znajdziesz w informacjach o wersji.

Komponent	Opis limitu	Wartość limitu
Niestandardowi odbiorcy (Kanada)	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 czasu 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 dziennego	400 bajtów
	Maksymalny rozmiar identyfikatora URI logiki ustalania stawek	400 bajtów
	Maksymalny rozmiar danych dotyczących zaufanego określania stawek	10 KB
	Maksymalny rozmiar sygnałów dotyczących określania stawek przez użytkowników	10 KB
	Maksymalna stawka za połączenie leaveCustomAudience na kupującego	1 na sekundę
	Maksymalna stawka za połączenie joinCustomAudience na kupującego	1 na sekundę
Pobieranie danych w tle z CA	Przekroczenie limitu czasu oczekiwania na połączenie	5 sekund
	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 została zaktualizowana 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
	Upłynął limit czasu na nawiązanie połączenia	5 sekund
	Upłynął limit czasu odczytu połączenia	5 sekund
	Maksymalny czas wykonywania ogólnego AdSelection	10 sekund,
	Maksymalny czas wykonywania określania stawek na urząd certyfikacji w: AdSelection	5 sekund
	Maksymalny czas wykonywania oceny w AdSelection	5 sekund
	Maksymalny czas wykonania na kupującego (AdSelection)	Do ustalenia
	Maksymalny rozmiar sygnałów dotyczących wyboru reklamy/sprzedawcy/kupującego	Do ustalenia
	Maksymalny rozmiar skryptów sprzedawcy/kupującego	Do ustalenia
	Maksymalna szybkość połączeń w okresie selectAds	1 zapytanie na sekundę
Raporty wyświetleń	Minimalny czas potrzebny do usunięcia wyboru reklamy z trwałości	24 godziny
	Maksymalna liczba wybranych reklam służących do przechowywania danych	Do ustalenia
	Maksymalny rozmiar wyjściowego adresu URL raportowania	Do ustalenia
	Maksymalny czas na raportowanie wyświetleń	Do ustalenia
	Maksymalna liczba ponownych prób wywołań powiadomień	Do ustalenia
	Limit czasu połączenia	5 sekund
	Maksymalny ogólny czas wykonywania kodu reportImpression	2 sekundy
	Maksymalna szybkość połączeń w okresie reportImpressions	1 zapytanie na sekundę
Raporty o zdarzeniach	Maksymalna liczba obrazów typu beacon na kupującego na aukcję	10
	Maksymalna liczba obrazów typu beacon na sprzedawcę na aukcję	10
	Maksymalny rozmiar klucza zdarzenia	40 bajtów
	Maksymalny rozmiar danych zdarzenia	64KB
Reklamy	Maksymalny rozmiar listy reklam	10 KB współużytkowane przez wszystkie AdData w jednym urzędzie certyfikacji na potrzeby kontekstu
Adresy URL	Maksymalna długość dowolnego ciągu adresu URL liczonego jako dane wejściowe	Do ustalenia
JavaScript	Maksymalny czas wykonywania	1 sekunda na potrzeby określania stawek i oceniania na potrzeby raportowania wyświetleń
	Maksymalne wykorzystanie pamięci	10 MB

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

Twoja opinia jest kluczowym elementem Piaskownicy prywatności na Androida. Jeśli zauważysz jakieś problemy lub pomysły na ulepszenie Piaskownicy prywatności na Androidzie, daj nam znać.