Przewodnik dla programistów interfejsu Protected Audience API

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

Protected Audience API na Androida (wcześniej FLEDGE) obejmuje interfejsy Custom Audience API i Ad Selection API. Platformy technologii reklamowych i reklamodawcy mogą używać tych interfejsów API do wyświetlania reklam niestandardowych na podstawie danych o wcześniejszym zaangażowaniu użytkowników w aplikację. Ogranicza to udostępnianie identyfikatorów między aplikacjami i ogranicza udostępnianie osobom trzecim informacji o interakcji w aplikacji.

Interfejs Custom Audience API koncentruje się na abstrakcji „niestandardowych odbiorców”, która reprezentuje grupę użytkowników o wspólnych zamiarach. Reklamodawca może zarejestrować użytkownika w niestandardowej liście odbiorców 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 zapewnia środowisko umożliwiające wielu deweloperom przeprowadzanie lokalnych aukcji dla niestandardowych odbiorców. W tym celu system bierze pod uwagę odpowiednie reklamy powiązane z listą niestandardowych odbiorców i przeprowadza dodatkowe przetwarzanie reklam, które platforma technologiczna reklam zwraca na urządzenie.

Platformy technologii reklamowych mogą zintegrować te interfejsy API, aby wdrażać remarketing, który chroni prywatność użytkowników. W kolejnych wersjach planujemy dodać obsługę innych zastosowań, w tym reklam promujących instalacje aplikacji. Więcej informacji o interfejsie Protected Audience API na Androida znajdziesz w propozycji projektu.

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

1. Zarządzanie grupami odbiorców niestandardowych
2. Konfigurowanie i uruchamianie selekcji reklam na urządzeniu
3. Zgłaszanie wyświetleń reklamy

Zanim zaczniesz

Zanim zaczniesz, wykonaj te czynności:

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

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

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

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

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

5. Umieść w pliku manifestu uprawnienia ACCESS_ADSERVICES_CUSTOM_AUDIENCE:

     <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. Dowiedz się więcej o uprawnieniach w usługach reklamowych i kontroli dostępu do pakietów 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 raportowania aukcji lub wyświetleń. Funkcja ograniczenia pamięci wymaga wersji WebView 105.0.5195.58 lub nowszej. Platforma wymusza sprawdzanie wersji, a w przypadku niespełnienia tego warunku wywołania interfejsów API selectAds i reportImpression kończą się niepowodzeniem. Dostępne są 2 opcje:

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

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • Opcja 2. Zainstaluj WebView Beta ze Sklepu Google Play. Musi być co najmniej równa wersji podanej wcześniej.

Dołączanie do grupy odbiorców niestandardowych

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

1. 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 asynchroniczny obiekt joinCustomAudience() za pomocą obiektu JoinCustomAudienceRequest i odpowiednich obiektów Executor oraz OutcomeReceiver.

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

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

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

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

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

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

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

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

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

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

Powtarzane wywoływanie funkcji joinCustomAudience() z inną instancją funkcji CustomAudience aktualizuje wszystkie istniejące obiekty CustomAudience z odpowiednimi parametrami owner, buyer i name. Ze względu na ochronę prywatności wynik interfejsu API nie rozróżnia „tworzenia” i „aktualizacji”.

Dodatkowo musisz utworzyć CustomAudience z tymi wymaganymi parametrami:

• URL z codzienną aktualizacją: adres URL HTTPS wysyłany codziennie w tle w celu zaktualizowania sygnałów określania stawek przez użytkownika w niestandardowych segmentach odbiorców, danych dotyczących zaufanego określania stawek oraz renderowania adresów URL i metadanych reklam na potrzeby reklam.
• URL logiki ustalania stawek: adres URL HTTPS zapytany podczas wyboru reklamy w celu pobrania logiki ustalania stawek w kodzie JavaScript kupującego. Sprawdź wymagane podpisy funkcji w tym skrypcie JavaScript.
• Identyfikatory renderowania reklam: dowolny identyfikator ustawiany przez technologię reklamową kupującego. Jest to optymalizacja służąca do generowania danych dla B&A.

Opcjonalne parametry obiektu CustomAudience:

• Czas aktywacji: lista odbiorców niestandardowych może uczestniczyć w wybieraniu reklam i ich codziennych aktualizacjach dopiero po jej aktywacji. Przydaje się to np. do angażowania nieaktywnych użytkowników aplikacji.
• Czas ważności: czas w przyszłości, po którym niestandardowa lista odbiorców zostanie usunięta z urządzenia.
• Sygnały dotyczące określania stawek przez użytkownika: ciąg znaków JSON zawierający sygnały użytkownika, np. preferowany język użytkownika, używane przez logikę ustalania stawek kupującego do generowania stawek podczas procesu wyboru reklamy. Ten format pomaga platformom reklamowym korzystać z kodu na różnych platformach i ułatwia jego wykorzystanie w funkcjach JavaScript.
• Zaufane dane dotyczące określania stawek: adres URL HTTPS i lista ciągów znaków używanych podczas procesu wyboru reklam, które pobierają sygnały dotyczące określania stawek z usługi zaufanego klucza/wartości.
• Reklamy: lista obiektów AdData odpowiadających reklamom, które biorą udział w wybieraniu reklam. Każdy obiekt AdData składa się z tych elementów:
  • URL renderowania: adres URL HTTPS, który jest wyszukiwany w celu renderowania ostatecznej reklamy.
  • Metadane: obiekt JSON zserializowany jako ciąg znaków zawierający informacje, które mają zostać wykorzystane przez logikę ustalania stawek kupującego podczas procesu wyboru reklamy.
  • Filtry reklam: klasa zawierająca wszystkie informacje potrzebne do filtrowania reklam w celu instalacji aplikacji i określania limitu wyświetleń na użytkownika podczas wyboru reklam.

Oto przykład utworzenia obiektu CustomAudience:

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

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

Obsługa wyników funkcji joinCustomAudience()

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

• Wywołanie zwrotne onResult() oznacza, że lista niestandardowych odbiorców została utworzona lub zaktualizowana.
• Wywołanie onError() oznacza 2 możliwe warunki.
  • Jeśli JoinCustomAudienceRequest zostanie zainicjowany z nieprawidłowymi argumentami, AdServicesException wskazuje IllegalArgumentException jako przyczynę.
  • Wszystkie inne błędy otrzymują błąd AdServicesException z IllegalStateException jako przyczyną.

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

Opuść grupę odbiorców niestandardowych

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

1. Zainicjuj obiekt CustomAudienceManager.
2. Inicjalizacja LeaveCustomAudienceRequest z użyciem wartości buyer i name z listy niestandardowych odbiorców. Więcej informacji o tych polach znajdziesz w artykule Dołączanie do listy niestandardowych odbiorców.
3. Wywołaj asynchroniczną metodę leaveCustomAudience() za pomocą obiektu LeaveCustomAudienceRequest i odpowiednich obiektów Executor oraz OutcomeReceiver.

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

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

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

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

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

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

Podobnie jak w przypadku wywołania joinCustomAudience(), OutcomeReceiver sygnalizuje koniec wywołania interfejsu API. Aby chronić prywatność, wynik błędu nie rozróżnia błędów wewnętrznych od nieprawidłowych argumentów. 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.

Wybór reklamy

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

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

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

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

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

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

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

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

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

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

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

• Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały, które będą używane przez logikę określania stawek kupującego pobraną z CustomAudience.getBiddingLogicUrl().
• Sygnały sprzedawcy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały wykorzystywane przez logikę podejmowania decyzji w JavaScript pobrane z pliku AdSelectionConfig.getDecisionLogicUrl().
• Według sygnałów kupujących: mapa obiektów JSON zserializowanych jako ciągi tekstowe, zawierająca sygnały wykorzystywane przez logikę określania stawek w JavaScriptzie w przypadku konkretnych kupujących, pobierane z CustomAudience.getBiddingLogicUrl() i identyfikowane przez pola kupujących w uwzględnionych listach niestandardowych.
• Reklamy kontekstowe: zbiór propozycji reklam zbieranych bezpośrednio od kupujących podczas aukcji, która odbywa się poza aukcją z Protected Audience API.

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

• URL renderowania zwycięskiej reklamy pobrany z AdData.getRenderUrl().
• Identyfikator wyboru reklamy unikalny dla użytkownika urządzenia. Ten identyfikator jest używany do raportowania wyświetleń 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() udostępnia AdServicesException z takim zachowaniem:

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

Reklamy kontekstowe

Protected Audience może uwzględniać reklamy kontekstowe w ramach aukcji chronionej. Reklamy kontekstowe należy wybrać na serwerze technologii reklamowych i zwrócić na urządzenie poza interfejsami Protected Audience API. Reklamy kontekstowe można następnie uwzględniać w aukcji za pomocą parametru AdSelectionConfig. W tym momencie działają one tak samo jak reklamy na urządzeniu, w tym pod kątem możliwości filtrowania reklam negatywnych. Po zakończeniu aukcji z listą odbiorców chronionych musisz wywołać funkcję reportImpression(). Powoduje to wywołanie funkcji reportWin() w zwycięskiej reklamie kontekstowej (tak samo jak w przypadku raportowania wyświetleń), aby pobrać zwycięską reklamę na urządzeniu. Każda reklama kontekstowa wymaga kupującego, stawki, linku do funkcji raportowania, adresu URL renderowania i metadanych reklamy.

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

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

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

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

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

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

Filtrowanie reklam promujących instalacje aplikacji

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

Pierwszym krokiem w tym procesie jest określenie, którzy reklamodawcy mogą filtrować wyniki według zainstalowanego pakietu. Musisz to zrobić w aplikacji, w której 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 poprzedni kod zostanie wykonany, przekazani reklamodawcy będą mogli odfiltrować zainstalowane aplikacje, które określisz podczas generowania stawek. Jeśli chcesz zablokować dostęp reklamodawcy do informacji o stanie instalacji tej aplikacji, uruchom ten kod ponownie, ale bez informacji o reklamodawcy.

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

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

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

Wydawcy korzystający z usług DSP mogą też ustawić AdFilter w przypadku reklam, które występują w ich niestandardowych odbiorcach.

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

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

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

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

Filtrowanie według limitu wyświetleń na użytkownika umożliwia ograniczenie liczby wyświetleń reklamy. Filtrowanie limitu wyświetleń na użytkownika zmniejsza ryzyko nadmiernej ekspozycji na reklamę i optymalizuje alternatywny wybór reklam w 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: zdarzenie wygrana wskazuje, że reklama wygrała aukcję. Zdarzenia „Win” są automatycznie aktualizowane przez interfejs Protected Audience API i deweloper nie może ich wywoływać bezpośrednio. Dane o wygrywaniu są widoczne tylko w przypadku reklam w danej grupie niestandardowej.
• Wyświetlenie: niezależnie od reportImpression, wywołujący na urządzeniu (SSP lub MMP) używa updateAdCounterHistogram() do wywoływania zdarzeń wyświetlenia w wybranym przez siebie miejscu w kodzie. Zdarzenia wyświetlenia są widoczne dla wszystkich reklam należących do danej platformy DSP, a nie tylko dla reklam z tej samej niestandardowej grupy odbiorców.
• Wyświetlanie: wywołanie zdarzenia przez wywołującego na urządzeniu (SSP lub MMP) w wybranym przez niego miejscu kodu za pomocą wywołania updateAdCounterHistogram(). Zdarzenia wyświetleń są widoczne dla wszystkich reklam należących do danego DSP i nie są ograniczone do reklam na tej samej liście odbiorców niestandardowych.
• Kliknięcie: wywołanie zdarzenia przez wywołującego na urządzeniu (SSP lub MMP) w wybranym przez niego miejscu kodu za pomocą wywołania updateAdCounterHistogram(). Zdarzenia kliknięcia są widoczne dla wszystkich reklam należących do danego systemu DSP, a nie tylko dla reklam na tej samej liście odbiorców niestandardowych.

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

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

Klucze licznika można wykorzystać do nadawania priorytetów reklamom, które z większym prawdopodobieństwem będą interesujące dla danego użytkownika, na podstawie ich interakcji z innymi reklamami danego kupującego. Na przykład reklama, która cieszyła się dużym zainteresowaniem dzięki wygranej w aukcjach reklam, wyświetleniom i kliknięciu, stanowi wywnioskowany punkt danych. Aby to zilustrować, podajmy przykład reklamy kijów golfowych dla leworęcznych. Może to oznaczać, że użytkownik nie jest zainteresowany kijami dla praworęcznych. Filtr limitu wyświetleń na użytkownika ustawiony dla klucza licznika przypisanego do reklam dla leworęcznych może odfiltrowywać reklamy dla osób praworęcznych.

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

// 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 ograniczeń liczby wyświetleń, można go przekazać podczas tworzenia listy odbiorców niestandardowej:

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

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

Gdy wdrożysz filtry limitu wyświetleń na użytkownika, platforma SSP może wywołać niezbędne zdarzenia kliknięcia, obejrzenia lub wyświetlenia.

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

Reklamy, które osiągnęły ustawione wcześniej limity filtra ograniczeń liczby wyświetleń, są odfiltrowywane z aukcji. Filtrowanie odbywa się przed wykonaniem reguł określania stawek w przypadku aukcji na urządzeniu oraz podczas generowania ładunku na potrzeby aukcji w usługach związanych z określaniem stawek i usług aukcyjnych.Ten zestaw narzędzi zapewnia technikom reklamowym elastyczność, dzięki której może korzystać z interakcji między użytkownikami i reklamami w ramach niestandardowych list odbiorców w celu skoncentrowania kierowania na reklamach i minimalizowania nadmiernej ekspozycji na reklamy.

Filtrowanie reklam kontekstowych bez wywołań sieciowych

Jeśli z urządzenia nie ma popytu na remarketing, możesz uruchomić 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 danych logiki określania stawek, sygnałów określania stawek i sygnałów punktacji. Platforma używa gotowego identyfikatora URI, by wybrać reklamę kontekstową o najwyższej stawce.

Aby skrócić czas oczekiwania, specjaliści ds. technologii reklamowych mogą uruchomić proces wyboru reklamy obejmujący tylko reklamy kontekstowe z funkcją filtrowania reklam bez wywołań sieciowych. W tym celu możesz wykorzystać gotowe identyfikatory URI do oceny sygnałów. Listę zastosowań scoreAds znajdziesz w sekcji Obsługiwane gotowe przypadki użycia i nazwy identyfikatorów URI.

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

1. Konfigurowanie filtrowania reklam
2. Tworzenie reklam kontekstowych

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

   1. Pusta lista kupujących.
   2. Gotowy identyfikator URI do wyboru najwyższej stawki
   3. Reklamy kontekstowe
   4. Pusty identyfikator URI sygnałów punktowych. Pusty identyfikator URI może wskazywać, że nie chcesz używać 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);
   

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

Obecnie platforma Piaskownica prywatności udostępnia tylko podstawową implementację JavaScriptu do raportowania w przypadku gotowych adresów URI. Jeśli chcesz uruchomić własny kod JavaScript do raportowania, a jednocześnie używać gotowych identyfikatorów URI do wyboru reklam z krótkim czasem oczekiwania, możesz zastąpić ustawienie DecisionLogicUri między wyborem reklam a uruchomieniami raportowania.

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

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

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

3. Generowanie raportów o wyświetleniach

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

Uruchamianie zapośredniczenia kaskadowego

Zapośredniczenie kaskadowe wymaga, aby w ramach własnej sieci zapośredniczeń zorganizowała wiele zewnętrznych pakietów SDK (sieci zewnętrznych). Pośrednictwo w schemacie kaskadowym działa w taki sam sposób niezależnie od tego, czy aukcja miała miejsce na urządzeniu, czy w ramach usługi określania stawek i usług aukcji (B&A).

Sieci innych firm

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

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

Oto przykład adaptera sieci zapośredniczeń:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Każdy pakiet SDK ma swoich menedżerów i klientów usługi doboru reklam oraz własne implementacje selectAds i reportImpressions. Dostawcy pakietów SDK mogą zapoznać się z sekcjami o wybieraniu reklam w przypadku aukcji na urządzeniu lub opisie B&A w przypadku aukcji B&A. Postępuj zgodnie z instrukcjami raportowania wyświetleń reklamy (postępuj zgodnie z raportem wyświetleń na jednej platformie SSP na potrzeby raportowania.

Sieć zapośredniczeń

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

Sieci zapośredniczenia odpowiadają za działanie łańcucha zapośredniczenia i swoje miejsce w tym łańcuchu. W następnej sekcji znajdziesz informacje o konfigurowaniu i wykonywaniu tego procesu.

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ę tak zdarzyć w żądaniu pobrania reklam kontekstowych wykonywanych przez sieć zapośredniczenia. Łańcuch zapośredniczenia określa sposób iteracji w sieciach zewnętrznych, a stawki minimalne mogą być przekazywane do procesu aukcji jako adSelectionSignals.

Miejsce sieci w łańcuchu zapośredniczenia

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

Uruchom wybór reklamy

Aby pobrać kandydata reklamy własnej, sieć zapośredniczająca może przeprowadzić aukcję na urządzeniu zgodnie z instrukcjami podanymi w sekcji wybór reklamy. Spowoduje to wygenerowanie własnej reklamy kandydującej, stawki i elementu AdSelectionId używanego w procesie zapośredniczenia.

Tworzenie obiektu AdSelectionFromResultsConfig

Pole AdSelectionFromOutcomesConfig umożliwia sieci zapośredniczenia przekazywanie listy AdSelectionIds (wyników z poprzednich aukcji), sygnałów wyboru reklamy oraz identyfikatora URI do pobierania kodu JavaScriptu, który wybiera reklamę od kilku kandydatów. Lista identyfikatorów AdSelectionId wraz z ich stawkami i sygnałami jest przekazywana do kodu JavaScript, który może zwrócić jedną z wartości AdSelectionIds, jeśli jest wyższa od stawki minimalnej, lub żadną, jeśli łańcuch zapośredniczenia ma być kontynuowany.

Sieci zapośredniczenia tworzą AdSelectionFromOutcomesConfig na podstawie danych własnych AdSelectionId z poprzedniej sekcji oraz minimalnej stawki dla branej pod uwagę sieci zewnętrznej. Dla każdego etapu łańcucha zapośredniczenia należy utworzyć nowy obiekt AdSelectionFromOutcomesConfig.

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

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

    return adSelectionClient.selectAds(config){}
}

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

• Sprzedawca: identyfikator sieci reklamowej sprzedawcy, który inicjuje wybór reklamy.
• AdSelectionIds: pojedyncza lista poprzednich uruchomień selectAds() dla reklamy własnej.
• Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały, które będą używane przez logikę określania stawek przez kupującego. W tym przypadku uwzględnij stawkę minimalną pobraną dla danej sieci zewnętrznej.
• URI logiki wyboru: adres URL HTTPS zapytany podczas wyboru reklamy w celu pobrania kodu JavaScript sieci reklamowej do wyboru reklamy zwycięskiej. W tym kodzie JavaScript znajdziesz wymagane funkcje podpisów. Jeśli stawka jest wyższa niż minimalna stawka, kod JavaScript powinien zwrócić reklamę zewnętrzną, a w przeciwnym razie – wartość null. Umożliwia to pakietowi SDK zapośredniczenia skrócenie łańcucha zapośredniczenia po znalezieniu zwycięzcy.

Po utworzeniu obiektu 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);

Administrowanie zapośredniczeniem kaskadowym

Poniżej znajduje się kolejność działań w procesie zapośredniczenia.

1. Wykonaj selekcję reklam własnych.
2. Przejdź przez łańcuch zapośredniczenia. W przypadku każdej sieci zewnętrznej:
   1. Utwórz AdSelectionFromOutcomeConfig, w tym outcomeId własnego dostawcy i zewnętrznego pakietu SDK.
   2. Wywołaj selectAds() z konfiguracją 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, zwraca reklamę.
3. Jeśli w łańcuchu nie uda się znaleźć zwycięzcy, zwróć reklamę własną.

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

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

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

class MediationNetwork {
    AdSelectionManager adSelectionManager;

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

    public void runAdSelection() {...}

    public void reportImpressions() {...}

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

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

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

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

Raportowanie wyświetleń reklam

W zależności od przebiegu aukcji można zgłosić wyświetlenie reklamy na 2 sposoby. Jeśli jesteś pojedynczym SSP, który prowadzi aukcję, zapoznaj się z tę sekcją. Jeśli zamierzasz wdrożyć zapośredniczenie kaskadowe, wykonaj czynności opisane w sekcji raportowania wyświetleń zapośredniczenia kaskadowego.

Raportowanie wyświetleń w pojedynczym SSP

Po wybraniu reklamy zwycięskiej z ramy procesu 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. Inicjuje obiekt AdSelectionManager.
2. Utwórz obiekt ReportImpressionRequest z identyfikatorem selekcji reklamy.
3. Wywołaj asynchroniczną metodę reportImpression() z obiektem ReportImpressionRequest oraz odpowiednimi obiektami Executor i OutcomeReceiver.

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

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

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

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

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

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

Zainicjuj ReportImpressionRequest za pomocą tych wymaganych parametrów:

• Identyfikator wyboru reklamy: identyfikator unikalny dla użytkownika urządzenia, który umożliwia wybór reklamy.
• Konfiguracja wyboru reklamy: ta sama konfiguracja, która została użyta w wywołaniu selectAds(), z użyciem podawanego identyfikatora 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 onError() wskazuje te możliwe warunki:
  • Jeśli wywołanie zostanie zainicjowane z użyciem nieprawidłowego argumentu wejściowego, AdServicesException wskazuje IllegalArgumentException jako przyczynę.
  • Wszystkie inne błędy otrzymują błąd AdServicesException z IllegalStateException jako przyczyną.

Raportowanie wyświetleń w przypadku zapośredniczenia kaskadowego

Pakiet SDK zapośredniczenia musi śledzić zwycięski pakiet SDK, aby uruchamiać procesy raportowania. Pakiety SDK uczestniczące w łańcuchu zapośredniczenia powinny udostępnić metodę, którą mediator może wywołać, aby aktywować własny przepływ raportowania. Pakiet SDK uczestniczący w aukcji pośredniczącej może zaimplementować własne raportowanie, wykonując powyższe czynności.

SSP-y mogą użyć tego przykładowego kodu pakietu SDK firmy zewnętrznej jako prototypu do dołączania do procesów pośrednictwa:

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

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

Punkty końcowe raportowania wyświetleń

Interfejs API do raportowania wyświetleń wysyła żądania HTTPS GET do punktów końcowych udostępnianych przez platformę sprzedażową i zwycięską platformę zakupową:

Punkt końcowy platformy po stronie kupującego:

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

Punkt końcowy platformy SSP:

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

Ustalanie stawek i raportowanie usług aukcji

Zaszyfrowana odpowiedź z aukcji po stronie serwera zawiera wszystkie niezbędne informacje raportowania, w tym wygenerowane adresy URL na potrzeby raportowania interakcji z reklamami. Podczas odszyfrowania odpowiedzi odpowiednie adresy URL są rejestrowane na platformie, więc raportowanie reklam i wyświetleń przebiega tak samo jak powyżej.

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

Metoda reportImpression() została zaprojektowana tak, aby umożliwić jak najdokładniejsze generowanie raportów.

Zgłaszanie interakcji z reklamami

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

Rejestrowanie się w celu otrzymywania zdarzeń interakcji

Rejestrowanie zdarzeń interakcji odbywa się w funkcjach JavaScript reportWin() kupującego i reportResult() sprzedawcy za pomocą funkcji JavaScript udostępnianej przez platformę: registerAdBeacon. Aby zarejestrować się, by otrzymywać raport o zdarzeniach, wystarczy wywołać funkcję JavaScript platformy z JavaScriptu raportowania. Ten fragment kodu używa właściwości reportWin() kupującego, ale dotyczy to tej samej zasady co reportResult().

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

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

    return reportingUri;
}

Raportowanie zdarzeń interakcji

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

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

Inicjalizacja ReportInteractionRequest z tymi wymaganymi parametrami:

• Identyfikator selekcji reklamy: identyfikator selekcji reklamy pobrany z zwróconego wcześniej zapytaniaAdSelectionOutcome.
• Klucz interakcji: klucz ciągu znaków zdefiniowany przez klienta, opisujący rejestrowane działanie. Musi on być zgodny z kluczem zarejestrowanym przez sprzedawcę lub kupującego w funkcjach JavaScript do raportowania.
• Dane interakcji: ciąg znaków zawierający dane, które mają zostać uwzględnione w raporcie zdarzeń, które są wysyłane z powrotem do serwerów raportowania za pomocą metody POST.
• Miejsca docelowe raportowania: maska bitowa określająca, czy zdarzenia mają być zgłaszane kupującemu, sprzedawcy czy obu. Te flagi są dostarczane przez platformę, a końcową maskę miejsca docelowego można utworzyć za pomocą operacji bitowych. Aby przesłać raport do jednego miejsca docelowego, możesz użyć flagi udostępnionej bezpośrednio przez platformę. Aby przesyłać dane do wielu miejsc docelowych, możesz użyć operatora logicznego OR (|) do łączenia wartości flagi.

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

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

Punkty końcowe raportowania interakcji

Interfejs API interakcji z raportami wysyła żądania HTTPS POST do punktów końcowych udostępnionych przez platformę po stronie sprzedawcy i wygrywającą platformę po stronie kupującego. Protected Audience API dopasuje klucze interakcji do identyfikatorów URI zadeklarowanych w kodzie JavaScript służącym do raportowania i wysyła żądanie POST do każdego punktu końcowego dla każdej zgłaszanej interakcji. Typ treści żądania to zwykły tekst, którego treść jest danymi interakcji.

Możliwie najlepsza obsługa raportowania interakcji

Interfejs reportInteraction() został zaprojektowany tak, aby umożliwić jak najdokładniejsze wykonywanie raportów za pomocą metody POST HTTP.

Codzienna aktualizacja w tle

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

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

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

• Odpowiedź w formacie JSON może zawierać dowolne obsługiwane pola metadanych, które należy zaktualizować.
• Każde pole JSON jest sprawdzane niezależnie. Klient zignoruje wszystkie nieprawidłowo sformatowane pola, co spowoduje, że dane pole nie będzie aktualizowane.
• Pusty komunikat HTTP lub pusty obiekt JSON „{}” nie powoduje aktualizacji metadanych.
• Rozmiar wiadomości z odpowiedzią musi być ograniczony do 10 KB.
• Do korzystania z HTTPS są wymagane wszystkie identyfikatory URI.
• trusted_bidding_uri musi mieć ten sam identyfikator ETLD+1 co kupujący.

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

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

Kod JavaScript do wyboru reklamy

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

Kod JavaScript dostarczony przez kupującego jest pobierany z adresu URL funkcji ustalania stawek określonej w sekcji odbiorców niestandardowych. Zwrócony kod JavaScript powinien zawierać te funkcje:

• generateBid()
• reportWin()

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

• scoreAd()
• reportResult()

generateBid()

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

Parametry wejściowe:

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

• custom_audience_bidding_signals: obiekt JSON wygenerowany przez platformę. Obiekt JSON ma format:

  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 pobrany z usług o tej samej nazwie listy niestandardowych odbiorców uwzględnionych w wyborze reklamy.
  • activation_time i expiration_time to czas aktywacji i wygaśnięcia listy niestandardowych odbiorców wyrażony w sekundach od epoki uniksowej.
  • ca_user_bidding_signals to ciąg JSON określony w polu userBiddingSignals obiektu CustomAudience w momencie jego utworzenia.
  • trusted_bidding_signals, contextual_signals i user_signals to obiekty JSON. Są one przekazywane jako puste obiekty i zostaną wypełnione w przyszłych wersjach. Ich format nie jest narzucany przez platformę, a zarządza nim technologia reklamowa.

Efekt:

• ad: 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: wartość typu float, która określa wartość stawki dla tej reklamy.
• status: liczba całkowita, która może być:
  • 0: oznacza pomyślne wykonanie.
  • 1: (lub dowolna wartość różna od 0) na wypadek, gdyby którykolwiek z sygnałów wejściowych był nieprawidłowy. Jeśli w wyniku generowania stawki zostanie zwrócona wartość inna niż 0, proces ustalania stawek zostanie unieważniony w przypadku wszystkich reklam CA

scoreAd()

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

Parametry wejściowe:

• ad: wyświetl dokumentację generateBid
• bid: wartość stawki reklamy

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

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

• seller_signals: obiekty JSON odczytują się 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 przyszłych wersjach. Format ten nie jest wymuszany przez platformę i jest zarządzany przez technologię reklamową.

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

Dane wyjściowe:

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

selectOutcome()

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

Parametry wejściowe:

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

Dane wyjściowe:

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

reportResult()

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

Parametry wejściowe:

• ad_selection_config: wyświetl dokumentację scoreAds
• render_url: wyrenderowany URL zwycięskiej reklamy.
• bid: stawka zaoferowana za zwycięską reklamę.
• contextual_signals: zobacz dokumentację generateBid

Dane wyjściowe:

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

reportWin()

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

Parametry wejściowe:

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

Dane wyjściowe:

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

registerAdBeacon()

function registerAdBeacon(
  beacons
)

Parametry wejściowe:

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

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

  • interaction_key: ciąg znaków reprezentujący zdarzenie. Jest ona używana przez platformę później podczas raportowania interakcji ze zdarzeniami do wyszukania elementu reporting_uri, który należy powiadomić. Klucz musi być taki sam w przypadku rejestracji przez kupującego lub sprzedającego oraz w raportach sprzedającego.
  • reporting_uri: identyfikator URI do otrzymywania raportów o zdarzeniach. Powinien on dotyczyć konkretnego typu zdarzenia. Musi ono akceptować żądania POST, aby obsługiwać wszelkie dane zgłaszane wraz ze zdarzeniem.

  Na przykład:

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

Gotowe identyfikatory URI funkcji wyboru reklamy

Gotowe identyfikatory URI umożliwiają specjalistom ds. technologii reklamowych określanie funkcji JavaScriptu na potrzeby logiki decydowania o wyborze reklamy w klasach AdSelectionConfig i AdSelectionFromOutcomesConfig. Gotowe identyfikatory URI nie wymagają wywołań sieciowych do pobrania odpowiedniego JavaScriptu. Firmy zajmujące się technologiami reklamowymi mogą używać gotowych identyfikatorów URI bez konieczności konfigurowania zarejestrowanej domeny, która będzie hostować kod JavaScript.

Gotowy identyfikator URI jest tworzony w tym formacie:

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

Platforma Piaskownica prywatności udostępnia JavaScript, który używa informacji z tego URI w czasie wykonywania.

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

• w identyfikatorze URI nie ma żadnego z wymaganych parametrów
• w identyfikatorze URI znajdują się nierozpoznane parametry

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

Przykład zastosowania 1: wybór reklamy

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

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

Ten gotowy adres URI udostępnia kod JavaScript, który po ustaleniu stawek wybiera reklamę z najwyższą stawką. Udostępnia też podstawową funkcję raportowania do raportowania wyników render_uri i bid zwycięzcy.

Parametry wymagane

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

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

Wykorzystanie

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

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

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

W przypadku ad-selection-from-outcomes gotowe identyfikatory URI obsługują przepływ pracy selectAds(AdSelectionFromOutcomesConfig).

Nazwa gotowego identyfikatora URI: waterfall-mediation-truncation

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

Parametry wymagane

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

Wykorzystanie

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

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

Testowanie

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

Wymagania wstępne

Podczas wybierania reklamy i raportowania wyświetleń interfejs Protected Audience API wymaga JavaScriptu. Kod JavaScript można udostępniać w środowisku testowym na 2 sposoby:

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

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

Punkty końcowe HTTPS

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

1. Punkt końcowy kupującego, który udostępnia logikę ustalania stawek w JavaScript.
2. Punkt końcowy, który udostępnia sygnały określania stawek.
3. Punkt końcowy sprzedawcy, który udostępnia kod JavaScript do podejmowania decyzji.
4. Punkt końcowy, który udostępnia sygnały oceny.
5. Punkt końcowy raportowania wyświetleń zwycięskiego kupującego.
6. Punkt końcowy raportowania wyświetleń sprzedawcy.
7. Punkt końcowy do wyświetlania codziennych aktualizacji dla niestandardowej grupy odbiorców.

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

Zastępowanie pobierania kodu JavaScript z dalszego serwera

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

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

<application
  android:debuggable="true">

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

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

Zastąpienie pobierania kodu JavaScript po stronie sprzedawcy i kupującego jest możliwe niezależnie, ale do wyświetlania kodu JavaScript, dla którego nie udostępniasz zastąpienia, potrzebujesz punktu końcowego HTTPS. Informacje o konfigurowaniu serwera, który obsługuje te przypadki, znajdziesz w pliku README.

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

Zastąp kod JavaScript po stronie sprzedawcy

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

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

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

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

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

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

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

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

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

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

Więcej informacji o poszczególnych polach w AdSelectionConfig znajdziesz w sekcji Uruchom wybór reklamy. Główna różnica polega na tym, że dla parametru decisionLogicUrl można ustawić wartość zmiennej, ponieważ będzie ona ignorowana.

Aby zastąpić kod JavaScript użyty podczas wybierania reklamy, element decisionLogicJs musi zawierać prawidłowe podpisy funkcji po stronie sprzedawcy. Przykład odczytu pliku JavaScript jako ciągu znaków znajdziesz w przykładowej aplikacji Protected Audience API w GitHub.

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ć decyzji i logiki raportowania, które zostały przekazane jako zastąpienie.

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

• Jeśli próba zastąpienia zostanie podjęta za pomocą nieprawidłowych argumentów, AdServiceException wskazuje jako przyczynę IllegalArgumentException.
• Jeśli podejmowana jest próba zastąpienia, gdy aplikacja nie działa w trybie debugowania z włączonymi opcjami programisty, AdServiceException wskazuje IllegalStateException jako przyczynę.

Resetowanie zastąpień po stronie sprzedawcy

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

Aby zresetować zastąpienia dla wszystkich AdSelectionConfigs:

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

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

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

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

Jeśli wywołanie resetAllAdSelectionConfigRemoteOverrides() się nie powiedzie, wywołanie zwrotne OutComeReceiver.onError() zwróci wartość AdServiceException. Jeśli próba usunięcia zastąpień zostanie podjęta w przypadku aplikacji, która nie działa w trybie debugowania i ma włączone opcje dla programistów, AdServiceException wskazuje IllegalStateException jako przyczynę.

Zastąp JavaScript po stronie kupującego

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

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

// Join custom audience

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

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

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

// Join custom audience

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

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

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

Możesz też podać 2 dodatkowe parametry:

• biddingLogicJs: kod JavaScript zawierający logikę kupującego, która jest używana podczas wyboru reklamy. Sprawdź wymagane podpisy funkcji w tym JavaScript.
• trustedBiddingSignals: sygnały 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 przekazanej przez Ciebie jako zastąpienia.

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

• Jeśli próba zastąpienia zostanie podjęta z nieprawidłowymi argumentami, parametr AdServiceException wskazuje jako przyczynę wartość IllegalArgumentException.
• Jeśli próba zastąpienia zostanie podjęta w przypadku aplikacji, która nie działa w trybie debugowania z włączonymi opcjami programisty, AdServiceException wskazuje IllegalStateException jako przyczynę.

Resetowanie zastąpień po stronie kupującego

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

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

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

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

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

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

Jeśli wywołanie funkcji resetCustomAudienceRemoteInfoOverride() zakończy się niepowodzeniem, wywołanie funkcji OutComeReceiver.onError() zwróci wartość AdServiceException. Jeśli zostanie podjęta próba usunięcia zastąpień, gdy aplikacja nie będzie działać w trybie debugowania z włączonymi opcjami programisty, AdServiceException będzie wskazywać IllegalStateException jako przyczynę.

Skonfiguruj serwer raportowania

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

Gdy szukasz definicji OpenAPI, znajdź plik Reporting-server.json. Ten plik zawiera prosty punkt końcowy, który zwraca 200, co odpowiada kodowi odpowiedzi HTTP. Ten punkt końcowy jest używany podczas selectAds() i sygnalizuje interfejsowi Protected Audience API informację, że udało się zakończyć raportowanie wyświetleń.

Funkcje do przetestowania

• Wykonaj ćwiczenie polegające na dołączaniu do listy lub opuszczaniu jej i konfigurowaniu listy niestandardowych odbiorców na podstawie wcześniejszych działań użytkownika.
• Zacznij wybierać reklamy na urządzeniu za pomocą skryptów JavaScript hostowanych zdalnie.
• Zwróć uwagę na to, jak powiązanie aplikacji z ustawieniami niestandardowych odbiorców może wpłynąć na wyniki wyboru reklamy.
• Raportowanie wyświetleń ćwiczeń po wybraniu reklamy.

Ograniczenia

W tabeli poniżej znajdziesz ograniczenia przetwarzania przez interfejs Protected Audience API. Przedstawione limity mogą ulec zmianie w zależności od opinii użytkowników. Aby dowiedzieć się więcej o funkcjach w trakcie opracowywania, przeczytaj informacje o wersji.

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

Twoja opinia jest kluczowym elementem Piaskownicy prywatności na Androida. Daj nam znać o wszelkich problemach lub pomysłach na ulepszenie Piaskownicy prywatności na Androida.