Podczas czytania informacji z Piaskownicy prywatności na urządzeniu z Androidem dokumentacji, kliknij przycisk Podgląd dla programistów lub Beta, aby wybrać używanej wersji programu, ponieważ instrukcje mogą się różnić.
Interfejs Protected Audience API na Androida (dawniej FLEDGE) obejmuje Custom Audience API i Ad Selection API. Platformy technologii reklamowych i reklamodawcy mogą za pomocą tych interfejsów API wyświetlać reklamy dopasowane na podstawie wcześniejszego zaangażowania w aplikację, ogranicza udostępnianie identyfikatorów między aplikacjami i ogranicza udostępnianie aplikacji użytkownika informacji o interakcjach z innymi firmami.
Interfejs Custom Audience API koncentruje się na „niestandardowych odbiorcach”. abstrakcję, która reprezentuje grupę użytkowników o wspólnych zamiarach. An reklamodawca może zarejestrować użytkownika w niestandardowych odbiorcach i powiązać z nim odpowiednie reklamy z nim. Te informacje są przechowywane lokalnie i mogą zostać wykorzystane do przekazania informacji reklamodawcy stawki, filtrowanie i renderowanie reklam.
Interfejs Ad Selection API zapewnia środowisko umożliwiające wielu deweloperom lokalnie przeprowadzasz aukcję dla niestandardowych odbiorców. W tym celu system Uwzględnia trafne reklamy powiązane z niestandardowymi odbiorcami i skuteczność dodatkowe przetwarzanie reklam, które platforma technologii reklamowych zwraca na urządzenie.
Platformy technologii reklamowych mogą zintegrować te interfejsy API, by wdrożyć remarketing, chronią prywatność użytkownika. Obsługa dodatkowych przypadków użycia, takich jak instalacja aplikacji reklam, są planowane w kolejnych wersjach. Więcej informacji o Protected Audience API API na Androida w propozycji projektu.
Z tego przewodnika dowiesz się, jak korzystać z interfejsu Protected Audience API na Androidzie, aby wykonaj te czynności:
- Zarządzanie odbiorcami niestandardowymi
- Konfigurowanie i wyświetlanie wyboru reklam na urządzeniu
- Raportowanie wyświetleń reklam
Zanim zaczniesz
Zanim zaczniesz, wykonaj te czynności:
- Skonfiguruj środowisko programistyczne na potrzeby Piaskownicy prywatności na Androida.
- Zainstaluj obraz systemu na obsługiwanym urządzeniu lub skonfiguruj emulatorowi, który zapewnia obsługę Piaskownicy prywatności na urządzeniach z Androidem.
W terminalu włącz dostęp do interfejsu Protected Audience API (wyłączony). domyślnie) za pomocą tego polecenia adb.
adb shell device_config put adservices ppapi_app_allow_list \"*\"
Dodaj w aplikacji uprawnienie
ACCESS_ADSERVICES_CUSTOM_AUDIENCE
plik manifestu:<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
Odwołaj się do konfiguracji usług reklamowych w elemencie
<application>
tego elementu Twój plik manifestu:<property android:name="android.adservices.AD_SERVICES_CONFIG" android:resource="@xml/ad_services_config" />
Określ zasób XML usług reklamowych, do którego odwołuje się plik manifestu, np.
res/xml/ad_services_config.xml
Więcej informacji o uprawnieniach dotyczących usług reklamowych i kontrolę dostępu do pakietów SDK.<ad-services-config> <custom-audiences allowAllToAccess="true" /> </ad-services-config>
Domyślnie interfejs Ad Selection API wymusza limity z maksymalnej ilości pamięci wykorzystywanej w raportach aukcji lub wyświetleń który skrypt może przydzielić. Funkcja ograniczania pamięci wymaga wersji WebView 105.0.5195.58 lub nowsza. Platforma wymusza sprawdzanie wersji i wywołuje funkcję interfejsy API
selectAds
ireportImpression
zawiodą, jeśli zostanie nie jest zadowolony/zadowolona. Możesz to skonfigurować na 2 sposoby:Opcja 1. Uruchom to polecenie adb, aby dezaktywować sprawdzanie:
adb device_config put fledge_js_isolate_enforce_max_heap_size false
Opcja 2. Zainstaluj WebView w wersji beta ze Sklepu Google Play. Musi to być być równa lub wyższa niż wersja podana wcześniej.
Dołącz do grupy niestandardowych odbiorców
Niestandardowa lista odbiorców reprezentuje grupę użytkowników o wspólnych zamiarach lub zainteresowań określonych przez aplikację reklamodawcy. Aplikacja lub pakiet SDK może używać niestandardowego atrybutu odbiorców, aby wskazać konkretną grupę odbiorców, np. osobę, która opuściła elementy w koszyku na zakupy. Aby asynchronicznie utworzyć niestandardową listę odbiorców lub dołączyć do niej, wykonaj :
- Zainicjuj obiekt
CustomAudienceManager
. - Utwórz obiekt
CustomAudience
, określając kluczowe parametry, takie jak pakiet kupującego i odpowiednia nazwa. Następnie zainicjujJoinCustomAudienceRequest
obiekt zCustomAudience
obiektu. - Wywołaj asynchroniczne polecenie
joinCustomAudience()
zJoinCustomAudienceRequest
i odpowiednieExecutor
oraz ObiektyOutcomeReceiver
.
Kotlin
val customAudienceManager: CustomAudienceManager =
context.getSystemService(CustomAudienceManager::class.java)
// Initialize a custom audience.
val audience = CustomAudience.Builder()
.setBuyer(buyer)
.setName(name)
...
.build()
// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()
// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
executor,
outcomeReceiver)
Java
CustomAudienceManager customAudienceManager =
context.getSystemService(CustomAudienceManager.class);
// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
.setBuyer(buyer)
.setName(name)
...
.build();
// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();
// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
executor,
outcomeReceiver);
Kombinacja poniższych parametrów jednoznacznie identyfikuje każdy
Obiekt CustomAudience
na urządzeniu:
owner
: nazwa pakietu aplikacji właściciela. Domyślnie jest ona ustawiona na nazwa pakietu aplikacji wywołującej.buyer
: identyfikator sieci reklamowej kupującego, która zarządza reklamami dla tego niestandardowego zamówienia z całego świata.name
: dowolna nazwa lub identyfikator niestandardowej listy odbiorców.
Wielokrotne wywoływanie aplikacji joinCustomAudience()
z innym wystąpieniem
CustomAudience
aktualizuje wszystkie istniejące CustomAudience
przy użyciu
pasujące do parametrów owner, buyer
i name
. Aby chronić prywatność,
wynik interfejsu API nie rozróżnia „tworzenia” i „zaktualizuj”.
Dodatkowo CustomAudience
musi być utworzony z tymi wymaganymi.
parametry:
- URL codziennej aktualizacji: adres URL HTTPS wysyłany codziennie w tle w celu aktualizować sygnały określania stawek przez użytkownika, dane dotyczące zaufanego określania stawek na liście odbiorców niestandardowych renderowania adresów URL i metadanych reklam.
- Adres URL logiki określania stawek: adres URL HTTPS wysłany do użytkownika podczas wyboru reklamy w celu pobrania parametru zasady ustalania stawek za pomocą JavaScriptu przez kupującego. Sprawdź wymagane podpisy funkcji. w tym skrypcie JavaScript.
- Identyfikatory renderowania reklam: dowolny identyfikator ustawiony przez kupującego ds. technologii reklamowych. To jest optymalizacji generowania ładunku dla firmy B&A.
Opcjonalne parametry obiektu CustomAudience
mogą obejmować:
- Czas aktywacji: niestandardowe grupy odbiorców mogą uczestniczyć tylko w wyborze reklamy oraz codzienne aktualizacje po aktywacji. Pozwala to na zaangażowanie np. nieaktywnych użytkowników aplikacji.
- Czas ważności: przyszły czas, po którym niestandardowa lista odbiorców zostanie zostały usunięte z urządzenia.
- Sygnały dotyczące określania stawek przez użytkownika: ciąg znaków JSON zawierający sygnały użytkownika, takie jak preferowany język użytkownika, stosowany przez JavaScript logikę ustalania stawek kupującego do generowania stawek w procesie wyboru reklamy. Ten format pomaga technologii reklamowej platformy wykorzystują kod na różnych platformach i ułatwiają jego wykorzystanie w języku JavaScript. funkcji.
- Zaufane dane określania stawek: adres URL HTTPS i lista ciągów znaków użytych podczas proces wyboru reklamy, który pobiera sygnały ustalania stawek z zaufanej pary klucz-wartość posprzedażna.
- Reklamy: lista obiektów
AdData
odpowiadających reklamom, dla których mają uczestniczyć w wyborze reklamy. Każdy obiektAdData
składa się z tych elementów:- URL renderowania: adres URL HTTPS, którego dotyczy zapytanie wyrenderowane w celu wyrenderowania ostatecznej reklamy.
- Metadane: obiekt JSON zserializowany jako ciąg znaków zawierający informacje do nie są uwzględniane przez logikę ustalania stawek przez kupującego w procesie wyboru reklamy.
- Filtry reklam: klasa zawierająca wszystkie informacje wymagane do działania aplikacji. zainstalować filtrowanie reklam i ograniczenie liczby wyświetleń podczas ich wyboru.
Oto przykład tworzenia instancji obiektu CustomAudience
:
Kotlin
// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
.setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
.setName("example-custom-audience-name")
.setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
.setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
.build()
Java
// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
.setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
.setName("example-custom-audience-name")
.setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
.setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
.build();
Obsługa wyników JoinCustomAudience()
Asynchroniczna metoda joinCustomAudience()
korzysta z metody OutcomeReceiver
, aby sygnalizować wynik wywołania interfejsu API.
- Wywołanie zwrotne
onResult()
oznacza, że lista odbiorców niestandardowych została prawidłowo utworzona. utworzonych lub zaktualizowanych. - Wywołanie zwrotne
onError()
wskazuje 2 możliwe warunki.- Jeśli
JoinCustomAudienceRequest
zainicjowano nieprawidłowym kodem argumentówAdServicesException
oznaczaIllegalArgumentException
. - Wszystkie inne błędy otrzymują komunikat
AdServicesException
z atrybutemIllegalStateException
.
- Jeśli
Oto przykład obsługi wyniku funkcji joinCustomAudience()
:
Kotlin
var callback: OutcomeReceiver<Void, AdServicesException> =
object : OutcomeReceiver<Void, AdServicesException> {
override fun onResult(result: Void) {
Log.i("CustomAudience", "Completed joinCustomAudience")
}
override fun onError(error: AdServicesException) {
// Handle error
Log.e("CustomAudience", "Error executing joinCustomAudience", error)
}
};
Java
OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
@Override
public void onResult(@NonNull Void result) {
Log.i("CustomAudience", "Completed joinCustomAudience");
}
@Override
public void onError(@NonNull AdServicesException error) {
// Handle error
Log.e("CustomAudience", "Error executing joinCustomAudience", error);
}
};
Opuść grupę odbiorców niestandardowych
Jeśli użytkownik nie spełnia już kryteriów biznesowych dla danego
aplikacji lub pakietu SDK, aplikacja lub pakiet SDK może wywołać metodę leaveCustomAudience()
, by usunąć niestandardową
odbiorców z danego urządzenia. Aby usunąć kolumnę CustomAudience
na podstawie jej niepowtarzalnych danych
wykonaj te czynności:
- Zainicjuj obiekt
CustomAudienceManager
. - Zainicjuj pole
LeaveCustomAudienceRequest
niestandardową listą odbiorcówbuyer
iname
. Więcej informacji o tych polach do wprowadzania danych znajdziesz w artykule „Dołącz do grupy niestandardowych odbiorców”. - Wywołaj asynchroniczną metodę
leaveCustomAudience()
za pomocą funkcjiLeaveCustomAudienceRequest
i odpowiednieExecutor
oraz ObiektyOutcomeReceiver
.
Kotlin
val customAudienceManager: CustomAudienceManager =
context.getSystemService(CustomAudienceManager::class.java)
// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
LeaveCustomAudienceRequest.Builder()
.setBuyer(buyer)
.setName(name)
.build()
// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
leaveCustomAudienceRequest,
executor,
outcomeReceiver)
Java
CustomAudienceManager customAudienceManager =
context.getSystemService(CustomAudienceManager.class);
// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
new LeaveCustomAudienceRequest.Builder()
.setBuyer(buyer)
.setName(name)
.build();
// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
leaveCustomAudienceRequest,
executor,
outcomeReceiver);
Podobnie jak w przypadku wywoływania usługi joinCustomAudience()
, sygnały OutcomeReceiver
na koniec wywołania interfejsu API. Ze względu na ochronę prywatności wynik błędu
odróżniać błędy wewnętrzne od nieprawidłowych argumentów. onResult()
wywołanie zwrotne jest wywoływane po zakończeniu wywołania interfejsu API niezależnie od tego, czy
usunięto niestandardową listę odbiorców.
Uruchom wybór reklamy
Aby do wybierania reklam używać interfejsu Protected Audience API, wywołaj metodę selectAds()
:
- Zainicjuj obiekt
AdSelectionManager
. - Utwórz obiekt
AdSelectionConfig
. - Wywołaj asynchroniczną metodę
selectAds()
za pomocą funkcjiAdSelectionConfig
i odpowiednieExecutor
oraz ObiektyOutcomeReceiver
.
Kotlin
val adSelectionManager: AdSelectionManager =
context.getSystemService(AdSelectionManager::class.java)
// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
AdSelectionConfig.Builder().setSeller(seller)
.setDecisionLogicUrl(decisionLogicUrl)
.setCustomAudienceBuyers(customAudienceBuyers)
.setAdSelectionSignals(adSelectionSignals)
.setSellerSignals(sellerSignals)
.setPerBuyerSignals(perBuyerSignals)
.setBuyerContextualAds(
Collections.singletonMap(
contextualAds.getBuyer(), contextualAds
)
).build()
// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
adSelectionConfig, executor, outcomeReceiver
)
Java
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
new AdSelectionConfig.Builder()
.setSeller(seller)
.setDecisionLogicUrl(decisionLogicUrl)
.setCustomAudienceBuyers(customAudienceBuyers)
.setAdSelectionSignals(adSelectionSignals)
.setSellerSignals(sellerSignals)
.setPerBuyerSignals(perBuyerSignals)
.setBuyerContextualAds(
Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
)
.build();
// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(adSelectionConfig, executor, outcomeReceiver);
Metoda selectAds()
wymaga danych wejściowych AdSelectionConfig
, gdzie
musisz określić następujące wymagane parametry:
- Sprzedawca: identyfikator sieci reklamowej sprzedawcy, która inicjuje wybór reklamy.
- Adres URL mechanizmu decyzyjnego: adres URL HTTPS wysłany w celu uzyskania adresu sieci reklamowej sprzedawcy
to logika JavaScriptu.
- Adres URL HTTPS: wysłano zapytanie o logikę JavaScript sieci reklamowej sprzedawcy. Sprawdź wymagane podpisy funkcji.
- Gotowe identyfikatory URI: są zgodne z formatem wyboru reklamy FLEDGE.
Jeśli nieprawidłowy lub nieprawidłowy format to
IllegalArgumentException
jest przekazywany gotowy identyfikator URI.
- Kupujący niestandardowych odbiorców: pełna lista identyfikatorów sieci reklamowych kupujących.
które sprzedawca może uczestniczyć w procesie wyboru reklam.
Te identyfikatory kupujących odpowiadają
CustomAudience.getBuyer()
z niestandardowych odbiorców.
Opcjonalnie możesz określić te parametry, aby lepiej dostosować reklamę wybór:
- Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający
które mają być wykorzystywane przez logikę określania stawek przez kupującego pobieraną z aplikacji JavaScript
CustomAudience.getBiddingLogicUrl()
- Sygnały sprzedawcy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały
są uwzględniane przez logikę podejmowania decyzji w zakresie JavaScriptu pobieranych przez sprzedawcę z
AdSelectionConfig.getDecisionLogicUrl()
- Sygnały według kupującego: mapa obiektów JSON zserializowanych jako ciągi znaków,
które zawierają sygnały, które mogą być wykorzystane przez konkretnych kupujących logika określania stawek w JavaScripcie
pobrane z tabeli
CustomAudience.getBiddingLogicUrl()
, które są identyfikowane przez pola kupujących uczestniczących w programie niestandardowych odbiorców. - Reklamy kontekstowe: zbiór propozycji reklam, które są zbierane bezpośrednio. od kupujących podczas aukcji, która odbywa się poza chronioną listą odbiorców aukcji.
Po wybraniu reklamy wyniki, stawki i sygnały są zachowywane wewnętrznie
do raportowania. Wywołanie zwrotne OutcomeReceiver.onResult()
zwraca błąd
AdSelectionOutcome
, który zawiera:
- Wyrenderowany URL zwycięskiej reklamy pobrany z
AdData.getRenderUrl()
. - Identyfikator wyboru reklamy unikalny dla użytkownika urządzenia. Ten identyfikator jest używany do raportowania wyświetlenie reklamy.
Jeśli nie można dokonać wyboru reklamy z takich powodów:
nieprawidłowych argumentów, przekroczenia limitu czasu lub nadmiernego zużycia zasobów,
Wywołanie zwrotne OutcomeReceiver.onError()
udostępnia parametr AdServicesException
z takimi zachowaniami:
- Jeśli wybór reklamy został zainicjowany za pomocą nieprawidłowych argumentów, parametr
AdServicesException
wskazujeIllegalArgumentException
jako przyczyna. - Wszystkie inne błędy otrzymują komunikat
AdServicesException
z atrybutemIllegalStateException
.
Reklamy kontekstowe
Funkcja Protected Audience API może uwzględniać reklamy kontekstowe w aukcji chronionej.
Reklamy kontekstowe muszą być wybrane na serwerze technologii reklam i zwrócone do
poza interfejsami Protected Audience API. Można wówczas użyć reklam kontekstowych,
w aukcji przy użyciu AdSelectionConfig
. W tym momencie funkcja
tak samo jak w przypadku reklam na urządzenia, łącznie z możliwością filtrowania wykluczających reklam. Gdy funkcja
Aukcja z Protected Audience API została zakończona, musisz wywołać
reportImpression()
Wywołuje to funkcję reportWin()
w zwycięskiej reklamie kontekstowej w:
jak w przypadku raportowania wyświetleń, aby otrzymać zwycięską reklamę
urządzenia. Każda reklama kontekstowa wymaga kupującego, stawki, linku do funkcji raportowania,
wyrenderowany URL
i metadane reklamy.
Aby można było wdrożyć w aplikacji reklamy kontekstowe, aplikacja docelowa musi utworzyć
ContextualAds
obiekt:
Kotlin
val contextualAds: ContextualAds =
Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
//Pass in your valid app install ads
.setDecisionLogicUri(mContextualLogicUri)
.setAdsWithBid(appInstallAd)
.build()
Java
ContextualAds contextualAds = new ContextualAds.Builder()
.setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
.setDecisionLogicUri(mContextualLogicUri)
//Pass in your valid app install ads
.setAdsWithBid(appInstallAd)
.build();
Powstały obiekt ContextualAds
można następnie przekazać podczas tworzenia
AdSelectionConfig
:
Kotlin
// Create a new ad
val noFilterAd: AdData = Builder()
.setMetadata(JSONObject().toString())
.setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
.build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)
Java
// Create a new ad
AdData noFilterAd = new AdData.Builder()
.setMetadata(new JSONObject().toString())
.setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
.build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);
Filtrowanie reklam promujących instalację aplikacji
Filtrowanie reklam promujących instalacje aplikacji pomaga filtrować reklamy promujące instalacje aplikacji. które są już zainstalowane na urządzeniu.
Pierwszym krokiem w tym procesie jest określenie, którzy reklamodawcy mogą aby filtrować według zainstalowanego pakietu. Musisz to zrobić w aplikacji, której chcesz użyć kierować daną reklamę.
Kotlin
//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)
//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
request,
mExecutor,
object : OutcomeReceiver<Any?, Exception?>() {
fun onResult(@NonNull ignoredResult: Any?) {
Log.v("[your tag]", "Updated app install advertisers")
}
fun onError(@NonNull error: Exception?) {
Log.e("[your tag]", "Failed to update app install advertisers", error)
}
})
Java
//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);
//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
request,
mExecutor,
new OutcomeReceiver<Object, Exception>() {
@Override
public void onResult(@NonNull Object ignoredResult) {
Log.v("[your tag]", "Updated app install advertisers");
}
@Override
public void onError(@NonNull Exception error) {
Log.e("[your tag]", "Failed to update app install advertisers", error);
}
});
Gdy poprzedni kod zostanie wykonany, przekazani reklamodawcy będą mogli odfiltrowywać zainstalowane aplikacje, które określisz podczas generowania stawek. Jeśli Musisz usunąć reklamodawcę z dostępu do strony, na której można zainstalować tę aplikację stanu, należy uruchomić kod ponownie z usuniętymi informacjami o reklamodawcy.
Następnym krokiem jest skonfigurowanie filtrowania reklam w aplikacji wydawcy. Impreza,
wyświetla reklamę w aplikacji wydawcy (najprawdopodobniej jest to pakiet SDK po stronie dostawców).
musi zainicjować swój obiekt AdFilters
informacjami o tym, które reklamy
związane z aplikacjami, które chcą odfiltrować:
Kotlin
// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
Builder().setPackageNames(setOf("example.target.app")).build()
).build()
Java
// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
new AppInstallFilters.Builder()
.setPackageNames(Collections.singleton("example.target.app"))
.build())
.build();
Wydawcy korzystający z usługi DSP mogą też ustawić AdFilter
w przypadku reklam znajdujących się w
dla niestandardowych odbiorców.
AdFilters
można również przekazać podczas tworzenia nowej instancji AdData
obiekt:
Kotlin
// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
Builder().setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
.setAdFilters(filters).build()
Java
// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
.setAdFilters(filters)
.build();
Filtrowanie limitu wyświetleń na użytkownika
Filtrowanie limitu wyświetleń na użytkownika umożliwia technikom reklamowym ograniczenie liczby wyświetleń reklamy wyświetlane. Filtrowanie limitu wyświetleń na użytkownika zmniejsza ryzyko nadmiernej ekspozycji reklamy i optymalizuje wyboru reklamy w danej kampanii reklamowej.
Filtr limitu wyświetleń na użytkownika składa się z 2 głównych elementów: typu zdarzenia reklamowego klucz licznika reklam. Dostępne typy zdarzeń reklamowych:
- Win (już wkrótce): zdarzenie wygranej oznacza, że reklama wygrała aukcję. Zdarzenia wygrane są automatycznie aktualizowane przez interfejs Protected Audience API i nie mogą bezpośrednio przez programistę. Dane o wygranej są widoczne tylko dla reklam w dla danej niestandardowej grupy odbiorców.
- Wyświetlenie: oddzielnie od
reportImpression
, rozmówcy na urządzeniu (SSP lub MMP) używaupdateAdCounterHistogram()
do wywoływania zdarzeń wyświetlenia w i wskazywać w wybranym przez siebie kodzie. Zdarzenia wyświetlenia są widoczne dla wszystkich reklam należących do do danej platformy DSP, bez ograniczania się do reklam z tej samej niestandardowej grupy odbiorców. - Widok: zdarzenie jest wywoływane przez element wywołujący na urządzeniu (SSP lub MMP) w punkcie
wybranego przez siebie kodu za pomocą wywołania
updateAdCounterHistogram()
. Wyświetl zdarzenia są widoczne dla wszystkich reklam należących do danej platformy DSP, a nie tylko do reklam na tej samej platformie Niestandardowi odbiorcy. - Kliknięcie: zdarzenie jest wywoływane przez element wywołujący na urządzeniu (SSP lub MMP) w punkcie
wybranego przez siebie kodu za pomocą wywołania
updateAdCounterHistogram()
. Zdarzenia kliknięcia są widoczne dla wszystkich reklam należących do danej platformy DSP, a nie tylko dla reklam na platformie tych samych niestandardowych odbiorców.
W aplikacji wydawcy reklama wywoływana jest przez platformę SSP lub MMP widoczną na urządzeniu.
zdarzeń. Po wywołaniu funkcji updateAdCounterHistogram()
licznik częstotliwości
jest zwiększany, tak aby przyszłe aukcje były
informacji na temat ekspozycji użytkownika na daną reklamę. Typy zdarzeń reklamowych nie są
są powiązane z odpowiednimi działaniami użytkownika i stanowią wskazówki,
aby utworzyć strukturę systemu zdarzeń. Aby zwiększyć liczniki reklam w momencie
zdarzenie, użytkownik na urządzeniu podaje identyfikator wyboru reklamy zwycięskiej aukcji reklam.
Klucze licznika reklam to dowolne 32-bitowe liczby całkowite ze znakiem i przypisane przez reklamę kupującego i odpowiadają one określonemu zbiorowi reklam zdefiniowanemu przez platformę DSP. Od reklamy są ograniczone tylko do reklam należących do danej platformy DSP, mogą one wybrać bez nakładania się histogramów z innej technologii reklamowej. Licznik reklam klucze są używane do zwiększania liczby identyfikatorów specyficznych dla platformy DSP w reklamach tej platformy lub w jej obrębie dla danej niestandardowej grupy odbiorców, aby odfiltrować reklamy z przyszłych aukcji.
Klucze licznika można wykorzystać do nadania priorytetu reklamom, które z większym prawdopodobieństwem interesująca użytkownika na podstawie jego interakcji z innymi reklamami w danej technologii reklamowej nabywcy. Na przykład reklama, która otrzymała dużą liczbę wyświetleń zaangażowanie pochodzące ze zwycięskich aukcji reklam, obejrzeń i kliknięć, reprezentuje punkt danych. Aby dodatkowo zilustrować ten punkt: reklama kijów golfowych dla leworęcznych może wskazywać, że użytkownik nie jest zainteresowany reklamami dla praworęcznych. O filtr limitu wyświetleń na użytkownika ustawiony dla klawisza licznika przypisanego do reklam leworęcznych może odfiltrowywać reklamy klubów praworęcznych.
Aby używać w aukcji ograniczenia liczby wyświetleń, musisz najpierw utworzyć
KeyedFrequencyCap
obiektów jak pokazano poniżej:
Kotlin
// Value used when incrementing frequency counter
val adCounterKey = 123
// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
adCounterKey, 2, Duration.ofSeconds(10)
).build()
// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
adCounterKey, 1, Duration.ofSeconds(10)
).build()
Java
// Value used when incrementing frequency counter
int adCounterKey = 123;
// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
new KeyedFrequencyCap.Builder(
adCounterKey, 2, Duration.ofSeconds(10)
).build();
// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
new KeyedFrequencyCap.Builder(
adCounterKey, 1, Duration.ofSeconds(10)
).build();
Po utworzeniu obiektów KeyedFrequencyCap
możesz przekazać je do
AdFilters
obiekt.
Kotlin
val filters: AdFilters = Builder()
.setFrequencyCapFilters(
Builder()
.setKeyedFrequencyCapsForImpressionEvents(
ImmutableObject.of(keyedFrequencyCapForImpression)
)
.setKeyedFrequencyCapsForClickEvents(
ImmutableObject.of(keyedFrequencyCapForClick)
)
).build()
Java
AdFilters filters = new AdFilters.Builder()
.setFrequencyCapFilters(new FrequencyCapFilters.Builder()
.setKeyedFrequencyCapsForImpressionEvents(
ImmutableObject.of(keyedFrequencyCapForImpression)
)
.setKeyedFrequencyCapsForClickEvents(
ImmutableObject.of(keyedFrequencyCapForClick)
)
).build();
Gdy obiekt AdFilters
jest zapełniany filtrami limitu wyświetleń na użytkownika, może
są przekazywane podczas tworzenia listy odbiorców niestandardowych:
Kotlin
// Initialize a custom audience.
val audience: CustomAudience = Builder()
.setBuyer(buyer)
.setName(name)
.setAds(
listOf(
Builder()
.setRenderUri(renderUri)
.setMetadata(JSONObject().toString())
.setAdFilters(filters)
.setAdCounterKeys(adCounterKeys)
.build()
)
).build()
Java
// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
.setBuyer(buyer)
.setName(name)
.setAds(Collections.singletonList(new AdData.Builder()
.setRenderUri(renderUri)
.setMetadata(new JSONObject().toString())
.setAdFilters(filters)
.setAdCounterKeys(adCounterKeys)
.build()))
.build();
Gdy zastosujesz filtry limitu wyświetleń na użytkownika w niestandardowej liście odbiorców, platforma SSP może i wywoływanie niezbędnych zdarzeń kliknięcia, obejrzenia lub wyświetlenia.
Kotlin
val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()
val request: UpdateAdCounterHistogramRequest = Builder(
adSelectionId,
FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
callerAdTech
).build()
Java
AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();
UpdateAdCounterHistogramRequest request =
new UpdateAdCounterHistogramRequest.Builder(
adSelectionId,
FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
callerAdTech
).build();
Reklamy, które osiągnęły ustalony wcześniej limit filtra wyświetleń na użytkownika, są odfiltrowywane aukcji. Filtrowanie następuje przed wykonaniem logiki określania stawek w przypadku aukcji na urządzeniu oraz gdy ładunek jest generowany na potrzeby określania stawek Aukcja pomaga w aukcji usług. Ten zestaw narzędzi zapewnia specjalistom ds. reklamy swobodę korzystania interakcji między użytkownikami a reklamami w ramach niestandardowych list odbiorców w celu skierowania reklamy przy jednoczesnym minimalizowaniu nadmiernej ekspozycji na reklamę.
Filtrowanie reklam kontekstowych bez wywołań sieciowych
Jeśli nie ma popytu na remarketing na danym urządzeniu, możesz wyświetlać reklamy reklam kontekstowych bez wywołań sieciowych. Z gotowymi adresami URI i listą kontekstowych ze stawkami, platforma może pominąć logikę ustalania stawek, sygnały wykorzystywane w ustalaniu stawek i sygnały oceny. Platforma używa gotowego identyfikatora URI do wybierania reklamę kontekstową o najwyższej stawce.
Aby skrócić czas oczekiwania, specjaliści ds. technologii reklamowych mogą uruchomić proces wyboru reklamy obejmujący tylko
reklam kontekstowych z funkcją filtrowania reklam bez wywołań sieciowych. To jest
Można to osiągnąć za pomocą gotowych identyfikatorów URI do oceny sygnałów. Zajrzyj do sekcji Obsługiwane
gotową sekcję przypadków użycia i nazw identyfikatorów URI dla listy scoreAds
implementacji.
Aby wyświetlać wybrane reklamy bez wywołań sieciowych:
- Konfigurowanie filtrowania reklam
- Tworzenie reklam kontekstowych
Utwórz obiekt
AdSelectionConfig
z tymi elementami:- Pusta lista kupujących.
- Gotowy identyfikator URI do wyboru najwyższej stawki
- Reklamy kontekstowe
- Pusty identyfikator URI sygnałów punktowych. Pusty identyfikator URI może wskazywać, , że nie chcesz korzystać z pobierania zaufanych sygnałów na potrzeby punktacji:
Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting"); // Initialize AdSelectionConfig AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder() .setSeller(seller) .setDecisionLogicUri(prebuiltURIScoringUri) .setCustomAudienceBuyers(Collections.emptyList()) .setAdSelectionSignals(adSelectionSignals) .setSellerSignals(sellerSignals) .setPerBuyerSignals(perBuyerSignals) .setBuyerContextualAds(buyerContextualAds) .setTrustedScoringSignalsUri(Uri.EMPTY) .build();
Uruchom wybór reklamy:
adSelectionManager.selectAds( adSelectionConfig, executor, outcomeReceiver);
Uruchamiaj własny kod JavaScript do raportowania i używaj gotowych identyfikatorów URI
Obecnie platforma Piaskownicy prywatności ma tylko podstawowy kod JavaScript do raportowania
jest dostępna dla gotowych identyfikatorów URI. Jeśli chcesz prowadzić
raportowanie JavaScriptu przy jednoczesnym korzystaniu z gotowych identyfikatorów URI na potrzeby reklam o krótkim czasie oczekiwania
możesz zastąpić ustawienie DecisionLogicUri
między wyborem reklamy
raportów.
- Wykonaj odpowiednie czynności, aby wybrać reklamy na potrzeby reklam kontekstowych za pomocą gotowych identyfikatorów URI.
Zanim zaczniesz generować raporty, utwórz kopię raportu
AdSelectionConfig
adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder() // Replace <urlToFetchYourReportingJS> with your own URL: .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>)) .build();
Generowanie raportów o wyświetleniach
// adSelectionId is from the result of the previous selectAds run ReportImpressionRequest request = new ReportImpressionRequest( adSelectionId, adSelectionConfigWithYourReportingJS); adSelectionManager.reportImpression( request, executor, outcomeReceiver);
Uruchom zapośredniczenie kaskadowe
Zapośredniczenie kaskadowe wymaga korzystania z wielu zewnętrznych pakietów SDK (sieci zewnętrznych) jest prowadzona przez własną sieć zapośredniczenia SDK. Zapośredniczenie kaskadowe to Tak samo niezależnie od tego, czy aukcja miała miejsce na urządzeniu czy Określanie stawek Usługi aukcyjne.
Sieci innych firm
Sieci zewnętrzne muszą zapewnić adapter, który pozwoli sieci zapośredniczeń wywołują metody niezbędne do przeprowadzenia aukcji:
- Uruchom wybór reklamy
- Raportowanie wyświetleń
Oto przykład adaptera sieci zapośredniczeń:
Kotlin
class NetworkAdaptor {
private val adSelectionManager : AdSelectionManager
init {
adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
}
fun selectAds() {...}
fun reportImpressions() {...}
}
Java
class NetworkAdaptor {
AdSelectionManager adSelectionManager;
public NetworkAdaptor() {
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
}
public void selectAds() {...}
public void reportImpressions() {...}
}
Każdy pakiet SDK ma własnych menedżerów i klientów oraz menedżerów usługi wyboru reklamy.
Implementacja za pomocą funkcji selectAds
i reportImpressions
. Dostawcy pakietów SDK mogą zapoznać się z tymi informacjami:
sekcji poświęconej wybieraniu reklam w aukcjach na urządzeniu lub B&A
wyjaśnienia dotyczących aukcji B&A. Postępuj zgodnie z instrukcjami zgłaszania reklamy
wyświetlenia (po raporcie wyświetleń na jednej platformie SSP dotyczącym
i raportowania danych.
Sieć zapośredniczeń
Podobnie jak sieci zewnętrzne, sieci zapośredniczenia muszą mieć te parametry: selectAds
oraz
reportImpression
. Zapoznaj się z sekcjami o wyświetlaniu reklam
wyboru reklam i raportowanie wyświetleń reklam.
Sieci zapośredniczeń odpowiadają za prowadzenie łańcucha zapośredniczenia i umieszczanie w łańcuchu zapośredniczenia. Z następnej sekcji dowiesz się, jak skonfigurować i wykonam ten proces.
Pobieranie łańcucha zapośredniczenia i minimalnych stawek
Sieć zapośredniczenia jest odpowiedzialna za pobieranie danych własnych.
reklam kontekstowych, łańcucha zapośredniczenia i sieci zewnętrznych minimalne stawki (3P). Ten
może wystąpić w żądaniu pobrania reklam kontekstowych realizowanych w ramach zapośredniczenia
Łańcuch zapośredniczenia określa sposób iteracji w sieciach zewnętrznych,
, a stawki minimalne mogą być przekazywane do procesu aukcji jako adSelectionSignals
.
Miejsca docelowe w sieci w łańcuchu zapośredniczenia
Pakiet SDK zapośredniczenia może umieścić się w łańcuchu zapośredniczenia na podstawie aktualnego eCPM
własnych stawek. W interfejsie Protected Audience API stawki reklamowe są nieprzezroczyste. Mediacja
Aby porównać dane własne, pakiet SDK powinien używać parametru AdSelectionFromOutcomesConfig
stawki reklamy do stawki minimalnej w kolejnej sieci zewnętrznej w łańcuchu. Jeśli stawka własna wynosi
wyższy od minimalnej stawki, oznacza to, że pakiet SDK zapośredniczenia jest umieszczony przed
sieci zewnętrznej.
Uruchom wybór reklamy
Aby pobrać kandydaturę do reklamy własnej, sieć zapośredniczenia może uruchomić żądanie na urządzeniu
aukcji, postępuj zgodnie z instrukcjami z sekcji Uruchom wybór reklamy. Generuje
Własna kandydująca reklama, stawka i AdSelectionId
używane w zapośredniczeniu
proces tworzenia konta.
Tworzenie obiektu AdSelectionFromResultsConfig
Pole AdSelectionFromOutcomesConfig
umożliwia sieci zapośredniczenia przekazywanie listy
z AdSelectionIds
(wyniki poprzednich aukcji), sygnały wyboru reklamy oraz
identyfikator URI umożliwiający pobranie kodu JavaScriptu, który wybiera reklamę spośród kilku kandydatów. Lista
identyfikatorów AdSelectionId wraz ze stawkami, a sygnały są przekazywane do
JavaScript, który może zwrócić jeden z tych elementów (AdSelectionIds
), jeśli przebije stawkę
ceny minimalnej lub brak, jeśli łańcuch zapośredniczenia ma być kontynuowany.
Sieci zapośredniczenia tworzą AdSelectionFromOutcomesConfig
na podstawie danych własnych
AdSelectionId
z poprzedniej sekcji oraz minimalną stawkę dla sieci zewnętrznej
są brane pod uwagę. Należy utworzyć nowy element AdSelectionFromOutcomesConfig
dla każdego etapu łańcucha zapośredniczenia.
Kotlin
fun runSelectOutcome(
adSelectionClient : AdSelectionClient,
outcome1p : AdSelectionOutcome,
network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
val config = AdSelectionFromOutcomesConfig.Builder()
.setSeller(seller)
.setAdSelectionIds(listOf(outcome1p))
.setSelectionSignals({"bid_floor": bid_floor})
.setSelectionLogicUri(selectionLogicUri)
.build()
return adSelectionClient.selectAds(config)
}
Java
public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
NetworkAdapter network3p) {
AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
.setSeller(seller)
.setAdSelectionIds(Collection.singletonList(outcome1p))
.setSelectionSignals({"bid_floor": bid_floor})
.setSelectionLogicUri(selectionLogicUri)
.build();
return adSelectionClient.selectAds(config){}
}
Zastąpienie metody selectAds()
w przypadku zapośredniczenia kaskadowego wymaga parametru
Pole wejściowe AdSelectionFromOutcomesConfig
, gdzie należy określić
wymagane parametry:
- Sprzedawca: identyfikator sieci reklamowej sprzedawcy, która inicjuje wybór reklamy.
- AdSelectionIds: pojedyncza lista poprzednich uruchomień
selectAds()
dla danych własnych. reklama. - Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający które mają być używane przez logikę ustalania stawek przez kupującego. W takim przypadku uwzględnij minimalną stawkę. pobranych dla danej sieci zewnętrznej.
- Identyfikator URI logiki wyboru: adres URL HTTPS wysłany do użytkownika podczas wyboru reklamy w celu pobrania
JavaScript sieci zapośredniczenia do wyboru zwycięskiej reklamy. Zobacz wymagane
podpisy funkcji w tym skrypcie JavaScript. JavaScript powinien zwrócić parametr
Reklama innej firmy, jeśli stawka jest wyższa niż minimalna stawka lub z innego powodu zwraca
null
. Dzięki temu pakiet SDK zapośredniczenia może skrócić łańcuch zapośredniczenia, gdy zwycięzca .
Po utworzeniu obiektu AdSelectionOutcomesConfig
wywołaj metodę selectAds()
sieć innej firmy, która jest pierwsza w łańcuchu.
Kotlin
val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
AdSelectionFromOutcomesConfig.Builder()
.setSeller(seller)
.setAdSelectionIds(listof(outcome1p))
.setSelectionSignals({"bid_floor": bid_floor})
.setSelectionLogicUri(selectionLogicUri)
.setAdSelectionIds(outcomeIds)
.build()
// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
adSelectionFromOutcomesConfig,
executor,
outcomeReceiver)
Java
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
new AdSelectionFromOutcomesConfig.Builder()
.setSeller(seller)
.setAdSelectionIds(Collection.singletonList(outcome1p))
.setSelectionSignals({"bid_floor": bid_floor})
.setSelectionLogicUri(selectionLogicUri)
.setAdSelectionIds(outcomeIds)
.build();
// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
adSelectionFromOutcomesConfig,
executor,
outcomeReceiver);
Administrowanie zapośredniczeniem kaskadowym
Oto kolejność działań przez mediację proces tworzenia konta.
- Wygeneruj własną reklamę.
- Wykonanie iteracji w łańcuchu zapośredniczenia W przypadku każdej sieci zewnętrznej wykonaj te czynności:
- Kompilacja
AdSelectionFromOutcomeConfig
, w tym własneoutcomeId
oraz Minimalna stawka pakietu SDK firmy zewnętrznej. - Wywołaj funkcję
selectAds()
z konfiguracją z poprzedniego kroku. - Jeśli wynik nie jest pusty, zwróć reklamę.
- Wywołaj metodę
selectAds()
obecnego adaptera sieci SDK. Jeśli wynik jest pusty, zwraca reklamę.
- Kompilacja
- Jeśli w łańcuchu nie uda się znaleźć zwycięzcy, zwróć reklamę własną.
Kotlin
fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
: Pair<AdSelectionOutcome, NetworkAdapter> {
val outcome1p = runAdSelection()
var outcome : AdSelectionOutcome
for(network3p in mediationChain) {
outcome = runSelectOutcome(outcome1p, network3p)
if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
return Pair(outcome, this)
}
outcome = network3p.runAdSelection()
if(outcome.hasOutcome()) {
return Pair(outcome, network3p)
}
}
return Pair(outcome1p, this)
}
Java
class MediationNetwork {
AdSelectionManager adSelectionManager;
public MediationNetwork() {
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
}
public void runAdSelection() {...}
public void reportImpressions() {...}
public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
List<NetworkAdapter> mediationChain) {
AdSelectionOutcome outcome1p = runAdSelection();
AdSelectionOutcome outcome;
for(NetworkAdapter network3p: mediationChain) {
if (outcome1p.hasOutcome() &&
(outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
return new Pair<>(outcome, this);
}
if((outcome = network3p.runAdSelection()).hasOutcome()) {
return new Pair<>(outcome, network3p);
}
}
return new Pair<>(outcome1p, this);
}
/* Runs comparison by creating an AdSelectionFromOutcomesConfig */
public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
NetworkAdapter network3p) { ... }
}
Raportowanie wyświetleń reklam
Raportowanie wyświetlenia reklamy odbywa się na 2 sposoby, w zależności od tego, jak aukcja przed uruchomieniem. Jeśli korzystasz z pojedynczej platformy SSP przeprowadzającej aukcję, przejdź do tej sekcji. Jeśli zamierzasz wdrożyć zapośredniczenie kaskadowe, wykonaj czynności opisane na .
Raportowanie wyświetleń w ramach pojedynczej platformy SSP
Po wybraniu zwycięskiej reklamy z procedury wyboru reklamy można ją
zgłaszanie wyświetlenia z powrotem do platform po stronie kupującego i sprzedawcy;
za pomocą metody AdSelectionManager.reportImpression()
. Aby zgłosić reklamę
wyświetlenie:
- Zainicjuj obiekt
AdSelectionManager
. - Utwórz obiekt
ReportImpressionRequest
z identyfikatorem wyboru reklamy. - Wywołaj asynchroniczną metodę
reportImpression()
za pomocą funkcjiReportImpressionRequest
i odpowiednieExecutor
oraz ObiektyOutcomeReceiver
.
Java
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
new ReportImpressionRequest.Builder()
.setAdSelectionId(adSelectionId)
.setAdSelectionConfig(adSelectionConfig)
.build();
// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
reportImpressionRequest,
executor,
outcomeReceiver);
Kotlin
val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
ReportImpressionRequest.Builder()
.setAdSelectionId(adSelectionId)
.setAdSelectionConfig(adSelectionConfig)
.build()
// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
reportImpressionRequest,
executor,
outcomeReceiver)
Zainicjuj ReportImpressionRequest
, używając tych wymaganych elementów
parametry:
- Identyfikator wyboru reklamy: niepowtarzalny identyfikator tylko dla użytkownika urządzenia, który identyfikuje pomyślnego wyboru reklamy.
- Konfiguracja wyboru reklamy: ta sama konfiguracja co w tabeli
selectAds()
. zgodnie z podanym identyfikatorem wyboru reklamy.
Asynchroniczna metoda reportImpression()
korzysta z metody OutcomeReceiver
, aby sygnalizować wynik wywołania interfejsu API.
- Wywołanie zwrotne
onResult()
wskazuje, czy adresy URL raportowania wyświetleń zostały a żądanie zostało zaplanowane. - Wywołanie zwrotne
onError()
wskazuje te możliwe warunki:- Jeśli wywołanie zostanie zainicjowane z nieprawidłowym argumentem wejściowym, funkcja
AdServicesException
oznaczaIllegalArgumentException
jako przyczyna. - Wszystkie inne błędy otrzymują komunikat
AdServicesException
z atrybutemIllegalStateException
.
- Jeśli wywołanie zostanie zainicjowane z nieprawidłowym argumentem wejściowym, funkcja
Kaskadowe raportowanie wyświetleń w ramach zapośredniczenia
Pakiet zapośredniczenia SDK musi śledzić zwycięski pakiet SDK, aby aktywować procesów raportowania. Pakiety SDK uczestniczące w łańcuchu zapośredniczenia powinny przekazywać do wywołania przez mediatora własnego przepływu raportowania. Pakiet SDK biorąc udział w aukcji zapośredniczonej, wykonaj powyższe czynności, aby zaimplementować własne raporty.
Platformy SSP mogą wykorzystać ten przykładowy kod pakietu SDK firmy zewnętrznej jako prototyp procesu dołączania Procesy zapośredniczenia:
Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
mediationSdk.orchestrateMediation(mediationChain);
if (winner.first.hasOutcome()) {
winner.second.reportImpressions(winner.first.getAdSelectionId());
Punkty końcowe raportowania wyświetleń
Interfejs API do raportowania wyświetleń wysyła żądania HTTPS GET do punktów końcowych dostarczanych przez platformę SSP i zwycięską platformę po stronie kupującego:
Punkt końcowy platformy po stronie kupującego:
- Interfejs API korzysta z adresu URL mechanizmu ustalania stawek określonego w liście odbiorców niestandardowych, aby pobiera kod JavaScript dostarczony przez kupującego, który zawiera funkcje logiczne zwracające adresu URL raportowania wyświetleń.
- Wywołaj funkcję JavaScript
reportWin()
, która powinna zwrócić adresu URL raportowania wyświetleń kupującego.
Punkt końcowy platformy sprzedażowej:
- Użyj adresu URL logiki decyzyjnej podanego w
AdSelectionConfig
pobierze kod JavaScript oparty na logice decyzji sprzedawcy. - Wywołaj funkcję JavaScript
reportResult()
, która powinna zwrócić błąd adres URL raportowania wyświetleń sprzedawcy.
Określanie stawek Raporty dotyczące usług aukcyjnych
Aukcja przeprowadzona na podstawie określania stawek Usługi aukcyjne będą zawierać wszystkie niezbędne raportowanie informacji, w tym adresy URL wygenerowane na potrzeby raportowania interakcji z reklamami, zawarte w zaszyfrowanej odpowiedzi z aukcji po stronie serwera. Gdy gdy odpowiedź zostanie odszyfrowana, na platformie zostaną zarejestrowane odpowiednie adresy URL, aby generować raporty o reklamach i wyświetleniach, wykonując te same czynności co powyżej.
Raporty wyświetleń w ramach najlepszych starań
Metoda reportImpression()
została zaprojektowana tak, aby umożliwić z najlepszym wykonaniem
i raportowania danych.
Raportowanie interakcji z reklamami
Protected Audience API umożliwia tworzenie bardziej szczegółowych raportów o interakcjach po wyrenderowaniu reklamy. Mogą to być interakcje takie jak czas wyświetlenia, kliknięcia, najechanie kursorem, lub inne przydatne dane, które można zebrać. Proces ich otrzymywania wymaga wykonania dwóch czynności. Po pierwsze, kupujący i sprzedawcy muszą się zarejestrować, w kodzie JavaScriptu. Następnie klient musi i je zgłaszać.
Rejestracja w celu otrzymywania zdarzeń interakcji
Rejestrowanie na zdarzenia interakcji odbywa się w reportWin()
oraz
funkcji JavaScript sprzedawcy reportResult()
za pomocą funkcji JavaScript
udostępnione przez platformę: registerAdBeacon
. Aby zarejestrować się i otrzymać
w raporcie zdarzeń, wystarczy wywołać funkcję JavaScript platformy
JavaScriptu. Ten fragment kodu używa właściwości reportWin()
kupującego, ale tej samej
dotyczy metody reportResult()
.
reportWin(
adSelectionSignals,
perBuyerSignals,
signalsForBuyer,
contextualSignals,
customAudienceSignals) {
...
// Calculate reportingUri, clickUri, viewUri, and hoverUri
registerAdBeacon("click", clickUri)
registerAdBeacon("view", viewUri)
registerAdBeacon("hover", hoverUri)
return reportingUrl;
}
Raportowanie zdarzeń interakcji
Po zgłoszeniu wyświetlenia klienci mogą zgłaszać interakcje do firmy
wcześniej zarejestrowane, wygrywające platformy po stronie kupującego i sprzedaży
Metoda AdSelectionManager.reportInteraction()
. Aby zgłosić zdarzenie reklamowe:
- Zainicjuj obiekt
AdSelectionManager
. - Utwórz obiekt
ReportInteractionRequest
z identyfikatorem wyboru reklamy. klucz interakcji, dane interakcji i miejsce docelowe raportowania. - Wywoływanie asynchronicznej metody
reportInteraction()
za pomocą obiekturequest
i odpowiednie obiektyExecutor
iOutcomeReceiver
.
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
new ReportInteractionRequest.Builder()
.setAdSelectionId(adSelectionId)
.setInteractionKey("view")
.setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
.setReportingDestinations(
FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
)
.build();
// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportInteraction(
reportImpressionRequest,
executor,
outcomeReceiver);
Zainicjuj ReportInteractionRequest
, używając tych wymaganych elementów
parametry:
- Identyfikator wyboru reklamy: identyfikator wyboru reklamy pobrany ze zwróconego wcześniej
AdSelectionOutcome
- Klucz interakcji: klucz ciągu zdefiniowany przez klienta i opisujący działanie. są zgłaszane. Musi on być zgodny z kluczem zarejestrowanym przez sprzedawcę lub w funkcjach JavaScriptu do raportowania.
- Dane interakcji: ciąg znaków zawierający dane, które zostaną uwzględnione w zdarzeniu. który ma zostać przesłany z powrotem do serwerów raportowania za pomocą metody POST.
- Miejsca docelowe raportowania: maska bitowa określająca, czy zdarzenia powinny być
nabywcy, sprzedawcy lub obu tych stronom. Flagi te są udostępniane przez
platformy i końcowej maski miejsca docelowego można utworzyć za pomocą metody bitowej
operacji. Aby zgłosić problem do jednego miejsca docelowego, możesz użyć flagi dostarczonej przez
bezpośrednio na platformie. Aby wygenerować raport do wielu miejsc docelowych, możesz użyć
LUB (
|
), aby połączyć wartości flag.
Asynchroniczna metoda reportInteraction()
korzysta z metody OutcomeReceiver
, aby sygnalizować wynik wywołania interfejsu API.
- Wywołanie zwrotne
onResult()
wskazuje, że wywołanie interakcji w raporcie jest prawidłowe. - Wywołanie zwrotne
onError()
wskazuje te możliwe warunki:- Jeśli połączenie jest wykonywane w czasie, gdy aplikacja działa w tle,
Zwracany jest element
IllegalStateException
z opisem błędu. - Jeśli dostęp klienta do funkcji
reportInteraction()
zostanie zablokowany, WartośćLimitExceededException
jest zwracana. - Jeśli pakiet nie jest zarejestrowany do wywoływania interfejsów Privacy PreServing API,
Zwracana jest wartość
SecurityException()
. - Jeśli interakcje w raportowaniu aplikacji różnią się od interakcji z aplikacją, która wywołała
selectAds()
, zwracany jestIllegalStateException
.
- Jeśli połączenie jest wykonywane w czasie, gdy aplikacja działa w tle,
Zwracany jest element
- Jeśli użytkownik nie wyraził zgody na włączenie interfejsów API Piaskownicy prywatności, wywołanie dyskretnie się nie powiodły.
Punkty końcowe raportowania interakcji
Interfejs API interakcji z raportami wysyła żądania HTTPS POST do punktów końcowych dostarczanych przez między platformą sprzedaży i zwycięską platformą kupna. Protected Audience API dopasuje klucze interakcji do identyfikatorów URI zadeklarowanych w kodzie JavaScript służącym do raportowania i wysyłaj żądanie POST do każdego punktu końcowego dla każdej zgłaszanej interakcji. Typ treści żądania to zwykły tekst, którego treść jest Dane dotyczące interakcji.
Raportowanie interakcji w ramach najlepszych starań
reportInteraction()
zaprojektowano tak, aby jak najdokładniej wykonywać
za pomocą metody HTTP POST.
Codzienna aktualizacja tła
Gdy tworzysz grupę odbiorców niestandardowych, aplikacja lub pakiet SDK może ją zainicjować metadanych. Dodatkowo platforma może aktualizować następujące elementy niestandardowych z metadanymi odbiorców z codzienną aktualizacją w tle.
- Sygnały dotyczące określania stawek przez użytkownika
- Dane dotyczące zaufanego określania stawek
AdData
lista
Ten proces wysyła zapytania do adresu URL codziennej aktualizacji zdefiniowanego w niestandardowych listach odbiorców. i URL może zwrócić odpowiedź JSON.
- Odpowiedź JSON może zawierać dowolne z obsługiwanych pól metadanych, które wymaga do zaktualizowania.
- Każde pole JSON jest sprawdzane niezależnie. Klient ignoruje wszystkie nieprawidłowych pól, które nie powodują aktualizacji danych w danym polu odpowiedź.
- Pusta odpowiedź HTTP lub pusty obiekt JSON „
{}
” w wyniku nie aktualizacji metadanych. - Rozmiar wiadomości z odpowiedzią musi być ograniczony do 10 KB.
- Do korzystania z HTTPS są wymagane wszystkie identyfikatory URI.
- Domena
trusted_bidding_uri
musi mieć tę samą wartość ETLD+1 co kupujący.
Przykład: odpowiedź JSON z codzienną aktualizacją w tle
{
"user_bidding_signals" : { ... }, // Valid JSON object
"trusted_bidding_data" : {
"trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
"trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
},
'ads' : [
{
"render_uri" : 'www.example-dsp1.com/.../campaign123.html',
'metadata' : { ... } // Valid JSON object
},
{
"render_uri" : 'www.example-dsp1.com/.../campaign456.html',
'metadata' : { ... } // Valid JSON object
},
...
]
}
Kod JavaScript do wyboru reklamy
Proces wyboru reklamy administruje wykonaniem kreacji przesłanych przez kupującego JavaScript dostępny przez sprzedawcę.
Kod JavaScript dostarczony przez kupującego jest pobierany z adresu URL logiki ustalania stawek podanego w polu niestandardowych odbiorców. Zwrócony kod JavaScript powinien zawierać te funkcje:
Kod JavaScript dostarczony przez sprzedawcę jest pobierany z adresu URL procesu decyzyjnego określonego w polu
parametr AdSelectionConfig
interfejsu Ad Selection API. Zwrócone wartości
JavaScript powinien zawierać te funkcje:
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 formacievar ad = { 'render_url': url, 'metadata': json_metadata };
auction_signals, per_buyer_signals
: obiekty JSON określone w aukcji. obiekt konfiguracjicustom_audience_bidding_signals
: obiekt JSON wygenerowany przez platformę. format tego obiektu JSON to:var custom_audience_signals = { "owner":"ca_owner", "buyer":"ca_buyer", "name":"ca_name", "activation_time":"ca_activation_time_epoch_ms", "expiration_time":"ca_expiration_time_epoch_ms", "user_bidding_signals":"ca_user_bidding_signals" }
gdzie:
owner
,buyer
iname
to ciągi tekstowe pobrane z właściwości z parametrem ta sama nazwa listy niestandardowych odbiorców uwzględnionych w wyborze reklamy;activation_time
iexpiration_time
to moment aktywacji oraz wygaśnięcia niestandardowej listy odbiorców, wyrażony w sekundach od czasu utworzenia systemu uniksowego epokaca_user_bidding_signals
to ciąg znaków JSON określony w PoleuserBiddingSignals
obiektuCustomAudience
w momencie utworzeniatrusted_bidding_signals, contextual_signals
iuser_signals
są zapisane w formacie JSON obiektów. Są one przekazywane jako puste obiekty i zostaną wypełnione kolejnych wersji. Ich format nie jest wymuszany przez platformę i jest zarządzany. w dziedzinie technologii reklamowych.
Efekt:
ad
: reklama, której dotyczy stawka. Skrypt może zwrócić kopię otrzymaną reklamę z różnymi metadanymi. Właściwośćrender_url
elementu reklama powinna pozostać niezmieniona.bid
: wartość zmiennoprzecinkowa reprezentująca wartość stawki dla tej reklamy.status
: liczba całkowita, która może być:0
: oznacza pomyślne wykonanie.1
: (lub dowolna wartość różna od 0) na wypadek, gdyby którykolwiek z sygnałów wejściowych był nieprawidłowy. W Jeśli funkcja Wygeneruj stawkę zwraca wartość inną niż zero, proces licytacji unieważniona dla wszystkich reklam CA
scoreAd()
function scoreAd(
ad,
bid,
ad_selection_config,
seller_signals,
trusted_scoring_signals,
contextual_signal,
user_signal,
custom_audience_signal) {
return {'status': 0, 'score': score };
}
Parametry wejściowe:
ad
: wyświetl dokumentacjęgenerateBid
bid
: wartość stawki za reklamę.ad_selection_config
: obiekt JSON reprezentujący klucz ParametrAdSelectionConfig
interfejsu APIselectAds
. Format to:var ad_selection_config = { 'seller': 'seller', 'decision_logic_url': 'url_of_decision_logic', 'custom_audience_buyers': ['buyer1', 'buyer2'], 'auction_signals': auction_signals, 'per_buyer_signals': per_buyer_signals, 'contextual_ads': [ad1, ad2] }
seller_signals
: obiekty JSON odczytane zsellerSignals
Parametr interfejsu APIAdSelectionConfig
trusted_scoring_signal
: odczyt z polaadSelectionSignals
w Parametr interfejsu APIAdSelectionConfig
contextual_signals, user_signals
: obiekty JSON. Obecnie są przekazywane jako puste obiekty i zostaną wypełnione w kolejnych wersjach. Ich format nie jest jest egzekwowana przez platformę i zarządzana przez technologię reklamową.per_buyer_signals
: obiekt JSON odczytany z mapyperBuyerSignal
w Parametr interfejsu APIAdSelectionConfig
używany jako klucz bieżącego parametru niestandardowego Kupujący będący odbiorcami. Puste, jeśli mapa nie zawiera żadnych wpisów dla danego kupującego.
Dane wyjściowe:
score
: wartość zmiennoprzecinkowa określająca wartość wyniku tej reklamy.status
: liczba całkowita, która może być:- 0: oznacza pomyślne wykonanie
- 1: na wypadek, gdyby
customAudienceSignals
były nieprawidłowe - 2: jeśli
AdSelectionConfig
jest nieprawidłowy - 3. Jeśli inne sygnały są nieprawidłowe
- Każda wartość różna od 0 powoduje niepowodzenie procesu; wartość określa typ zgłoszonego wyjątku
selectOutcome()
function selectOutcome(
outcomes,
selection_signals) {
return {'status': 0, 'result': null};
}
Parametry wejściowe:
outcomes
: obiekt JSON{"id": id_string, "bid": bid_double}
selection_signals
: obiekty JSON określone w konfiguracji aukcji. obiekt
Dane wyjściowe:
status
:0
oznacza sukces, wartość inna niż 0 w przypadku niepowodzeniaresult
: jeden z przekazanych wyników lub wartość null.
reportResult()
function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
return {
'status': status,
'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
};
}
Parametry wejściowe:
ad_selection_config
: wyświetl dokumentacjęscoreAds
render_url
: wyrenderowany URL zwycięskiej reklamy.bid
: stawka zaoferowana za zwycięską reklamę.contextual_signals
: wyświetl dokumentacjęgenerateBid
Dane wyjściowe:
status: 0
oznacza sukces i wartość inna niż 0 w przypadku niepowodzeniaresults
: obiekty JSON zawierające:signals_for_buyer
: obiekt JSON przekazywany do metodyreportWin
funkcjareporting_url
: adres URL używany przez platformę do powiadamiania wyświetlenie reklamy kupującemu.
reportWin()
function reportWin(
ad_selection_signals,
per_buyer_signals,
signals_for_buyer,
contextual_signals,
custom_audience_signals) {
return {'status': 0, 'results': {'reporting_url': reporting_url } };
}
Parametry wejściowe:
ad_selection_signals, per_buyer_signals
: zapoznaj się z dokumentacją usługiscoreAd
signals_for_buyer
: obiekt JSON zwrócony przez funkcjęreportResult
contextual_signals, custom_audience_signals
: zapoznaj się z dokumentacją usługigenerateBid
Dane wyjściowe:
status: 0
oznacza sukces i wartość inna niż 0 w przypadku niepowodzeniaresults
: obiekt JSON zawierający:reporting_url
: adres URL używany przez platformę do powiadamiania wyświetlenie reklamy sprzedawcy
registerAdBeacon()
function registerAdBeacon(
interaction_key,
reporting_uri
)
Parametry wejściowe:
interaction_key
: ciąg znaków reprezentujący zdarzenie. Jest ona używana przez później podczas raportowania interakcji ze zdarzeniami, aby wyszukaćreporting_uri
, które należy powiadomić. Ten klucz musi pasować do tego, w których rejestruje się kupujący lub sprzedawca, i to, co raportuje sprzedawca.reporting_uri
: identyfikator URI do otrzymywania raportów o zdarzeniach. Powinna być związana z typ zgłaszanego zdarzenia. Musi zaakceptować żądanie POST do obsługi przesyłane razem ze zdarzeniem.
Gotowe identyfikatory URI funkcji wyboru reklamy
Gotowe identyfikatory URI umożliwiają specjalistom ds. technologii reklamowych wybór funkcji JavaScriptu na potrzeby reklamy
logika wyboru w systemach AdSelectionConfig
oraz
AdSelectionFromOutcomesConfig
zajęć. Gotowe identyfikatory URI nie wymagają sieci
w celu pobrania odpowiedniego JavaScriptu. Technologie reklamowe mogą używać gotowych identyfikatorów URI
bez konieczności konfigurowania zarejestrowanej domeny do hostowania JavaScriptu.
Gotowy identyfikator URI jest tworzony w tym formacie:
ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>
Platforma Piaskownicy prywatności udostępnia kod JavaScript, wykorzystując informacje z tej Identyfikator URI w środowisku wykonawczym.
IllegalArgumentException
jest zgłaszany, jeśli:
- w identyfikatorze URI nie ma żadnego z wymaganych parametrów
- identyfikator URI zawiera nierozpoznane parametry
Obsługiwane przypadki użycia i nazwy gotowych identyfikatorów URI
Przykład zastosowania 1: wybór reklamy
Gotowe identyfikatory URI według przypadku użycia ad-selection
są obsługiwane w
Proces selectAds(AdSelectionConfig)
.
Nazwa gotowego identyfikatora URI: highest-bid-wins
Ten gotowy identyfikator URI udostępnia kod JavaScript, który wybiera reklamę o najwyższej stawce
po ustaleniu stawek. Udostępnia też podstawową funkcję raportowania do raportowania
render_uri
i bid
zwycięzcy.
Parametry wymagane
reportingUrl
: podstawowy adres URL raportowania z parametrami
render_uri
oraz bid
zwycięskiej reklamy:
<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>
Wykorzystanie
Jeśli podstawowy adres URL raportowania to https://www.ssp.com/reporting
,
Identyfikator URI będzie miał postać:
`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`
Przykład zastosowania 2: wybór reklamy z wyników
Gotowe identyfikatory URI w ramach przypadku użycia ad-selection-from-outcomes
obsługują
selectAds(AdSelectionFromOutcomesConfig)
– przepływ pracy.
Nazwa gotowego identyfikatora URI: waterfall-mediation-truncation
Gotowy identyfikator URI waterfall-mediation-truncation
udostępnia kod JavaScript, który
implementuje logikę obcinania zapośredniczenia kaskadowego, gdzie kod JavaScript zwraca
własną reklamę, jeśli wartość bid
jest większa od wartości bid floor
lub jej równa oraz
w przeciwnym razie zwraca null
.
Parametry wymagane
bidFloor
: klucz wartości minimalnej stawki przekazywanej w parametrze getSelectionSignals()
.
w porównaniu z reklamą z pakietu zapośredniczenia.
Wykorzystanie
Jeśli sygnały wyboru reklam mają postać {"bid_floor": 10}
, wynikowy wynik
Gotowy identyfikator URI wygląda tak:
`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`
Testowanie
Aby ułatwić Ci rozpoczęcie pracy z interfejsem Protected Audience API, przygotowaliśmy przykładowy w języku Kotlin i Javie, które znajdziesz na GitHub.
Wymagania wstępne
Interfejs Protected Audience API wymaga JavaScriptu podczas wyboru reklamy w raportach wyświetleń. Istnieją dwie metody dostarczania tego kodu JavaScript w środowisko testowe:
- Uruchom serwer z wymaganymi punktami końcowymi HTTPS, który zwraca kod JavaScript
- Zastąp pobieranie zdalne, podając niezbędny kod ze źródła lokalnego
Każda z tych metod wymaga skonfigurowania punktu końcowego HTTPS do obsługi wyświetleń i raportowania danych.
Punkty końcowe HTTPS
Aby przetestować wybór reklam i raportowanie wyświetleń, musisz skonfigurować 7 punkty końcowe, do których urządzenie testowe lub emulator ma dostęp:
- Punkt końcowy kupującego, który udostępnia logikę ustalania stawek w JavaScript.
- Punkt końcowy, który udostępnia sygnały ustalania stawek.
- Punkt końcowy sprzedawcy, który udostępnia kod JavaScript do podejmowania decyzji.
- Punkt końcowy, który udostępnia sygnały oceny.
- Punkt końcowy raportowania wyświetleń zwycięskiego kupującego.
- Punkt końcowy raportowania wyświetleń sprzedawcy.
- Punkt końcowy, w którym będą przesyłane codzienne aktualizacje dla niestandardowej grupy odbiorców.
Repozytorium GitHub udostępnia dla Twojej wygody podstawowy kod JavaScript do testowania w celach informacyjnych. Zawiera również definicje usług OpenAPI, które można wdrożyć w za pomocą obsługiwanej platformy testowej czy mikroserwisów. Aby dowiedzieć się więcej, zapoznaj się z projektem README.
Zastąp zdalne pobieranie JavaScriptu
Ta funkcja jest przeznaczona do kompleksowego testowania. Zastąpienie pilota aplikacja musi działać w trybie debugowania z włączonymi opcjami programisty.
Aby włączyć tryb debugowania w swojej aplikacji, dodaj ten wiersz do atrybut aplikacji w pliku AndroidManifest.xml:
<application
android:debuggable="true">
Przykłady korzystania z tych zastąpień znajdziesz w Przykładowa aplikacja Audience API na GitHubie.
Musisz dodać własny, niestandardowy kod JavaScript, by obsługiwać procedury wyboru reklamy, takie jak takich jak określanie stawek, decyzje dotyczące punktacji i raportowanie. Podstawowy kod JavaScript które obsługują wszystkie wymagane żądania w repozytorium GitHub. Przykładowa aplikacja interfejsu Protected Audience API pokazuje, jak odczytywać kod ten plik i przygotować go do użycia jako zastąpienia.
Można zastąpić pobieranie JavaScriptu po stronie sprzedającego i kupującego. niezależnie od siebie, ale do obsługi kodu JavaScript potrzebny jest punkt końcowy HTTPS dla których nie stosujesz zastąpień. Zapoznaj się z materiałami README dotyczącymi gdzie znajdziesz informacje o tym, jak skonfigurować serwer, który będzie obsługiwał takie przypadki.
Pobieranie JavaScriptu można zastąpić tylko w przypadku niestandardowych odbiorców, którzy należą do pakietu.
Zastąp kod JavaScript po stronie sprzedawcy
Aby skonfigurować zastępowanie kodu JavaScript po stronie sprzedawcy, wykonaj te czynności zgodnie z przykładem w tym przykładowym kodzie:
- Zainicjuj obiekt
AdSelectionManager
. - Uzyskaj odniesienie do:
TestAdSelectionManager
zAdSelectionManager
obiekt. - Utwórz obiekt
AdSelectionConfig
. - Utwórz
AddAdSelectionOverrideRequest
z obiektAdSelectionConfig
i obiektString
reprezentujący kod JavaScript. których chcesz użyć jako zastąpienia. - Wywołaj asynchroniczną metodę
overrideAdSelectionConfigRemoteInfo()
za pomocą funkcjiAddAdSelectionOverrideRequest
obiekt i odpowiednieExecutor
iOutcomeReceiver
.
Kotlin
val testAdSelectionManager: TestAdSelectionManager =
context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()
// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
.setSeller(seller)
.setDecisionLogicUrl(decisionLogicUrl)
.setCustomAudienceBuyers(customAudienceBuyers)
.setAdSelectionSignals(adSelectionSignals)
.setSellerSignals(sellerSignals)
.setPerBuyerSignals(perBuyerSignals)
.build()
// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
.setAdSelectionConfig(adSelectionConfig)
.setDecisionLogicJs(decisionLogicJS)
.build()
// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
request,
executor,
outComeReceiver)
Java
TestAdSelectionManager testAdSelectionManager =
context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();
// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
.setSeller(seller)
.setDecisionLogicUrl(decisionLogicUrl)
.setCustomAudienceBuyers(customAudienceBuyers)
.setAdSelectionSignals(adSelectionSignals)
.setSellerSignals(sellerSignals)
.setPerBuyerSignals(perBuyerSignals)
.build();
// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
.setAdSelectionConfig(adSelectionConfig)
.setDecisionLogicJs(decisionLogicJS)
.build();
// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
request,
executor,
outComeReceiver);
W sekcji Wybór reklam znajdziesz więcej informacji o tym, jakie
reprezentowane przez pola w AdSelectionConfig
. Główna różnica polega na tym,
że parametr decisionLogicUrl może być ustawiony na wartość zmiennej,
zignorowano.
Aby zastąpić kod JavaScript użyty podczas wybierania reklamy, komponent
Pole decisionLogicJs
musi zawierać prawidłowe podpisy funkcji po stronie sprzedawcy.
Przykład odczytywania pliku JavaScript jako ciągu znaków znajdziesz w
Przykładowa aplikacja Protected Audience API na GitHubie.
Asynchroniczna metoda overrideAdSelectionConfigRemoteInfo()
korzysta z metody
OutcomeReceiver
obiekt sygnalizujący wynik wywołania interfejsu API.
Wywołanie zwrotne onResult()
oznacza, że zastąpienie zostało zastosowane.
W przyszłości połączenia z numerem selectAds()
będą używane niezależnie od decyzji i raportów
które zostały przesłane jako zastąpienie.
Wywołanie zwrotne onError()
oznacza 2 możliwe warunki:
- Jeśli zostanie podjęta próba zastąpienia za pomocą nieprawidłowych argumentów, w funkcji
AdServiceException
wskazujeIllegalArgumentException
jako przyczyna. - Jeśli próba zastąpienia zostanie zastąpiona, gdy aplikacja nie działa w trybie debugowania z parametrem
włączone opcje programisty, ikona
AdServiceException
wskazuje,IllegalStateException
.
Zresetuj zastąpienia po stronie sprzedawcy
W tej sekcji zakładamy, że masz zastąpiony kod JavaScript używany do sprzedaży i
masz odwołanie do: TestAdSelectionManager
oraz
Wartość AdSelectionConfig
została użyta w poprzedniej sekcji.
Aby zresetować zastąpienia dla wszystkich AdSelectionConfigs
:
- Wywoływanie asynchronicznej metody
resetAllAdSelectionConfigRemoteOverrides()
z odpowiednim obiektemOutcomeReceiver
.
Kotlin
// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver)
Java
// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver);
Po zresetowaniu zastąpień po stronie sprzedawcy połączenia do selectAds()
będą używać dowolnych
Parametr decisionLogicUrl jest przechowywany w AdSelectionConfig
, aby podjąć próbę
pobierz wymagany JavaScript.
Jeśli wywołanie resetAllAdSelectionConfigRemoteOverrides()
nie powiedzie się,
Wywołanie zwrotne OutComeReceiver.onError()
udostępnia wartość AdServiceException
.
Jeśli zostanie podjęta próba usunięcia zastąpień, gdy aplikacja nie będzie uruchomiona w trybie debugowania
z włączonymi opcjami programisty, AdServiceException
oznacza
IllegalStateException
.
Zastąp JavaScript po stronie kupującego
- Postępuj zgodnie z instrukcjami, aby dołączyć do grupy niestandardowych odbiorców.
- Tworzenie
AddCustomAudienceOverrideRequest
z kupującym i nazwę listy odbiorców niestandardowych, której ustawienia chcesz zastąpić. reguły określania stawek i dane, których chcesz użyć jako zastąpień. - Wywołaj asynchroniczną metodę
overrideCustomAudienceRemoteInfo()
za pomocą funkcjiAddCustomAudienceOverrideRequest
obiekt i trafny ObiektyExecutor
iOutcomeReceiver
Kotlin
val testCustomAudienceManager: TestCustomAudienceManager =
context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()
// Join custom audience
// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
.setBuyer(buyer)
.setName(name)
.setBiddingLogicJs(biddingLogicJS)
.setTrustedBiddingSignals(trustedBiddingSignals)
.build()
// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
request,
executor,
outComeReceiver)
Java
TestCustomAudienceManager testCustomAudienceManager =
context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();
// Join custom audience
// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
AddCustomAudienceOverrideRequest.Builder()
.setBuyer(buyer)
.setName(name)
.setBiddingLogicJs(biddingLogicJS)
.setTrustedBiddingSignals(trustedBiddingSignals)
.build();
// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
request,
executor,
outComeReceiver);
Wartości atrybutów buyer i name są takie same jak użyte do utworzenia. grupę niestandardowych odbiorców. Więcej informacji o tych polach
Możesz też podać dwa dodatkowe parametry:
biddingLogicJs
: kod JavaScript zawierający logikę kupującego, która jest używana. podczas wyboru reklamy. Wymagane podpisy funkcji znajdziesz w tym artykule JavaScriptu.trustedBiddingSignals
: sygnały służące do określania stawek, które mają być używane podczas wyboru reklamy. Do celów testowych może to być pusty ciąg znaków.
Asynchroniczna metoda overrideCustomAudienceRemoteInfo()
korzysta z metody
OutcomeReceiver
sygnalizujący wynik wywołania interfejsu API.
Wywołanie zwrotne onResult()
oznacza, że zastąpienie zostało zastosowane.
Kolejne wywołania funkcji selectAds()
używają dowolnej logiki określania stawek i raportowania
który został przekazany jako zastąpienie.
Wywołanie zwrotne onError()
wskazuje 2 możliwe warunki.
- Jeśli zostanie podjęta próba zastąpienia za pomocą nieprawidłowych argumentów, w funkcji
AdServiceException
wskazujeIllegalArgumentException
jako przyczyna. - Jeśli próba zastąpienia zostanie zastąpiona, gdy aplikacja nie działa w trybie debugowania z parametrem
włączone opcje programisty, ikona
AdServiceException
wskazuje,IllegalStateException
.
Zresetuj zastąpienia po stronie kupującego
W tej sekcji zakładamy, że kod JavaScript po stronie kupującego został zastąpiony i że
masz odwołanie do obiektu TestCustomAudienceManager
użytego w
poprzedniej sekcji.
Aby zresetować zastąpienia dla wszystkich niestandardowych odbiorców:
- Wywołaj asynchroniczną metodę
resetAllCustomAudienceOverrides()
za pomocą funkcji odpowiednie obiektyExecutor
iOutcomeReceiver
.
Kotlin
// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
executor,
outComeReceiver)
Java
// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
executor,
outComeReceiver)
Po zresetowaniu zastąpień po stronie zakupu kolejne wywołania selectAds()
używaj dowolnych biddingLogicUrl
i trustedBiddingData
przechowywane w CustomAudience
, aby spróbować pobrać wymagane
JavaScriptu.
Jeśli wywołanie resetCustomAudienceRemoteInfoOverride()
nie powiedzie się,
Wywołanie zwrotne OutComeReceiver.onError()
udostępnia wartość AdServiceException
.
Jeśli zostanie podjęta próba usunięcia zastąpień, gdy aplikacja nie będzie uruchomiona w trybie debugowania
z włączoną opcją programisty, ikona AdServiceException
oznacza
IllegalStateException
.
Skonfiguruj serwer raportowania
Jeśli używasz zastąpień zdalnego pobierania, nadal musisz skonfigurować serwer które urządzenie lub emulator może sięgać, aby reagować na zgłaszane zdarzenia. Prosta który zwraca wartość 200, wystarczy do przeprowadzenia testów. Repozytorium GitHub zawiera: Definicje usług OpenAPI, które można wdrożyć w obsługiwanej wersji makiety lub platformy mikroserwisów. Aby dowiedzieć się więcej, zapoznaj się z projektem README.
Gdy szukasz definicji OpenAPI, znajdź plik Reporting-server.json.
Ten plik zawiera prosty punkt końcowy, który zwraca kod 200, reprezentujący protokół HTTP
kodu odpowiedzi. Ten punkt końcowy jest używany podczas: selectAds()
i sygnalizuje:
interfejsu Protected Audience API.
Funkcje do przetestowania
- Ćwicz, dołączając do grupy lub ją opuszczając i konfigurując niestandardową grupę odbiorców na podstawie wcześniejszych działań użytkownika.
- Uruchamiaj wybór reklam na urządzeniu za pomocą hostowanych skryptów JavaScript zdalnie.
- Obserwuj, jak powiązanie aplikacji z ustawieniami niestandardowych odbiorców może wpłynąć na reklamę wyniki wyboru.
- Raporty wyświetleń ćwiczenia po wybraniu reklamy.
Ograniczenia
W tabeli poniżej znajdziesz ograniczenia przetwarzania przez interfejs Protected Audience API. Przedstawione limity mogą ulec zmianie w zależności od opinii użytkowników. Dla: są w trakcie opracowywania, zapoznaj się z informacjami o wersji.
Komponent | Opis limitu | Wartość limitu |
---|---|---|
Niestandardowi odbiorcy (CA) | Maksymalna liczba reklam na urząd certyfikacji | 100 |
Maksymalna liczba urzędów certyfikacji na aplikację | 1000 | |
Maksymalna liczba aplikacji, które mogą utworzyć urząd certyfikacji | 1000 | |
Maksymalne opóźnienie czasu aktywacji urzędu certyfikacji od momentu jego utworzenia | 60 dni | |
Maksymalny czas wygaśnięcia urzędu certyfikacji od momentu aktywacji | 60 dni | |
Maksymalna liczba urzędów certyfikacji na urządzeniu | 4000 | |
Maksymalny rozmiar nazwy urzędu certyfikacji | 200 bajtów | |
Maksymalny rozmiar identyfikatora URI pobierania dziennie | 400 bajtów | |
Maksymalny rozmiar identyfikatora URI logiki ustalania stawek | 400 bajtów | |
Maksymalny rozmiar danych dotyczących zaufanych stawek | 10 KB | |
Maksymalny rozmiar sygnałów dotyczących określania stawek przez użytkownika | 10 KB | |
Maksymalna liczba połączeń za leaveCustomAudience na kupującego |
1 na sekundę | |
Maksymalna liczba połączeń za joinCustomAudience na kupującego |
1 na sekundę | |
Pobieranie informacji w tle z Kalifornii | Przekroczenie limitu czasu oczekiwania na połączenie | 5 sekund |
Upłynął limit czasu odczytu HTTP | 30 sekund | |
Maksymalny łączny rozmiar pobierania | 10 KB | |
Maksymalny czas trwania iteracji pobierania | 5 minut | |
Maksymalna liczba urzędów certyfikacji aktualizowanych na zadanie | 1000 | |
Wybór reklamy | Maksymalna liczba kupujących | Do ustalenia |
Maksymalna liczba urzędów certyfikacji na kupującego | Do ustalenia | |
Maksymalna liczba reklam w aukcji | Do ustalenia | |
Limit czasu połączenia początkowego | 5 sekund | |
Upłynął limit czasu odczytu połączenia | 5 sekund | |
Maksymalny czas wykonania ogólnego zasobu AdSelection |
10 sekund | |
Maksymalny czas wykonywania określania stawek na urząd certyfikacji w AdSelection |
5 sekund | |
Maksymalny czas wykonania punktacji w AdSelection |
5 sekund | |
Maksymalny czas realizacji na kupującego w AdSelection |
Do ustalenia | |
Maksymalny rozmiar sygnałów wyboru reklamy/sprzedawcy/na kupującego | Do ustalenia | |
Maksymalny rozmiar skryptów sprzedawcy/kupującego | Do ustalenia | |
Maksymalna częstotliwość połączeń (selectAds ) |
1 QPS | |
Raporty wyświetleń | Minimalny czas przed usunięciem wybranej reklamy z trwałości | 24 godz. |
Maksymalna liczba wybranych reklam pamięci masowej | Do ustalenia | |
Maksymalny rozmiar wyjściowego adresu URL raportowania | Do ustalenia | |
Maksymalny czas raportowania wyświetleń | Do ustalenia | |
Maksymalna liczba ponownych prób w przypadku połączeń z powiadomieniami | Do ustalenia | |
Limit czasu połączenia | 5 sekund | |
Maksymalny ogólny czas wykonywania dla reguły reportImpression |
2 sekundy | |
Maksymalna częstotliwość połączeń (reportImpressions ) |
1 QPS | |
Raporty o zdarzeniach | Maksymalna liczba beaconów na kupującego na aukcję | 10 |
Maksymalna liczba beaconów na sprzedawcę na aukcję |
10 |
|
Maksymalny rozmiar klucza zdarzenia |
40 bajtów |
|
Maksymalny rozmiar danych zdarzenia |
64KB |
|
Reklamy | Maksymalny rozmiar listy reklam | 10 KB udostępniane przez wszystkich
AdData
w jednym urzędu certyfikacji
na potrzeby kontekstu |
Adresy URL | Maksymalna długość dowolnego ciągu adresu URL uznawanego za dane wejściowe | Do ustalenia |
JavaScript | Maksymalny czas wykonania | 1 sekunda na określanie stawek i punktowanie na potrzeby raportowania wyświetleń |
Maksymalna używana pamięć | 10 MB |
Zgłaszanie błędów i problemów
Twoja opinia jest kluczowym elementem Piaskownicy prywatności na Androida. Daj nam znać żadnych problemów lub pomysłów na ulepszenie Piaskownicy prywatności na Androida.
Polecane dla Ciebie
- Uwaga: tekst linku wyświetla się, gdy JavaScript jest wyłączony
- Obsługa kierowania na niestandardowych odbiorców za pomocą interfejsu Protected Audience API
- Informacje o wersji
- Protected Audience API: przewodnik po integracji