Przewodnik dla deweloperów dotyczący Protected Audience API

Podczas czytania dokumentacji Piaskownicy prywatności na Androida używaj przycisku Wersja przedpremierowa dla programistów lub Beta, aby wybrać wersję programu, z której korzystasz, ponieważ instrukcje mogą się różnić.

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

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

Interfejs Ad Selection API udostępnia platformę, która umożliwia wielu deweloperom przeprowadzanie lokalnej aukcji na potrzeby odbiorców niestandardowych. W tym celu system bierze pod uwagę odpowiednie reklamy powiązane z odbiorcami niestandardowymi i przeprowadza dodatkowe przetwarzanie reklam, które platforma technologii reklamowej zwraca na urządzenie.

Platformy technologii reklamowych mogą zintegrować te interfejsy API, aby wdrożyć remarketing, który chroni prywatność użytkowników. W przyszłych wersjach planujemy dodać obsługę kolejnych przypadków użycia, w tym reklam promujących instalację aplikacji. Więcej informacji o interfejsie Protected Audience API na Androidzie znajdziesz w projekcie.

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

1. Zarządzanie niestandardowymi grupami odbiorców
2. Konfigurowanie i przeprowadzanie wyboru reklam na urządzeniu
3. Raportowanie wyświetleń reklam

Zanim zaczniesz

Zanim zaczniesz, wykonaj te czynności:

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

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

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

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

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

5. Dodaj uprawnienia ACCESS_ADSERVICES_CUSTOM_AUDIENCE do pliku manifestu aplikacji:

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

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

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

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

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

8. Domyślnie interfejs Ad Selection API wymusza limity maksymalnej ilości pamięci, jaką może przydzielić skrypt aukcji lub raportowania 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 ten warunek nie zostanie spełniony. Możesz to zrobić na 2 sposoby:

   • Opcja 1. Aby dezaktywować to sprawdzanie, uruchom to polecenie adb:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

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

Dołączanie do grupy odbiorców niestandardowych

Lista odbiorców niestandardowych to grupa użytkowników o podobnych zamiarach lub zainteresowaniach, określonych przez aplikację reklamodawcy. Aplikacja lub pakiet SDK może używać listy odbiorców niestandardowych do wskazywania konkretnych odbiorców, np. osób, które zostawiły produkty w koszyku. Aby utworzyć niestandardową listę odbiorców lub dołączyć do niej asynchronicznie, wykonaj te czynności:

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

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

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

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

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

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

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

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

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

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

• owner: nazwa pakietu aplikacji będącej właścicielem. Jest ona niejawnie ustawiona na nazwę pakietu aplikacji wywołującej.
• buyer: Identyfikator sieci reklamowej kupującego, która zarządza reklamami kierowanymi na tę niestandardową listę odbiorców.
• name: dowolna nazwa lub identyfikator listy odbiorców niestandardowych.

Wielokrotne wywoływanie funkcji joinCustomAudience() z różnymi instancjami CustomAudience aktualizuje wszystkie istniejące obiekty CustomAudience o pasujących parametrach owner, buyer i name. Aby chronić prywatność, wynik interfejsu API nie rozróżnia „utworzenia” i „aktualizacji”.

Dodatkowo CustomAudience musi być utworzony z tymi wymaganymi parametrami:

• URL codziennej aktualizacji: adres URL HTTPS odpytywany codziennie w tle w celu aktualizowania sygnałów licytowania użytkowników, zaufanych danych o licytowaniu oraz adresów URL renderowania i metadanych reklam na potrzeby niestandardowej listy odbiorców.
• Adres URL logiki określania stawek: adres URL HTTPS, do którego wysyłane jest zapytanie podczas wybierania reklamy w celu pobrania logiki określania stawek w JavaScript kupującego. Wymagane sygnatury funkcji znajdziesz w tym kodzie JavaScript.
• Identyfikatory renderowania reklamy: dowolny identyfikator ustawiony przez technologię reklamową kupującego. Jest to optymalizacja generowania ładunku na potrzeby B&A.

Opcjonalne parametry obiektu CustomAudience mogą obejmować:

• Czas aktywacji: lista odbiorców niestandardowych może uczestniczyć w wybieraniu reklam i codziennych aktualizacjach dopiero po upływie czasu aktywacji. Może to być przydatne np. do ponownego zaangażowania użytkowników, którzy przestali korzystać z aplikacji.
• Czas wygaśnięcia: przyszły czas, po którym lista niestandardowych odbiorców zostanie usunięta z urządzenia.
• Sygnały określania stawek użytkownika: ciąg JSON zawierający sygnały użytkownika, takie jak preferowane ustawienia regionalne użytkownika, które są wykorzystywane przez kod JavaScript logiki określania stawek kupującego do generowania stawek podczas procesu wyboru reklamy. Ten format pomaga platformom technologii reklamowej ponownie wykorzystywać kod na różnych platformach i ułatwia korzystanie z funkcji JavaScriptu.
• Zaufane dane określania stawek: adres URL HTTPS i lista ciągów znaków używane podczas procesu wyboru reklam, które pobierają sygnały określania stawek z zaufanej usługi klucz/wartość.
• Ads: lista obiektów AdData odpowiadających reklamom, które biorą udział w wybieraniu reklam. Każdy obiekt AdData składa się z tych elementów:
  • Adres URL renderowania: adres URL HTTPS, do którego wysyłane jest zapytanie w celu renderowania ostatecznej reklamy.
  • Metadane: obiekt JSON zserializowany jako ciąg znaków zawierający informacje, które będą wykorzystywane przez logikę określania stawek kupującego podczas procesu wyboru reklamy.
  • Filtry reklam: klasa zawierająca wszystkie niezbędne informacje do filtrowania reklam zachęcających do instalacji aplikacji i ograniczania częstotliwości wyświetlania podczas wyboru reklam.

Oto przykład utworzenia instancji obiektu CustomAudience:

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

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

Obsługa wyników wywołania funkcji joinCustomAudience()

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

• Wywołanie zwrotne onResult() oznacza, że lista odbiorców niestandardowych została utworzona lub zaktualizowana.
• Wywołanie zwrotne onError() oznacza 2 możliwe warunki.
  • Jeśli JoinCustomAudienceRequest zostanie zainicjowany z nieprawidłowymi argumentami, AdServicesException wskaże IllegalArgumentException jako przyczynę.
  • W przypadku wszystkich innych błędów wyświetla się kod AdServicesException z przyczyną IllegalStateException.

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

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

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

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

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

Opuszczanie grupy odbiorców niestandardowych

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

1. Zainicjuj obiekt CustomAudienceManager.
2. Zainicjuj LeaveCustomAudienceRequest za pomocą buyer i name niestandardowych odbiorców. Więcej informacji o tych polach do wprowadzania danych znajdziesz w artykule „Dołączanie do odbiorców niestandardowych”.
3. Wywołaj asynchroniczną metodę leaveCustomAudience() z obiektem LeaveCustomAudienceRequest oraz odpowiednimi obiektami Executor i OutcomeReceiver.

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

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

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

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

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

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

Podobnie jak w przypadku wywołania joinCustomAudience(), znak OutcomeReceiver oznacza koniec wywołania interfejsu API. Aby chronić prywatność, wynik błędu nie rozróżnia błędów wewnętrznych od nieprawidłowych argumentów. onResult()Wywołanie zwrotne jest wywoływane po zakończeniu wywołania interfejsu API, niezależnie od tego, czy pasująca lista odbiorców niestandardowych 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.

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

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

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

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

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

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

Metoda selectAds() wymaga danych wejściowych AdSelectionConfig, w których musisz podać te wymagane parametry:

• Sprzedawca: identyfikator sieci reklamowej sprzedawcy, która inicjuje wybór reklamy.
• Adres URL logiki decyzyjnej: adres URL HTTPS, do którego wysyłane jest zapytanie w celu uzyskania logiki JavaScript sieci reklamowej sprzedawcy.
  • Adres URL HTTPS: wysyłane jest zapytanie w celu uzyskania logiki JavaScriptu sieci reklamowej sprzedawcy. Sprawdź wymagane sygnatury funkcji.
  • Wstępnie utworzony identyfikator URI: zgodny z formatem wyboru reklam FLEDGE. IllegalArgumentException jest zgłaszany, jeśli przekazany zostanie nieobsługiwany lub nieprawidłowo sformatowany wstępnie utworzony identyfikator URI.
• Kupujący odbiorców niestandardowych: pełna lista identyfikatorów sieci reklamowych kupujących, które sprzedawca dopuszcza do udziału w procesie wyboru reklamy. Te identyfikatory kupującego odpowiadają CustomAudience.getBuyer() uczestniczących niestandardowych grup odbiorców.

Aby bardziej dostosować wybieranie reklam, możesz opcjonalnie określić te parametry:

• Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały, które mają być wykorzystywane przez logikę określania stawek kupującego w JavaScript pobranym z CustomAudience.getBiddingLogicUrl().
• Sygnały sprzedawcy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały wykorzystywane przez pobraną logikę decyzyjną JavaScript sprzedawcy z AdSelectionConfig.getDecisionLogicUrl().
• Sygnały dotyczące poszczególnych kupujących: mapa obiektów JSON zserializowanych jako ciągi tekstowe, zawierająca sygnały, które mają być wykorzystywane przez logikę określania stawek w JavaScript poszczególnych kupujących pobraną z CustomAudience.getBiddingLogicUrl(), zidentyfikowaną przez pola kupującego w uczestniczących niestandardowych listach odbiorców.
• Reklamy kontekstowe: zbiór kandydatów do wyświetlenia reklam, którzy są zbierani bezpośrednio od kupujących podczas aukcji odbywającej się poza aukcją Protected Audience.

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

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

Jeśli wybór reklamy nie może zostać ukończony z powodów takich jak nieprawidłowe argumenty, przekroczenie limitu czasu lub nadmierne zużycie zasobów, wywołanie zwrotne OutcomeReceiver.onError() zapewnia AdServicesException z następującymi zachowaniami:

• Jeśli wybór reklamy zostanie zainicjowany z nieprawidłowymi argumentami, wartość AdServicesException będzie wskazywać IllegalArgumentException jako przyczynę.
• W przypadku wszystkich innych błędów wyświetla się kod AdServicesException z przyczyną IllegalStateException.

Reklamy kontekstowe

Protected Audience API może uwzględniać reklamy kontekstowe w aukcji chronionej. Reklamy kontekstowe muszą być wybierane na serwerze technologii reklamowych i zwracane do urządzenia poza interfejsami Protected Audience API. Reklamy kontekstowe można następnie uwzględnić w aukcji za pomocą parametru AdSelectionConfig, w którym to momencie działają one tak samo jak reklamy na urządzeniu, w tym kwalifikują się do filtrowania reklam wykluczających. Po zakończeniu aukcji Protected Audience API musisz wywołać funkcję reportImpression(). Wywołuje to funkcję reportWin() w wygrywającej reklamie kontekstowej, w taki sam sposób jak raportowanie wyświetleń, aby wyświetlić wygrywającą reklamę na urządzeniu. Każda reklama kontekstowa wymaga kupującego, stawki, linku do logiki raportowania, adresu URL renderowania i metadanych reklamy.

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

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

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

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

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

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

Filtrowanie reklam promujących instalacje aplikacji

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

Pierwszym krokiem w tym procesie jest określenie, którzy reklamodawcy mogą filtrować zainstalowany pakiet. Musisz to zrobić w aplikacji, na którą chcesz kierować reklamę.

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

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

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

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

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

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

Gdy powyższy kod zostanie wykonany, reklamodawcy będą mogli odfiltrować zainstalowane aplikacje, które określisz podczas generowania przez nich stawek. Jeśli chcesz odebrać reklamodawcy dostęp do stanu instalacji tej aplikacji, ponownie uruchom ten kod, usuwając informacje o reklamodawcy.

Następnym krokiem jest skonfigurowanie filtrowania reklam w aplikacji wydawcy. Podmiot, który wyświetla reklamę w aplikacji wydawcy (najprawdopodobniej pakiet SDK platformy SSP), musi zainicjować swój obiekt AdFilters, podając informacje o tym, które reklamy związane z aplikacjami mają być odfiltrowane:

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

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

Wydawcy korzystający z platformy DSP mogą też ustawić AdFilter w przypadku reklam wyświetlanych w ramach ich odbiorców niestandardowych.

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

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

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

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

Filtrowanie według limitu wyświetleń umożliwia platformom reklamowym ograniczenie liczby wyświetleń reklamy. Filtrowanie według ograniczenia liczby wyświetleń zmniejsza nadmierną ekspozycję reklam i optymalizuje wybór alternatywnych reklam w danej kampanii reklamowej.

Filtr limitu wyświetleń składa się z 2 głównych komponentów: typu zdarzenia reklamy i klucza licznika reklam. Dostępne typy zdarzeń reklamowych, których można używać:

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

W aplikacji wydawcy platforma SSP lub MMP, która jest obecna na urządzeniu, wywołuje zdarzenia reklamowe. Gdy wywoływana jest funkcja updateAdCounterHistogram(), licznik filtra ograniczenia liczby wyświetleń jest zwiększany, aby przyszłe aukcje miały aktualne informacje o wyświetleniach danej reklamy przez użytkownika. Typy zdarzeń związanych z reklamami nie są powiązane z odpowiednimi działaniami użytkowników i stanowią wytyczne, które pomagają wywołującym w strukturyzacji systemu zdarzeń. Aby zwiększać liczniki reklam w momencie zdarzenia, podmiot działający na urządzeniu podaje identyfikator wyboru reklamy zwycięskiej aukcji reklam.

Klucze licznika reklam to dowolne 32-bitowe liczby całkowite ze znakiem przypisywane przez technologię reklamową kupującego. Odpowiadają one danemu zestawowi reklam zdefiniowanemu przez platformę DSP. Klucze licznika reklam są ograniczone tylko do reklam należących do danej platformy DSP, więc można je wybierać bez nakładania się na histogramy z innej technologii reklamowej. Klucze licznika reklam służą do zwiększania identyfikatorów specyficznych dla platformy DSP w reklamach tej platformy lub w danej grupie odbiorców niestandardowych, aby odfiltrowywać reklamy z przyszłych aukcji.

Klucze licznika mogą służyć do określania priorytetów reklam, które z większym prawdopodobieństwem zainteresują danego użytkownika na podstawie jego interakcji z innymi reklamami pochodzącymi z technologii reklamowych danego kupującego. Na przykład reklama, która uzyskała wysoki poziom zaangażowania w wygrywanych aukcjach reklam, wyświetleniach i kliknięciach, stanowi wywnioskowany punkt danych. Aby to zilustrować: reklama kijów golfowych dla osób leworęcznych może wskazywać, że użytkownik nie jest zainteresowany kijami dla osób praworęcznych. Filtr limitu wyświetleń na użytkownika ustawiony dla klucza licznika przypisanego do reklam dla osób leworęcznych może odfiltrować reklamy klubów dla osób praworęcznych.

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

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

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

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

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

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

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

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

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

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

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

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

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

Gdy w przypadku niestandardowej listy odbiorców zostaną wdrożone filtry limitu częstotliwości, platforma SSP może wywołać niezbędne zdarzenia kliknięcia, wyświetlenia lub wyświetlenia reklamy.

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

Reklamy, które osiągnęły wstępnie ustawione limity filtrowania ograniczeń liczby wyświetleń, są odfiltrowywane z aukcji. Filtrowanie odbywa się przed wykonaniem logiki ustalania stawek w przypadku aukcji na urządzeniu oraz podczas generowania ładunku w przypadku aukcji w usługach ustalania stawek i aukcji.Ten zestaw narzędzi daje dostawcom technologii reklamowych elastyczność w zakresie wykorzystywania interakcji między użytkownikami a reklamami w ramach ich niestandardowych odbiorców do kierowania reklam przy jednoczesnym minimalizowaniu nadmiernej ekspozycji reklam.

Filtrowanie reklam kontekstowych bez wywołań sieciowych

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

Aby zmniejszyć opóźnienie, dostawcy technologii reklamowych mogą uruchamiać proces wyboru reklam, który obejmuje tylko reklamy kontekstowe z funkcją filtrowania reklam bez wywołań sieciowych. Osiąga się to dzięki używaniu gotowych adresów URI do sygnałów oceny. Listę implementacji scoreAds znajdziesz w sekcji Obsługiwane przypadki użycia i nazwy gotowych identyfikatorów URI.

Aby przeprowadzić wybór reklamy bez wywołań sieciowych:

1. Konfigurowanie filtrowania reklam
2. Tworzenie reklam kontekstowych

3. Utwórz obiekt AdSelectionConfig z tymi ustawieniami:

   1. pusta lista kupujących,
   2. Gotowy identyfikator URI do wybierania najwyższej stawki
   3. Reklamy kontekstowe
   4. Pusty identyfikator URI sygnałów oceny. Pusty identyfikator URI jest dozwolony, aby wskazać, że nie chcesz używać pobierania zaufanych sygnałów do określania wyniku:

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

4. Uruchom wybór reklamy:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Uruchamianie własnego kodu JavaScript do raportowania podczas korzystania z gotowych identyfikatorów URI

Obecnie platforma Piaskownicy prywatności ma tylko podstawową implementację JavaScriptu do raportowania dostępną w przypadku gotowych identyfikatorów URI. Jeśli chcesz uruchamiać własny kod JavaScript do raportowania, ale nadal używać gotowych identyfikatorów URI do wyboru reklam o niskim opóźnieniu, możesz zastąpić DecisionLogicUri między wyborem reklamy a raportowaniem.

1. Wykonaj czynności , aby uruchomić wybieranie reklam kontekstowych za pomocą gotowych identyfikatorów URI.

2. Przed wygenerowaniem raportu utwórz kopię AdSelectionConfig

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

3. Generowanie raportów o wyświetleniach

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

Uruchamianie zapośredniczenia kaskadowego

Zapośredniczenie kaskadowe wymaga, aby wiele pakietów SDK firm zewnętrznych (sieci innych firm) było zarządzanych przez pakiet SDK sieci zapośredniczenia firmy. Mediacja kaskadowa działa tak samo niezależnie od tego, czy aukcja odbyła się na urządzeniu, czy w usługach Bidding & Auction (B&A).

Sieci 3P

Sieci zewnętrzne muszą udostępniać adapter, który umożliwia sieci mediacyjnej wywoływanie metod niezbędnych do przeprowadzania aukcji:

• Uruchom wybór reklamy
• Wyświetlenia raportu

Oto przykład adaptera sieci mediacyjnej:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Każdy pakiet SDK ma własnych menedżerów i klientów usługi wyboru reklam oraz własną implementację selectAds i reportImpressions. Dostawcy pakietów SDK mogą zapoznać się z sekcjami dotyczącymi przeprowadzania wyboru reklam w przypadku aukcji na urządzeniu lub z wyjaśnieniem dotyczącym aukcji B&A. Postępuj zgodnie z instrukcjami raportowania wyświetleń reklam (w przypadku raportowania postępuj zgodnie z instrukcjami raportowania wyświetleń w przypadku pojedynczej platformy SSP).

Sieć zapośredniczeń

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

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

Pobieranie łańcucha zapośredniczenia i minimalnych stawek

Sieć zapośredniczeń jest odpowiedzialna za pobieranie reklam kontekstowych własnych (1P), łańcucha zapośredniczeń i minimalnych stawek sieci innych firm (3P). Może to nastąpić w żądaniu pobrania reklam kontekstowych wykonanym przez sieć zapośredniczenia. Łańcuch zapośredniczenia określa, jak iterować sieci innych firm, a minimalne stawki mogą być przekazywane do procesu aukcji jako adSelectionSignals.

Pozycja sieci w łańcuchu zapośredniczenia

Pakiet SDK do zapośredniczenia może umieścić się w łańcuchu zapośredniczenia na podstawie wartości eCPM w czasie rzeczywistym w przypadku stawek za reklamy własne. W interfejsie Protected Audience API stawki za reklamy są nieprzejrzyste. Pakiet SDK zapośredniczenia powinien używać AdSelectionFromOutcomesConfig, aby móc porównać stawkę danej reklamy własnej z najniższą stawką w następnej sieci zewnętrznej w łańcuchu. Jeśli stawka 1P jest wyższa niż minimalna stawka, oznacza to, że pakiet SDK do zapośredniczenia jest umieszczony przed tą siecią zewnętrzną.

Uruchom wybór reklamy

Aby pobrać kandydata na reklamę własną, sieć zapośredniczenia może przeprowadzić aukcję na urządzeniu, wykonując czynności opisane w sekcji Przeprowadzanie wyboru reklamy. Generuje to kandydata na reklamę własną, stawkę i AdSelectionId, które są używane w procesie zapośredniczenia.

Tworzenie obiektu AdSelectionFromOutcomesConfig

AdSelectionFromOutcomesConfig umożliwia sieci mediacyjnej przekazywanie listy AdSelectionIds (wyników poprzednich aukcji), sygnałów wyboru reklamy i identyfikatora URI do pobierania JavaScriptu, który wybiera reklamę spośród wielu kandydatów. Lista identyfikatorów wyboru reklamy wraz z ich stawkami i sygnałami jest przekazywana do kodu JavaScript, który może zwrócić jeden z identyfikatorów AdSelectionIds, jeśli przekroczy on minimalną stawkę, lub żaden, jeśli łańcuch zapośredniczenia powinien być kontynuowany.

Sieci mediacyjne tworzą AdSelectionFromOutcomesConfig, używając AdSelectionId z sekcji powyżej oraz ceny minimalnej dla rozważanej sieci zewnętrznej. Dla każdego kroku w łańcuchu zapośredniczenia należy utworzyć nowy AdSelectionFromOutcomesConfig.

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

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

    return adSelectionClient.selectAds(config){}
}

Zastąpienie metody selectAds() w przypadku mediacji kaskadowej wymaga podania danych wejściowych AdSelectionFromOutcomesConfig, w których musisz określić te wymagane parametry:

• Sprzedawca: identyfikator sieci reklamowej sprzedawcy, która inicjuje wybór reklamy.
• AdSelectionIds: lista pojedynczych identyfikatorów poprzedniego uruchomienia selectAds() w przypadku reklamy własnej.
• Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały, które mają być używane przez logikę określania stawek kupującego. W takim przypadku uwzględnij minimalną stawkę pobraną dla danej sieci zewnętrznej.
• Identyfikator URI logiki wyboru: adres URL HTTPS, do którego wysyłane jest zapytanie podczas wyboru reklamy w celu pobrania kodu JavaScript sieci mediacyjnej do wyboru zwycięskiej reklamy. Wymagane sygnatury funkcji znajdziesz w tym kodzie JavaScript. Jeśli stawka jest wyższa niż minimalna, JavaScript powinien zwrócić reklamę podmiotu zewnętrznego, a w przeciwnym razie – null. Umożliwia to pakietowi SDK do zapośredniczenia skracanie łańcucha zapośredniczenia po znalezieniu zwycięzcy.

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

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

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

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

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

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

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

Orkiestracja kaskady zapośredniczenia

Poniżej przedstawiamy kolejność działań w procesie zapośredniczenia.

1. Uruchom wybieranie reklam z danych własnych.
2. Iteruj po łańcuchu zapośredniczenia. W przypadku każdej sieci zewnętrznej wykonaj te czynności:
   1. Ustal AdSelectionFromOutcomeConfig, w tym cenę minimalną outcomeId pakietu SDK podmiotu 1. i 3.
   2. Wywołaj funkcję selectAds() z konfiguracją z poprzedniego kroku.
   3. Jeśli wynik nie jest pusty, zwróć reklamę.
   4. Wywołaj metodę selectAds() bieżącego adaptera sieciowego pakietu SDK. Jeśli wynik nie jest pusty, zwróć reklamę.
3. Jeśli w łańcuchu nie zostanie znaleziony żaden zwycięzca, zwróć reklamę 1P.

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

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

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

class MediationNetwork {
    AdSelectionManager adSelectionManager;

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

    public void runAdSelection() {...}

    public void reportImpressions() {...}

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

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

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

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

Raportowanie wyświetleń reklam

Istnieją 2 sposoby zgłaszania wyświetlenia reklamy w zależności od tego, jak przebiega aukcja. Jeśli jesteś pojedynczą platformą SSP, która przeprowadza aukcję, postępuj zgodnie z instrukcjami w tej sekcji. Jeśli zamierzasz wdrożyć kaskadowe zapośredniczenie, wykonaj czynności opisane w sekcji raportowania wyświetleń w przypadku kaskadowego zapośredniczenia.

Raportowanie wyświetleń z pojedynczej platformy SSP

Po wybraniu zwycięskiej reklamy w procesie wyboru reklam możesz zgłosić wyświetlenie do uczestniczących platform po stronie kupującego i sprzedającego za pomocą metody AdSelectionManager.reportImpression(). 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.

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

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

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

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

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

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

Zainicjuj ReportImpressionRequest za pomocą tych wymaganych parametrów:

• Identyfikator wyboru reklamy: identyfikator unikalny tylko dla użytkownika urządzenia, który identyfikuje udany wybór reklamy.
• Konfiguracja wyboru reklamy: ta sama konfiguracja, która jest używana w wywołaniu selectAds() zidentyfikowanym przez podany identyfikator wyboru reklamy.

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

• Funkcja zwrotna onResult() wskazuje, czy utworzono adresy URL raportowania wyświetleń i czy zaplanowano wysłanie żądania.
• Wywołanie zwrotne onError() wskazuje te możliwe warunki:
  • Jeśli wywołanie zostanie zainicjowane z nieprawidłowym argumentem wejściowym, kod błędu AdServicesException będzie wskazywać IllegalArgumentException jako przyczynę.
  • W przypadku wszystkich innych błędów wyświetla się kod AdServicesException z przyczyną IllegalStateException.

Raportowanie wyświetleń w przypadku zapośredniczenia kaskadowego

Pakiet SDK do zapośredniczenia musi śledzić zwycięski pakiet SDK, aby uruchamiać przepływy raportowania. Zestawy SDK uczestniczące w łańcuchu zapośredniczenia powinny udostępniać metodę, którą zapośredniczenie może wywołać, aby uruchomić własny proces raportowania. Pakiet SDK uczestniczący w aukcji z mediacją może wykonać powyższe czynności, aby wdrożyć własne raportowanie.

Platformy SSP mogą użyć tego przykładowego kodu pakietu SDK firmy zewnętrznej jako prototypu sposobu dołączania do przepływów mediacji:

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 wyświetleń raportu wysyła żądania HTTPS GET do punktów końcowych udostępnianych przez platformę sprzedającą i wygrywającą platformę kupującą:

Punkt końcowy platformy po stronie kupującego:

• Interfejs API używa adresu URL logiki określania stawek podanego w grupie odbiorców niestandardowych, aby pobrać dostarczony przez kupującego kod JavaScript, który zawiera logikę zwracania adresu URL raportowania wyświetleń.
• Wywołaj funkcję JavaScript reportWin(), która powinna zwrócić adres URL raportowania wyświetleń kupującego.

Punkt końcowy platformy SSP:

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

Raportowanie usług określania stawek i aukcji

Aukcja przeprowadzona w usługach ustalania stawek i aukcji będzie zawierać wszystkie niezbędne informacje do raportowania, w tym wygenerowane adresy URL do raportowania interakcji z reklamami, które będą uwzględnione 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ń przebiega w ten sam sposób.

Raportowanie wyświetleń w ramach możliwie najlepszej obsługi

Metoda reportImpression() ma na celu jak najdokładniejsze ukończenie raportowania.

Raportowanie interakcji z reklamami

Protected Audience umożliwia raportowanie bardziej szczegółowych interakcji z wyświetloną reklamą. Mogą to być interakcje takie jak czas wyświetlania, kliknięcia, najechania kursorem myszy lub inne przydatne dane, które można zebrać. Proces otrzymywania tych raportów składa się z 2 etapów. Najpierw kupujący i sprzedawcy muszą zarejestrować się, aby otrzymywać te raporty w swoim JavaScript do raportowania. Następnie klient musi zgłosić te zdarzenia.

Rejestrowanie się w celu otrzymywania zdarzeń interakcji

Rejestracja zdarzeń interakcji odbywa się w funkcjach JavaScriptu kupującego reportWin() i sprzedawcy reportResult() za pomocą funkcji JavaScriptu udostępnianej przez platformę: registerAdBeacon. Aby zarejestrować się w celu otrzymywania raportu o wydarzeniu, wywołaj funkcję JavaScript platformy z JavaScriptu raportowania. W tym fragmencie kodu użyto reportWin() kupującego, ale to samo podejście można zastosować w przypadku reportResult().

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

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

    return reportingUri;
}

Raportowanie zdarzeń interakcji

Po zgłoszeniu wyświetlenia klienci mogą zgłaszać interakcje do wcześniej zarejestrowanych zwycięskich platform kupujących i sprzedających za pomocą metody AdSelectionManager.reportInteraction(). Aby zgłosić zdarzenie związane z reklamą:

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

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

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

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

Zainicjuj ReportInteractionRequest za pomocą tych wymaganych parametrów:

• Identyfikator wyboru reklamy: identyfikator wyboru reklamy pobrany z wcześniej zwróconegoAdSelectionOutcome.
• Klucz interakcji: ciąg znaków zdefiniowany przez klienta, który opisuje zgłaszane działanie. Musi on być zgodny z kluczem zarejestrowanym przez sprzedawcę lub kupującego w funkcjach JavaScript raportowania.
• Interaction Data: ciąg znaków zawierający dane, które mają być uwzględnione w raporcie o zdarzeniu i przesłane z powrotem na serwery raportowania.
• Miejsca docelowe raportowania: maska bitowa określająca, czy zdarzenia mają być raportowane kupującemu, sprzedawcy czy obu tym podmiotom. Te flagi są udostępniane przez platformę, a maskę miejsca docelowego można utworzyć za pomocą operacji bitowych. Aby wysyłać raporty do jednego miejsca docelowego, możesz bezpośrednio użyć flagi udostępnionej przez platformę. Aby wysyłać raporty do wielu miejsc docelowych, możesz użyć operatora bitowego OR (|) 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 połączenie zostanie nawiązane, gdy aplikacja działa w tle, zwracany jest błąd IllegalStateException z opisem problemu.
  • Jeśli klient nie może wywołać funkcji reportInteraction(), zwracana jest wartość LimitExceededException.
  • Jeśli pakiet nie jest zarejestrowany do wywoływania interfejsów Privacy Preserving API, zwracana jest wartość SecurityException().
  • Jeśli aplikacja zgłaszająca interakcje jest inna niż aplikacja, która wywołała funkcję selectAds(), zwracana jest wartość IllegalStateException.
• Jeśli użytkownik nie wyraził zgody na włączenie interfejsów API Piaskownicy prywatności, wywołanie zakończy się bez powiadomienia o błędzie.

Punkty końcowe raportowania interakcji

Interfejs API interakcji z raportem wysyła żądania HTTPS POST do punktów końcowych udostępnianych przez platformę sprzedającą i platformę kupującą, która wygrała aukcję. Protected Audience dopasuje klucze interakcji do adresów URI zadeklarowanych w raportującym kodzie JavaScript i wyśle żądanie POST do każdego punktu końcowego dla każdej raportowanej interakcji. Content-Type żądania to zwykły tekst, a treść to dane interakcji.

Raportowanie interakcji z możliwie najlepszą obsługą

reportInteraction() ma na celu zapewnienie możliwie najlepszego uzupełniania raportów za pomocą żądań HTTP POST.

Codzienna aktualizacja w tle

Podczas tworzenia listy niestandardowych odbiorców aplikacja lub pakiet SDK może inicjować metadane listy niestandardowych odbiorców. Dodatkowo platforma może aktualizować te elementy metadanych niestandardowych list odbiorców w ramach codziennego procesu aktualizacji w tle.

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

W tym procesie wysyłane jest zapytanie do adresu URL codziennej aktualizacji zdefiniowanego na liście odbiorców niestandardowych, a adres URL może zwrócić odpowiedź JSON.

• Odpowiedź JSON może zawierać dowolne obsługiwane pola metadanych, które wymagają aktualizacji.
• Każde pole JSON jest weryfikowane niezależnie. Klient ignoruje nieprawidłowo sformatowane pola, co powoduje, że w odpowiedzi nie ma aktualizacji dotyczących tych pól.
• Pusta odpowiedź HTTP lub pusty obiekt JSON „{}” nie powodują aktualizacji metadanych.
• Rozmiar wiadomości z odpowiedzią musi być ograniczony do 10 KB.
• Wszystkie identyfikatory URI muszą używać protokołu HTTPS.
• trusted_bidding_uri musi mieć taką samą domenę ETLD+1 jak 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 wybierania reklam

Proces wyboru reklamy koordynuje wykonywanie kodu JavaScript dostarczonego przez kupującego i sprzedawcę.

Dostarczony przez kupującego kod JavaScript jest pobierany z adresu URL logiki ustalania stawek określonego w niestandardowej liście odbiorców. Zwrócony kod JavaScript powinien zawierać te funkcje:

• generateBid()
• reportWin()

Kod JavaScript dostarczony przez sprzedawcę jest pobierany z adresu URL logiki decyzyjnej określonego w parametrze AdSelectionConfig interfejsu API do wyboru reklam. Zwrócony kod JavaScript powinien zawierać te funkcje:

• scoreAd()
• reportResult()

generateBid()

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

Parametry wejściowe:

• ad: obiekt JSON 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 jest następujący:

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

  gdzie:

  • owner, buyer i name to ciągi znaków pobrane z właściwości o tej samej nazwie na niestandardowej liście odbiorców biorącej udział w wyborze reklamy.
  • activation_time i expiration_time to czas aktywacji i wygaśnięcia listy odbiorców niestandardowych wyrażony w sekundach od epoki uniksowej.
  • ca_user_bidding_signals to ciąg JSON określony w polu userBiddingSignals obiektu CustomAudience w momencie tworzenia.
  • trusted_bidding_signals, contextual_signals i user_signals to obiekty JSON. Są one przekazywane jako puste obiekty i będą wypełniane w przyszłych wersjach. Ich format nie jest wymuszany przez platformę i jest zarządzany przez technologię reklamową.

Wynik:

• ad: to reklama, do której odnosi się stawka. Skrypt może zwrócić kopię otrzymanej reklamy z innymi metadanymi. Właściwość render_url reklamy powinna pozostać niezmieniona.
• bid: wartość zmiennoprzecinkowa reprezentująca wartość stawki za tę reklamę.
• status: wartość całkowita, która może być:
  • 0: w przypadku pomyślnego wykonania
  • 1: (lub dowolna wartość różna od zera), jeśli którykolwiek z sygnałów wejściowych jest nieprawidłowy. Jeśli funkcja generate-bid zwróci wartość inną niż zero, proces ustalania stawek zostanie unieważniony w przypadku wszystkich reklam CA.

scoreAd()

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

Parametry wejściowe:

• ad: zobacz dokumentację generateBid
• bid: wartość stawki za reklamę;

• ad_selection_config: obiekt JSON reprezentujący parametr AdSelectionConfig interfejsu selectAds API. Format jest następujący:

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

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

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

• contextual_signals, user_signals: obiekty JSON. Są one przekazywane jako puste obiekty i zostaną wypełnione w przyszłych wersjach. Platforma nie wymusza ich formatu, a zarządza nim technologia reklamowa.

• per_buyer_signals: obiekt JSON odczytany z mapy perBuyerSignal w parametrze interfejsu API AdSelectionConfig, w którym jako klucz używany jest bieżący kupujący odbiorców niestandardowych. Pusta, jeśli mapa nie zawiera żadnego wpisu dla danego kupującego.

Dane wyjściowe:

• score: wartość zmiennoprzecinkowa reprezentująca wartość wyniku tej reklamy.
• status: wartość całkowita, która może być:
  • 0: w przypadku udanego wykonania
  • 1. w przypadku nieprawidłowych customAudienceSignals.
  • 2. w przypadku nieprawidłowego parametru AdSelectionConfig;
  • 3. w przypadku, gdy którykolwiek z pozostałych sygnałów jest nieprawidłowy.
  • Każda wartość różna od zera 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.

Dane wyjściowe:

• status: 0 – w przypadku powodzenia, wartość różna od zera w przypadku niepowodzenia
• result: jeden z wyników przekazanych 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: zapoznaj się z dokumentacją scoreAds
• render_url: adres URL renderowania zwycięskiej reklamy;
• bid: stawka za zwycięską reklamę;
• contextual_signals: zapoznaj się z dokumentacją generateBid

Dane wyjściowe:

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

reportWin()

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

Parametry wejściowe:

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

Dane wyjściowe:

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

registerAdBeacon()

function registerAdBeacon(
  beacons
)

Parametry wejściowe:

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

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

  • interaction_key: ciąg znaków reprezentujący zdarzenie. Platforma używa tego parametru później podczas raportowania interakcji ze zdarzeniami, aby wyszukać reporting_uri, które powinny otrzymać powiadomienie. Klucz musi być zgodny z tym, co rejestruje kupujący lub sprzedawca, oraz z tym, co zgłasza sprzedawca.
  • reporting_uri: Identyfikator URI do otrzymywania raportów o zdarzeniach. Powinno to być konkretne zdarzenie związane z rodzajem zgłaszanego zdarzenia. Musi akceptować żądanie POST, aby obsługiwać wszystkie dane zgłaszane wraz ze zdarzeniem.

  Na przykład:

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

Wbudowane identyfikatory URI wyboru reklamy

Wstępnie utworzone identyfikatory URI umożliwiają dostawcom technologii reklamowych wyznaczanie funkcji JavaScript do logiki podejmowania decyzji o wyborze reklamy w klasach AdSelectionConfig i AdSelectionFromOutcomesConfig. Wstępnie utworzone identyfikatory URI nie wymagają wywołań sieciowych, aby pobrać odpowiedni kod JavaScript. Technologie reklamowe mogą używać gotowych identyfikatorów URI bez konieczności konfigurowania zarejestrowanej domeny do hostowania kodu JavaScript.

Gotowy identyfikator URI jest tworzony w tym formacie:

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

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

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

• w identyfikatorze URI brakuje któregokolwiek z wymaganych parametrów;
• w identyfikatorze URI występują nierozpoznane parametry.

Obsługiwane gotowe przypadki użycia 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 przepływie selectAds(AdSelectionConfig).

Nazwa gotowego identyfikatora URI: highest-bid-wins

Ten gotowy identyfikator URI zawiera kod JavaScript, który po zakończeniu licytacji wybiera reklamę z najwyższą stawką. Udostępnia też podstawową funkcję raportowania, która pozwala zgłaszać render_uri i bid zwycięzcy.

Parametry wymagane

reportingUrl: podstawowy adres URL raportowania, który jest sparametryzowany za pomocą 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 adres URI będzie wyglądać tak:

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

Przypadek użycia 2. Wybieranie reklam na podstawie wyników

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

Nazwa gotowego identyfikatora URI: waterfall-mediation-truncation

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

Parametry wymagane

bidFloor: klucz wartości ceny minimalnej przekazanej w parametrze getSelectionSignals() porównywanej z reklamą pakietu SDK do zapośredniczenia.

Wykorzystanie

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

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

Testowanie

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

Wymagania wstępne

Interfejs Protected Audience API wymaga użycia JavaScriptu podczas wyboru reklamy i raportowania wyświetleń. W środowisku testowym możesz udostępnić ten kod JavaScript na 2 sposoby:

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

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

Punkty końcowe HTTPS

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

1. Punkt końcowy kupującego, który obsługuje skrypt JavaScript z logiką określania stawek.
2. Punkt końcowy, który obsługuje sygnały określania stawek.
3. Punkt końcowy sprzedawcy, który obsługuje JavaScript z logiką podejmowania decyzji.
4. Punkt końcowy, który udostępnia sygnały oceny.
5. Punkt końcowy raportowania wyświetleń kupującego, który wygrał.
6. Punkt końcowy raportowania wyświetleń sprzedawcy.
7. Punkt końcowy do wyświetlania codziennych aktualności dla odbiorców niestandardowych.

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

Zastępowanie zdalnego pobierania JavaScriptu

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

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

<application
  android:debuggable="true">

Przykład użycia tych zastąpień znajdziesz w przykładowej aplikacji interfejsu Protected Audience API w GitHubie.

Musisz dodać własny kod JavaScript, który będzie obsługiwać procedury wyboru reklam, takie jak ustalanie stawek, podejmowanie decyzji dotyczących oceny i raportowanie. Podstawowe przykłady kodu JavaScript, które obsługują wszystkie wymagane żądania, znajdziesz w repozytorium GitHub. Przykładowa aplikacja interfejsu Protected Audience API pokazuje, jak odczytać kod z tego pliku i przygotować go do użycia jako zastąpienie.

Możesz niezależnie zastępować pobieranie JavaScriptu po stronie sprzedawcy i po stronie kupującego, ale potrzebujesz punktu końcowego HTTPS, aby wyświetlać JavaScript, dla którego nie podajesz zastąpień. Więcej informacji o konfigurowaniu serwera, który obsługuje te przypadki, znajdziesz w pliku README.

Zastąpienie pobierania JavaScriptu jest możliwe tylko w przypadku list odbiorców niestandardowych, które należą do Twojego pakietu.

Zastępowanie kodu JavaScript po stronie sprzedawcy

Aby skonfigurować zastąpienie kodu JavaScript po stronie sprzedawcy, wykonaj te czynności, jak pokazano w tym przykładzie kodu:

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

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

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

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

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

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

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

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

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

Więcej informacji o znaczeniu poszczególnych pól w sekcji AdSelectionConfig znajdziesz w sekcji Uruchamianie wyboru reklamy. Kluczowa różnica polega na tym, że w przypadku parametru decisionLogicUrl można ustawić wartość zastępczą, ponieważ zostanie ona zignorowana.

Aby zastąpić JavaScript używany podczas wybierania reklam, element decisionLogicJs musi zawierać odpowiednie sygnatury funkcji po stronie sprzedawcy. Przykład odczytywania pliku JavaScript jako ciągu znaków znajdziesz w przykładowej aplikacji Protected Audience API w GitHubie.

Metoda asynchroniczna 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ą korzystać z logiki decyzji i raportowania przekazanej przez Ciebie jako zastąpienie.

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

• Jeśli zastąpienie zostanie podjęte z nieprawidłowymi argumentami, AdServiceException wskazuje IllegalArgumentException jako przyczynę.
• Jeśli zastąpienie zostanie podjęte w przypadku aplikacji, która nie działa w trybie debugowania z włączonymi opcjami programisty, AdServiceException wskaże IllegalStateException jako przyczynę.

Resetowanie zastąpień po stronie sprzedawcy

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

Aby zresetować zmiany w przypadku wszystkich AdSelectionConfigs:

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

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

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

Po zresetowaniu zastąpień po stronie sprzedawcy wywołania funkcji selectAds() używają adresu decisionLogicUrl przechowywanego w parametrze AdSelectionConfig, aby spróbować pobrać wymagany kod JavaScript.

Jeśli wywołanie funkcji resetAllAdSelectionConfigRemoteOverrides() się nie powiedzie, wywołanie zwrotne OutComeReceiver.onError() zwraca wartość AdServiceException. Jeśli usunięcie zastąpień zostanie podjęte w przypadku aplikacji, która nie działa w trybie debugowania z włączonymi opcjami programisty, AdServiceException wskaże IllegalStateException jako przyczynę.

Zastępowanie kodu JavaScript po stronie kupującego

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

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

// Join custom audience

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

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

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

// Join custom audience

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

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

Wartości parametrów buyer i name są takie same jak te, które zostały użyte do utworzenia niestandardowej grupy odbiorców. Więcej informacji o tych polach

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

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

Metoda asynchroniczna 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() będą korzystać z logiki określania stawek i raportowania, którą przekażesz jako zastąpienie.

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

• Jeśli zastąpienie zostanie podjęte z nieprawidłowymi argumentami, AdServiceException wskazuje IllegalArgumentException jako przyczynę.
• Jeśli zastąpienie zostanie podjęte w przypadku aplikacji, która nie działa w trybie debugowania z włączonymi opcjami programisty, AdServiceException wskaże IllegalStateException jako przyczynę.

Resetowanie zastąpień po stronie kupującego

W tej sekcji zakładamy, że masz zastąpiony JavaScript po stronie kupującego i masz odniesienie do zmiennej TestCustomAudienceManager użytej w poprzedniej sekcji.

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

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

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

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

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

Jeśli wywołanie funkcji resetCustomAudienceRemoteInfoOverride() się nie powiedzie, wywołanie zwrotne OutComeReceiver.onError() zwraca wartość AdServiceException. Jeśli usunięcie zastąpień zostanie podjęte w przypadku aplikacji, która nie działa w trybie debugowania z włączonymi opcjami programisty, przyczyną będzie AdServiceExceptionIllegalStateException.

Konfigurowanie serwera raportowania

Gdy używasz zastąpień zdalnego pobierania, musisz skonfigurować serwer, do którego urządzenie lub emulator będzie mieć dostęp, aby odpowiadać na zdarzenia raportowania. Do testowania wystarczy punkt końcowy, który zwraca kod 200. Repozytorium GitHub zawiera definicje usług OpenAPI, które można wdrożyć na obsługiwanej platformie mocków lub mikroserwisów. Więcej informacji znajdziesz w pliku README projektu.

Podczas wyszukiwania definicji OpenAPI poszukaj pliku reporting-server.json. Ten plik zawiera punkt końcowy, który zwraca kod 200, co oznacza kod odpowiedzi HTTP. Ten punkt końcowy jest używany podczas selectAds() i sygnalizuje interfejsowi Protected Audience API, że raportowanie wyświetleń zostało zakończone.

Funkcje do przetestowania

• Ćwiczenie dołączania do niestandardowej grupy odbiorców i opuszczania jej oraz konfigurowania jej na podstawie wcześniejszych działań użytkowników.
• Uruchamiać inicjowanie wyboru reklam na urządzeniu za pomocą skryptów JavaScript hostowanych zdalnie.
• Obserwuj, jak powiązanie aplikacji z ustawieniami odbiorców niestandardowych może wpływać na wyniki wyboru reklam.
• Raportowanie wyświetleń ćwiczeń po wybraniu reklamy.

Ograniczenia

W tabeli poniżej znajdziesz ograniczenia dotyczące przetwarzania w Protected Audience API. Podane limity mogą ulec zmianie na podstawie opinii. Informacje o funkcjach, które są w trakcie wdrażania, znajdziesz w informacjach o wersji.

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

Twoje opinie są kluczową częścią Piaskownicy prywatności na Androida. Daj nam znać o wszelkich problemach, które napotkasz, lub o pomysłach na ulepszenie Piaskownicy prywatności na Androida.