Android'de Özel Korumalı Alan dokümanlarını okurken, çalıştığınız program sürümünü seçmek için Geliştirici Önizlemesi veya Beta düğmesini kullanın, talimatlar farklılık gösterebilir.
Android'deki Protected Audience API (eski adıyla FLEDGE), Özel Kitle API'sini ve Reklam Seçimi API'sini içerir. Reklam teknolojisi platformları ve reklamverenler, bu API'leri önceki uygulama etkileşimine göre özel reklamlar yayınlamak için kullanabilir. Bu özel reklamlar, uygulamalar arasında tanımlayıcıların paylaşımını ve kullanıcının uygulama etkileşimi bilgilerinin üçüncü taraflarla paylaşımını sınırlandırır.
Custom Audience API, ortak amaçları olan bir kullanıcı grubunu temsil eden "özel kitle" soyutlamasının merkezindedir. Bir reklamveren, bir kullanıcıyı özel bir kitleye kaydedebilir ve alakalı reklamları bu kitleyle ilişkilendirebilir. Bu bilgiler yerel olarak depolanır ve reklamveren teklifleri, reklam filtreleme ve reklam oluşturma işlemlerinde kullanılabilir.
Reklam Seçimi API'si, birden fazla geliştiricinin özel bir kitle için yerel olarak açık artırma yürütmesine olanak tanıyan bir çerçeve sağlar. Sistem, bunu başarmak için özel kitleyle ilişkili reklamları değerlendirir ve bir reklam teknolojisi platformunun cihaza döndürdüğü reklamlar üzerinde ek işlemler gerçekleştirir.
Reklam teknolojisi platformları, kullanıcı gizliliğini koruyan yeniden pazarlamayı uygulamak için bu API'leri entegre edebilir. Gelecekteki sürümlerde, uygulama yükleme reklamları dahil olmak üzere ek kullanım alanları için destek verilmesi planlanmaktadır. Tasarım teklifinde, Android'de Protected Audience API hakkında daha fazla bilgi edinebilirsiniz.
Bu kılavuzda, aşağıdaki işlemleri gerçekleştirmek için Android'de Protected Audience API ile nasıl çalışabileceğiniz açıklanmaktadır:
- Özel kitleleri yönetme
- Bir cihazda reklam seçimini ayarlayıp yayınlama
- Reklam gösterimlerini raporlama
Başlamadan önce
Başlamadan önce aşağıdaki adımları tamamlayın:
- Android'de Özel Korumalı Alan için geliştirme ortamınızı ayarlayın.
- Desteklenen bir cihaza sistem görüntüsü yükleyin veya Android'de Özel Korumalı Alan desteği içeren bir emülatör oluşturun.
Bir terminalde, aşağıdaki adb komutuyla Protected Audience API'ye erişimi etkinleştirin (varsayılan olarak devre dışıdır).
adb shell device_config put adservices ppapi_app_allow_list \"*\"
Uygulama manifestinize bir
ACCESS_ADSERVICES_CUSTOM_AUDIENCE
izni ekleyin:<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
Manifest'inizin
<application>
öğesinde bir reklam hizmetleri yapılandırmasına referans verin:<property android:name="android.adservices.AD_SERVICES_CONFIG" android:resource="@xml/ad_services_config" />
Manifest'inizde başvurulan reklam hizmetleri XML kaynağını belirtin (ör.
res/xml/ad_services_config.xml
). Reklam hizmetleri izinleri ve SDK erişim kontrolü hakkında daha fazla bilgi edinin.<ad-services-config> <custom-audiences allowAllToAccess="true" /> </ad-services-config>
Varsayılan olarak Reklam Seçimi API'si, bir açık artırma veya gösterim raporlama komut dosyasının ayırabileceği maksimum bellek miktarı için sınırlar uygular. Bellek sınırlama özelliği, WebView'un 105.0.5195.58 veya sonraki sürümünü gerektirir. Platform bir sürüm kontrolü uygular ve bu yerine getirilmezse
selectAds
vereportImpression
API'lerine yapılan çağrılar başarısız olur. Bunu iki şekilde ayarlayabilirsiniz:1. Seçenek: Bu denetimi devre dışı bırakmak için aşağıdaki adb komutunu çalıştırın:
adb device_config put fledge_js_isolate_enforce_max_heap_size false
2. Seçenek: Google Play Store'dan WebView Beta'yı yükleyin. Bu sayı, daha önce belirtilen sürüme eşit veya bundan daha yüksek olmalıdır.
Özel bir kitleye katılma
Özel kitle, reklamveren uygulamasının belirlediği ortak amaçları veya ilgi alanlarına sahip kullanıcı grubunu temsil eder. Bir uygulama veya SDK, belirli bir kitleyi (ör. alışveriş sepetinde ürün bırakan kullanıcılar) belirtmek için özel bir kitle kullanabilir. Eşzamansız olarak özel bir kitle oluşturmak veya bu kitleye katılmak için aşağıdakileri yapın:
CustomAudienceManager
nesnesini başlatın.- Alıcının paketi ve ilgili ad gibi anahtar parametreleri belirterek bir
CustomAudience
nesnesi oluşturun. ArdındanJoinCustomAudienceRequest
nesnesiniCustomAudience
nesnesiyle başlatın. - Eşzamansız
joinCustomAudience()
yönteminiJoinCustomAudienceRequest
nesnesi ve ilgiliExecutor
ileOutcomeReceiver
nesneleriyle çağırın.
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);
Aşağıdaki parametrelerin kombinasyonu, bir cihazdaki her bir CustomAudience
nesnesini benzersiz şekilde tanımlar:
owner
: Sahip uygulamanın paket adı. Bu, dolaylı olarak arayan uygulamanın paket adı olarak ayarlanır.buyer
: Bu özel kitle için reklamları yöneten alıcı reklam ağının tanımlayıcısı.name
: Özel kitle için rastgele bir ad veya tanımlayıcı.
joinCustomAudience()
öğesinin farklı bir CustomAudience
örneğiyle art arda çağrılması, mevcut CustomAudience
öğesinin eşleşen owner, buyer
ve name
parametreleriyle güncellenmesini sağlar. API'nin sağladığı sonuç, gizliliğin korunmasına yardımcı olmak için "oluşturma" ile "güncelleme" arasında ayrım yapmaz.
Ayrıca, CustomAudience
şu gerekli parametrelerle oluşturulmalıdır:
- Günlük güncelleme URL'si: Özel kitlenin kullanıcı teklif sinyallerini, güvenilir teklif verme verilerini ve reklamların URL'lerini ve meta verilerini oluşturmak için arka planda her gün sorgulanan HTTPS URL'si.
- Teklif mantığı URL'si: Alıcının JavaScript teklif verme mantığını getirmek için reklam seçimi sırasında sorgulanan HTTPS URL'si. Bu JavaScript'te gerekli işlev imzalarına bakın.
- Reklam Oluşturma Kimlikleri: Alıcı reklam teknolojisi tarafından ayarlanan rastgele kimliktir. Bu, B&A için yükü oluşturmaya yönelik bir optimizasyondur.
CustomAudience
nesnesi için isteğe bağlı parametreler şunları içerebilir:
- Etkinleştirme zamanı: Özel bir kitle, yalnızca etkinleştirme zamanından sonra reklam seçimine ve günlük güncellemelere katılabilir. Bu, örneğin bir uygulamayı eski kullanıcılarıyla etkileşime almak için yararlı olabilir.
- Sona erme süresi: Özel kitlenin cihazdan kaldırılması için gelecekteki bir zaman.
- Kullanıcı teklif verme sinyalleri: Bir alıcının teklif mantığı JavaScript'inin reklam seçim sürecinde teklif oluşturmak için kullandığı, kullanıcının tercih edilen yerel ayarı gibi kullanıcı sinyallerini içeren bir JSON dizesi. Bu biçim, reklam teknolojisi platformlarının kodu platformlar arasında yeniden kullanmasına yardımcı olur ve JavaScript işlevlerinde kullanımı kolaylaştırır.
- Güvenilir teklif verileri: Reklam seçim sürecinde kullanılan ve güvenilir bir Anahtar/Değer hizmetinden teklif sinyalleri getiren bir HTTPS URL'si ve dizelerin listesi.
- Reklamlar: Reklam seçiminde yer alan reklamlara karşılık gelen
AdData
nesnelerinin listesi. HerAdData
nesnesi şunlardan oluşur:- Oluşturma URL'si: Nihai reklamı oluşturmak için sorgulanan bir HTTPS URL'si.
- Meta veri: Reklam seçim sürecinde alıcı teklif verme mantığı tarafından kullanılabilecek bilgileri içeren dize olarak serileştirilmiş bir JSON nesnesi.
- Reklam Filtreleri: Reklam seçimi sırasında uygulama yükleme reklam filtrelemesi ve sıklık sınırı için gerekli tüm bilgileri içeren bir sınıf.
Aşağıda, bir CustomAudience
nesne örneklendirmesi verilmiştir:
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();
joinCustomAudience() sonuçlarını işleme
Eşzamansız joinCustomAudience()
yöntemi, API çağrısının sonucunu işaret etmek için OutcomeReceiver
nesnesini kullanır.
onResult()
geri çağırması, özel kitlenin başarıyla oluşturulduğunu veya güncellendiğini belirtir.onError()
geri çağırması iki olası koşulu ifade eder.JoinCustomAudienceRequest
geçersiz bağımsız değişkenlerle başlatıldıysaAdServicesException
neden neden olarakIllegalArgumentException
belirtir.- Diğer tüm hatalar, neden olarak
IllegalStateException
ile birlikte birAdServicesException
alır.
Aşağıda, joinCustomAudience()
sonucunun ele alınmasına ilişkin bir örnek verilmiştir:
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);
}
};
Özel bir kitleden ayrılma
Kullanıcı, belirli bir özel kitlenin iş ölçütlerini artık karşılamıyorsa bir uygulama veya SDK, özel kitleyi cihazdan kaldırmak için leaveCustomAudience()
yöntemini çağırabilir. Bir CustomAudience
öğesini benzersiz parametrelerine bağlı olarak kaldırmak için aşağıdakileri yapın:
CustomAudienceManager
nesnesini başlatın.LeaveCustomAudienceRequest
öğesini, özel kitleninbuyer
vename
ayarlarıyla başlatın. Bu giriş alanları hakkında daha fazla bilgi edinmek için "Özel bir kitleye katılma" bölümünü okuyun.- Eşzamansız
leaveCustomAudience()
yönteminiLeaveCustomAudienceRequest
nesnesi ve ilgiliExecutor
ileOutcomeReceiver
nesneleriyle çağırın.
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);
joinCustomAudience()
çağrısına benzer şekilde, OutcomeReceiver
de bir API çağrısının sonunu işaret eder. Gizliliğin korunmasına yardımcı olmak için hata sonucu, dahili hatalar ile geçersiz bağımsız değişkenler arasında ayrım yapmaz. Eşleşen bir özel kitlenin başarıyla kaldırılıp kaldırılmadığına bakılmaksızın, API çağrısı tamamlandığında onResult()
geri çağırması çağrılır.
Reklam seçimini yayınla
Reklam seçmek amacıyla Protected Audience API'yi kullanmak istiyorsanız selectAds()
yöntemini çağırın:
- Bir
AdSelectionManager
nesnesini başlatın. AdSelectionConfig
nesnesi oluşturun.- Eşzamansız
selectAds()
yönteminiAdSelectionConfig
nesnesi ve ilgiliExecutor
ileOutcomeReceiver
nesneleriyle çağırın.
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);
selectAds()
yöntemi, aşağıdaki gerekli parametreleri belirtmeniz gereken bir AdSelectionConfig
girişi gerektirir:
- Satıcı: Reklam seçimini başlatan, satıcı reklam ağının tanımlayıcısı.
- Karar mantığı URL'si: Satıcı reklam ağının JavaScript mantığını edinmek için sorgulanan HTTPS URL'si.
- HTTPS URL'si: Satıcı reklam ağının JavaScript mantığını elde etmek için sorgulanır. Gerekli işlev imzalarını inceleyin.
- Önceden oluşturulmuş URI: FLEDGE'in reklam seçimi biçimine göre hareket eder.
Desteklenmeyen veya hatalı biçimlendirilmiş önceden oluşturulmuş bir URI aktarılırsa
IllegalArgumentException
döndürülür.
- Özel kitle alıcıları: Satıcının reklam seçim sürecine katılmasına izin verdiği alıcı reklam ağları için tanımlayıcıların tam listesi.
Bu alıcı tanımlayıcıları, katılan özel kitlelerin
CustomAudience.getBuyer()
oranındaki kısmına karşılık gelir.
Daha özelleştirilmiş reklam seçimi için isteğe bağlı olarak aşağıdaki parametreler belirtilebilir:
- Reklam seçimi sinyalleri:
CustomAudience.getBiddingLogicUrl()
adresinden getirilen alıcı teklif verme mantığı JavaScript'i tarafından kullanılacak sinyalleri içeren, dize olarak serileştirilmiş bir JSON nesnesi. - Satıcı sinyalleri: Dize olarak serileştirilmiş, satıcının
AdSelectionConfig.getDecisionLogicUrl()
kaynağından getirilen JavaScript karar mantığı tarafından kullanılan sinyalleri içeren bir JSON nesnesi. - Alıcıya göre sinyaller: Dize olarak serileştirilmiş, katılımcı özel kitlelerin alıcı alanları tarafından tanımlanan ve
CustomAudience.getBiddingLogicUrl()
'den getirilen belirli alıcıların teklif mantığı JavaScript'i tarafından kullanılacak sinyalleri içeren JSON nesnelerinin haritası. - İçeriğe dayalı reklamlar: Protected Audience açık artırmasının dışında gerçekleşen bir açık artırma sırasında doğrudan alıcılardan toplanan reklam adayları koleksiyonu.
Bir reklam seçildikten sonra sonuçlar, teklifler ve sinyaller raporlama için dahili olarak saklanır. OutcomeReceiver.onResult()
geri çağırma işlevi şunları içeren bir AdSelectionOutcome
döndürür:
- Kazanan reklam için
AdData.getRenderUrl()
adresinden alınan oluşturma URL'si. - Cihaz kullanıcısına özel bir reklam seçimi kimliği. Bu kimlik, reklam gösterimini raporlamak için kullanılır.
Reklam seçimi geçersiz bağımsız değişkenler, zaman aşımları veya aşırı kaynak tüketimi gibi nedenlerle başarıyla tamamlanamazsa OutcomeReceiver.onError()
geri çağırma aşağıdaki davranışlarla bir AdServicesException
sağlar:
- Reklam seçimi geçersiz bağımsız değişkenlerle başlatılırsa
AdServicesException
neden olarak birIllegalArgumentException
belirtir. - Diğer tüm hatalar, neden olarak
IllegalStateException
ile birlikte birAdServicesException
alır.
Bağlama dayalı reklamlar
Korunan kitle, bağlamsal reklamları korumalı açık artırmaya dahil edebilir.
İçeriğe dayalı reklamların, reklam teknolojisi sunucusunda seçilmesi ve Protected Audience API'lerin dışında cihaza döndürülmesi gerekir. İçeriğe dayalı reklamlar, daha sonra AdSelectionConfig
kullanılarak açık artırmaya dahil edilebilir. İçeriğe dayalı reklamlar, negatif reklam filtrelemesi için uygunluk da dahil olmak üzere, cihaz reklamlarıyla aynı şekilde işlev görür. Korunan Kitle açık artırması tamamlandıktan sonra reportImpression()
yöntemini çağırmanız gerekir. Bu, bir cihazda kazanan reklamı almak için kazanan içeriğe dayalı reklamda, gösterim raporlama ile aynı kalıpta reportWin()
çağrısı yapar. Her içeriğe dayalı reklamda alıcı, teklif, raporlama mantığı bağlantısı, oluşturma URL'si ve reklam meta verisi bulunmalıdır.
Uygulamada içeriğe dayalı reklamlar dağıtmak için hedef uygulamanın bir ContextualAds
nesnesi oluşturması gerekir:
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();
Ardından elde edilen ContextualAds
nesnesi, AdSelectionConfig
oluşturulurken bu nesneye aktarılabilir:
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);
Uygulama yükleme reklam filtrelemesi
Uygulama yükleme reklamlarını filtreleme, bir cihazda halihazırda yüklü olan uygulamaların yükleme reklamlarını filtrelemenize yardımcı olur.
Bu süreçteki ilk adım, hangi reklamverenlerin yüklü paket üzerinde filtreleme yapabileceğini tanımlamaktır. Bunun, bir reklamla hedeflemek istediğiniz uygulamada gerçekleşmesi gerekir.
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);
}
});
Önceki kod yürütüldüğünde, hesaba aktarılan reklamverenler teklif oluşturma sırasında belirttiğiniz yüklü uygulamaları filtreleyebilir. Bir reklamverenin bu uygulamanın yükleme durumuna erişimini kaldırmanız gerekiyorsa reklamverenin bilgilerini kaldırarak bu kodu tekrar çalıştırın.
Sonraki adım, yayıncı uygulamasının içinde reklam filtrelemesini ayarlamaktır. Reklamı yayıncı uygulamasının içinde sunan taraf (büyük olasılıkla bir arz tarafı SDK'sı olabilir) AdFilters
nesnesini, filtrelemek istediği uygulamalarla alakalı reklamlarla ilgili bilgilerle başlatmalıdır:
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();
Talep tarafı yayıncıları, özel kitlelerinde bulunan reklamlar için bir AdFilter
de ayarlayabilir.
Yeni bir AdData
nesnesi örneklenirken de AdFilters
geçirilebilir:
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();
Sıklık sınırı filtreleme
Sıklık sınırı filtreleme, reklam teknolojisinin bir reklamın gösterilme sayısını sınırlamasına olanak tanır. Sıklık sınırı filtreleme, reklamın aşırı maruz kalmasını azaltır ve belirli bir reklam kampanyası için alternatif reklam seçimini optimize eder.
Sıklık sınırı filtresinin iki ana bileşeni vardır: reklam etkinlik türü ve reklam sayacı anahtarı. Kullanılabilecek mevcut reklam etkinliği türleri şunlardır:
- Kazan (yakında): Kazanma etkinliği, reklamın bir açık artırmayı kazandığını gösterir. Kazanma etkinlikleri Protected Audience API tarafından otomatik olarak güncellenir ve doğrudan geliştirici tarafından çağrılamaz. Kazanma verileri, yalnızca belirli bir özel kitledeki reklamlar tarafından görüntülenebilir.
- Gösterim: Cihaz üzerinde bir arayan (STP veya MMP),
reportImpression
'den ayrı olarak, gösterim etkinliklerini seçtikleri kod noktasında çağırmak içinupdateAdCounterHistogram()
kullanır. Gösterim etkinlikleri, belirli bir TTP'ye ait olan tüm reklamlar tarafından görülebilir ve aynı özel kitledeki reklamlarla sınırlı değildir. - Görüntüleme: Etkinlik, cihaz üzerinde arayan kişi (SSP veya MMP) tarafından
updateAdCounterHistogram()
numaralı telefonu arayarak kodda seçtikleri bir noktada çağrılır. Görüntüleme etkinlikleri, belirli bir TTP'ye ait olan tüm reklamlar tarafından görülebilir ve aynı Özel Kitle'deki reklamlarla sınırlı değildir. - Tıklama: Etkinlik, cihaz üzerinde arayan (SSP veya MMP) tarafından
updateAdCounterHistogram()
numaralı telefonu arayarak kodda seçtikleri bir noktada çağrılır. Tıklama etkinlikleri, belirli bir TTP'ye ait tüm reklamlar tarafından görülebilir ve aynı Özel Kitledeki reklamlarla sınırlı değildir.
Yayıncı uygulamasında, cihazda varlığı olan bir STP veya MMP reklam etkinliklerini çağırır. updateAdCounterHistogram()
çağrıldığında, sıklık sınırı filtresinin sayacı artırılır. Böylece, gelecekteki açık artırmaların bir kullanıcının belirli bir reklamla karşılaşmasıyla ilgili güncel bilgilere sahip olur. Reklam etkinliği türleri, ilgili kullanıcı işlemine zorla bağlanmaz ve arayanların kendi etkinlik sistemlerini yapılandırmalarına yardımcı olmak için verilen yönergelerdir. Cihaz üzerinde işlem gerçekleştiren, reklam sayaçlarını etkinlik sırasında artırmak için kazanan reklam açık artırmasının reklam seçimi kimliğini sağlar.
Reklam sayacı anahtarları, alıcı reklam teknolojisi tarafından atanan rastgele 32 bit imzalı tam sayılardır ve TTP tarafından tanımlanan belirli bir reklam grubuna karşılık gelir. Reklam sayacı anahtarları yalnızca belirli bir TTP'ye ait reklamlarla sınırlı olduğundan, bu anahtarlar başka bir reklam teknolojisinin histogramlarıyla çakışmadan seçilebilir. Reklam sayaç anahtarları, bir TTP'nin reklamlarında veya belirli bir özel kitle içinde reklamları gelecekteki açık artırmalardan filtrelemek için TTP'ye özgü tanımlayıcıları artırmak için kullanılır.
Sayaç anahtarlarından, belirli bir alıcı reklam teknolojisinin diğer reklamlarıyla olan etkileşimlerine göre belirli bir kullanıcının ilgisini çekme olasılığı daha yüksek olan reklamlara öncelik vermek için kullanılabilir. Örneğin, kazanan reklam açık artırmaları, görüntülemeler ve tıklamalardan yüksek düzeyde etkileşim alan bir reklam, tahmin edilen bir veri noktasını temsil eder. Bu noktayı daha iyi açıklamak gerekirse: Sol el golf sopalarına yönelik bir reklam, kullanıcının sağ elle kullanımla ilgilenmeyeceğini gösterebilir. Sol elli reklamlara atanan bir sayaç anahtarı için ayarlanan sıklık sınırı filtresi, sağ elle kullanan sopaların reklamlarını filtreleyebilir.
Açık artırmada sıklık sınırını kullanmak için önce aşağıda gösterildiği gibi KeyedFrequencyCap
nesne oluşturmanız gerekir:
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();
KeyedFrequencyCap
nesneleri oluşturulduktan sonra bunları bir AdFilters
nesnesine geçirebilirsiniz.
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();
AdFilters
nesnesi sıklık sınırı filtreleriyle doldurulduğunda, özel kitle oluşturulduğunda bu nesne geçirilebilir:
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();
Sıklık sınırı filtreleri özel bir kitleye uygulandığında, STP gerekli tıklama, görüntüleme veya gösterim etkinliklerini çağırabilir.
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();
Önceden belirlenmiş sıklık sınırı filtre sınırlarına ulaşan reklamlar filtrelenerek açık artırmanın dışında bırakılır. Filtreleme, cihaz üzerinde açık artırmalarda teklif verme mantığı çalıştırılmadan önce ve yük, Teklif Verme ve Açık Artırma hizmetleri açık artırmaları için oluşturulurken gerçekleşir.Bu araç seti, reklam tekniklerine, reklam aşırı gösterimini en aza indirirken reklam hedeflemeye odaklanmak için kullanıcılar ve özel kitlelerindeki reklamlar arasındaki etkileşimleri kullanma esnekliği sunar.
Ağ çağrıları olmadan içeriğe dayalı reklam filtrelemesi
Cihazda yeniden pazarlama talebi yoksa, ağ çağrıları olmadan içeriğe dayalı reklamlar için reklam seçimi yayınlayabilirsiniz. Önceden oluşturulmuş URI'lar ve teklifler içeren içeriğe dayalı reklamlardan oluşan bir liste sayesinde platform, teklif mantığını, teklif sinyallerini ve puanlama sinyallerini atlayabilir. Platform, en yüksek teklife sahip içeriğe dayalı reklamı seçmek için önceden oluşturulmuş bir URI kullanır.
Reklam teknolojileri, gecikmeyi iyileştirmek için ağ çağrıları olmadan yalnızca reklam filtreleme işlevine sahip içeriğe dayalı reklamların yer aldığı bir reklam seçimi akışı çalıştırabilir. Bu, puanlama sinyalleri için önceden oluşturulmuş URI'lar kullanılarak gerçekleştirilir. scoreAds
uygulamalarının bir listesi için desteklenen önceden oluşturulmuş URI kullanım alanları ve adları bölümüne bakın.
Reklam seçimini ağ çağrıları olmadan çalıştırmak için:
- Reklam filtrelemeyi ayarlama
- İçeriğe dayalı reklamlarınızı oluşturma
Aşağıdakilerle bir
AdSelectionConfig
nesnesi oluşturun:- Boş alıcı listesi
- En yüksek teklifi seçmek için önceden oluşturulmuş URI
- Bağlama dayalı reklamlar
- Puanlama sinyalleri için boş URI. Boş URI'nın, puanlama için güvenilir sinyallerin getirilmesini kullanmak istemediğinizi belirtmesine izin verilir:
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();
Reklam seçimini yayınla:
adSelectionManager.selectAds( adSelectionConfig, executor, outcomeReceiver);
Önceden oluşturulmuş URI'ları kullanırken kendi raporlama JavaScript'inizi çalıştırın
Bugün, Özel Korumalı Alan platformunda yalnızca önceden oluşturulmuş URI'lar için kullanılabilen temel bir raporlama JavaScript uygulaması bulunmaktadır. Düşük gecikmeli bir reklam seçimi için önceden oluşturulmuş URI'ları kullanmaya devam ederken kendi raporlama JavaScript'inizi çalıştırmak isterseniz reklam seçimi ile raporlama çalıştırmaları arasında DecisionLogicUri
geçersiz kılınabilirsiniz.
- Önceden oluşturulmuş URI'lar kullanarak içeriğe dayalı reklamlar için reklam seçimini çalıştırma adımlarını çalıştırın
Raporlamayı çalıştırmadan önce
AdSelectionConfig
verilerinizin bir kopyasını oluşturunadSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder() // Replace <urlToFetchYourReportingJS> with your own URL: .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>)) .build();
Gösterim raporlamasını çalıştırma
// adSelectionId is from the result of the previous selectAds run ReportImpressionRequest request = new ReportImpressionRequest( adSelectionId, adSelectionConfigWithYourReportingJS); adSelectionManager.reportImpression( request, executor, outcomeReceiver);
Şelale uyumlulaştırmasını çalıştır
Şelale uyumlulaştırması, birden fazla üçüncü taraf SDK'nın (3. taraf ağ) birinci taraf SDK uyumlulaştırma ağı tarafından düzenlenmesini gerektirir. Şelale uyumlulaştırması, açık artırmanın cihazda veya Teklifli Sistem ve Açık Artırma hizmetlerinde (B&A) çalıştırılmasından bağımsız olarak aynı şekilde gerçekleştirilir.
Üçüncü taraf ağları
Üçüncü taraf ağlarının, uyumlulaştırma ağının açık artırma yürütmek için gerekli yöntemleri çağırmasını sağlayan bir bağdaştırıcı sağlaması gerekir:
- Reklam seçimini yayınla
- Rapor gösterimleri
Aşağıda bir uyumlulaştırma ağ bağdaştırıcısı örneği verilmiştir:
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() {...}
}
Her SDK'nın kendi reklam seçimi hizmet yöneticileri ve istemcilerinin yanı sıra kendi selectAds
ve reportImpressions
uygulamaları vardır. SDK sağlayıcıları, cihaz üzerinde açık artırmalar için reklam seçiminin nasıl çalıştırılacağı ile ilgili veya B&A açık artırmaları için B&A açıklayıcısı ile ilgili bölümlere başvurabilir. Reklam gösterimlerini nasıl raporlayacağınızı (raporlama için tek STP gösterim raporlamasını takip ederek) uygulayın.
Uyumlulaştırma ağı
Üçüncü taraf ağlarda olduğu gibi, uyumlulaştırma ağlarında da selectAds
ve reportImpression
uygulamalarının uygulanması gerekir. Daha fazla bilgi için reklam seçimini çalıştırma ve reklam gösterimlerini bildirme ile ilgili bölümlere bakın.
Uyumlulaştırma ağları, uyumlulaştırma zincirini çalıştırmaktan ve kendilerini uyumlulaştırma zincirine yerleştirmekten sorumludur. Sonraki bölümde bu sürecin nasıl ayarlanacağı ve yürütüleceği ele alınmaktadır.
Uyumlulaştırma zincirini ve teklif tabanlarını alma
Uyumlulaştırma ağı, birinci taraf içeriğe dayalı reklamlarını, uyumlulaştırma zincirini ve üçüncü taraf ağların teklif tabanlarını (3. taraf) almaktan sorumludur. Bu durum, uyumlulaştırma ağı tarafından yürütülen içeriğe dayalı reklamlar alma isteğinde gerçekleşebilir. Uyumlulaştırma zinciri, Üçüncü Taraf Ağlar üzerinden nasıl yineleneceğini belirler ve teklif tabanları açık artırma sürecine adSelectionSignals
olarak aktarılabilir.
Uyumlulaştırma zincirinde ağ yerleşimi
Uyumlulaştırma SDK'sı, birinci taraf reklam tekliflerindeki etkin eBGBM değerine göre kendisini uyumlulaştırma zincirine yerleştirebilir. Protected Audience API'de reklam teklifleri opaktır. Uyumlulaştırma SDK'sının, belirli bir birinci taraf reklamın teklifini zincirde bir sonraki üçüncü taraf ağın teklif tabanıyla karşılaştırabilmesi için AdSelectionFromOutcomesConfig
kullanılması gerekir. Birinci taraf teklifinin teklif tabanından yüksek olması, uyumlulaştırma SDK'sının söz konusu üçüncü taraf ağının önüne yerleştirildiği anlamına gelir.
Reklam seçimini yayınla
Uyumlulaştırma ağı, bir birinci taraf reklam adayını almak için reklam seçimini çalıştırma bölümündeki adımları izleyerek cihaz üzerinde bir açık artırma gerçekleştirebilir. Bu işlem sonucunda birinci taraf reklam adayı, teklif ve uyumlulaştırma sürecinde kullanılacak bir AdSelectionId
oluşturulur.
AdSelectionFromResultsConfig oluşturma
AdSelectionFromOutcomesConfig
; uyumlulaştırma ağının AdSelectionIds
listesi (önceki açık artırmaların sonuçları), reklam seçimi sinyalleri ve birden fazla aday arasından reklam seçen JavaScript'i getirmek için bir URI iletmesine olanak tanır. AdSelectionId'lerin listesi, teklifleri ve sinyallerle birlikte JavaScript'e iletilir. Bu liste, teklif tabanını geçerse AdSelectionIds
değerlerinden birini döndürebilir veya uyumlulaştırma zincirinin devam etmesi gerekiyorsa hiç döndürmeyebilir.
Uyumlulaştırma Ağları, önceki bölümde yer alan birinci taraf AdSelectionId
öğesini ve değerlendirilen 3. Taraf Ağı için teklif tabanını kullanarak bir AdSelectionFromOutcomesConfig
oluşturur. Uyumlulaştırma zincirindeki her adım için yeni bir AdSelectionFromOutcomesConfig
oluşturulmalıdır.
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){}
}
Şelale uyumlulaştırması için selectAds()
yöntemini geçersiz kılma, aşağıdaki gerekli parametreleri belirtmeniz gereken AdSelectionFromOutcomesConfig
girişi gerektirir:
- Satıcı: Reklam seçimini başlatan, satıcı reklam ağının tanımlayıcısı.
- AdSelectionIds: Birinci taraf reklam için önceki
selectAds()
çalıştırmasının tekil listesi. - Reklam seçimi sinyalleri: Dize olarak serileştirilmiş, alıcı teklif verme mantığı tarafından kullanılacak sinyalleri içeren bir JSON nesnesi. Bu durumda, belirtilen 3. taraf ağ için alınan teklif tabanını ekleyin.
- Selection Logic URI'si (Seçim Mantığı URI'si): Kazanan bir reklamı seçmek için uyumlulaştırma ağının JavaScript'ini getirmek üzere reklam seçimi sırasında sorgulanan HTTPS URL'si. Bu JavaScript'te gerekli işlev imzalarına bakın. Teklif, teklif tabanından yüksekse JavaScript'in üçüncü taraf reklamı döndürmesi veya
null
değerini döndürmesi gerekir. Bu, uyumlulaştırma SDK'sının bir kazanan bulunduğunda uyumlulaştırma zincirini kısaltmasını sağlar.
AdSelectionOutcomesConfig
oluşturulduktan sonra, zincirde ilk olan 3. taraf ağın selectAds()
yöntemini çağırın.
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);
Şelale uyumlulaştırmasını düzenleme
Aşağıda, uyumlulaştırma süreciyle yürütülecek işlemlerin sırası verilmiştir.
- Birinci taraf reklam seçimini yayınla.
- Uyumlulaştırma zincirini tekrarlayın. Her üçüncü taraf ağ için aşağıdakileri yapın:
- Birinci taraf
outcomeId
ve 3. taraf SDK'nın teklif tabanı dahilAdSelectionFromOutcomeConfig
oluşturun. - Önceki adımdaki yapılandırma ile
selectAds()
işlevini çağırın. - Sonuç boş değilse reklamı döndürün.
- Mevcut SDK ağ bağdaştırıcısının
selectAds()
yöntemini çağırın. Sonuç boş olmazsa reklamı döndürün.
- Birinci taraf
- Zincirde kazanan bulunamazsa birinci taraf reklamı döndürün.
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) { ... }
}
Reklam gösterimlerini raporla
Açık artırmanın nasıl yapıldığına bağlı olarak bir reklam gösterimini raporlamak için iki akış vardır. Açık artırma gerçekleştiren tek bir STP iseniz bu bölümü takip edin. Şelale uyumlulaştırmasını uygulayacaksanız şelale uyumlulaştırması gösterim raporlama bölümündeki adımları uygulayın.
Tek STP gösterim raporlaması
Reklam seçimi iş akışından kazanan bir reklam seçildikten sonra, AdSelectionManager.reportImpression()
yöntemini kullanarak gösterimi katılımcı alıcı tarafı ve satıcı tarafı platformlarına geri bildirebilirsiniz. Bir reklam gösterimini bildirmek için:
- Bir
AdSelectionManager
nesnesini başlatın. - Reklam seçim kimliğiyle bir
ReportImpressionRequest
nesnesi oluşturun. - Eşzamansız
reportImpression()
yönteminiReportImpressionRequest
nesnesi ve ilgiliExecutor
ileOutcomeReceiver
nesneleriyle çağırın.
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)
Aşağıdaki gerekli parametrelerle ReportImpressionRequest
'i başlatın:
- Reklam seçimi kimliği: Başarılı bir reklam seçimini tanımlayan, yalnızca cihaz kullanıcısına özgü bir kimlik.
- Reklam seçimi yapılandırması: Sağlanan reklam seçimi kimliği ile tanımlanan
selectAds()
çağrısında kullanılan yapılandırmanın aynısıdır.
Eşzamansız reportImpression()
yöntemi, API çağrısının sonucunu işaret etmek için OutcomeReceiver
nesnesini kullanır.
onResult()
geri çağırması, gösterim raporlama URL'lerinin oluşturulup oluşturulmadığını ve isteğin planlanıp planlanmadığını belirtir.onError()
geri çağırması aşağıdaki olası koşulları gösterir:- Çağrı, geçersiz bir giriş bağımsız değişkeniyle başlatılırsa
AdServicesException
neden olarak birIllegalArgumentException
belirtir. - Diğer tüm hatalar, neden olarak
IllegalStateException
ile birlikte birAdServicesException
alır.
- Çağrı, geçersiz bir giriş bağımsız değişkeniyle başlatılırsa
Şelale uyumlulaştırma gösterim raporlaması
Uyumlulaştırma SDK'sının, raporlama akışlarını tetiklemek için kazanan SDK'yı takip etmesi gerekir. Bir uyumlulaştırma zincirine katılan SDK'lar, arabulucunun kendi raporlama akışını tetiklemek için çağırması için bir yöntem sağlamalıdır. Uyumlulaştırılmış açık artırmaya katılan bir SDK, kendi raporlamasını uygulamak için yukarıdaki adımları izleyebilir.
STP'ler, bu üçüncü taraf SDK kodu örneğini uyumlulaştırma akışlarına nasıl katılacakları konusunda prototip olarak kullanabilir:
Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
mediationSdk.orchestrateMediation(mediationChain);
if (winner.first.hasOutcome()) {
winner.second.reportImpressions(winner.first.getAdSelectionId());
Gösterim raporlama uç noktaları
Rapor gösterimi API'si, satıcı tarafı platformu ve kazanan alıcı tarafı platformu tarafından sağlanan uç noktalara HTTPS GET istekleri gönderir:
Satın alma tarafı platform uç noktası:
- API, alıcı tarafından sağlanan ve gösterim raporlama URL'si döndürme mantığını içeren JavaScript'i getirmek için özel kitlede belirtilen Teklif verme mantığı URL'sini kullanır.
- Alıcının gösterim raporlama URL'sini döndürmesi beklenen
reportWin()
JavaScript işlevini çağırın.
Satış tarafı platform uç noktası:
- Satıcının karar mantığı JavaScript'ini getirmek için
AdSelectionConfig
nesnesinde belirtilen Decision logic URL'yi (Karar mantığı URL'si) kullanın. - Alıcı gösterimi raporlama URL'sini döndürmesi beklenen
reportResult()
JavaScript işlevini çağırın.
Teklifli sistem ve açık artırma hizmetleri raporları
Teklifli Sistem ve Açık Artırma hizmetlerinde yürütülen bir açık artırma, reklam etkileşimi raporlaması için oluşturulan URL'ler dahil olmak üzere gerekli tüm raporlama bilgilerini içerir. Bu bilgiler, sunucu tarafı açık artırmadan alınan şifrelenmiş yanıta dahil edilir. Yanıtın şifresi çözüldüğünde uygun URL'ler platforma kaydedilir. Böylece reklam ve gösterim raporlaması yukarıda listelenen adımları uygular.
En yüksek çaba Gösterim raporlaması
reportImpression()
yöntemi, raporlamanın en iyi şekilde tamamlanmasını sağlamak için tasarlanmıştır.
Reklam Etkileşimlerini Rapor Etme
Korunan Kitle, oluşturulan reklam için daha ayrıntılı etkileşimler hakkında rapor oluşturma desteği sağlar. Buna görüntüleme süresi, tıklama sayısı, fareyle üzerine gelme sayısı gibi etkileşimler veya toplanabilecek diğer faydalı metrikler dahildir. Bu raporları alma süreci iki adımdan oluşur. Öncelikle, alıcılar ve satıcıların raporlama JavaScript'inde bu raporları almak için kaydolması gerekir. Ardından, istemcinin bu etkinlikleri raporlaması gerekir.
Etkileşim etkinliklerini almak için kaydolma
Etkileşim etkinliklerine kayıt, alıcının reportWin()
ve satıcının reportResult()
JavaScript işlevlerinde, platform tarafından sağlanan bir JavaScript işlevini kullanarak gerçekleşir: registerAdBeacon
. Bir etkinlik raporu almak üzere kaydolmak için raporlama JavaScript'inizden platform JavaScript İşlevini çağırmanız yeterlidir. Aşağıdaki snippet, alıcının reportWin()
özelliğini kullanmaktadır. Ancak aynı yaklaşım reportResult()
için de geçerlidir.
reportWin(
adSelectionSignals,
perBuyerSignals,
signalsForBuyer,
contextualSignals,
customAudienceSignals) {
...
// Calculate reportingUri, clickUri, viewUri, and hoverUri
registerAdBeacon("click", clickUri)
registerAdBeacon("view", viewUri)
registerAdBeacon("hover", hoverUri)
return reportingUrl;
}
Etkileşim etkinliklerini raporlama
Müşteriler bir gösterimi bildirdikten sonra, AdSelectionManager.reportInteraction()
yöntemini kullanarak etkileşimleri daha önce kaydedilmiş olan kazanan alıcı ve satıcı tarafı platformlara geri raporlayabilir. Bir reklam etkinliğini bildirmek için:
- Bir
AdSelectionManager
nesnesini başlatın. - Reklam seçim kimliği, etkileşim anahtarı, etkileşim verileri ve raporlama hedefine sahip bir
ReportInteractionRequest
nesnesi oluşturun. - Eşzamansız
reportInteraction()
yönteminirequest
nesnesiyle ve ilgiliExecutor
ileOutcomeReceiver
nesneleriyle çağırın.
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);
Aşağıdaki gerekli parametrelerle ReportInteractionRequest
'i başlatın:
- Reklam seçimi kimliği: Daha önce döndürülen bir
AdSelectionOutcome
reklam seçimi kimliği. - Etkileşim Anahtarı: Müşteri tarafından tanımlanan ve raporlanmakta olan işlemi açıklayan bir dize anahtarı. Bu değer, satıcı veya alıcı tarafından raporlama JavaScript işlevlerine kaydedilen anahtarla eşleşmelidir.
- Etkileşim Verileri: Raporlama sunucularına POSTlanacak ve etkinlik raporuna dahil edilecek verileri içeren bir dize.
- Raporlama Hedefleri: Etkinliklerin alıcıya, satıcıya veya her ikisine de bildirilmesi gerektiğini belirten bir bit maskesi. Bu işaretler platform tarafından sağlanır ve son hedef maskesi bit tabanlı işlemler kullanılarak oluşturulabilir. Tek bir hedefe bildirmek için doğrudan platform tarafından sağlanan işareti kullanabilirsiniz. Birden fazla hedefe yönelik rapor oluşturmak için bit tabanlı VEYA (
|
) kullanarak işaret değerlerini birleştirebilirsiniz.
Eşzamansız reportInteraction()
yöntemi, API çağrısının sonucunu işaret etmek için OutcomeReceiver
nesnesini kullanır.
onResult()
geri çağırması, rapor etkileşim çağrısının geçerli olduğunu gösterir.onError()
geri çağırması aşağıdaki olası koşulları gösterir:- Uygulama arka planda çalışırken çağrı yapılırsa
hatanın açıklamasını içeren bir
IllegalStateException
döndürülür. - İstemcinin
reportInteraction()
çağrısı yapması kısıtlanırsaLimitExceededException
döndürülür. - Paket, Gizliliği Koruma API'lerini çağırmak için kayıtlı değilse
SecurityException()
döndürülür. - Uygulama raporlama etkileşimleri,
selectAds()
çağrısı yapan uygulamadan farklıysaIllegalStateException
döndürülür.
- Uygulama arka planda çalışırken çağrı yapılırsa
hatanın açıklamasını içeren bir
- Kullanıcı, Özel Korumalı Alan API'lerini etkinleştirmek için izin vermezse çağrı sessizce başarısız olur.
Etkileşim raporlama uç noktaları
Rapor etkileşimi API'si, satıcı tarafı platformu ve kazanan alıcı tarafı platformu tarafından sağlanan uç noktalara HTTPS POST istekleri gönderir. Korunan Kitle, etkileşim anahtarlarını raporlama JavaScript'inde belirtilen URI'lerle eşleştirir ve raporlanan her etkileşim için her bir uç noktaya POST isteği gönderir. İsteğin içerik türü düz metindir; gövde ise Etkileşim Verileri'dir.
En iyi çaba Etkileşim raporlaması
reportInteraction()
, HTTP POST aracılığıyla raporlamanın en iyi şekilde tamamlanmasını sağlamak için tasarlanmıştır.
Günlük arka plan güncellemesi
Özel kitle oluştururken uygulamanız veya SDK'nız, özel kitle meta verilerini başlatabilir. Ayrıca platform, aşağıdaki özel kitle meta verisi parçalarını günlük bir arka plan güncelleme işlemiyle güncelleyebilir.
- Kullanıcı teklif sinyalleri
- Güvenilir teklif verileri
AdData
listesi
Bu işlem, özel kitlede tanımlanan Günlük Güncelleme URL'sini temel alır ve URL, bir JSON yanıtı döndürebilir.
- JSON yanıtı, güncellenmesi gereken desteklenen meta veri alanlarından herhangi birini içerebilir.
- Her JSON alanı bağımsız olarak doğrulanır. İstemci, hatalı biçimlendirilmiş alanları yoksayar. Bu durum, yanıttaki söz konusu alanda güncelleme yapılmasına neden olmaz.
- Boş bir HTTP yanıtı veya boş bir JSON nesnesi ("
{}
"), meta veri güncellemesine neden olmaz. - Yanıt iletisi boyutu 10 KB ile sınırlı olmalıdır.
- HTTPS kullanmak için tüm URI'ler gereklidir.
trusted_bidding_uri
, alıcı ile aynı ETLD+1'i paylaşmalıdır.
Örnek: Arka planda günlük güncelleme için JSON yanıtı
{
"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
},
...
]
}
Reklam seçimi için JavaScript
Reklam seçimi iş akışı, alıcı ve satıcı tarafından sağlanan JavaScript'in yürütülmesini düzenler.
Alıcı tarafından sağlanan JavaScript, özel kitlede belirtilen Teklifli Sistem mantık URL'sinden getirilir. Döndürülen JavaScript aşağıdaki işlevleri içermelidir:
Satıcı tarafından sağlanan JavaScript, reklam seçimi API'sinin AdSelectionConfig
parametresinde belirtilen karar mantığı URL'sinden getirilir. Döndürülen JavaScript, aşağıdaki işlevleri içermelidir:
createBid()
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 };
}
Giriş parametreleri:
ad
:var ad = { 'render_url': url, 'metadata': json_metadata };
biçiminde bir JSON nesnesiauction_signals, per_buyer_signals
: Açık artırma yapılandırma nesnesinde belirtilen JSON nesnelericustom_audience_bidding_signals
: Platform tarafından oluşturulan JSON nesnesi. Bu JSON nesnesinin biçimi şu şekildedir: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" }
Bu örnekte:
owner
,buyer
vename
, reklam seçimine katılan Özel Kitle ile aynı ada sahip mülklerden alınan dizelerdiractivation_time
veexpiration_time
, özel kitlenin etkinleştirme ve geçerlilik bitiş zamanıdır. Unix dönemi'nden bu yana saniye olarak ifade edilir.ca_user_bidding_signals
, oluşturulma sırasındaCustomAudience
öğesininuserBiddingSignals
alanında belirtilen bir JSON dizesidirtrusted_bidding_signals, contextual_signals
veuser_signals
, JSON nesneleridir. Bunlar boş nesne olarak aktarılır ve gelecekteki sürümlerde doldurulur. Biçimleri platform tarafından zorunlu kılınmaz ve reklam teknolojisi tarafından yönetilir.
Sonuç:
ad
: Teklifin ilgili olduğu reklamdır. Komut dosyasının, aldığı reklamın farklı meta verilerle bir kopyasını döndürmesine izin verilir. Reklamınrender_url
özelliğinin değiştirilmemiş olması beklenir.bid
: Bu reklam için teklif değerini temsil eden bir hareketli değerstatus
: Şu olabilecek bir tam sayı değeri:0
: başarılı bir yürütme için1
: (veya sıfır dışında bir değer). Oluşturma teklifinin sıfır dışında bir değer döndürmesi durumunda, teklif verme süreci tüm CA reklamları için geçersiz kılınır.
puanAd()
function scoreAd(
ad,
bid,
ad_selection_config,
seller_signals,
trusted_scoring_signals,
contextual_signal,
user_signal,
custom_audience_signal) {
return {'status': 0, 'score': score };
}
Giriş parametreleri:
ad
:generateBid
belgelerini inceleyinbid
: reklamın teklif değeriad_selection_config
:selectAds
API'ninAdSelectionConfig
parametresini temsil eden bir JSON nesnesi. Biçim şöyledir: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
:sellerSignals
AdSelectionConfig
API parametresinden okunan JSON nesneleritrusted_scoring_signal
:AdSelectionConfig
API parametresindekiadSelectionSignals
alanından okurcontextual_signals, user_signals
: JSON nesneleri. Bunlar şu anda boş nesne olarak iletilir ve gelecekteki sürümlerde doldurulacaktır. Bu biçimlerin biçimi platform tarafından zorunlu kılınmaz ve reklam teknolojisi tarafından yönetilir.per_buyer_signals
: Mevcut Özel Kitle alıcısı anahtar olarak kullanılarakAdSelectionConfig
API parametresindekiperBuyerSignal
haritasından okunan JSON nesnesi. Haritada belirtilen alıcı için herhangi bir giriş yoksa boştur.
Çıkış:
score
: Bu reklamın puan değerini temsil eden bir kayan değerstatus
: Şu olabilecek bir tam sayı değeri:- 0: başarılı bir yürütme için
- 1:
customAudienceSignals
geçersizse - 2:
AdSelectionConfig
geçersizse - 3: diğer sinyallerden herhangi birinin geçersiz olması durumunda
- Sıfır olmayan herhangi bir değer işlemin başarısız olmasına neden olur. Değer, işlemden etkilenen
selectOutcome()
function selectOutcome(
outcomes,
selection_signals) {
return {'status': 0, 'result': null};
}
Giriş parametreleri:
outcomes
: Bir JSON nesnesi{"id": id_string, "bid": bid_double}
selection_signals
: Açık artırma yapılandırma nesnesinde belirtilen JSON nesneleri
Çıkış:
status
: Başarılı için0
, başarısız için sıfır değilresult
: Geçirilen sonuçlardan biri veya 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 }
};
}
Giriş parametreleri:
ad_selection_config
:scoreAds
belgelerine bakınrender_url
: kazanan reklamın oluşturma URL'sibid
: kazanan reklam için sunulan teklifcontextual_signals
:generateBid
belgelerine bakın
Çıkış:
- Başarılı için
status: 0
, başarısızlık için sıfır dışında bir değer results
: Şunları içeren bir JSON nesneleri:signals_for_buyer
:reportWin
işlevine geçirilen bir JSON nesnesireporting_url
: Gösterimi alıcıya bildirmek için platform tarafından kullanılan URL
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 } };
}
Giriş parametreleri:
ad_selection_signals, per_buyer_signals
:scoreAd
belgelerini inceleyinsignals_for_buyer
:reportResult
tarafından döndürülen bir JSON nesnesicontextual_signals, custom_audience_signals
:generateBid
belgelerini inceleyin
Çıkış:
- Başarılı için
status: 0
, başarısızlık için sıfır dışında bir değer results
: Şunları içeren bir JSON nesnesi:reporting_url
: Gösterimi satıcıya bildirmek için platform tarafından kullanılan URL
registerAdBeacon()
function registerAdBeacon(
interaction_key,
reporting_uri
)
Giriş Parametreleri:
interaction_key
: Etkinliği temsil eden bir dize. Bu bilgi, daha sonra etkinlik etkileşimleri bildirilirken bildirilecekreporting_uri
olup olmadığına bakmak için platform tarafından kullanılır. Bu anahtarın, alıcının veya satıcının kaydettikleri ile satıcının bildirdikleri arasında eşleşmesi gerekir.reporting_uri
: Etkinlik raporlarını alacak bir URI. Bu, raporlanan etkinlik türüne özel olmalıdır. Etkinlikle birlikte bildirilen tüm verileri işlemek için POST isteğini kabul etmelidir.
Reklam Seçimi önceden oluşturulmuş URI'ları
Önceden oluşturulmuş URI'lar, reklam teknisyenlerinin AdSelectionConfig
ve AdSelectionFromOutcomesConfig
sınıflarında reklam seçimi karar mantığı için JavaScript işlevleri atamasına olanak tanır. Önceden oluşturulmuş URI'lar, ilgili JavaScript'i indirmek için ağ çağrıları gerektirmez. Reklam teknisyenleri, JavaScript'i barındırmak için kayıtlı bir alan adı ayarlamak zorunda kalmadan önceden oluşturulmuş URI'ları kullanabilir.
Önceden oluşturulmuş bir URI aşağıdaki biçim kullanılarak oluşturulur:
ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>
Özel Korumalı Alan platformu, çalışma zamanında bu URI'daki bilgileri kullanarak JavaScript sağlar.
Aşağıdaki durumlarda IllegalArgumentException
atılır:
- gerekli parametrelerden hiçbiri URI'de yok
- URI'de tanınmayan parametreler var
Desteklenen önceden oluşturulmuş URI kullanım durumları ve adları
1. kullanım alanı: reklam seçimi
ad-selection
kullanım alanı altındaki önceden oluşturulmuş URI'lar selectAds(AdSelectionConfig)
akışında desteklenir.
Önceden oluşturulmuş URI adı: highest-bid-wins
Bu önceden oluşturulmuş URI, teklif verdikten sonra en yüksek teklife sahip reklamı seçen bir JavaScript sağlar. Ayrıca kazananın render_uri
ve bid
değerlerini raporlayan temel bir raporlama işlevi sağlar.
Gerekli parametreler
reportingUrl
: Kazanan reklamın render_uri
ve bid
ile parametreleştirilmiş temel raporlama URL'si:
<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>
Kullanım
Temel raporlama URL'niz https://www.ssp.com/reporting
ise önceden oluşturulmuş URI şöyle olur:
`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`
2. kullanım alanı: reklam seçimi-sonuçları
ad-selection-from-outcomes
kullanım alanı altındaki önceden oluşturulmuş URI'lar selectAds(AdSelectionFromOutcomesConfig)
iş akışını destekler.
Önceden oluşturulmuş URI adı: waterfall-mediation-truncation
Önceden oluşturulmuş waterfall-mediation-truncation
URI'si, bid
, bid floor
değerinden daha yüksekse veya ona eşitse JavaScript'in birinci taraf reklamı döndürdüğü ve aksi takdirde null
döndürdüğü, şelale uyumlulaştırmasını kesme mantığını uygulayan JavaScript'i sağlar.
Gerekli parametreler
bidFloor
: Uyumlulaştırma SDK'sının reklamıyla karşılaştırıldığında, getSelectionSignals()
içinde iletilen teklif tabanı değerinin anahtarı.
Kullanım
Reklam seçimi sinyalleriniz {"bid_floor": 10}
gibi görünüyorsa elde edilen önceden oluşturulmuş URI şöyle olur:
`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`
Test
Protected Audience API'yi kullanmaya başlamanıza yardımcı olmak için Kotlin ve Java'da örnek uygulamalar oluşturduk. Bunları GitHub'da bulabilirsiniz.
Ön koşullar
Protected Audience API, reklam seçimi ve gösterim raporlaması sırasında bazı JavaScript kodları gerektirir. Bu JavaScript'i bir test ortamında sağlamanın iki yöntemi vardır:
- JavaScript'i döndüren gerekli HTTPS uç noktalarına sahip bir sunucu çalıştırın
- Yerel bir kaynaktan gerekli kodu sağlayarak uzaktan getirmeyi geçersiz kılın
Her iki yaklaşım da gösterim raporlamasını işlemek için bir HTTPS uç noktasının ayarlanmasını gerektirir.
HTTPS uç noktaları
Reklam seçimini ve gösterim raporlamasını test etmek için test cihazınızın veya emülatörünüzün erişebileceği 7 HTTPS uç noktası ayarlamanız gerekir:
- Teklif mantığı JavaScript'ini sunan alıcı uç noktası.
- Teklif sinyallerini sunan bir uç nokta.
- Karar mantığı JavaScript'ini sunan satıcı uç noktası.
- Puanlama sinyalleri sunan bir uç nokta.
- Kazanan alıcı gösterimi raporlama uç noktası.
- Satıcı gösterimi raporlama uç noktası.
- Özel bir kitle için günlük güncellemeleri sunan bir uç nokta.
GitHub deposu, test amacıyla kolaylık sağlamak amacıyla temel JavaScript kodu sağlar. Ayrıca, desteklenen bir örnek veya mikro hizmet platformuna dağıtılabilen OpenAPI hizmet tanımları da içerir. Daha fazla bilgi için BENİOKU projesine göz atın.
JavaScript'in uzaktan getirilmesini geçersiz kıl
Bu özellik, uçtan uca testler için kullanılmak üzere tasarlanmıştır. Uzaktan getirmeyi geçersiz kılmak için uygulamanızın, geliştirici seçenekleri etkinleştirilmiş şekilde hata ayıklama modunda çalışması gerekir.
Uygulamanızda hata ayıklama modunu etkinleştirmek için AndroidManifest.xml dosyanızdaki uygulama özelliğine aşağıdaki satırı ekleyin:
<application
android:debuggable="true">
Bu geçersiz kılmaların nasıl kullanılacağına dair örnek için lütfen GitHub'daki Protected Audience API örnek uygulamasına göz atın.
Teklif verme, puanlama kararları ve raporlama gibi reklam seçimi rutinlerini işlemek için kendi özel JavaScript'inizi eklemeniz gerekir. Gerekli tüm istekleri işleyen temel JavaScript kod örneklerini GitHub deposunda bulabilirsiniz. Protected Audience API örnek uygulaması, bu dosyadaki kodun nasıl okunacağını ve geçersiz kılma olarak kullanılmak üzere nasıl hazırlanacağını gösterir.
Geçersiz kılma sağlamadığınız JavaScript'leri sunmak için bir HTTPS uç noktasına ihtiyacınız olsa da, satıcı tarafı ve alıcı tarafı JavaScript getirme işlemini bağımsız olarak geçersiz kılmak mümkündür. Bu tür durumları ele alacak bir sunucunun nasıl ayarlanacağı hakkında bilgi edinmek için lütfen BENİOKU sayfasına bakın.
Yalnızca paketinize ait olan özel kitleler için JavaScript getirme işlemini geçersiz kılmak mümkündür.
Satış tarafı JavaScript'ini geçersiz kıl
Satış tarafı JavaScript'ini geçersiz kılma ayarı yapmak için aşağıdaki kod örneğinde gösterildiği gibi aşağıdakileri yapın:
- Bir
AdSelectionManager
nesnesini başlatın. AdSelectionManager
nesnesindenTestAdSelectionManager
referansı alın.AdSelectionConfig
nesnesi oluşturun.AdSelectionConfig
nesnesiyle birAddAdSelectionOverrideRequest
ve geçersiz kılma olarak kullanmayı düşündüğünüz JavaScript'i temsil eden birString
oluşturun.- Eşzamansız
overrideAdSelectionConfigRemoteInfo()
yönteminiAddAdSelectionOverrideRequest
nesnesi ve ilgiliExecutor
ileOutcomeReceiver
nesneleriyle çağırın.
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);
AdSelectionConfig
içindeki her bir alanın neyi temsil ettiği hakkında daha fazla bilgi için Reklam seçimini çalıştırma bölümüne bakın. Aradaki temel fark, decisionLogicUrl öğesinin yok sayılacağı için bir yer tutucu değere ayarlanmasıdır.
Reklam seçimi sırasında kullanılan JavaScript'i geçersiz kılmak için decisionLogicJs
, uygun satıcı tarafı işlev imzalarını içermelidir.
JavaScript dosyasının dize olarak nasıl okunacağına dair örnek için lütfen GitHub'daki Protected Audience API örnek uygulamasına göz atın.
Eşzamansız overrideAdSelectionConfigRemoteInfo()
yöntemi, API çağrısının sonucunu işaret etmek için OutcomeReceiver
nesnesini kullanır.
onResult()
geri çağırması, geçersiz kılma işleminin başarıyla uygulandığını belirtir.
Gelecekteki selectAds()
çağrıları, geçersiz kılma olarak iletmiş olduğunuz kararı ve raporlama mantığını kullanacaktır.
onError()
geri çağırması iki olası koşulu ifade eder:
- Geçersiz kılma işlemi, geçersiz bağımsız değişkenlerle denenirse
AdServiceException
neden olarak birIllegalArgumentException
belirtir. - Geçersiz kılma işlemi, geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulama ile denenirse
AdServiceException
neden olarakIllegalStateException
gösterilir.
Satış tarafı geçersiz kılmalarını sıfırla
Bu bölümde, satış tarafı JavaScript'ini geçersiz kıldığınız ve önceki bölümde kullanılan TestAdSelectionManager
ve AdSelectionConfig
referanslarına sahip olduğunuz varsayılır.
Tüm AdSelectionConfigs
için geçersiz kılmaları sıfırlamak üzere:
- İlgili
OutcomeReceiver
nesnesiyle eşzamansızresetAllAdSelectionConfigRemoteOverrides()
yöntemini çağırın.
Kotlin
// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver)
Java
// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver);
Satış tarafı geçersiz kılmalarını sıfırladıktan sonra selectAds()
çağrıları, gerekli JavaScript'i getirmek için AdSelectionConfig
içinde depolanan decisionLogicUrl öğelerini kullanır.
resetAllAdSelectionConfigRemoteOverrides()
çağrısı başarısız olursa OutComeReceiver.onError()
geri çağırması bir AdServiceException
sağlar.
Geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulama varken geçersiz kılmaların kaldırılması girişiminde bulunursa AdServiceException
neden olarak IllegalStateException
değerini belirtir.
Alıcı tarafı JavaScript'i geçersiz kıl
- Özel bir kitleye katılma adımlarını uygulayın
- Teklif verme mantığı ve geçersiz kılma olarak kullanmak istediğiniz verilere ek olarak geçersiz kılmak istediğiniz özel kitlenin alıcısı ve adı ile bir
AddCustomAudienceOverrideRequest
oluşturun. - Eşzamansız
overrideCustomAudienceRemoteInfo()
yönteminiAddCustomAudienceOverrideRequest
nesnesi ve ilgiliExecutor
ileOutcomeReceiver
nesneleriyle çağırın
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);
buyer ve name değerleri, özel kitleyi oluşturmak için kullanılan değerlerle aynıdır. Bu alanlar hakkında daha fazla bilgi edinin.
Ayrıca, iki ek parametre belirtebilirsiniz:
biddingLogicJs
: Reklam seçimi sırasında kullanılan, alıcının mantığını barındıran JavaScript. Bu JavaScript'te gerekli işlev imzalarına bakın.trustedBiddingSignals
: Reklam seçimi sırasında kullanılacak teklif sinyalleri. Test amacıyla bu boş bir dize olabilir.
Eşzamansız overrideCustomAudienceRemoteInfo()
yöntemi, API çağrısının sonucunu işaret etmek için OutcomeReceiver
nesnesini kullanır.
onResult()
geri çağırması, geçersiz kılma işleminin başarıyla uygulandığını belirtir.
selectAds()
için yapılan sonraki çağrılar, geçersiz kılma olarak geçirdiğiniz teklif ve raporlama mantığını kullanır.
onError()
geri çağırması iki olası koşulu ifade eder.
- Geçersiz kılma işlemi, geçersiz bağımsız değişkenlerle denenirse
AdServiceException
neden olarak birIllegalArgumentException
belirtir. - Geçersiz kılma işlemi, geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulama ile denenirse
AdServiceException
neden olarakIllegalStateException
gösterilir.
Alıcı tarafı geçersiz kılmalarını sıfırla
Bu bölümde, alıcı tarafı JavaScript'i geçersiz kıldığınız ve önceki bölümde kullanılan TestCustomAudienceManager
için referansınızın olduğu varsayılır.
Tüm özel kitleler için geçersiz kılmaları sıfırlamak üzere:
- Alakalı
Executor
veOutcomeReceiver
nesneleriyle eşzamansızresetAllCustomAudienceOverrides()
yöntemini çağırın.
Kotlin
// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
executor,
outComeReceiver)
Java
// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
executor,
outComeReceiver)
Alıcı tarafı geçersiz kılmalarını sıfırladıktan sonra, sonraki selectAds()
çağrıları, gerekli JavaScript'i getirmeye çalışmak için CustomAudience
içinde depolanan biddingLogicUrl
ve trustedBiddingData
öğelerini kullanır.
resetCustomAudienceRemoteInfoOverride()
çağrısı başarısız olursa OutComeReceiver.onError()
geri çağırması bir AdServiceException
sağlar.
Geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulama varken geçersiz kılmaların kaldırılması denenirse neden AdServiceException
simgesi olarak IllegalStateException
belirtilir.
Raporlama Sunucusu Kurma
Uzaktan getirme geçersiz kılma işlemlerini kullandığınızda, raporlama etkinliklerine yanıt vermek için cihazınızın veya emülatörünüzün erişebileceği bir sunucu ayarlamanız gerekir. 200 döndüren basit bir uç nokta test için yeterlidir. GitHub deposu, desteklenen bir örnek veya mikro hizmet platformuna dağıtılabilen OpenAPI hizmet tanımları içerir. Daha fazla bilgi için BENİOKU projesine göz atın.
OpenAPI tanımlarını ararken reporting-server.json dosyasını bulun.
Bu dosya, HTTP yanıt kodunu temsil eden 200 değerini döndüren basit bir uç nokta içerir. Bu uç nokta, selectAds()
boyunca kullanılır ve Protected Audience API'ye gösterim raporlamasının başarıyla tamamlandığını belirtir.
Test edilecek işlev
- Katılma veya ayrılma ve önceki kullanıcı işlemlerine dayalı özel bir kitle oluşturma alıştırması yapın.
- Cihaz üzerinde reklam seçiminin başlatılmasını, uzaktan barındırılan JavaScript'ler aracılığıyla gerçekleştirin.
- Bir uygulamanın özel kitle ayarlarıyla ilişkilendirmesinin reklam seçimi sonuçlarını nasıl etkileyebileceğini gözlemleyin.
- Reklam seçiminden sonra gösterim raporlaması yapın.
Sınırlamalar
Aşağıdaki tabloda, Protected Audience API işleme sınırlamaları listelenmektedir. Sunulan sınırlar, geri bildirimlere göre değiştirilebilir. Devam eden özellikler için sürüm notlarını okuyun.
Bileşen | Sınır Açıklaması | Değeri Sınırla |
---|---|---|
Özel kitle (CA) | CA başına maksimum reklam sayısı | 100 |
Uygulama başına maksimum CA sayısı | 1000 | |
Sertifika yetkilisi oluşturabilecek maksimum uygulama sayısı | 1000 | |
CA'nın, oluşturulma zamanından itibaren etkinleştirme süresindeki maksimum gecikme | 60 gün | |
CA'nın etkinleştirme zamanından itibaren maksimum geçerlilik süresi | 60 gün | |
Cihazdaki maksimum CA sayısı | 4.000 | |
Maksimum CA adı boyutu | 200 bayt | |
Günlük getirme URI'sının maksimum boyutu | 400 bayt | |
Maksimum teklif mantığı URI'si boyutu | 400 bayt | |
Güvenilir teklif verme verilerinin maksimum boyutu | 10 KB | |
Kullanıcı teklif sinyallerinin maksimum boyutu | 10 KB | |
Alıcı başına leaveCustomAudience için maksimum arama ücreti |
Saniyede 1 | |
Alıcı başına joinCustomAudience için maksimum arama ücreti |
Saniyede 1 | |
CA Arka Planda Getirme | Bağlantı zaman aşımı | 5 saniye |
HTTP okuma zaman aşımı | 30 saniye | |
Maksimum toplam indirme boyutu | 10 KB | |
Getirme yinelemesinin maksimum süresi | 5 dakika | |
İş başına güncellenen maksimum CA sayısı | 1000 | |
Reklam Seçimi | Maksimum alıcı sayısı | Henüz belli değil |
Alıcı başına maksimum CA sayısı | Henüz belli değil | |
Bir açık artırmadaki maksimum reklam sayısı | Henüz belli değil | |
İlk bağlantı zaman aşımı | 5 saniye | |
Bağlantı okuma zaman aşımı | 5 saniye | |
Toplam AdSelection maksimum yürütme süresi |
10 saniye | |
AdSelection bölgesinde CA başına teklif için maksimum teklif yürütme süresi |
5 saniye | |
AdSelection içinde puanlamanın maksimum yürütme süresi |
5 saniye | |
AdSelection ayında alıcı başına maksimum yürütme süresi |
Henüz belli değil | |
Maksimum reklam seçimi/satıcı/alıcı başına sinyal boyutu boyutu | Henüz belli değil | |
Satıcı/alıcı komut dosyalarının maksimum boyutu | Henüz belli değil | |
selectAds için maksimum arama ücreti |
1 QPS | |
Gösterim raporlama | Reklam seçiminin kalıcılıktan kaldırılması için gereken minimum süre | 24 sa. |
Maksimum depolama alanı reklam seçimi sayısı | Henüz belli değil | |
Maksimum raporlama çıkış URL'si boyutu | Henüz belli değil | |
Gösterim raporlaması için maksimum süre | Henüz belli değil | |
Bildirim çağrıları için maksimum yeniden deneme sayısı | Henüz belli değil | |
Bağlantı zaman aşımı | 5 saniye | |
reportImpression için maksimum genel yürütme süresi |
2 saniye | |
reportImpressions için maksimum arama ücreti |
1 QPS | |
Etkinlik raporlama | Açık artırma başına alıcı başına maksimum işaretçi sayısı | 10 |
Açık artırma başına satıcı başına maksimum işaretçi sayısı |
10 |
|
Etkinlik anahtarının maksimum boyutu |
40 bayt |
|
Etkinlik verilerinin maksimum boyutu |
64KB |
|
Reklamlar | Reklam listesinin maksimum boyutu | Bağlam için tek bir CA'da tüm AdData tarafından paylaşılan 10 KB |
URL'ler | Girdi olarak alınan herhangi bir URL dizesinin maksimum uzunluğu | Henüz belli değil |
JavaScript | Maksimum yürütme süresi | Gösterim raporlamasında teklif verme ve puanlama için 1 saniye |
Kullanılan maksimum bellek | 10 MB |
Hataları ve sorunları bildirme
Geri bildirimleriniz, Android'deki Özel Korumalı Alan için çok önemlidir. Android'de Özel Korumalı Alan'ın iyileştirilmesiyle ilgili sorunları veya fikirlerinizi bizimle paylaşabilirsiniz.
Sizin için önerilenler
- Not: Bağlantı metni JavaScript kapalıyken görüntülenir
- Protected Audience API ile özel kitle hedeflemeyi destekleme
- Sürüm notları
- Korunan Kitle: Entegrasyon kılavuzu