Podczas czytania dokumentacji Piaskownicy prywatności na Androida wybierz odpowiednią wersję programu, korzystając z przycisku Podgląd dla programistów lub Beta. Instrukcje mogą się różnić.
Interfejs Protected Audience API na Androida (dawniej FLEDGE) obejmuje interfejsy Custom Audience API i Ad Selection API. Reklamodawcy i platformy z branży technologii reklamowych mogą używać tych interfejsów API do wyświetlania reklam dopasowanych na podstawie wcześniejszego zaangażowania w aplikację. Ogranicza to udostępnianie identyfikatorów między aplikacjami i ogranicza udostępnianie firmom zewnętrznym informacji o interakcji z aplikacjami.
Interfejs Custom Audience API koncentruje się na grupie „niestandardowych odbiorców”, czyli grupie użytkowników o podobnych zamiarach. Reklamodawca może zarejestrować użytkownika na niestandardowej liście odbiorców i powiązać z nią odpowiednie reklamy. Informacje te są przechowywane lokalnie i mogą służyć do ustalania stawek reklamodawców oraz ich filtrowania i renderowania.
Interfejs Ad Selection API umożliwia wielu deweloperom przeprowadzanie lokalnych aukcji dla niestandardowych odbiorców. Aby to osiągnąć, system uwzględnia trafne reklamy powiązane z niestandardową listą odbiorców i dodatkowo przetwarza reklamy, które platforma technologii reklamowych zwraca na urządzenie.
Platformy z branży technologii reklamowych mogą integrować te interfejsy API, aby wdrażać remarketing chroniący prywatność użytkowników. W kolejnych wersjach planujemy wprowadzić obsługę dodatkowych przypadków użycia, w tym reklam promujących instalacje aplikacji. Więcej informacji o interfejsie Protected Audience API na Androida znajdziesz w ofercie pakietowej.
Z tego przewodnika dowiesz się, jak korzystać z interfejsu Protected Audience API na Androidzie, aby:
- Zarządzanie odbiorcami niestandardowymi
- Konfigurowanie i wyświetlanie wyboru reklam na urządzeniu
- Raportowanie wyświetleń reklam
Zanim zaczniesz
Przed rozpoczęciem wykonaj te czynności:
- Skonfiguruj środowisko programistyczne Piaskownicy prywatności na Androida.
- Zainstaluj obraz systemu na obsługiwanym urządzeniu lub skonfiguruj emulator obsługujący Piaskownicę prywatności na urządzeniach z Androidem.
W terminalu włącz dostęp do interfejsu Protected Audience API (domyślnie wyłączony) za pomocą poniższego polecenia adb.
adb shell device_config put adservices ppapi_app_allow_list \"*\"
Dodaj do pliku manifestu aplikacji uprawnienie
ACCESS_ADSERVICES_CUSTOM_AUDIENCE
:<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
Utwórz odniesienie do konfiguracji usług reklamowych w elemencie
<application>
pliku manifestu:<property android:name="android.adservices.AD_SERVICES_CONFIG" android:resource="@xml/ad_services_config" />
Określ zasób XML usług reklamowych, do którego odwołuje się Twój plik manifestu, np.
res/xml/ad_services_config.xml
. Dowiedz się więcej o uprawnieniach do usług reklamowych i kontroli dostępu do pakietów SDK<ad-services-config> <custom-audiences allowAllToAccess="true" /> </ad-services-config>
Domyślnie interfejs Ad Selection API egzekwuje limity maksymalnej ilości pamięci, którą może przydzielić skrypt raportowania aukcji lub wyświetleń. Funkcja ograniczenia pamięci wymaga WebView w wersji 105.0.5195.58 lub nowszej. Platforma wymusza sprawdzanie wersji, a wywołania interfejsów API
selectAds
ireportImpression
kończą się niepowodzeniem, jeśli są one niezgodne z zasadami. Możesz to zrobić na 2 sposoby:Opcja 1. Aby dezaktywować kontrolę, uruchom to polecenie adb:
adb device_config put fledge_js_isolate_enforce_max_heap_size false
Opcja 2. Zainstaluj WebView Beta ze Sklepu Google Play. Ta wartość musi być równa lub wyższa od wersji podanej wcześniej.
Dołącz do niestandardowej listy odbiorców
Niestandardowa lista odbiorców to grupa użytkowników o wspólnych zamiarach lub zainteresowaniach, zgodnie z ustawieniami aplikacji reklamodawcy. Aplikacja lub pakiet SDK może używać tej listy do wskazywania konkretnej grupy odbiorców, np. osoby, która zostawiła produkty w koszyku. Aby asynchronicznie utworzyć niestandardową listę odbiorców lub dołączyć do niej:
- Zainicjuj obiekt
CustomAudienceManager
. - Utwórz obiekt
CustomAudience
, określając kluczowe parametry, np. pakiet kupującego i odpowiednią nazwę. Następnie zainicjuj obiektJoinCustomAudienceRequest
za pomocą obiektuCustomAudience
. - Wywołaj asynchroniczny
joinCustomAudience()
z obiektemJoinCustomAudienceRequest
i odpowiednimi obiektamiExecutor
iOutcomeReceiver
.
Kotlin
val customAudienceManager: CustomAudienceManager =
context.getSystemService(CustomAudienceManager::class.java)
// Initialize a custom audience.
val audience = CustomAudience.Builder()
.setBuyer(buyer)
.setName(name)
...
.build()
// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()
// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
executor,
outcomeReceiver)
Java
CustomAudienceManager customAudienceManager =
context.getSystemService(CustomAudienceManager.class);
// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
.setBuyer(buyer)
.setName(name)
...
.build();
// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();
// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
executor,
outcomeReceiver);
Kombinacja tych parametrów jednoznacznie identyfikuje każdy obiekt CustomAudience
na urządzeniu:
owner
: nazwa pakietu aplikacji właściciela. Jest ona domyślnie ustawiona na nazwę pakietu aplikacji wywołującej.buyer
: identyfikator sieci reklamowej kupującego, która zarządza reklamami tej niestandardowej listy odbiorców.name
: dowolna nazwa lub identyfikator niestandardowej listy odbiorców.
Wywoływanie funkcji joinCustomAudience()
wielokrotnie z innym wystąpieniem obiektu CustomAudience
aktualizuje istniejące już CustomAudience
o pasujące parametry owner, buyer
i name
. Aby chronić prywatność, wynik działania interfejsu API nie rozróżnia „tworzenia” i „aktualizacji”.
Dodatkowo należy utworzyć CustomAudience
z tymi wymaganymi parametrami:
- Adres URL z codzienną aktualizacją: adres URL HTTPS wysyłany codziennie w tle w celu aktualizowania sygnałów dotyczących określania stawek przez użytkowników i zaufanych danych dotyczących określania stawek w przypadku niestandardowej listy odbiorców oraz renderowania adresów URL i metadanych reklam na potrzeby reklam.
- Adres URL logiki określania stawek: adres URL HTTPS, którego kliknięcie jest wysyłane podczas wyboru reklamy w celu pobrania logiki ustalania stawek JavaScriptu przez kupującego. Zobacz wymagane podpisy funkcji w tym JavaScripcie.
- Identyfikatory renderowania reklam: dowolny identyfikator ustawiany przez technologię reklamową kupującego. Jest to optymalizacja generowania ładunku na potrzeby B&A.
Opcjonalne parametry obiektu CustomAudience
mogą obejmować:
- Czas aktywacji: niestandardowa grupa odbiorców może uczestniczyć w wyborze reklam i codziennych aktualizacjach po upływie czasu aktywacji. Pomaga to na przykład zaangażować nieaktywnych użytkowników aplikacji.
- Data ważności: czas, po którym niestandardowa lista odbiorców jest usuwana z urządzenia.
- Sygnały dotyczące określania stawek przez użytkowników: ciąg znaków JSON zawierający sygnały użytkownika, np. preferowany język użytkownika, których JavaScript używa do generowania stawek podczas procesu wyboru reklamy. Format ten ułatwia platformy technologii reklamowych ponowne używanie kodu na różnych platformach i ułatwia wykorzystanie kodu w funkcjach JavaScript.
- Dane dotyczące zaufanego określania stawek: adres URL HTTPS i lista ciągów znaków używanych podczas procesu wyboru reklamy, które pobierają sygnały dotyczące określania stawek z zaufanej usługi klucz-wartość.
- Reklamy: lista obiektów
AdData
odpowiadających reklamom, które uczestniczą w wyborze. Każdy obiektAdData
składa się z:- URL renderowania: adres URL HTTPS, do którego jest wysyłane zapytanie o wyrenderowanie ostatecznej reklamy.
- Metadane: obiekt JSON zserializowany jako ciąg znaków zawierający informacje, które ma wykorzystać logika ustalania stawek przez kupującego podczas procesu wyboru reklamy.
- Filtry reklam: klasa zawierająca wszystkie informacje niezbędne do filtrowania reklam promujących instalacje aplikacji i ograniczania liczby wyświetleń podczas wyboru reklamy.
Oto przykład tworzenia instancji obiektu CustomAudience
:
Kotlin
// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
.setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
.setName("example-custom-audience-name")
.setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
.setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
.build()
Java
// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
.setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
.setName("example-custom-audience-name")
.setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
.setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
.build();
Obsługa wyników JoinCustomAudience()
Asynchroniczna metoda joinCustomAudience()
, używa obiektu OutcomeReceiver
do sygnalizowania wyniku wywołania interfejsu API.
- Wywołanie zwrotne
onResult()
oznacza, że niestandardowa lista odbiorców została utworzona lub zaktualizowana. - Wywołanie zwrotne
onError()
oznacza 2 możliwe warunki.- Jeśli
JoinCustomAudienceRequest
został zainicjowany z nieprawidłowymi argumentami,AdServicesException
wskazuje jako przyczynęIllegalArgumentException
. - W przypadku pozostałych błędów wyświetlany jest
AdServicesException
z przyczynąIllegalStateException
.
- Jeśli
Oto przykład postępowania z wynikiem joinCustomAudience()
:
Kotlin
var callback: OutcomeReceiver<Void, AdServicesException> =
object : OutcomeReceiver<Void, AdServicesException> {
override fun onResult(result: Void) {
Log.i("CustomAudience", "Completed joinCustomAudience")
}
override fun onError(error: AdServicesException) {
// Handle error
Log.e("CustomAudience", "Error executing joinCustomAudience", error)
}
};
Java
OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
@Override
public void onResult(@NonNull Void result) {
Log.i("CustomAudience", "Completed joinCustomAudience");
}
@Override
public void onError(@NonNull AdServicesException error) {
// Handle error
Log.e("CustomAudience", "Error executing joinCustomAudience", error);
}
};
Opuszczanie grupy odbiorców niestandardowych
Jeśli użytkownik nie spełnia już kryteriów biznesowych danej niestandardowej listy odbiorców, aplikacja lub pakiet SDK może wywołać metodę leaveCustomAudience()
, aby usunąć tę listę z urządzenia. Aby usunąć element CustomAudience
związany z jego unikalnymi parametrami, wykonaj te czynności:
- Zainicjuj obiekt
CustomAudienceManager
. - Zainicjuj
LeaveCustomAudienceRequest
, używając listy niestandardowych odbiorców:buyer
iname
. Więcej informacji o tych polach znajdziesz w artykule „Dołączanie do grupy odbiorców niestandardowych”. - Wywołaj asynchroniczną metodę
leaveCustomAudience()
z obiektemLeaveCustomAudienceRequest
oraz odpowiednimi obiektamiExecutor
iOutcomeReceiver
.
Kotlin
val customAudienceManager: CustomAudienceManager =
context.getSystemService(CustomAudienceManager::class.java)
// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
LeaveCustomAudienceRequest.Builder()
.setBuyer(buyer)
.setName(name)
.build()
// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
leaveCustomAudienceRequest,
executor,
outcomeReceiver)
Java
CustomAudienceManager customAudienceManager =
context.getSystemService(CustomAudienceManager.class);
// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
new LeaveCustomAudienceRequest.Builder()
.setBuyer(buyer)
.setName(name)
.build();
// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
leaveCustomAudienceRequest,
executor,
outcomeReceiver);
Podobnie jak wywołanie joinCustomAudience()
, OutcomeReceiver
sygnalizuje zakończenie wywołania interfejsu API. Z myślą o ochronie prywatności wynik błędu nie odróżnia błędów wewnętrznych od nieprawidłowych argumentów. Wywołanie zwrotne onResult()
jest wywoływane po zakończeniu wywołania interfejsu API niezależnie od tego, czy pasująca niestandardowa lista odbiorców została usunięta.
Uruchom wybór reklamy
Aby wybrać reklamy za pomocą interfejsu Protected Audience API, wywołaj metodę selectAds()
:
- Zainicjuj obiekt
AdSelectionManager
. - Utwórz obiekt
AdSelectionConfig
. - Wywołaj asynchroniczną metodę
selectAds()
z obiektemAdSelectionConfig
oraz odpowiednimi obiektamiExecutor
iOutcomeReceiver
.
Kotlin
val adSelectionManager: AdSelectionManager =
context.getSystemService(AdSelectionManager::class.java)
// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
AdSelectionConfig.Builder().setSeller(seller)
.setDecisionLogicUrl(decisionLogicUrl)
.setCustomAudienceBuyers(customAudienceBuyers)
.setAdSelectionSignals(adSelectionSignals)
.setSellerSignals(sellerSignals)
.setPerBuyerSignals(perBuyerSignals)
.setBuyerContextualAds(
Collections.singletonMap(
contextualAds.getBuyer(), contextualAds
)
).build()
// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
adSelectionConfig, executor, outcomeReceiver
)
Java
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
new AdSelectionConfig.Builder()
.setSeller(seller)
.setDecisionLogicUrl(decisionLogicUrl)
.setCustomAudienceBuyers(customAudienceBuyers)
.setAdSelectionSignals(adSelectionSignals)
.setSellerSignals(sellerSignals)
.setPerBuyerSignals(perBuyerSignals)
.setBuyerContextualAds(
Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
)
.build();
// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(adSelectionConfig, executor, outcomeReceiver);
Metoda selectAds()
wymaga danych wejściowych AdSelectionConfig
, w których musisz podać te wymagane parametry:
- Sprzedawca: identyfikator sieci reklamowej sprzedawcy, która inicjuje wybór reklamy.
- URL logiki decyzji: adres URL HTTPS używany w celu uzyskania logiki JavaScript sieci reklamowej sprzedawcy.
- Adres URL HTTPS: przesłany w celu uzyskania logiki JavaScript sieci reklamowej sprzedawcy. Zobacz wymagane podpisy funkcji.
- Gotowy identyfikator URI zgodny z formatem wyboru reklam FLEDGE.
W przypadku przesłania nieobsługiwanego lub nieprawidłowo utworzonego identyfikatora URI zgłaszany jest
IllegalArgumentException
.
- Kupujący na liście niestandardowych odbiorców: pełna lista identyfikatorów sieci reklamowych kupujących, którzy mogą uczestniczyć w procesie wyboru reklamy.
Te identyfikatory kupujących odpowiadają
CustomAudience.getBuyer()
listom odbiorców niestandardowych, które uczestniczą w programie.
Aby trafniej dobierać reklamy, możesz opcjonalnie określić te parametry:
- Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały do wykorzystania przez logikę określania stawek przez kupującego, pobrany z
CustomAudience.getBiddingLogicUrl()
. - Sygnały sprzedawcy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały używane przez pobraną przez sprzedawcę logikę decyzji JavaScriptu pobranej z
AdSelectionConfig.getDecisionLogicUrl()
. - Sygnały dla kupującego: mapa obiektów JSON, zserializowanych jako ciągi znaków, zawierających sygnały do wykorzystania przez logikę ustalania stawek konkretnych kupujących pobrany z
CustomAudience.getBiddingLogicUrl()
. Są one identyfikowane przez pola kupującego na listach niestandardowych odbiorców, które uczestniczą w programie. - Reklamy kontekstowe: zbiór kandydatów reklam pozyskiwanych bezpośrednio od kupujących podczas aukcji prowadzonej poza aukcją w ramach Protected Audience API.
Po wybraniu reklamy wyniki, stawki i sygnały są zapisywane wewnętrznie na potrzeby raportów. Wywołanie zwrotne OutcomeReceiver.onResult()
zwraca wartość AdSelectionOutcome
, która zawiera:
- URL renderowania zwycięskiej reklamy uzyskany z pliku
AdData.getRenderUrl()
. - Unikalny identyfikator wyboru reklamy dla użytkownika urządzenia. Służy on do raportowania wyświetlenia reklamy.
Jeśli nie można wybrać reklamy z powodu nieprawidłowych argumentów, przekroczenia limitu czasu lub nadmiernego zużycia zasobów, wywołanie zwrotne OutcomeReceiver.onError()
powoduje wywołanie funkcji AdServicesException
o tych zachowaniach:
- Jeśli wybór reklamy został zainicjowany przy użyciu nieprawidłowych argumentów,
AdServicesException
wskazuje jako przyczynęIllegalArgumentException
. - W przypadku pozostałych błędów wyświetlany jest
AdServicesException
z przyczynąIllegalStateException
.
Reklamy kontekstowe
W ramach Protected Audience API reklamy kontekstowe mogą być włączane do aukcji chronionej.
Reklamy kontekstowe muszą być wybierane na serwerze technologii reklamowej i zwracane na urządzenie poza interfejsami Protected Audience API. Reklamy kontekstowe mogą być wtedy uwzględniane w aukcji za pomocą elementu AdSelectionConfig
. Dzięki temu działają tak samo jak reklamy na urządzeniu, w tym spełniają kryteria filtrowania reklam wykluczających. Po zakończeniu aukcji Protected Audience API musisz wywołać reportImpression()
. Wywołuje to zdarzenie reportWin()
w zwycięskiej reklamie kontekstowej (tak samo jak w przypadku raportowania wyświetleń) w celu otrzymania na urządzeniu zwycięskiej reklamy. Każda reklama kontekstowa wymaga kupującego, stawki, linku do logiki raportowania, adresu URL renderowania i metadanych reklamy.
Aby wdrożyć reklamy kontekstowe w aplikacji, aplikacja docelowa musi utworzyć obiekt ContextualAds
:
Kotlin
val contextualAds: ContextualAds =
Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
//Pass in your valid app install ads
.setDecisionLogicUri(mContextualLogicUri)
.setAdsWithBid(appInstallAd)
.build()
Java
ContextualAds contextualAds = new ContextualAds.Builder()
.setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
.setDecisionLogicUri(mContextualLogicUri)
//Pass in your valid app install ads
.setAdsWithBid(appInstallAd)
.build();
Otrzymany obiekt ContextualAds
możesz przekazać podczas tworzenia AdSelectionConfig
:
Kotlin
// Create a new ad
val noFilterAd: AdData = Builder()
.setMetadata(JSONObject().toString())
.setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
.build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)
Java
// Create a new ad
AdData noFilterAd = new AdData.Builder()
.setMetadata(new JSONObject().toString())
.setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
.build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);
Filtrowanie reklam promujących instalacje aplikacji
Filtrowanie reklam promujących instalacje aplikacji pomaga filtrować reklamy promujące instalacje aplikacji, które zostały już zainstalowane na urządzeniu.
Pierwszym krokiem w tym procesie jest określenie, którzy reklamodawcy mogą filtrować zainstalowany pakiet. Musi to nastąpić w aplikacji, na którą chcesz kierować reklamę.
Kotlin
//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)
//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
request,
mExecutor,
object : OutcomeReceiver<Any?, Exception?>() {
fun onResult(@NonNull ignoredResult: Any?) {
Log.v("[your tag]", "Updated app install advertisers")
}
fun onError(@NonNull error: Exception?) {
Log.e("[your tag]", "Failed to update app install advertisers", error)
}
})
Java
//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);
//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
request,
mExecutor,
new OutcomeReceiver<Object, Exception>() {
@Override
public void onResult(@NonNull Object ignoredResult) {
Log.v("[your tag]", "Updated app install advertisers");
}
@Override
public void onError(@NonNull Exception error) {
Log.e("[your tag]", "Failed to update app install advertisers", error);
}
});
Gdy poprzedni kod zostanie uruchomiony, przekazani reklamodawcy mogą odfiltrowywać zainstalowane aplikacje określone przez Ciebie podczas generowania stawek. Jeśli chcesz zablokować reklamodawcy dostęp do stanu instalacji tej aplikacji, uruchom ten kod ponownie z usuniętymi informacjami o nim.
Następnym krokiem jest skonfigurowanie filtrowania reklam w aplikacji wydawcy. Firma, która wyświetla reklamę w aplikacji wydawcy (najprawdopodobniej to pakiet SDK po stronie dostawców), musi zainicjować obiekt AdFilters
, podając informacje o tym, które reklamy związane z aplikacjami chce odfiltrowywać:
Kotlin
// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
Builder().setPackageNames(setOf("example.target.app")).build()
).build()
Java
// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
new AppInstallFilters.Builder()
.setPackageNames(Collections.singleton("example.target.app"))
.build())
.build();
Wydawcy DSP mogą też ustawić AdFilter
w przypadku reklam, które występują w grupach niestandardowych odbiorców.
AdFilters
można też przekazać w momencie tworzenia wystąpienia nowego obiektu AdData
:
Kotlin
// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
Builder().setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
.setAdFilters(filters).build()
Java
// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
.setAdFilters(filters)
.build();
Filtrowanie limitu wyświetleń na użytkownika
Filtrowanie limitu wyświetleń na użytkownika pozwala technikom reklamowym ograniczać liczbę wyświetleń reklamy. Filtrowanie limitu wyświetleń na użytkownika ogranicza nadmierne wyświetlanie reklam i optymalizuje wybór reklam zastępczych w przypadku danej kampanii reklamowej.
Filtr limitu wyświetleń na użytkownika składa się z 2 głównych elementów: typu zdarzenia reklamowego i klucza licznika reklam. Dostępne typy zdarzeń reklamowych:
- Wygrana (już wkrótce): zdarzenie wygranej oznacza, że reklama wygrała aukcję. Zdarzenia wygranych są automatycznie aktualizowane przez Protected Audience API i deweloper nie może ich wywoływać bezpośrednio. Dane wygranych są widoczne tylko dla reklam na danej niestandardowej liście odbiorców.
- Wyświetlenie: niezależnie od
reportImpression
element wywołujący na urządzeniu (SSP lub MMP) używaupdateAdCounterHistogram()
do wywoływania zdarzeń wyświetlenia w wybranym punkcie kodu. Zdarzenia wyświetlenia są widoczne dla wszystkich reklam należących do danej platformy DSP, nie tylko w przypadku reklam na tej samej niestandardowej liście odbiorców. - Widok: zdarzenie jest wywoływane przez element wywołujący na urządzeniu (SSP lub MMP) w wybranym przez niego punkcie kodu za pomocą wywołania
updateAdCounterHistogram()
. Zdarzenia widoku danych są widoczne dla wszystkich reklam należących do danej platformy DSP, nie tylko w przypadku reklam z tej samej niestandardowej listy odbiorców. - Kliknięcie: zdarzenie jest wywoływane przez element wywołujący na urządzeniu (SSP lub MMP) w wybranym przez niego punkcie kodu za pomocą wywołania
updateAdCounterHistogram()
. Zdarzenia kliknięcia są widoczne dla wszystkich reklam należących do danej platformy DSP, nie tylko w przypadku reklam należących do tej samej niestandardowej listy odbiorców.
Zdarzenia reklamowe w aplikacji wydawcy wywoływane są przez platformę SSP lub MMP, która istnieje na urządzeniu. Po wywołaniu funkcji updateAdCounterHistogram()
licznik filtra limitu wyświetleń jest zwiększany, aby w przyszłych aukcjach uzyskać aktualne informacje o ekspozycji użytkownika na daną reklamę. Typy zdarzeń reklamowych nie są na stałe powiązane z odpowiadającymi im działaniami użytkownika. Są to wskazówki, które mają pomóc dzwoniącym w utworzeniu struktury systemu zdarzeń. Aby zwiększyć liczbę liczników reklam w momencie wystąpienia zdarzenia, użytkownik na urządzeniu podaje identyfikator wyboru reklamy zwycięskiej z aukcji.
Klucze licznika reklam to dowolne 32-bitowe liczby całkowite podpisane przez kupującego, które odpowiadają danemu zestawowi reklam zdefiniowanym przez platformę DSP. Klucze licznika reklam są ograniczone tylko do reklam należących do danej platformy DSP, więc można je wybrać bez pokrywania się z histogramami innych technologii reklamowych. Klucze licznika reklam służą do zwiększania liczby identyfikatorów DSP w reklamach platformy DSP lub w obrębie określonej niestandardowej listy odbiorców w celu odfiltrowywania reklam z przyszłych aukcji.
Klucze licznika można wykorzystać do nadawania priorytetu reklamom, które z większym prawdopodobieństwem będą interesujące dla danego użytkownika, na podstawie jego interakcji z innymi reklamami danej technologii reklamowej danego kupującego. Na przykład wywnioskowanym punktem danych jest reklama, która w dużym stopniu zaangażowała się w wygraną aukcję reklam, wyświetlenia i kliknięcia. Aby jeszcze lepiej wyjaśnić tę kwestię: reklama kijów golfowych dla leworęcznych może wskazywać, że użytkownik nie jest zainteresowany kijami praworęcznymi. Ustawiono filtr limitu wyświetleń na użytkownika dla klucza licznika przypisanego do reklam leworęcznych, aby odfiltrowywać reklamy kijów praworęcznych.
Aby użyć ograniczenia liczby wyświetleń w aukcji, musisz najpierw utworzyć obiekty (KeyedFrequencyCap
), jak pokazano poniżej:
Kotlin
// Value used when incrementing frequency counter
val adCounterKey = 123
// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
adCounterKey, 2, Duration.ofSeconds(10)
).build()
// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
adCounterKey, 1, Duration.ofSeconds(10)
).build()
Java
// Value used when incrementing frequency counter
int adCounterKey = 123;
// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
new KeyedFrequencyCap.Builder(
adCounterKey, 2, Duration.ofSeconds(10)
).build();
// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
new KeyedFrequencyCap.Builder(
adCounterKey, 1, Duration.ofSeconds(10)
).build();
Po utworzeniu obiektów KeyedFrequencyCap
możesz je przekazać do obiektu AdFilters
.
Kotlin
val filters: AdFilters = Builder()
.setFrequencyCapFilters(
Builder()
.setKeyedFrequencyCapsForImpressionEvents(
ImmutableObject.of(keyedFrequencyCapForImpression)
)
.setKeyedFrequencyCapsForClickEvents(
ImmutableObject.of(keyedFrequencyCapForClick)
)
).build()
Java
AdFilters filters = new AdFilters.Builder()
.setFrequencyCapFilters(new FrequencyCapFilters.Builder()
.setKeyedFrequencyCapsForImpressionEvents(
ImmutableObject.of(keyedFrequencyCapForImpression)
)
.setKeyedFrequencyCapsForClickEvents(
ImmutableObject.of(keyedFrequencyCapForClick)
)
).build();
Gdy obiekt AdFilters
jest wypełniony filtrami limitu wyświetleń na użytkownika, może być przekazywany podczas tworzenia listy odbiorców niestandardowej:
Kotlin
// Initialize a custom audience.
val audience: CustomAudience = Builder()
.setBuyer(buyer)
.setName(name)
.setAds(
listOf(
Builder()
.setRenderUri(renderUri)
.setMetadata(JSONObject().toString())
.setAdFilters(filters)
.setAdCounterKeys(adCounterKeys)
.build()
)
).build()
Java
// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
.setBuyer(buyer)
.setName(name)
.setAds(Collections.singletonList(new AdData.Builder()
.setRenderUri(renderUri)
.setMetadata(new JSONObject().toString())
.setAdFilters(filters)
.setAdCounterKeys(adCounterKeys)
.build()))
.build();
Po zaimplementowaniu filtrów limitu wyświetleń na użytkownika na niestandardowej liście odbiorców platforma SSP może wywoływać niezbędne zdarzenia kliknięcia, wyświetlenia lub wyświetlenia.
Kotlin
val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()
val request: UpdateAdCounterHistogramRequest = Builder(
adSelectionId,
FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
callerAdTech
).build()
Java
AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();
UpdateAdCounterHistogramRequest request =
new UpdateAdCounterHistogramRequest.Builder(
adSelectionId,
FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
callerAdTech
).build();
Reklamy, które osiągnęły wstępnie ustawiony limit filtra limitu wyświetleń na użytkownika, są odfiltrowywane z aukcji. Filtrowanie następuje przed uruchomieniem logiki ustalania stawek w przypadku aukcji na urządzeniu oraz w trakcie generowania ładunku na potrzeby aukcji ustalania stawek i usług aukcyjnych.Ten zestaw narzędzi zapewnia technikom reklamowym elastyczność w wykorzystywaniu interakcji między użytkownikami a reklamami w grupach niestandardowych, aby skupić się na kierowaniu reklam i zminimalizować ryzyko ich nadmiernej ekspozycji.
Filtrowanie reklam kontekstowych bez wywołań sieciowych
Jeśli na urządzeniu nie ma żądań remarketingu, możesz wyświetlać reklamy kontekstowe bez połączeń sieciowych. Dzięki gotowym identyfikatorom URI i liście reklam kontekstowych ze stawkami platforma może pominąć pobieranie logiki ustalania stawek, sygnałów ustalania stawek i sygnałów punktowych. Platforma używa gotowego identyfikatora URI, aby wybrać reklamę kontekstową z najwyższą stawką.
Aby skrócić czas oczekiwania, specjaliści ds. technologii reklamowych mogą przeprowadzać proces wyboru reklamy obejmujący tylko reklamy kontekstowe z funkcją filtrowania reklam bez wywołań sieciowych. Można to osiągnąć za pomocą gotowych identyfikatorów URI do określania wartości sygnałów. Listę obsługiwanych implementacji scoreAds
znajdziesz w sekcji na temat obsługiwanych gotowych identyfikatorów URI.
Aby wyświetlać wybór reklam bez połączeń sieciowych:
- Konfigurowanie filtrowania reklam
- Tworzenie reklam kontekstowych
Utwórz obiekt
AdSelectionConfig
z tą instrukcją:- Pusta lista kupujących
- Gotowy identyfikator URI służący do wybierania najwyższej stawki
- Reklamy kontekstowe
- Pusty identyfikator URI dla sygnałów punktowych. Pusty identyfikator URI może wskazać, że nie chcesz korzystać z pobierania zaufanych sygnałów do oceny:
Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting"); // Initialize AdSelectionConfig AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder() .setSeller(seller) .setDecisionLogicUri(prebuiltURIScoringUri) .setCustomAudienceBuyers(Collections.emptyList()) .setAdSelectionSignals(adSelectionSignals) .setSellerSignals(sellerSignals) .setPerBuyerSignals(perBuyerSignals) .setBuyerContextualAds(buyerContextualAds) .setTrustedScoringSignalsUri(Uri.EMPTY) .build();
Uruchom wybór reklamy:
adSelectionManager.selectAds( adSelectionConfig, executor, outcomeReceiver);
Uruchamiaj własny kod JavaScript do raportowania, korzystając z gotowych identyfikatorów URI
Obecnie platforma Piaskownicy prywatności obsługuje tylko podstawowe implementacje JavaScript służące do raportowania w przypadku gotowych identyfikatorów URI. Jeśli chcesz uruchamiać własny kod JavaScript do raportowania, jednocześnie korzystając z gotowych identyfikatorów URI do wyboru reklam z krótkim czasem oczekiwania, możesz zastąpić parametr DecisionLogicUri
między wyborem reklamy a generowaniem raportów.
- Wykonaj odpowiednie czynności, by korzystać z wyboru reklam kontekstowych przy użyciu gotowych identyfikatorów URI.
Zanim uruchomisz raportowanie, 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 organizacji wielu zewnętrznych pakietów SDK (sieci zewnętrznych) przez sieć zapośredniczenia SDK. Zapośredniczenie kaskadowe odbywa się w ten sam sposób niezależnie od tego, czy aukcja odbywała się na urządzeniu czy w usługach określania stawek i aukcji.
Sieci innych firm
Sieci zewnętrzne muszą dostarczyć adapter, który umożliwia sieci zapośredniczeń wywoływanie metod niezbędnych do przeprowadzenia aukcji:
- Uruchom wybór reklamy
- Raportuj wyświetlenia
Oto przykład adaptera sieci zapośredniczenia:
Kotlin
class NetworkAdaptor {
private val adSelectionManager : AdSelectionManager
init {
adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
}
fun selectAds() {...}
fun reportImpressions() {...}
}
Java
class NetworkAdaptor {
AdSelectionManager adSelectionManager;
public NetworkAdaptor() {
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
}
public void selectAds() {...}
public void reportImpressions() {...}
}
Każdy pakiet SDK ma własnych menedżerów i klientów usługi wyboru reklamy oraz własną implementację selectAds
i reportImpressions
. Dostawcy pakietów SDK mogą zapoznać się z sekcjami dotyczącymi wyboru reklam w przypadku aukcji na urządzeniu lub skorzystać z objaśnienia na temat aukcji B&A (w języku angielskim). Postępuj zgodnie z instrukcjami tworzenia raportów o wyświetleniach reklam (zgodnie z raportem wyświetleń pojedynczej platformy SSP na potrzeby raportowania).
Sieć zapośredniczeń
Podobnie jak sieci zewnętrzne, sieci zapośredniczenia potrzebują implementacji selectAds
i reportImpression
. Więcej informacji znajdziesz w sekcjach dotyczących wybierania reklam i raportowania wyświetleń reklam.
Sieci zapośredniczenia odpowiadają za uruchamianie łańcucha zapośredniczenia i umieszczanie się w nim. W następnej sekcji opisujemy, jak skonfigurować i przeprowadzić ten proces.
Pobieranie łańcucha zapośredniczenia i minimalnych stawek
Sieć zapośredniczenia odpowiada za pobieranie własnych reklam kontekstowych, łańcucha zapośredniczenia i minimalnych stawek z sieci zewnętrznych. Może się to zdarzyć w żądaniu pobrania reklam kontekstowych wykonanych przez sieć zapośredniczenia. Łańcuch zapośredniczenia określa sposób iteracji w sieciach zewnętrznych, a minimalne stawki mogą być przekazywane do procesu aukcji jako adSelectionSignals
.
Miejsce docelowe w sieci w łańcuchu zapośredniczenia
Pakiet SDK zapośredniczenia może umieścić się w łańcuchu zapośredniczenia na podstawie rzeczywistego eCPM własnych stawek reklam. W interfejsie Protected Audience API stawki za reklamy są nieprzejrzyste. Pakiet SDK zapośredniczenia powinien używać parametru AdSelectionFromOutcomesConfig
, aby móc porównywać stawkę za daną reklamę własnej reklamy ze stawką minimalną następnej sieci zewnętrznej w łańcuchu. Jeśli stawka własna jest wyższa niż minimalna stawka, oznacza to, że pakiet SDK zapośredniczenia jest umieszczony przed daną siecią zewnętrzną.
Uruchom wybór reklamy
Aby pobrać propozycję reklamy własnej, sieć zapośredniczenia może przeprowadzić aukcję na urządzeniu zgodnie z instrukcjami w sekcji Uruchom wybór reklamy. W ten sposób wygenerujemy własną kandydaturę, stawkę i AdSelectionId
, które będą używane w procesie zapośredniczenia.
Tworzenie konfiguracji AdSelectionFromResultsConfig
Element AdSelectionFromOutcomesConfig
umożliwia sieci zapośredniczeń przekazanie listy AdSelectionIds
(wyników z poprzednich aukcji), sygnałów wyboru reklamy oraz identyfikatora URI do pobrania kodu JavaScript, który wybiera reklamę spośród wielu kandydatów. Lista identyfikatorów AdSelectionId wraz z ich stawkami i sygnałami jest przekazywana do kodu JavaScript, który może zwrócić jedną z wartości AdSelectionIds
, jeśli przekroczy dolny limit stawki, lub żaden, jeśli łańcuch zapośredniczenia powinien kontynuować działanie.
Sieci zapośredniczenia tworzą AdSelectionFromOutcomesConfig
, korzystając z własnego elementu (AdSelectionId
) z poprzedniej sekcji oraz minimalnej stawki dla danej sieci zewnętrznej. Dla każdego kroku łańcucha zapośredniczenia należy utworzyć nowy obiekt AdSelectionFromOutcomesConfig
.
Kotlin
fun runSelectOutcome(
adSelectionClient : AdSelectionClient,
outcome1p : AdSelectionOutcome,
network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
val config = AdSelectionFromOutcomesConfig.Builder()
.setSeller(seller)
.setAdSelectionIds(listOf(outcome1p))
.setSelectionSignals({"bid_floor": bid_floor})
.setSelectionLogicUri(selectionLogicUri)
.build()
return adSelectionClient.selectAds(config)
}
Java
public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
NetworkAdapter network3p) {
AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
.setSeller(seller)
.setAdSelectionIds(Collection.singletonList(outcome1p))
.setSelectionSignals({"bid_floor": bid_floor})
.setSelectionLogicUri(selectionLogicUri)
.build();
return adSelectionClient.selectAds(config){}
}
Zastępowanie metody selectAds()
w przypadku zapośredniczenia kaskadowego wymaga podania danych wejściowych AdSelectionFromOutcomesConfig
, w których musisz podać te wymagane parametry:
- Sprzedawca: identyfikator sieci reklamowej sprzedawcy, która inicjuje wybór reklamy.
- AdSelectionIds: lista pojedynczych wartości z poprzedniego uruchomienia
selectAds()
dla reklamy własnej. - Sygnały wyboru reklamy: obiekt JSON zserializowany jako ciąg znaków zawierający sygnały do wykorzystania przez logikę ustalania stawek przez kupującego. W takim przypadku uwzględnij minimalną stawkę pobraną dla danej sieci zewnętrznej.
- Identyfikator URI usługi Selection Logic: adres URL HTTPS wysłany podczas wyboru reklamy w celu pobrania kodu JavaScript sieci zapośredniczenia na potrzeby wyboru zwycięskiej reklamy. Zobacz wymagane podpisy funkcji w tym JavaScripcie. Kod JavaScript powinien zwrócić reklamę firmy zewnętrznej, jeśli stawka jest wyższa niż dolna stawka lub w inny sposób zwróci wartość
null
. Dzięki temu pakiet SDK zapośredniczenia może skrócić łańcuch zapośredniczenia po znalezieniu zwycięzcy.
Po utworzeniu AdSelectionOutcomesConfig
wywołaj metodę selectAds()
sieci zewnętrznej, która jest pierwsza w łańcuchu.
Kotlin
val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
AdSelectionFromOutcomesConfig.Builder()
.setSeller(seller)
.setAdSelectionIds(listof(outcome1p))
.setSelectionSignals({"bid_floor": bid_floor})
.setSelectionLogicUri(selectionLogicUri)
.setAdSelectionIds(outcomeIds)
.build()
// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
adSelectionFromOutcomesConfig,
executor,
outcomeReceiver)
Java
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
new AdSelectionFromOutcomesConfig.Builder()
.setSeller(seller)
.setAdSelectionIds(Collection.singletonList(outcome1p))
.setSelectionSignals({"bid_floor": bid_floor})
.setSelectionLogicUri(selectionLogicUri)
.setAdSelectionIds(outcomeIds)
.build();
// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
adSelectionFromOutcomesConfig,
executor,
outcomeReceiver);
Administrowanie zapośredniczeniem kaskadowym
Poniżej przedstawiono kolejność działań, które mają zostać przeprowadzone w ramach procesu zapośredniczenia.
- Uruchom wybór własnej reklamy.
- Powtórzenie w łańcuchu zapośredniczenia. W przypadku każdej sieci 3P wykonaj te czynności:
- Kompilacja
AdSelectionFromOutcomeConfig
z własnym elementemoutcomeId
oraz minimalną stawką z pakietu SDK firmy zewnętrznej. - Wywołaj funkcję
selectAds()
, używając konfiguracji z poprzedniego kroku. - Jeśli wynik nie jest pusty, zwraca reklamę.
- Wywołaj metodę
selectAds()
obecnego adaptera sieci SDK. Jeśli wynik nie jest pusty, zwracaj reklamę.
- Kompilacja
- Jeśli w łańcuchu nie zostanie znalezionego zwycięzcy, zwróć reklamę własną.
Kotlin
fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
: Pair<AdSelectionOutcome, NetworkAdapter> {
val outcome1p = runAdSelection()
var outcome : AdSelectionOutcome
for(network3p in mediationChain) {
outcome = runSelectOutcome(outcome1p, network3p)
if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
return Pair(outcome, this)
}
outcome = network3p.runAdSelection()
if(outcome.hasOutcome()) {
return Pair(outcome, network3p)
}
}
return Pair(outcome1p, this)
}
Java
class MediationNetwork {
AdSelectionManager adSelectionManager;
public MediationNetwork() {
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
}
public void runAdSelection() {...}
public void reportImpressions() {...}
public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
List<NetworkAdapter> mediationChain) {
AdSelectionOutcome outcome1p = runAdSelection();
AdSelectionOutcome outcome;
for(NetworkAdapter network3p: mediationChain) {
if (outcome1p.hasOutcome() &&
(outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
return new Pair<>(outcome, this);
}
if((outcome = network3p.runAdSelection()).hasOutcome()) {
return new Pair<>(outcome, network3p);
}
}
return new Pair<>(outcome1p, this);
}
/* Runs comparison by creating an AdSelectionFromOutcomesConfig */
public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
NetworkAdapter network3p) { ... }
}
Zgłaszanie wyświetleń reklam
Istnieją 2 procesy raportowania wyświetlenia reklamy w zależności od sposobu przeprowadzania aukcji. Jeśli prowadzisz jedną aukcję SSP, postępuj zgodnie z instrukcjami podanymi w tej sekcji. Jeśli zamierzasz wdrożyć zapośredniczenie kaskadowe, wykonaj czynności opisane w sekcji raportowania wyświetleń zapośredniczenia kaskadowego.
Raportowanie wyświetleń pojedynczej platformy SSP
Gdy zwycięska reklama zostanie wybrana w ramach procesu wyboru reklamy, możesz za pomocą metody AdSelectionManager.reportImpression()
generować raporty o wyświetleniach na uczestniczących w nich platformach po stronie kupujących i sprzedawców. Aby zgłosić wyświetlenie reklamy:
- Zainicjuj obiekt
AdSelectionManager
. - Utwórz obiekt
ReportImpressionRequest
z identyfikatorem wyboru reklamy. - Wywołaj asynchroniczną metodę
reportImpression()
z obiektemReportImpressionRequest
oraz odpowiednimi obiektamiExecutor
iOutcomeReceiver
.
Java
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
new ReportImpressionRequest.Builder()
.setAdSelectionId(adSelectionId)
.setAdSelectionConfig(adSelectionConfig)
.build();
// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
reportImpressionRequest,
executor,
outcomeReceiver);
Kotlin
val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
ReportImpressionRequest.Builder()
.setAdSelectionId(adSelectionId)
.setAdSelectionConfig(adSelectionConfig)
.build()
// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
reportImpressionRequest,
executor,
outcomeReceiver)
Zainicjuj ReportImpressionRequest
tymi wymaganymi parametrami:
- Identyfikator wyboru reklamy: unikalny identyfikator przypisany wyłącznie do użytkownika urządzenia, który pozwala wybrać reklamę.
- Konfiguracja wyboru reklamy: ta sama konfiguracja użyta w wywołaniu
selectAds()
określona przez podany identyfikator wyboru reklamy.
Asynchroniczna metoda reportImpression()
, używa obiektu OutcomeReceiver
do sygnalizowania wyniku wywołania interfejsu API.
- Wywołanie zwrotne
onResult()
wskazuje, czy adresy URL do raportowania wyświetleń zostały utworzone, a żądanie zostało zaplanowane. - Wywołanie zwrotne
onError()
wskazuje te możliwe warunki:- Jeśli wywołanie zostało zainicjowane przy użyciu nieprawidłowego argumentu wejściowego,
AdServicesException
wskazuje jako przyczynęIllegalArgumentException
. - W przypadku pozostałych błędów wyświetlany jest
AdServicesException
z przyczynąIllegalStateException
.
- Jeśli wywołanie zostało zainicjowane przy użyciu nieprawidłowego argumentu wejściowego,
Raportowanie wyświetleń zapośredniczenia kaskadowego
Pakiet SDK zapośredniczenia musi śledzić zwycięski pakiet SDK, aby aktywować procesy raportowania. Pakiety SDK, które należą do łańcucha zapośredniczenia, powinny udostępniać metodę wywoływania funkcji mediatorowi, która uruchamia własny proces raportowania. Pakiet SDK uczestniczący w aukcji zapośredniczonej może wykonać powyższe czynności, aby wdrożyć własne raportowanie.
Platformy SSP mogą użyć tego przykładowego kodu zewnętrznego pakietu SDK jako prototypu sposobu łączenia w procesach zapośredniczenia:
Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
mediationSdk.orchestrateMediation(mediationChain);
if (winner.first.hasOutcome()) {
winner.second.reportImpressions(winner.first.getAdSelectionId());
Punkty końcowe raportowania wyświetleń
Interfejs API wyświetleń raportu wysyła żądania HTTPS GET do punktów końcowych dostarczanych przez platformę sprzedawcy i wygrywającą platformę kupującego:
Punkt końcowy platformy po stronie kupującego:
- Interfejs API korzysta z adresu URL logiki ustalania stawek określonego w sekcji niestandardowej listy odbiorców do pobrania udostępnionego przez kupującego kodu JavaScriptu, który zawiera kod JavaScript zwracający adres URL do raportowania wyświetleń.
- Wywołaj funkcję JavaScript
reportWin()
, która powinna zwracać adres URL raportowania wyświetleń kupującego.
Punkt końcowy platformy po stronie sprzedawcy:
- Użyj adresu URL logiki decyzji określonego w obiekcie
AdSelectionConfig
, aby pobrać kod JavaScript logiki decyzji sprzedawcy. - Wywołaj funkcję JavaScript
reportResult()
, która powinna zwracać adres URL raportowania wyświetleń kupującego.
Raporty dotyczące ustalania stawek i usług aukcyjnych
Aukcja prowadzona w ramach usług określania stawek i aukcji będzie zawierać wszystkie niezbędne informacje raportowania, w tym wygenerowane adresy URL na potrzeby raportowania interakcji z reklamą, w zaszyfrowanej odpowiedzi z aukcji po stronie serwera. Po odszyfrowaniu odpowiedzi odpowiednie adresy URL są rejestrowane na platformie, więc raportowanie reklam i wyświetleń wymaga wykonania tych samych czynności, które opisaliśmy powyżej.
Raporty wyświetleń
Metoda reportImpression()
została zaprojektowana z myślą o możliwości pełnego raportowania.
Raportuj interakcje z reklamami
Protected Audience umożliwia raportowanie bardziej szczegółowych interakcji z renderowaną reklamą. Mogą to być interakcje takie jak czas oglądania, kliknięcia, najechanie kursorem i inne przydatne dane, które można gromadzić. Procedura otrzymywania tych raportów składa się z dwóch etapów. Po pierwsze kupujący i sprzedawcy muszą się zarejestrować, aby otrzymywać te raporty w swoim kodzie JavaScript. Następnie klient musi zgłosić te zdarzenia.
Rejestracja w celu otrzymywania zdarzeń interakcji
Rejestrowanie zdarzeń interakcji odbywa się w funkcjach JavaScript kupującego (reportWin()
) i w funkcjach reportResult()
sprzedawcy przy użyciu funkcji JavaScript udostępnianej przez platformę: registerAdBeacon
. Aby zarejestrować się w celu otrzymywania raportu o zdarzeniach, wystarczy wywołać funkcję JavaScript platformy z poziomu kodu JavaScript raportowania. Ten fragment kodu korzysta z elementu reportWin()
kupującego, ale to samo podejście dotyczy reportResult()
.
reportWin(
adSelectionSignals,
perBuyerSignals,
signalsForBuyer,
contextualSignals,
customAudienceSignals) {
...
// Calculate reportingUri, clickUri, viewUri, and hoverUri
registerAdBeacon("click", clickUri)
registerAdBeacon("view", viewUri)
registerAdBeacon("hover", hoverUri)
return reportingUrl;
}
Raportowanie zdarzeń interakcji
Po zgłoszeniu wyświetlenia klienci mogą raportować interakcje na wcześniej zarejestrowanych zwycięskich platformach po stronie kupujących i sprzedawców za pomocą metody AdSelectionManager.reportInteraction()
. Aby zgłosić zdarzenie reklamowe:
- Zainicjuj obiekt
AdSelectionManager
. - Utwórz obiekt
ReportInteractionRequest
z identyfikatorem wyboru reklamy, kluczem interakcji, danymi dotyczącymi interakcji i miejscem docelowym raportowania. - Wywołaj asynchroniczną metodę
reportInteraction()
z obiektemrequest
i odpowiednimi obiektamiExecutor
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
tymi wymaganymi parametrami:
- Ad Selection ID (Identyfikator wyboru reklamy): identyfikator wyboru reklamy pobrany z zwróconego wcześniej
AdSelectionOutcome
. - Klucz interakcji: zdefiniowany przez klienta klucz tekstowy opisujący zgłaszane działanie. Musi on być zgodny z kluczem zarejestrowanym przez sprzedawcę lub kupującego w funkcjach JavaScript służących do raportowania.
- Dane interakcji: ciąg znaków zawierający dane, które zostaną dołączone do raportu o zdarzeniach i wysłane z powrotem na serwery raportowania.
- Miejsca docelowe raportowania: maska określająca, czy zdarzenia powinny być raportowane do kupującego, sprzedawcy czy do obu tych elementów. Te flagi są dostarczane przez platformę, a końcową maskę docelową można utworzyć za pomocą operacji bitowych. Aby zgłosić problem do jednego miejsca docelowego, możesz użyć flagi dostarczonej bezpośrednio przez platformę. Aby tworzyć raporty dla wielu miejsc docelowych, możesz użyć operatora bitowego LUB (
|
) do połączenia wartości flag.
Asynchroniczna metoda reportInteraction()
, używa obiektu OutcomeReceiver
do sygnalizowania wyniku wywołania interfejsu API.
- Wywołanie zwrotne
onResult()
wskazuje, że wywołanie interakcji z raportem jest prawidłowe. - Wywołanie zwrotne
onError()
wskazuje te możliwe warunki:- Jeśli wywołanie jest wykonywane, gdy aplikacja działa w tle, zwracany jest błąd
IllegalStateException
z opisem błędu. - Jeśli klient ma ograniczone możliwości wywoływania funkcji
reportInteraction()
, zwracany jest kodLimitExceededException
. - Jeśli pakiet nie jest zarejestrowany do wywoływania interfejsów API zachowywania prywatności, zwracany jest błąd
SecurityException()
. - Jeśli interakcje z raportowaniem w aplikacji różnią się od aplikacji, która wywołuje
selectAds()
, zwracana jest wartośćIllegalStateException
.
- Jeśli wywołanie jest wykonywane, gdy aplikacja działa w tle, zwracany jest błąd
- Jeśli użytkownik nie wyrazi zgody na włączenie interfejsów API Piaskownicy prywatności, wywołanie nie powiedzie się po cichu.
Punkty końcowe raportowania interakcji
Interfejs API interakcji w raportach wysyła żądania HTTPS POST do punktów końcowych dostarczonych przez platformę sprzedawcy i wygrywającą platformę kupującego. Protected Audience dopasowuje klucze interakcji do identyfikatorów URI zadeklarowanych w przypadku raportowania JavaScriptu i w przypadku każdej zgłaszanej interakcji wysyła do każdego punktu końcowego żądanie POST. Typ treści żądania to zwykły tekst, a treścią są dane interakcji.
Raporty interakcji
Interfejs reportInteraction()
został zaprojektowany z myślą o jak najwygodniejszym wypełnianiu raportów za pomocą metody HTTP POST.
Codzienna aktualizacja w tle
Podczas tworzenia niestandardowej listy odbiorców aplikacja lub pakiet SDK może zainicjować niestandardowe metadane odbiorców. Dodatkowo platforma może w ramach codziennego procesu aktualizacji w tle aktualizować podane niżej niestandardowe metadane odbiorców.
- Sygnały dotyczące określania stawek przez użytkowników
- Dane dotyczące zaufanego określania stawek
AdData
lista
Spowoduje to przetwarzanie zapytań wysyłanych do adresu URL aktualizacji dziennej zdefiniowanej w niestandardowych grupach odbiorców, a adres URL może zwrócić odpowiedź JSON.
- Odpowiedź JSON może zawierać dowolne obsługiwane pola metadanych, które trzeba zaktualizować.
- Każde pole JSON jest sprawdzane niezależnie. Klient ignoruje wszystkie nieprawidłowe pola, które nie powodują żadnych aktualizacji tego konkretnego pola w odpowiedzi.
- Pusta odpowiedź HTTP lub pusty obiekt JSON „
{}
” nie powodują aktualizacji metadanych. - Rozmiar wiadomości z odpowiedzią musi być ograniczony do 10 KB.
- Do korzystania z HTTPS wymagane są wszystkie identyfikatory URI.
trusted_bidding_uri
musi mieć ten sam identyfikator ETLD + 1 co kupujący.
Przykład: odpowiedź JSON dotycząca codziennej aktualizacji w tle
{
"user_bidding_signals" : { ... }, // Valid JSON object
"trusted_bidding_data" : {
"trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
"trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
},
'ads' : [
{
"render_uri" : 'www.example-dsp1.com/.../campaign123.html',
'metadata' : { ... } // Valid JSON object
},
{
"render_uri" : 'www.example-dsp1.com/.../campaign456.html',
'metadata' : { ... } // Valid JSON object
},
...
]
}
JavaScript do wyboru reklamy
Proces wyboru reklamy administruje wykonywaniem kodu JavaScript dostarczonego przez kupującego i sprzedawcy.
Kod JavaScript dostarczony przez kupującego jest pobierany z adresu URL logiki ustalania stawek określonego w sekcji niestandardowej na liście odbiorców. Zwracany kod JavaScript powinien zawierać następujące funkcje:
Kod JavaScript udostępniony przez sprzedawcę jest pobierany z adresu URL opartego na logice decyzji określonego w parametrze AdSelectionConfig
interfejsu API wyboru reklamy. Zwracany JavaScript powinien zawierać te funkcje:
wygenerujesz_stawkę()
function generateBid(
ad,
auction_signals,
per_buyer_signals,
trusted_bidding_signals,
contextual_signals,
user_signals,
custom_audience_bidding_signals) {
return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}
Parametry wejściowe:
ad
: obiekt JSON w formacievar ad = { 'render_url': url, 'metadata': json_metadata };
.auction_signals, per_buyer_signals
: obiekty JSON określone w obiekcie konfiguracji aukcjicustom_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ąg znaków pochodzący z właściwości o tej samej nazwie grupy niestandardowych odbiorców, która uczestniczy w wyborze reklamy.activation_time
iexpiration_time
to czas aktywacji i wygaśnięcia niestandardowej listy odbiorców wyrażony w sekundach od epoki uniksowej.ca_user_bidding_signals
to ciąg znaków JSON określony w poluuserBiddingSignals
wCustomAudience
podczas tworzeniatrusted_bidding_signals, contextual_signals
iuser_signals
to obiekty JSON. Są one przekazywane jako puste obiekty i zostaną wypełnione w kolejnych wersjach. Ich format nie jest egzekwowany przez platformę i jest zarządzany przez technologię reklamową.
Efekt:
ad
: to reklama, której dotyczy stawka. Skrypt może zwrócić kopię otrzymanej reklamy z innymi metadanymi. Właściwośćrender_url
reklamy powinna pozostać niezmieniona.bid
: liczba zmiennoprzecinkowa odpowiadająca wartości stawki za tę reklamę.status
: liczba całkowita, którą może być:0
: skuteczne wykonanie1
: (lub dowolna wartość inna niż 0), jeśli którykolwiek z sygnałów wejściowych jest nieprawidłowy. Jeśli w procesie ustalania stawek zostanie zwrócona wartość inna niż 0, proces ustalania stawek zostanie unieważniony w przypadku wszystkich reklam z Kanady.
ScoreAd()
function scoreAd(
ad,
bid,
ad_selection_config,
seller_signals,
trusted_scoring_signals,
contextual_signal,
user_signal,
custom_audience_signal) {
return {'status': 0, 'score': score };
}
Parametry wejściowe:
ad
: patrz dokumentacjęgenerateBid
bid
: wartość stawki za reklamę.ad_selection_config
: obiekt JSON reprezentujący parametrAdSelectionConfig
interfejsuselectAds
API. Format to:var ad_selection_config = { 'seller': 'seller', 'decision_logic_url': 'url_of_decision_logic', 'custom_audience_buyers': ['buyer1', 'buyer2'], 'auction_signals': auction_signals, 'per_buyer_signals': per_buyer_signals, 'contextual_ads': [ad1, ad2] }
seller_signals
: obiekty JSON odczytywane z parametru interfejsu APIsellerSignals
AdSelectionConfig
trusted_scoring_signal
: odczyt z polaadSelectionSignals
w parametrze interfejsu APIAdSelectionConfig
.contextual_signals, user_signals
: obiekty JSON. Obecnie są one przekazywane jako puste obiekty i będą wypełniane w kolejnych wersjach. Ich format nie jest egzekwowany przez platformę i jest zarządzany przez technologię reklamową.per_buyer_signals
: obiekt JSON odczytywany z mapyperBuyerSignal
w parametrze interfejsu APIAdSelectionConfig
przy użyciu klucza bieżącego kupującego na liście odbiorców niestandardowych. Pusta, jeśli mapa nie zawiera żadnych wpisów dotyczących danego kupującego.
Dane wyjściowe:
score
: wartość zmiennoprzecinkowa reprezentująca wynik danej reklamy.status
: liczba całkowita, którą może być:- 0: skuteczne wykonanie
- 1: jeśli pola
customAudienceSignals
są nieprawidłowe - 2: jeśli
AdSelectionConfig
jest nieprawidłowy - 3: na wypadek, gdyby którykolwiek z pozostałych sygnałów jest nieprawidłowy
- Każda wartość różna od zera powoduje błąd procesu – ta wartość określa rodzaj zgłoszonego wyjątku.
selectOutcome()
function selectOutcome(
outcomes,
selection_signals) {
return {'status': 0, 'result': null};
}
Parametry wejściowe:
outcomes
: obiekt JSON{"id": id_string, "bid": bid_double}
selection_signals
: obiekty JSON określone w obiekcie konfiguracji aukcji
Dane wyjściowe:
status
:0
oznacza sukces, wartość inna niż 0 oznacza niepowodzenieresult
: jeden z wyników przekazanych lub null.
reportResult()
function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
return {
'status': status,
'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
};
}
Parametry wejściowe:
ad_selection_config
: wyświetl dokumentacjęscoreAds
render_url
: URL renderowania zwycięskiej reklamy;bid
: stawka zaoferowana dla zwycięskiej reklamy.contextual_signals
: wyświetl dokumentacjęgenerateBid
Dane wyjściowe:
status: 0
oznacza sukces, inne niż 0 w przypadku niepowodzeniaresults
: obiekty JSON zawierające:signals_for_buyer
: obiekt JSON przekazywany do funkcjireportWin
.reporting_url
: adres URL używany przez platformę do wysyłania powiadomień o wyświetleniu dla kupującego.
reportWin()
function reportWin(
ad_selection_signals,
per_buyer_signals,
signals_for_buyer,
contextual_signals,
custom_audience_signals) {
return {'status': 0, 'results': {'reporting_url': reporting_url } };
}
Parametry wejściowe:
ad_selection_signals, per_buyer_signals
: wyświetl dokumentacjęscoreAd
signals_for_buyer
: obiekt JSON zwrócony przezreportResult
contextual_signals, custom_audience_signals
: wyświetl dokumentacjęgenerateBid
Dane wyjściowe:
status: 0
oznacza sukces, inne niż 0 w przypadku niepowodzeniaresults
: obiekt JSON zawierający:reporting_url
: adres URL używany przez platformę do powiadamiania sprzedawcy o wyświetleniach.
registerAdBeacon()
function registerAdBeacon(
interaction_key,
reporting_uri
)
Parametry wejściowe:
interaction_key
: ciąg znaków reprezentujący zdarzenie. Będzie ona później używana przez platformę podczas raportowania interakcji ze zdarzeniami, aby wyszukać elementreporting_uri
, który ma zostać powiadomiony. Klucz ten musi odpowiadać temu, co rejestruje kupujący lub sprzedawca, a danymi przez sprzedawcę.reporting_uri
: identyfikator URI służący do otrzymywania raportów o zdarzeniach. To ustawienie powinno być związane z typem zgłaszanego zdarzenia. Musi zaakceptować żądanie POST, aby obsługiwać wszelkie dane zgłoszone w związku ze zdarzeniem.
Gotowe identyfikatory URI dotyczące wyboru reklamy
Gotowe identyfikatory URI dają technikom reklamowym możliwość wyznaczenia funkcji JavaScript na potrzeby logiki decyzji o wyborze reklamy w klasach AdSelectionConfig
i AdSelectionFromOutcomesConfig
. Gotowe identyfikatory URI nie wymagają
wywołań sieciowych w celu pobrania odpowiedniego kodu JavaScript. Technologie reklamowe mogą używać gotowych identyfikatorów URI bez konieczności konfigurowania zarejestrowanej domeny do hostowania kodu JavaScript.
Gotowy identyfikator URI powstaje w tym formacie:
ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>
Platforma Piaskownicy prywatności udostępnia kod JavaScript w czasie działania, korzystając z informacji z tego identyfikatora URI.
Obiekt IllegalArgumentException
jest zwracany, jeśli:
- Identyfikator URI nie zawiera dowolnego z wymaganych parametrów
- identyfikator URI zawiera nierozpoznane parametry
Obsługiwane gotowe zastosowania i nazwy identyfikatorów URI
Przypadek użycia 1: wybór reklamy
Gotowe identyfikatory URI w przypadku użycia ad-selection
są obsługiwane w procesie selectAds(AdSelectionConfig)
.
Wstępnie utworzona nazwa identyfikatora URI: highest-bid-wins
Ten gotowy identyfikator URI zawiera kod JavaScript, który po określeniu stawki wybiera reklamę z najwyższą stawką. Zapewnia też podstawową funkcję raportowania, która pozwala zgłosić render_uri
i bid
zwycięzcy.
Parametry wymagane
reportingUrl
: podstawowy adres URL raportowania z parametrami render_uri
i bid
zwycięskiej reklamy:
<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>
Wykorzystanie
Jeśli podstawowy adres URL raportowania to https://www.ssp.com/reporting
, gotowy identyfikator URI będzie miał postać:
`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`
Przypadek użycia 2: wybór reklamy z wyników
Gotowe identyfikatory URI w przykładzie użycia ad-selection-from-outcomes
obsługują przepływ pracy selectAds(AdSelectionFromOutcomesConfig)
.
Wstępnie utworzona nazwa identyfikatora URI: waterfall-mediation-truncation
Gotowy identyfikator URI waterfall-mediation-truncation
udostępnia kod JavaScript, który implementuje logikę obcinania zapośredniczenia kaskadowego. JavaScript zwraca reklamę własną, jeśli wartość bid
jest większa niż lub równa bid floor
, a w przeciwnym razie zwraca wartość null
.
Parametry wymagane
bidFloor
: klucz do wartości minimalnej stawki przekazywanej w elemencie getSelectionSignals()
, która jest porównywana z reklamą z pakietu SDK zapośredniczenia.
Wykorzystanie
Jeśli sygnały wyboru reklamy mają postać {"bid_floor": 10}
, otrzymany gotowy identyfikator URI będzie wyglądać tak:
`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`
Testowanie
Aby pomóc Ci zacząć korzystać z interfejsu Protected Audience API, utworzyliśmy przykładowe aplikacje w języku Kotlin i Javie, które znajdziesz na GitHub.
Wymagania wstępne
Protected Audience API wymaga obsługi JavaScriptu podczas wyboru reklamy i raportowania wyświetleń. Kod JavaScriptu w środowisku testowym można udostępniać na 2 sposoby:
- Uruchomić serwer z wymaganymi punktami końcowymi HTTPS, które zwracają kod JavaScript.
- Zastąp pobieranie zdalne, podając niezbędny kod ze źródła lokalnego
Oba sposoby wymagają skonfigurowania punktu końcowego HTTPS do obsługi raportów o wyświetleniach.
Punkty końcowe HTTPS
Aby przetestować wybór reklam i raportowanie wyświetleń, musisz skonfigurować 7 punktów końcowych HTTPS, do których ma dostęp urządzenie testowe lub emulator:
- Punkt końcowy kupującego, który obsługuje kod JavaScript określania stawek.
- Punkt końcowy, który obsługuje sygnały związane z ustalaniem stawek.
- Punkt końcowy sprzedawcy, który obsługuje kod JavaScript logiczny decyzji.
- Punkt końcowy, który obsługuje sygnały punktowe.
- Punkt końcowy raportowania wyświetleń zwycięskiego kupującego.
- Punkt końcowy raportowania wyświetleń przez sprzedawcę.
- Punkt końcowy do wysyłania codziennych aktualizacji w przypadku niestandardowej listy odbiorców.
Dla wygody repozytorium GitHub udostępnia podstawowy kod JavaScript do celów testowych. Zawiera też definicje usług OpenAPI, które można wdrożyć na obsługiwanej platformie testowej lub mikroserwisach. Więcej informacji znajdziesz w pliku README projektu.
Zastępowanie zdalnego pobierania kodu JavaScript
Ta funkcja jest przeznaczona do kompleksowego testowania. Aby zastąpić pobieranie zdalne, aplikacja musi działać w trybie debugowania z włączonymi opcjami programisty.
Aby włączyć tryb debugowania w przypadku swojej aplikacji, dodaj ten wiersz do atrybutu aplikacji w pliku AndroidManifest.xml:
<application
android:debuggable="true">
Przykład wykorzystania tych zastąpień znajdziesz w przykładowej aplikacji interfejsu Protected Audience API na GitHubie.
Aby obsługiwać procedury wyboru reklamy, takie jak ustalanie stawek, podejmowanie decyzji dotyczących punktacji i raportowanie, musisz dodać własny niestandardowy kod JavaScript. Podstawowe przykłady kodu JavaScript, które obsługują wszystkie wymagane żądania, znajdziesz w repozytorium GitHub. Przykładowa aplikacja Protected Audience API pokazuje, jak odczytać kod z tego pliku i przygotować go do użycia jako zastąpienia.
Możesz niezależnie zastępować pobieranie JavaScript po stronie sprzedawcy i po stronie kupującego, ale potrzebujesz punktu końcowego HTTPS do obsługi kodu JavaScript, w przypadku którego nie udostępniasz zastąpień. Informacje o konfigurowaniu serwera do obsługi takich przypadków znajdziesz w README.
Pobieranie za pomocą JavaScriptu można zastąpić tylko w przypadku niestandardowych list odbiorców, które należą do Twojego pakietu.
Zastąp kod JavaScript dostępny dla sprzedawców
Aby skonfigurować zastąpienie kodu JavaScript przeznaczonego do sprzedaży, wykonaj te czynności w sposób pokazany poniżej:
- Zainicjuj obiekt
AdSelectionManager
. - Uzyskaj odniesienie do obiektu
TestAdSelectionManager
z obiektuAdSelectionManager
. - Utwórz obiekt
AdSelectionConfig
. - Utwórz
AddAdSelectionOverrideRequest
z obiektemAdSelectionConfig
orazString
reprezentującą kod JavaScript, którego chcesz użyć jako zastąpienia. - Wywołaj asynchroniczną metodę
overrideAdSelectionConfigRemoteInfo()
z obiektemAddAdSelectionOverrideRequest
oraz odpowiednimi obiektamiExecutor
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);
Więcej informacji o tym, co reprezentują poszczególne pola w AdSelectionConfig
, znajdziesz w sekcji Uruchom wybór reklamy. Główna różnica polega na tym, że parametr decisionLogicUrl może zostać ustawiony na wartość zmiennej, ponieważ będzie ona ignorowana.
Aby zastąpić JavaScript używany podczas wyboru reklamy, decisionLogicJs
musi zawierać odpowiednie podpisy funkcji po stronie sprzedawcy.
Informacje o tym, jak odczytać plik JavaScript pod postacią ciągu znaków, znajdziesz w przykładowej aplikacji Protected Audience API w GitHubie.
Asynchroniczna metoda overrideAdSelectionConfigRemoteInfo()
, używa obiektu OutcomeReceiver
do sygnalizowania wyniku wywołania interfejsu API.
Wywołanie zwrotne onResult()
oznacza, że zastąpienie zostało zastosowane.
Przyszłe wywołania funkcji selectAds()
będą używać dowolnej decyzji i logiki raportowania przekazanej jako zastąpienie.
Wywołanie zwrotne onError()
oznacza 2 możliwe warunki:
- Jeśli zostanie podjęta próba zastąpienia przy użyciu nieprawidłowych argumentów,
AdServiceException
wskazuje jako przyczynęIllegalArgumentException
. - Jeśli zostanie podjęta próba zastąpienia przy aplikacji, która nie jest uruchomiona w trybie debugowania z włączonymi opcjami programisty,
AdServiceException
wskazujeIllegalStateException
jako przyczynę.
Zresetuj zastąpienia po stronie sprzedawcy
W tej sekcji zakładamy, że zastąpisz kod JavaScript sprzedawcy i że stosujesz odwołanie do metod TestAdSelectionManager
i AdSelectionConfig
użytych w poprzedniej sekcji.
Aby zresetować zastąpienia dla wszystkich AdSelectionConfigs
:
- Wywołaj asynchroniczną metodę
resetAllAdSelectionConfigRemoteOverrides()
za pomocą odpowiedniego obiektuOutcomeReceiver
.
Kotlin
// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver)
Java
// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver);
Po zresetowaniu zastąpień po stronie sprzedawcy wywołania selectAds()
używają dowolnego parametru decisionLogicUrl zapisanego w pliku AdSelectionConfig
, aby pobrać wymagany kod JavaScript.
Jeśli wywołanie resetAllAdSelectionConfigRemoteOverrides()
nie powiedzie się, wywołanie zwrotne OutComeReceiver.onError()
zwróci metodę AdServiceException
.
Jeśli spróbujesz usunąć zastąpienia, gdy aplikacja nie jest uruchomiona w trybie debugowania z włączonymi opcjami programisty, AdServiceException
wskazuje jako przyczynę IllegalStateException
.
Zastąp kod JavaScript po stronie kupującego
- Aby dołączyć do grupy odbiorców niestandardowych:
- Utwórz element
AddCustomAudienceOverrideRequest
z kupującym i nazwą niestandardowej listy odbiorców, której ustawienia chcesz zastąpić, oraz z logiką ustalania stawek i danymi, których chcesz użyć jako zastąpienia - Wywołaj asynchroniczną metodę
overrideCustomAudienceRemoteInfo()
z obiektemAddCustomAudienceOverrideRequest
oraz odpowiednimi obiektamiExecutor
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 parametrów kupujący i name są takie same jak podczas tworzenia listy niestandardowych odbiorców. Więcej informacji o tych polach
Można też określić 2 dodatkowe parametry:
biddingLogicJs
: kod JavaScript, który przechowuje logikę kupującego i używany podczas wyboru reklamy. Zobacz wymagane podpisy funkcji w tym JavaScript.trustedBiddingSignals
: sygnały dotyczące ustalania stawek, które mają być używane podczas wyboru reklamy. Do celów testowych może to być pusty ciąg znaków.
Asynchroniczna metoda overrideCustomAudienceRemoteInfo()
, używa obiektu OutcomeReceiver
do sygnalizowania wyniku wywołania interfejsu API.
Wywołanie zwrotne onResult()
oznacza, że zastąpienie zostało zastosowane.
Kolejne wywołania funkcji selectAds()
używają dowolnej logiki określania stawek i raportowania, która została podana jako zastąpienie.
Wywołanie zwrotne onError()
oznacza 2 możliwe warunki.
- Jeśli zostanie podjęta próba zastąpienia przy użyciu nieprawidłowych argumentów,
AdServiceException
wskazuje jako przyczynęIllegalArgumentException
. - Jeśli zostanie podjęta próba zastąpienia przy aplikacji, która nie jest uruchomiona w trybie debugowania z włączonymi opcjami programisty,
AdServiceException
wskazujeIllegalStateException
jako przyczynę.
Zresetuj zastąpienia po stronie kupującego
W tej sekcji zakładamy, że JavaScript po stronie zakupu został zastąpiony i że odwołujesz się do TestCustomAudienceManager
użytego w poprzedniej sekcji.
Aby zresetować zastąpienia w przypadku wszystkich odbiorców niestandardowych:
- Wywołaj asynchroniczną metodę
resetAllCustomAudienceOverrides()
z odpowiednimi obiektamiExecutor
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 kupującego kolejne wywołania selectAds()
wykorzystują biddingLogicUrl
i trustedBiddingData
przechowywane w CustomAudience
, aby pobrać wymagany kod JavaScript.
Jeśli wywołanie resetCustomAudienceRemoteInfoOverride()
nie powiedzie się, wywołanie zwrotne OutComeReceiver.onError()
zwróci metodę AdServiceException
.
Jeśli spróbujesz usunąć zastąpienia, gdy aplikacja nie jest uruchomiona w trybie debugowania z włączonymi opcjami programisty, AdServiceException
wskazuje jako przyczynę IllegalStateException
.
Skonfiguruj serwer raportowania
Gdy używasz zastąpień pobierania zdalnego, nadal musisz skonfigurować serwer, z którym urządzenie lub emulator będzie mogło odpowiadać na zdarzenia raportowania. Do testowania wystarczy prosty punkt końcowy, który zwraca wartość 200. Repozytorium GitHub zawiera definicje usług OpenAPI, które można wdrożyć na obsługiwanej platformie testowej lub na obsługiwanej platformie mikroserwisów. Więcej informacji znajdziesz w pliku README projektu.
Szukając definicji OpenAPI, szukaj pliku Reporting-server.json.
Ten plik zawiera prosty punkt końcowy, który zwraca kod 200, reprezentujący kod odpowiedzi HTTP. Ten punkt końcowy jest używany w czasie selectAds()
i informuje interfejs Protected Audience API, że raportowanie wyświetleń zakończyło się powodzeniem.
Testowane funkcje
- Ćwiczenie polegające na dołączaniu lub opuszczaniu i konfigurowaniu niestandardowych grup odbiorców na podstawie wcześniejszych działań użytkownika.
- Rozpocznij proces wyboru reklam na urządzeniu za pomocą hostowanych zdalnie skryptów JavaScript.
- Obserwuj, jak powiązanie aplikacji z niestandardowymi ustawieniami odbiorców może wpływać na wybór reklamy.
- Ćwiczenie raportowania wyświetleń po wybraniu reklamy.
Ograniczenia
W tabeli poniżej znajdziesz informacje o ograniczeniach dotyczących przetwarzania przez interfejs Protected Audience API. Pokazane limity mogą ulec zmianie w zależności od otrzymanych opinii. Informacje o funkcjach w toku znajdziesz w informacjach o wersji.
Komponent | Opis limitu | Wartość limitu |
---|---|---|
Niestandardowi odbiorcy (Kanada) | Maksymalna liczba reklam na urząd certyfikacji | 100 |
Maksymalna liczba urzędów certyfikacji na aplikację | 1000 | |
Maksymalna liczba aplikacji, które mogą utworzyć urząd certyfikacji | 1000 | |
Maksymalne opóźnienie czasu aktywacji urzędu certyfikacji od czasu jego utworzenia | 60 dni | |
Maksymalny czas wygaśnięcia urzędu certyfikacji od momentu aktywacji | 60 dni | |
Maksymalna liczba urzędów certyfikacji na urządzeniu | 4000 | |
Maksymalny rozmiar nazwy urzędu certyfikacji | 200 bajtów | |
Maksymalny rozmiar identyfikatora URI pobierania dziennego | 400 bajtów | |
Maksymalny rozmiar identyfikatora URI logiki ustalania stawek | 400 bajtów | |
Maksymalny rozmiar danych dotyczących zaufanego określania stawek | 10 KB | |
Maksymalny rozmiar sygnałów dotyczących określania stawek przez użytkowników | 10 KB | |
Maksymalna stawka za połączenie leaveCustomAudience na kupującego |
1 na sekundę | |
Maksymalna stawka za połączenie joinCustomAudience na kupującego |
1 na sekundę | |
Pobieranie danych w tle z CA | Przekroczenie limitu czasu oczekiwania na połączenie | 5 sekund |
Limit czasu odczytu HTTP | 30 sekund | |
Maksymalny łączny rozmiar pobierania | 10 KB | |
Maksymalny czas trwania iteracji pobierania | 5 minut, | |
Maksymalna liczba urzędów certyfikacji została zaktualizowana na zadanie | 1000 | |
Wybór reklamy | Maksymalna liczba kupujących | Do ustalenia |
Maksymalna liczba urzędów certyfikacji na kupującego | Do ustalenia | |
Maksymalna liczba reklam w aukcji | Do ustalenia | |
Upłynął limit czasu na nawiązanie połączenia | 5 sekund | |
Upłynął limit czasu odczytu połączenia | 5 sekund | |
Maksymalny czas wykonywania ogólnego AdSelection |
10 sekund, | |
Maksymalny czas wykonywania określania stawek na urząd certyfikacji w: AdSelection |
5 sekund | |
Maksymalny czas wykonywania oceny w AdSelection |
5 sekund | |
Maksymalny czas wykonania na kupującego (AdSelection ) |
Do ustalenia | |
Maksymalny rozmiar sygnałów dotyczących wyboru reklamy/sprzedawcy/kupującego | Do ustalenia | |
Maksymalny rozmiar skryptów sprzedawcy/kupującego | Do ustalenia | |
Maksymalna szybkość połączeń w okresie selectAds |
1 zapytanie na sekundę | |
Raporty wyświetleń | Minimalny czas potrzebny do usunięcia wyboru reklamy z trwałości | 24 godziny |
Maksymalna liczba wybranych reklam służących do przechowywania danych | Do ustalenia | |
Maksymalny rozmiar wyjściowego adresu URL raportowania | Do ustalenia | |
Maksymalny czas na raportowanie wyświetleń | Do ustalenia | |
Maksymalna liczba ponownych prób wywołań powiadomień | Do ustalenia | |
Limit czasu połączenia | 5 sekund | |
Maksymalny ogólny czas wykonywania kodu reportImpression |
2 sekundy | |
Maksymalna szybkość połączeń w okresie reportImpressions |
1 zapytanie na sekundę | |
Raporty o zdarzeniach | Maksymalna liczba obrazów typu beacon na kupującego na aukcję | 10 |
Maksymalna liczba obrazów typu beacon na sprzedawcę na aukcję |
10 |
|
Maksymalny rozmiar klucza zdarzenia |
40 bajtów |
|
Maksymalny rozmiar danych zdarzenia |
64KB |
|
Reklamy | Maksymalny rozmiar listy reklam | 10 KB współużytkowane przez wszystkie AdData w jednym urzędzie certyfikacji na potrzeby kontekstu |
Adresy URL | Maksymalna długość dowolnego ciągu adresu URL liczonego jako dane wejściowe | Do ustalenia |
JavaScript | Maksymalny czas wykonywania | 1 sekunda na potrzeby określania stawek i oceniania na potrzeby raportowania wyświetleń |
Maksymalne wykorzystanie pamięci | 10 MB |
Zgłaszanie błędów i problemów
Twoja opinia jest kluczowym elementem Piaskownicy prywatności na Androida. Jeśli zauważysz jakieś problemy lub pomysły na ulepszenie Piaskownicy prywatności na Androidzie, daj nam znać.
Polecane dla Ciebie
- Uwaga: tekst linku jest wyświetlany, gdy JavaScript jest wyłączony
- Obsługa niestandardowego kierowania na odbiorców za pomocą interfejsu Protected Audience API
- Informacje o wersji
- Protected Audience API: przewodnik po integracji