Protected Audience API Geliştirici Kılavuzu

Android'de Özel Korumalı Alan dokümanlarını okurken talimatlar farklılık gösterebileceğinden, çalıştığınız program sürümünü seçmek için Geliştirici Önizlemesi veya Beta düğmesini kullanın.

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, uygulamalar arası tanımlayıcı paylaşımını ve kullanıcının uygulama etkileşimi bilgilerinin üçüncü taraflarla paylaşımını sınırlayan, önceki uygulama etkileşimine dayalı özelleştirilmiş reklamlar yayınlamak için bu API'leri kullanabilir.

Özel Kitle API'si, ortak amaçları olan bir kullanıcı grubunu temsil eden "özel kitle" soyutlaması üzerine kuruludur. Reklamverenler, özel kitleye kullanıcı kaydedebilir ve alakalı reklamları bu kitleyle ilişkilendirebilir. Bu bilgiler yerel olarak depolanır ve reklamveren teklifleri, reklam filtreleme ve reklam oluşturma hakkında bilgi vermek için kullanılabilir.

Reklam Seçimi API'si, birden fazla geliştiricinin özel bir kitle için yerel olarak açık artırma yapmasına olanak tanıyan bir çerçeve sağlar. Bunu sağlamak için sistem, özel kitleyle ilişkili alakalı reklamları dikkate alır ve bir reklam teknolojisi platformunun cihaza döndürdüğü reklamlarda ek işlem gerçekleştirir.

Reklam teknolojisi platformları, kullanıcı gizliliğini koruyan yeniden pazarlamayı uygulamak için bu API'leri entegre edebilir. Uygulama yükleme reklamları da dahil olmak üzere ek kullanım alanları için destek, gelecekteki sürümlerde sunulacaktır. Android'deki Protected Audience API hakkında daha fazla bilgiyi tasarım önerisinde bulabilirsiniz.

Bu kılavuzda, Android'de Protected Audience API ile çalışarak aşağıdakileri nasıl yapacağınız açıklanmaktadır:

1. Özel kitleleri yönetme
2. Cihazda reklam seçimi ayarlama ve çalıştırma
3. Reklam gösterimlerini raporlama

Başlamadan önce

Başlamadan önce aşağıdakileri tamamlayın:

1. Android'de Özel Korumalı Alan için geliştirme ortamınızı ayarlayın.
2. Desteklenen bir cihaza sistem görüntüsü yükleyin veya Android'de Privacy Sandbox desteği içeren bir emülatör ayarlayın.

3. Bir terminalde, aşağıdaki adb komutuyla Protected Audience API'ye (varsayılan olarak devre dışıdır) erişimi etkinleştirin.

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. Terminalde aşağıdaki adb komutlarıyla sinyal raporlamayı etkinleştirin.

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

5. Uygulama manifestinize ACCESS_ADSERVICES_CUSTOM_AUDIENCE izni ekleyin:

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

6. Manifest dosyanızın <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" />
   

7. Manifest dosyanızda referans verilen reklam hizmetleri XML kaynağını belirtin (ör. res/xml/ad_services_config.xml). Reklam hizmetleri izinleri ve SDK erişimi kontrolü hakkında daha fazla bilgi edinin.

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

8. Varsayılan olarak, Ad Selection API, bir açık artırma veya gösterim raporlama komut dosyasının ayırabileceği maksimum bellek miktarıyla ilgili sınırlamalar uygular. Bellek sınırlama özelliği için WebView sürüm 105.0.5195.58 veya daha yeni bir sürüm gerekir. Platform, sürüm kontrolünü zorunlu kılar ve bu koşul karşılanmazsa selectAds ile reportImpression API'lerine yapılan çağrılar başarısız olur. Bu özelliği ayarlamak için iki seçeneğiniz vardır:

   • 1. seçenek: Bu kontrolü 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 sürüm, daha önce belirtilen sürümle aynı veya daha yüksek olmalıdır.

Özel kitleye katılma

Özel kitle, bir reklamveren uygulaması tarafından belirlenen ortak amaçlara veya ilgi alanlarına sahip bir kullanıcı grubunu temsil eder. Bir uygulama ya da SDK, belirli bir kitleyi (ör. alışveriş sepetinde ürün bırakan bir kullanıcı) belirtmek için özel kitle kullanabilir. Özel kitleyi eşzamansız olarak oluşturmak veya özel kitleye katılmak için aşağıdakileri yapın:

1. CustomAudienceManager nesnesini başlatın.
2. Alıcının paketi ve alakalı bir ad gibi temel parametreleri belirterek bir CustomAudience nesnesi oluşturun. Ardından, JoinCustomAudienceRequest nesnesini CustomAudience nesnesiyle başlatın.
3. JoinCustomAudienceRequest nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle eşzamansız joinCustomAudience() işlevini çağırın.

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

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

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

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

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

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

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

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

Aşağıdaki parametrelerin kombinasyonu, bir cihazdaki her CustomAudience nesneyi benzersiz bir şekilde tanımlar:

• owner: Sahip uygulamanın paket adı. Bu, arayan uygulamanın paket adı olarak dolaylı şekilde 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ı.

CustomAudience öğesinin farklı bir örneğiyle joinCustomAudience() işlevinin tekrar tekrar çağrılması, eşleşen owner, buyer ve name parametreleriyle mevcut tüm CustomAudience öğelerini günceller. Gizliliğin korunmasına yardımcı olmak için API'nin sonucu "oluşturma" ve "güncelleme" arasında ayrım yapmaz.

Ayrıca, CustomAudience aşağıdaki zorunlu parametrelerle oluşturulmalıdır:

• Günlük güncelleme URL'si: Özel bir kitlenin kullanıcı teklifi sinyallerini, güvenilir teklif verilerini ve reklamların oluşturma URL'lerini ve meta verilerini güncellemek için arka planda günlük olarak sorgulanan bir HTTPS URL'si.
• Teklif verme mantığı URL'si: Bir alıcının JavaScript teklif verme mantığını getirmek için reklam seçimi sırasında sorgulanan bir HTTPS URL'si. Bu JavaScript'te gerekli işlev imzalarını inceleyin.
• Reklam Oluşturma Kimlikleri: Alıcı reklam teknolojisi tarafından ayarlanan rastgele bir 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 süresi: Özel kitleler, yalnızca etkinleştirme süresinden sonra reklam seçimine ve günlük güncellemelere katılabilir. Bu özellik, örneğin bir uygulamayı kullanmayı bırakmış kullanıcılarla yeniden etkileşim kurmak için yararlı olabilir.
• Geçerlilik bitiş zamanı: Özel kitlenin cihazdan kaldırılacağı gelecekteki bir zaman.
• Kullanıcı teklif sinyalleri: Bir alıcının teklif verme mantığı JavaScript'inin, reklam seçimi sürecinde teklif oluşturmak için kullandığı, kullanıcının tercih ettiği yerel ayar gibi kullanıcı sinyallerini içeren bir JSON dizesi. Bu biçim, reklam teknolojisi platformlarının kodları platformlar arasında yeniden kullanmasına yardımcı olur ve JavaScript işlevlerinde tüketimi kolaylaştırır.
• Güvenilir teklif verileri: Güvenilir bir anahtar/değer hizmetinden teklif sinyallerini getiren, reklam seçimi sürecinde kullanılan bir HTTPS URL'si ve bir dizi dize.
• Reklamlar: Reklam seçimine katılan reklamlara karşılık gelen AdData nesnelerinin listesi. Her AdData nesnesi şunlardan oluşur:
  • Oluşturma URL'si: Nihai reklamın oluşturulması için sorgulanan bir HTTPS URL'si.
  • Meta veri: Reklam seçimi sürecinde alıcı teklif verme mantığı tarafından kullanılacak bilgileri içeren, dize olarak serileştirilmiş bir JSON nesnesi.
  • Reklam Filtreleri: Reklam seçimi sırasında uygulama yükleme reklamı filtreleme ve sıklık sınırlama için gerekli tüm bilgileri içeren bir sınıf.

CustomAudience nesne oluşturma örneğini aşağıda görebilirsiniz:

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

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

joinCustomAudience() sonuçlarını işleme

Asenkron joinCustomAudience() yöntemi, API çağrısının sonucunu bildirmek için OutcomeReceiver nesnesini kullanır.

• onResult() geri çağırması, özel kitlenin başarıyla oluşturulduğunu veya güncellendiğini gösterir.
• onError() geri çağırma işlevi iki olası durumu gösterir.
  • JoinCustomAudienceRequest geçersiz bağımsız değişkenlerle başlatılırsa AdServicesException, neden olarak IllegalArgumentException'ı gösterir.
  • Diğer tüm hatalar, neden olarak IllegalStateException ile birlikte AdServicesException alır.

joinCustomAudience() sonucunun nasıl ele alınacağına dair bir örneği aşağıda bulabilirsiniz:

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

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

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

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

Özel kitle bırakma

Kullanıcı artık belirli bir özel kitle için işletme ölçütlerini karşılamıyorsa bir uygulama veya SDK, özel kitleyi cihazdan kaldırmak için leaveCustomAudience() işlevini çağırabilir. Benzersiz parametrelerine göre bir CustomAudience kaldırmak için aşağıdakileri yapın:

1. CustomAudienceManager nesnesini başlatın.
2. LeaveCustomAudienceRequest öğesini özel kitlenin buyer ve name ile başlatın. Bu giriş alanları hakkında daha fazla bilgi edinmek için "Özel kitleye katılma" başlıklı makaleyi inceleyin.
3. leaveCustomAudience() yöntemini LeaveCustomAudienceRequest nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle birlikte eşzamansız olarak çağırın.

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

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

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

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

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

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

joinCustomAudience() çağrısına benzer şekilde, OutcomeReceiver sinyalleri bir API çağrısının sonunu gösterir. 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. onResult() Geri çağırma, eşleşen bir özel kitle başarıyla kaldırılmış olsun veya olmasın, API çağrısı tamamlandığında çağrılır.

Reklam seçimini çalıştırma

Reklam seçmek için Protected Audience API'yi kullanmak üzere selectAds() yöntemini çağırın:

1. Bir AdSelectionManager nesnesi başlatın.
2. AdSelectionConfig nesnesi oluşturun.
3. selectAds() yöntemini AdSelectionConfig nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle birlikte eşzamansız olarak çağırın.

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

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

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

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

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

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

selectAds() yöntemi için AdSelectionConfig girişi gerekir. Bu girişte aşağıdaki zorunlu parametreleri belirtmeniz gerekir:

• Satıcı: Reklam seçimini başlatan satıcı reklam ağının tanımlayıcısı.
• Karar mantığı URL'si: Satıcının reklam ağının JavaScript mantığını elde etmek için sorgulanan bir 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ına bakın.
  • Önceden oluşturulmuş URI: FLEDGE'in reklam seçimi biçimine uyar. Desteklenmeyen veya hatalı biçimlendirilmiş bir önceden oluşturulmuş URI geçirilirse IllegalArgumentException istisnası oluşturulur.
• Özel kitle alıcıları: Satıcının reklam seçimi sürecine katılmasına izin verdiği alıcı reklam ağlarının tanımlayıcılarının tam listesi. Bu alıcı tanımlayıcıları, CustomAudience.getBuyer() katılımcı özel kitleye karşılık gelir.

Daha özelleştirilmiş reklam seçimi için aşağıdaki parametreler isteğe bağlı olarak 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: Satıcının AdSelectionConfig.getDecisionLogicUrl() kaynağından getirilen JavaScript karar mantığı tarafından kullanılan sinyalleri içeren, dize olarak serileştirilmiş bir JSON nesnesi.
• Alıcı başına sinyaller: Belirli alıcıların teklif verme mantığı JavaScript'i tarafından kullanılacak sinyaller içeren, dizeler olarak serileştirilmiş bir JSON nesneleri haritası. Katılımcı özel kitlelerin alıcı alanlarıyla tanımlanan CustomAudience.getBiddingLogicUrl() kaynağından getirilir.
• Bağlamsal reklamlar: Protected Audience açık artırması 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 kalıcı hale getirilir. OutcomeReceiver.onResult() geri çağırması, aşağıdakileri içeren bir AdSelectionOutcome döndürür:

• AdData.getRenderUrl()'dan alınan, kazanan reklamın yayın URL'si.
• Cihaz kullanıcısına özgü bir reklam seçimi kimliği. Bu kimlik, reklam gösterimini raporlamak için kullanılır.

Geçersiz bağımsız değişkenler, zaman aşımları veya aşırı kaynak tüketimi gibi nedenlerle reklam seçimi başarıyla tamamlanamazsa OutcomeReceiver.onError() geri çağırma işlevi, aşağıdaki davranışlara sahip bir AdServicesException sağlar:

• Reklam seçimi geçersiz bağımsız değişkenlerle başlatılırsa AdServicesException, IllegalArgumentException'ü neden olarak gösterir.
• Diğer tüm hatalar, neden olarak IllegalStateException ile birlikte AdServicesException alır.

Bağlama dayalı reklamlar

Protected Audience, içerik hedefli reklamları Protected Audience açık artırmasına dahil edebilir. Bağlamsal reklamların, reklam teknolojisi sunucusunda seçilip Protected Audience API'leri dışında cihaza döndürülmesi gerekir. İçeriğe dayalı reklamlar, AdSelectionConfig kullanılarak açık artırmaya dahil edilebilir. Bu noktada, negatif reklam filtrelemeye uygunluk da dahil olmak üzere cihazdaki reklamlarla aynı şekilde çalışırlar. Protected Audience açık artırması tamamlandıktan sonra reportImpression() işlevini çağırmanız gerekir. Bu, bir cihazda kazanan reklamı almak için gösterim raporlaması ile aynı düzende, kazanan bağlamsal reklamda reportWin() çağrısı yapar. Her bağlamsal reklam için bir alıcı, teklif, raporlama mantığına giden bir bağlantı, oluşturma URL'si ve reklam meta verileri gerekir.

Uygulamada bağlamsal reklamları dağıtmak için hedef uygulamanın bir ContextualAds nesnesi oluşturması gerekir:

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

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

Elde edilen ContextualAds nesnesi, AdSelectionConfig oluşturulurken iletilebilir:

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

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

Uygulama yükleme reklamı filtreleme

Uygulama yükleme reklamlarını filtreleme, bir cihaza zaten yüklenmiş olan uygulamaların yükleme reklamlarını filtrelemenize yardımcı olur.

Bu sürecin ilk adımı, hangi reklamverenlerin yüklü pakete göre filtreleme yapabileceğini tanımlamaktır. Bu işlem, reklamla hedeflemek istediğiniz uygulamada yapılmalıdır.

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

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

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

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

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

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

Önceki kod yürütüldüğünde, 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 bu kodu reklamverenin bilgileri kaldırılmış şekilde tekrar çalıştırın.

Bir sonraki adım, yayıncı uygulamasında reklam filtrelemeyi ayarlamaktır. Yayıncı uygulamasında reklam sunan taraf (büyük olasılıkla bir arz tarafı SDK'sı) AdFilters nesnesini, uygulamalarla ilgili hangi reklamları filtrelemek istediği hakkında bilgilerle başlatmalıdır:

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

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

Talep tarafı yayıncılar, özel kitlelerinde bulunan reklamlar için de AdFilter ayarlayabilir.

AdFilters, yeni bir AdData nesnesi oluşturulurken de iletilebilir:

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

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

Sıklık sınırı filtreleme

Sıklık sınırı filtreleme, reklam teknolojilerinin bir reklamın gösterilme sayısını sınırlamasına olanak tanır. Sıklık sınırı filtreleme, reklamların aşırı gösterilmesini 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 etkinliği türü ve reklam sayacı anahtarı. Kullanılabilecek reklam etkinliği türleri şunlardır:

• Kazanma: 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 geliştirici tarafından doğrudan çağrılamaz. Kazanan verileri yalnızca belirli bir özel kitledeki reklamlar tarafından görülebilir.
• Gösterim: reportImpression'den ayrı olarak, cihaz üzerinde bir arayan (SSP veya MMP), kodda seçtiği noktada gösterim etkinliklerini çağırmak için updateAdCounterHistogram()'yi kullanır. Gösterim etkinlikleri, belirli bir TTP'ye ait tüm reklamlar tarafından görülebilir ve aynı özel kitledeki reklamlarla sınırlı değildir.
• Görüntüleme: Etkinlik, cihazdaki arayan (SSP veya MMP) tarafından updateAdCounterHistogram() çağrısı kullanılarak seçtikleri bir kod noktasında çağrılır. Görüntüleme etkinlikleri, belirli bir TTP'ye ait tüm reklamlar tarafından görülebilir ve aynı özel kitledeki reklamlarla sınırlı değildir.
• Tıklama: Etkinlik, cihazdaki arayan (SSP veya MMP) tarafından updateAdCounterHistogram() çağrısı kullanılarak seçtikleri bir kod noktasında ç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 SSP 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ırmalarda, kullanıcının belirli bir reklamla karşılaşmasıyla ilgili güncel bilgiler yer alır. Reklam etkinliği türleri, ilgili kullanıcı işlemine zorunlu olarak bağlı değildir ve arayanların etkinlik sistemlerini yapılandırmalarına yardımcı olmak için verilen yönergelerdir. Cihazdaki aktör, bir etkinlik sırasında reklam sayaçlarını artırmak için kazanan reklam açık artırmasının reklam seçimi kimliğini sağlar.

Reklam sayacı anahtarları, bir alıcı reklam teknolojisi tarafından atanan rastgele 32 bitlik imzalı tam sayılardır ve TTP tarafından tanımlanan belirli bir reklam grubuyla eşleşir. Reklam sayacı anahtarları yalnızca belirli bir DSP'ye ait reklamlarla sınırlı olduğundan bu anahtarlar, başka bir reklam teknolojisinden gelen histogramlarla çakışmadan seçilebilir. Reklam sayacı anahtarları, gelecekteki açık artırmalardan reklamları filtrelemek için bir DSP'nin reklamlarında veya belirli bir özel kitlede DSP'ye özgü tanımlayıcıları artırmak için kullanılır.

Sayaç anahtarları, belirli bir alıcı reklam teknolojisinden gelen diğer reklamlarla etkileşimlerine göre belirli bir kullanıcı için ilgi çekici olma olasılığı daha yüksek olan reklamlara öncelik vermek için kullanılabilir. Örneğin, kazanan reklam açık artırmalarından, görüntülemelerden ve tıklamalardan yüksek düzeyde etkileşim alan bir reklam, çıkarılmış bir veri noktasını temsil eder. Bu noktayı daha iyi açıklamak için bir örnek verelim: Solak golf sopalarıyla ilgili bir reklam, kullanıcının sağ elini kullananlar için olanlarla ilgilenmeyeceğini gösterebilir. Solaklara yönelik reklamlara atanan bir sayaç anahtarı için ayarlanan sıklık sınırı filtresi, sağ elini kullananlara yönelik reklamları filtreleyebilir.

Açık artırmanızda sıklık sınırını kullanmak için önce aşağıdaki KeyedFrequencyCap nesneleri oluşturmanız gerekir:

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

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

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

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

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

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

KeyedFrequencyCap nesneleri oluşturulduktan sonra bunları bir AdFilters nesnesine aktarabilirsiniz.

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

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

AdFilters nesnesi sıklık sınırı filtreleriyle doldurulduğunda, özel kitle oluşturulurken bu filtreler iletilebilir:

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

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

Sıklık sınırı filtreleri özel bir kitleye uygulandığında, SSP gerekli tıklama, görüntüleme veya gösterim etkinliklerini çağırabilir.

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

Önceden ayarlanmış sıklık sınırı filtre sınırlarına ulaşan reklamlar açık artırmadan filtrelenir. Filtreleme, cihaz üzerinde açık artırmalar için teklif verme mantığı yürütülmeden önce ve teklif verme ve açık artırma hizmetleri açık artırmaları için yük oluşturulurken gerçekleşir.Bu araç kiti, reklam teknolojisi sağlayıcılara reklam hedeflemeye odaklanırken reklamların aşırı gösterimini en aza indirmek için kullanıcılar ile özel kitlelerindeki reklamlar arasındaki etkileşimleri kullanma esnekliği sağlar.

Ağ aramaları olmadan bağlamsal reklam filtreleme

Cihazda yeniden pazarlama talebi yoksa ağ çağrıları olmadan bağlamsal reklamlar için reklam seçimi gerçekleştirebilirsiniz. Önceden oluşturulmuş URI'ler ve teklif içeren bağlamsal reklamlar listesi sayesinde platform, teklif mantığını, teklif sinyallerini ve puanlama sinyallerini almayı atlayabilir. Platform, en yüksek teklife sahip bağlamsal reklamı seçmek için önceden oluşturulmuş bir URI kullanır.

Reklam teknolojileri, gecikmeyi azaltmak için yalnızca ağ çağrıları olmadan reklam filtreleme işlevine sahip bağlamsal reklamları içeren bir reklam seçimi akışı çalıştırabilir. Bu, puanlama sinyalleri için önceden oluşturulmuş URI'ler kullanılarak sağlanır. scoreAds uygulamalarının listesi için Desteklenen önceden oluşturulmuş URI kullanım alanları ve adları bölümüne bakın.

Ağ aramaları olmadan reklam seçimi çalıştırmak için:

1. Reklam filtrelemeyi ayarlama
2. Bağlamsal reklamlarınızı oluşturma

3. Aşağıdaki bilgileri içeren bir AdSelectionConfig nesnesi oluşturun:

   1. Boş bir alıcı listesi
   2. En yüksek teklifi seçmek için önceden oluşturulmuş bir URI
   3. Bağlama dayalı reklamlar
   4. Puanlama sinyalleri için boş bir URI. Boş URI, puanlama için güvenilir sinyallerin getirilmesini kullanmak istemediğinizi belirtmek amacıyla kullanılabilir:

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

4. Reklam seçimi çalıştırma:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Önceden oluşturulmuş URI'leri kullanırken kendi raporlama JavaScript'inizi çalıştırma

Özel Korumalı Alan platformunda şu anda yalnızca önceden oluşturulmuş URI'ler için temel bir raporlama JavaScript uygulaması mevcuttur. Düşük gecikmeli reklam seçimi için önceden oluşturulmuş URI'leri kullanmaya devam ederken kendi raporlama JavaScript'inizi çalıştırmak istiyorsanız reklam seçimi ve raporlama çalıştırmaları arasındaki DecisionLogicUri değerini geçersiz kılabilirsiniz.

1. Önceden oluşturulmuş URI'ler kullanarak bağlamsal reklamlar için reklam seçimi çalıştırmak üzere adımları uygulayın.

2. Rapor oluşturmadan önce AdSelectionConfig kopyasını oluşturun

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

3. Gösterim raporu ç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ı çalıştırma

Şelale uyumlulaştırması, birinci taraf SDK uyumlulaştırma ağı tarafından düzenlenmek üzere birden fazla üçüncü taraf SDK'sı (3. taraf ağlar) gerektirir. Açık artırma cihazda gerçekleşmiş veya Teklif ve Açık Artırma Hizmetleri'nde (B&A) çalışmış olmasına bakılmaksızın, şelale aracılığı aynı şekilde yapılır.

Üçüncü taraf ağları

Üçüncü taraf ağları, aracılık ağının açık artırma çalıştırmak için gerekli yöntemleri çağırmasına olanak tanıyan bir bağdaştırıcı sağlamalıdır:

• Reklam seçimini çalıştırma
• Rapor gösterimleri

Aşağıda bir arabuluculuk ağı bağdaştırıcısı örneği verilmiştir:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Her SDK'nın kendi reklam seçimi hizmeti yöneticileri ve istemcileri ile kendi selectAds ve reportImpressions uygulaması vardır. SDK sağlayıcılar, cihaz üzerinde açık artırmalar için reklam seçimi yapma ile ilgili bölümlere veya B&A açık artırmaları için B&A açıklayıcıya başvurabilir. Reklam gösterimlerini raporlama (raporlama için tek TTP gösterim raporlaması izlenerek) adımlarını uygulayın.

Uyumlulaştırma ağı

3. taraf ağlarına benzer şekilde, uyumlulaştırma ağlarının selectAds ve reportImpression uygulamaları gerekir. Daha fazla bilgi için reklam seçimi çalıştırma ve reklam gösterimlerini raporlama 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 açıklanmaktadır.

Uyumlulaştırma zincirini ve teklif tabanlarını alma

Uyumlulaştırma ağı, birinci taraf (1P) içerik reklamlarını, uyumlulaştırma zincirini ve üçüncü taraf ağların teklif tabanlarını (3P) almaktan sorumludur. Bu durum, uyumlulaştırma ağı tarafından yürütülen bağlama dayalı reklamları alma isteğinde meydana gelebilir. Uyumlulaştırma zinciri, üçüncü taraf ağlarında nasıl yineleme yapılacağını belirler ve teklif taban fiyatları, açık artırma sürecine adSelectionSignals olarak iletilebilir.

Uyumlulaştırma zincirinde ağ yerleşimi

Uyumlulaştırma SDK'ları, birinci taraf reklam tekliflerinin canlı eBGBM'sine göre uyumlulaştırma zincirine yerleşebilir. Protected Audience API'de reklam teklifleri opak olur. Bir uyumlulaştırma SDK'sı, belirli bir birinci taraf reklamının teklifini zincirdeki bir sonraki üçüncü taraf ağının teklif tabanıyla karşılaştırabilmek için AdSelectionFromOutcomesConfig kullanmalıdır. Birinci taraf teklifi, teklif taban fiyatından yüksekse uyumlulaştırma SDK'sının bu üçüncü taraf ağının önüne yerleştirildiği anlamına gelir.

Reklam seçimini çalıştırma

Uyumlulaştırma ağı, birinci taraf reklam adayını almak için reklam seçimi çalıştırma bölümündeki adımları uygulayarak cihaz üzerinde bir açık artırma gerçekleştirebilir. Bu işlem, uyumlulaştırma sürecinde kullanılan bir 1. taraf reklam adayı, bir teklif ve bir AdSelectionId oluşturur.

AdSelectionFromOutcomesConfig oluşturma

Bir AdSelectionFromOutcomesConfig, aracılık ağının AdSelectionIds listesini (önceki açık artırmalardan elde edilen sonuçlar), reklam seçimi sinyallerini ve birden fazla aday arasından reklam seçen JavaScript'i getirmek için bir URI'yi iletmesine olanak tanır. Teklifleri ve sinyalleriyle birlikte AdSelectionId'lerin listesi, teklif tabanını aşarsa AdSelectionIds değerlerinden birini, uyumlulaştırma zincirinin devam etmesi gerekiyorsa hiçbirini döndürebilen JavaScript'e iletilir.

Aracılık ağları, önceki bölümdeki 1. taraf AdSelectionId ve dikkate alınan 3. taraf ağının teklif tabanını kullanarak bir AdSelectionFromOutcomesConfig oluşturur. Uyumlulaştırma zincirindeki her adım için yeni bir AdSelectionFromOutcomesConfig oluşturulmalıdır.

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

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

    return adSelectionClient.selectAds(config){}
}

Şelale aracılığı için selectAds() yöntemi geçersiz kılma, AdSelectionFromOutcomesConfig girişi gerektirir. Bu girişte aşağıdaki zorunlu parametreleri belirtmeniz gerekir:

• 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 tek öğeli listesi.
• Reklam seçimi sinyalleri: Alıcı teklif verme mantığı tarafından kullanılacak sinyalleri içeren, dize olarak serileştirilmiş bir JSON nesnesi. Bu durumda, söz konusu üçüncü taraf ağı için alınan teklif taban fiyatını ekleyin.
• Seçim mantığı URI'si: Kazanan bir reklamı seçmek için arabuluculuk ağının JavaScript'ini getirmek üzere reklam seçimi sırasında sorgulanan bir HTTPS URL'si. Bu JavaScript'teki gerekli işlev imzalarına bakın. Teklif, teklif taban fiyatından yüksekse JavaScript, üçüncü taraf reklamını döndürmeli, aksi takdirde null döndürmelidir. Bu, bir kazanan bulunduğunda uyumlulaştırma SDK'sının uyumlulaştırma zincirini kısaltmasına olanak tanır.

AdSelectionOutcomesConfig oluşturulduktan sonra zincirdeki ilk 3. taraf ağının selectAds() yöntemini çağırın.

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

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

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

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

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

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

Şelale uyumlulaştırmasını düzenleme

Aşağıda, arabuluculuk sürecinin yürütülmesiyle ilgili işlem sırası verilmiştir.

1. 1. taraf reklam seçimi çalıştırın.
2. Uyumlulaştırma zincirinde yineleme yapın. Her 3. taraf ağı için aşağıdakileri yapın:
   1. Birinci taraf outcomeId ve üçüncü taraf SDK'sının teklif taban fiyatı dahil olmak üzere AdSelectionFromOutcomeConfig oluşturun.
   2. Önceki adımdaki yapılandırmayla selectAds() işlevini çağırın.
   3. Sonuç boş değilse reklamı döndürün.
   4. Mevcut SDK ağ bağdaştırıcısının selectAds() yöntemini çağırın. Sonuç boş değilse reklamı döndürün.
3. Zincirde kazanan bulunamazsa birinci taraf reklamını döndürün.

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

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

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

class MediationNetwork {
    AdSelectionManager adSelectionManager;

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

    public void runAdSelection() {...}

    public void reportImpressions() {...}

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

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

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

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

Reklam gösterimlerini raporlama

Açık artırmanın nasıl yürütüldüğüne bağlı olarak bir reklam gösterimini bildirmek için iki akış vardır. Açık artırma yürüten tek bir SSP iseniz bu bölümdeki adımları uygulayın. Şelale uyumlulaştırması uygulayacaksanız Şelale uyumlulaştırması gösterim raporu bölümündeki adımları uygulayın.

Tek STP gösterim raporu

Reklam seçimi iş akışından kazanan bir reklam seçildikten sonra, gösterimi AdSelectionManager.reportImpression() yöntemiyle katılımcı alıcı tarafı ve satıcı tarafı platformlarına geri bildirebilirsiniz. Bir reklam gösterimini bildirmek için:

1. Bir AdSelectionManager nesnesi başlatın.
2. Reklam seçimi kimliğiyle bir ReportImpressionRequest nesnesi oluşturun.
3. reportImpression() yöntemini ReportImpressionRequest nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle birlikte eşzamansız olarak çağırın.

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

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

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

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

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

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

ReportImpressionRequest öğesini aşağıdaki zorunlu parametrelerle başlatın:

• Reklam seçimi kimliği: Yalnızca bir cihaz kullanıcısına özel olan ve başarılı bir reklam seçimini tanımlayan kimlik.
• Reklam seçimi yapılandırması: Sağlanan reklam seçimi kimliğiyle tanımlanan selectAds() çağrısında kullanılan yapılandırmayla aynıdır.

Asenkron reportImpression() yöntemi, API çağrısının sonucunu bildirmek için OutcomeReceiver nesnesini kullanır.

• onResult() geri çağırma işlevi, gösterim raporlama URL'lerinin oluşturulup oluşturulmadığını ve isteğin planlanıp planlanmadığını gösterir.
• onError() geri çağırma işlemi 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 IllegalArgumentException'ü gösterir.
  • Diğer tüm hatalar, neden olarak IllegalStateException ile birlikte AdServicesException alır.

Şelale uyumlulaştırması gösterim raporları

Arabuluculuk 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ğırabileceği bir yöntem sağlamalıdır. Aracılı açık artırmaya katılan bir SDK, kendi raporlamasını uygulamak için yukarıdaki adımları uygulayabilir.

SSP'ler, bu 3. taraf SDK kodu örneğini, arabuluculuk akışlarına nasıl katılacaklarına dair bir 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ı platform ve kazanan alıcı tarafı platform tarafından sağlanan uç noktalara HTTPS GET istekleri gönderir:

Alıcı tarafı platformu uç noktası:

• API, bir gösterim raporlama URL'si döndürme mantığını içeren alıcı tarafından sağlanan 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ı platformu uç noktası:

• Satıcının karar mantığı JavaScript'ini getirmek için AdSelectionConfig nesnesinde belirtilen Karar mantığı URL'sini kullanın.
• Satıcının gösterim raporlama URL'sini döndürmesi beklenen reportResult() JavaScript işlevini çağırın.

Teklif ve açık artırma hizmetleri raporlaması

Teklif verme ve açık artırma hizmetlerinde yürütülen bir açık artırmada, sunucu tarafı açık artırmadan gelen şifrelenmiş yanıtta reklam etkileşimi raporlaması için oluşturulan URL'ler de dahil olmak üzere gerekli tüm raporlama bilgileri yer alır. Yanıtın şifresi çözüldüğünde uygun URL'ler platforma kaydedilir. Böylece reklam ve gösterim raporlaması aynı adımları izler.

En iyi sonuç gösterim raporları

reportImpression() yöntemi, raporlamanın en iyi şekilde tamamlanmasını sağlamak için tasarlanmıştır.

Reklam Etkileşimlerini Bildirme

Protected Audience, oluşturulan bir reklamla ilgili daha ayrıntılı etkileşimler hakkında rapor oluşturma desteği sağlar. Bu etkileşimler arasında görüntüleme süresi, tıklama sayısı, fareyle üzerine gelme veya toplanabilecek diğer tüm yararlı metrikler yer alabilir. Bu raporları almak için iki adım gerekir. İlk olarak, alıcılar ve satıcılar bu raporları raporlama JavaScript'lerinde almak için kaydolmalıdır. Ardından, müşterinin bu etkinlikleri bildirmesi gerekir.

Etkileşim etkinliklerini almak için kaydolma

Etkileşim etkinliklerine kaydolma, platform tarafından sağlanan bir JavaScript işlevi (registerAdBeacon) kullanılarak alıcının reportWin() ve satıcının reportResult() JavaScript işlevlerinde gerçekleşir. Etkinlik raporu almak için kaydolmak üzere raporlama JavaScript'inizden platform JavaScript işlevini çağırın. Aşağıdaki snippet'te alıcının reportWin() değeri kullanılmaktadı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, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

Etkileşim etkinliklerini raporlama

Bir gösterim raporlandıktan sonra istemciler, etkileşimleri AdSelectionManager.reportInteraction() yöntemiyle daha önce kaydedilmiş kazanan satın alma tarafı ve satış tarafı platformlarına geri bildirebilir. Bir reklam etkinliğini bildirmek için:

1. Bir AdSelectionManager nesnesi başlatın.
2. Reklam seçimi kimliği, etkileşim anahtarı, etkileşim verileri ve raporlama hedefiyle bir ReportInteractionRequest nesnesi oluşturun.
3. reportInteraction() yöntemini request nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle birlikte eşzamansız olarak ç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);

ReportInteractionRequest öğesini aşağıdaki zorunlu parametrelerle başlatın:

• Reklam seçimi kimliği: Daha önce döndürülen bir AdSelectionOutcome öğesinden alınan reklam seçimi kimliği.
• Etkileşim Anahtarı: Bildirilen işlemi açıklayan, istemci tarafından tanımlanan bir dize anahtarı. Bu, satıcı veya alıcı tarafından raporlama JavaScript işlevlerinde kaydedilen anahtarla eşleşmelidir.
• Etkileşim Verileri: Etkinlik raporuna dahil edilecek ve raporlama sunucularına geri POST edilecek verileri içeren bir dize.
• Raporlama Hedefleri: Etkinliklerin alıcıya, satıcıya veya her ikisine de raporlanıp raporlanmayacağını belirten bit maskesi. Bu işaretler platform tarafından sağlanır ve nihai hedef maskesi bit düzeyinde 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 rapor göndermek için bit düzeyinde OR (|) işlemini kullanarak işaret değerlerini birleştirebilirsiniz.

Asenkron reportInteraction() yöntemi, API çağrısının sonucunu bildirmek için OutcomeReceiver nesnesini kullanır.

• onResult() geri çağırma, rapor etkileşimi çağrısının geçerli olduğunu gösterir.
• onError() geri çağırma işlemi aşağıdaki olası koşulları gösterir:
  • Arama, uygulama arka planda çalışırken yapılırsa hatanın açıklamasını içeren bir IllegalStateException döndürülür.
  • İstemci reportInteraction() numarasına çağrı gönderme konusunda sınırlandırılmışsa LimitExceededException döndürülür.
  • Paket, gizliliği korumaya yönelik API'leri çağırmak için kaydedilmemişse SecurityException() döndürülür.
  • Etkileşimleri bildiren uygulama, selectAds() işlevini çağıran uygulamadan farklıysa IllegalStateException döndürülür.
• Kullanıcı, Özel Korumalı Alan API'lerinin etkinleştirilmesine izin vermediyse çağrı sessizce başarısız olur.

Etkileşim raporlama uç noktaları

Rapor etkileşimi API'si, satış tarafı platformu ve kazanan alım tarafı platformu tarafından sağlanan uç noktalara HTTPS POST istekleri gönderir. Protected Audience, etkileşim anahtarlarını raporlama JavaScript'inde belirtilen URI'lerle eşleştirir ve raporlanan her etkileşim için her uç noktaya bir POST isteği gönderir. İsteğin Content-Type bölümü, metin kısmı Interaction Data olan düz metindir.

En iyi çaba ile etkileşim raporlama

reportInteraction(), HTTP POST üzerinden 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 verilerini günlük arka plan güncelleme süreciyle güncelleyebilir.

• Kullanıcı teklif verme sinyalleri
• Güvenilir teklif verileri
• AdData listesi

Bu işlem, özel kitlede tanımlanan günlük güncelleme URL'sine karşı sorgu oluşturur 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 nedenle, yanıttaki söz konusu alanda güncelleme yapılmaz.
• Boş bir HTTP yanıtı veya boş bir JSON nesnesi "{}" meta veri güncellemelerine neden olmaz.
• Yanıt mesajı boyutu 10 KB ile sınırlı olmalıdır.
• Tüm URI'lerin HTTPS kullanması gerekir.
• trusted_bidding_uri, alıcıyla 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ı tarafından sağlanan 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 teklif verme mantığı URL'sinden getirilir. Döndürülen JavaScript aşağıdaki işlevleri içermelidir:

• generateBid()
• reportWin()

Satıcı tarafından sağlanan JavaScript, reklam seçimi API'si için AdSelectionConfig parametresinde belirtilen karar mantığı URL'sinden getirilir. Döndürülen JavaScript aşağıdaki işlevleri içermelidir:

• scoreAd()
• reportResult()

generateBid()

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

Giriş parametreleri:

• ad: Şu biçimde bir JSON nesnesi: var ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals: Açık artırma yapılandırma nesnesinde belirtilen JSON nesneleri

• custom_audience_bidding_signals: Platform tarafından oluşturulan JSON nesnesi. Bu JSON nesnesinin biçimi şöyledir:

  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 ve name, reklam seçimine katılan özel kitleyle aynı ada sahip özelliklerden alınan dizedir.
  • activation_time ve expiration_time, özel kitlenin etkinleştirme ve geçerlilik bitiş zamanıdır. Unix sıfır zamanından itibaren saniye cinsinden ifade edilir.
  • ca_user_bidding_signals, oluşturma sırasında CustomAudience öğesinin userBiddingSignals alanında belirtilen bir JSON dizesidir.
  • trusted_bidding_signals, contextual_signals ve user_signals, JSON nesneleridir. Boş nesneler olarak iletilir 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 referans verdiği reklamdır. Komut dosyası, farklı meta verilerle aldığı reklamın bir kopyasını döndürebilir. Reklamın render_url özelliğinin değiştirilmemiş olması gerekir.
• bid: Bu reklamın teklif değerini temsil eden bir kayan nokta değeri
• status: Aşağıdaki değerleri alabilen bir tam sayı değeri:
  • 0: başarılı bir yürütme için
  • 1: Giriş sinyallerinden herhangi biri geçersizse (veya sıfır olmayan herhangi bir değer) generate-bid tarafından sıfır olmayan bir değer döndürülürse teklif verme süreci tüm CA reklamları için geçersiz kılınır.

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

Giriş parametreleri:

• ad: generateBid belgelerine bakın.
• bid: Reklamın teklif değeri

• ad_selection_config: selectAds API'sinin AdSelectionConfig parametresini temsil eden bir JSON nesnesi. Biçim:

  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 nesneleri

• trusted_scoring_signal: AdSelectionConfig API parametresindeki adSelectionSignals alanından okuma

• contextual_signals, user_signals: JSON nesneleri. Boş nesneler olarak iletilir ve gelecekteki sürümlerde doldurulur. Biçimleri platform tarafından zorunlu kılınmaz ve reklam teknolojisi tarafından yönetilir.

• per_buyer_signals: AdSelectionConfig API parametresindeki perBuyerSignal haritasından okunan JSON nesnesi. Anahtar olarak mevcut özel kitle alıcısı kullanılır. Harita, belirtilen alıcı için herhangi bir giriş içermiyorsa boş olur.

Çıkış:

• score: Bu reklamın puan değerini temsil eden bir kayan nokta değeri
• status: Aşağıdaki değerleri alabilen 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, oluşturulan istisnanın türünü belirler.

selectOutcome()

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

Giriş parametreleri:

• outcomes: JSON nesnesi {"id": id_string, "bid": bid_double}
• selection_signals: Müzayede yapılandırmasında belirtilen JSON nesneleri object

Çıkış:

• status: Başarı için 0, başarısızlık için sıfır olmayan bir değer
• result: Sonuçlardan biri iletildi 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 dokümanlarına bakın.
• render_url: Kazanan reklamın oluşturma URL'si
• bid: Kazanan reklam için verilen teklif
• contextual_signals: generateBid dokümanlarına bakın.

Çıkış:

• Başarı için status: 0, başarısızlık için sıfır olmayan bir değer
• results: Aşağıdakileri içeren bir JSON nesnesi:
  • signals_for_buyer: reportWin işlevine iletilen bir JSON nesnesi
  • reporting_url: Platform tarafından gösterimi alıcıya bildirmek için kullanılan bir 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 ile ilgili belgelere bakın.
• signals_for_buyer: reportResult tarafından döndürülen bir JSON nesnesi
• contextual_signals, custom_audience_signals: generateBid ile ilgili dokümanlara bakın.

Çıkış:

• Başarı için status: 0, başarısızlık için sıfır olmayan bir değer
• results: Aşağıdakileri içeren bir JSON nesnesi:
  • reporting_url: Platform tarafından gösterimi satıcıya bildirmek için kullanılan bir URL

registerAdBeacon()

function registerAdBeacon(
  beacons
)

Giriş Parametreleri:

• beacons: Etkileşim anahtarlarının ve raporlama URI'lerinin anahtar/değer çiftlerini içeren bir nesne. Biçim şöyledir:

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

  • interaction_key: Etkinliği temsil eden bir dize. Bu, etkinlik etkileşimlerini raporlarken platform tarafından daha sonra, hangi reporting_uri öğesinin bilgilendirilmesi gerektiğini aramak için kullanılır. Bu anahtar, alıcının veya satıcının kaydettirdiği bilgiler ile satıcının bildirdiği bilgilerle eşleşmelidir.
  • reporting_uri: Etkinlik raporlarını almak için kullanılan bir URI. Bu, bildirilen etkinlik türüne özel olmalıdır. Etkinlikle birlikte bildirilen tüm verileri işlemek için bir POST isteğini kabul etmelidir.

  Örneğin:

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

Reklam seçimi için önceden oluşturulmuş URI'ler

Önceden oluşturulmuş URI'ler, reklam teknolojilerine AdSelectionConfig ve AdSelectionFromOutcomesConfig sınıflarında reklam seçimi karar mantığı için JavaScript işlevleri atama olanağı tanır. Önceden oluşturulmuş URI'ler, ilgili JavaScript'i indirmek için ağ çağrıları gerektirmez. Reklam teknolojisi sağlayıcılar, JavaScript'i barındırmak için kayıtlı bir alan adı ayarlamadan önceden oluşturulmuş URI'leri 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, bu URI'deki bilgileri kullanarak çalışma zamanında JavaScript sağlar.

Aşağıdaki durumlarda IllegalArgumentException istisnası oluşturulur:

• Gerekli parametrelerden herhangi biri URI'de bulunmuyorsa
• URI'de tanınmayan parametreler varsa

Desteklenen önceden oluşturulmuş URI kullanım alanları ve adları

1. kullanım alanı: reklam seçimi

ad-selection kullanım alanındaki önceden oluşturulmuş URI'ler, selectAds(AdSelectionConfig) akışında desteklenir.

Önceden oluşturulmuş URI adı: highest-bid-wins

Bu önceden oluşturulmuş URI, teklif verildikten sonra en yüksek teklifi veren reklamı seçen bir JavaScript sağlar. Ayrıca, kazananın render_uri ve bid bilgilerini bildirmek için temel bir raporlama işlevi de sunar.

Gerekli parametreler

reportingUrl: Kazanan reklamın render_uri ve bid ile parametrelendirilmiş 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 şu şekilde olur:

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

2. kullanım alanı: ad-selection-from-outcomes

ad-selection-from-outcomes kullanım alanındaki önceden oluşturulmuş URI'ler, selectAds(AdSelectionFromOutcomesConfig) iş akışını destekler.

Önceden oluşturulmuş URI adı: waterfall-mediation-truncation

waterfall-mediation-truncation Önceden oluşturulmuş URI, şelale uyumlulaştırma kesme mantığını uygulayan JavaScript sağlar. Bu JavaScript, bid değeri bid floor değerinden yüksekse veya bu değere eşitse birinci taraf reklamı, aksi takdirde null değerini döndürür.

Gerekli parametreler

bidFloor: getSelectionSignals() içinde iletilen teklif taban fiyatı değerinin anahtarı uyumlulaştırma SDK'sının reklamıyla karşılaştırılır.

Kullanım

Reklam seçimi sinyalleriniz {"bid_floor": 10} gibi görünüyorsa sonuçta elde edilen önceden oluşturulmuş URI şu şekilde 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. Bu uygulamaları GitHub'da bulabilirsiniz.

Ön koşullar

Protected Audience API, reklam seçimi ve gösterim raporlama sırasında bazı JavaScript'lerin kullanılmasını 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.
• Gerekli kodu yerel bir kaynaktan sağlayarak uzaktan getirme işlemini geçersiz kılma

Her iki yaklaşım da gösterim raporlamayı işlemek için bir HTTPS uç noktası ayarlamayı gerektirir.

HTTPS uç noktaları

Reklam seçimi 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:

1. Teklif verme mantığı JavaScript'ini sunan alıcı uç noktası.
2. Teklif sinyallerini sunan bir uç nokta.
3. Karar mantığı JavaScript'ini sunan satıcı uç noktası.
4. Puanlama sinyallerini sunan bir uç nokta.
5. Kazanan alıcı gösterim raporlama uç noktası.
6. Satıcı gösterimi raporlama uç noktası.
7. Özel bir kitle için günlük güncellemeleri sunan bir uç nokta.

GitHub deposunda, kolaylık sağlaması için test amacıyla kullanılabilecek temel JavaScript kodu bulunur. Ayrıca, desteklenen bir sahte veya mikro hizmet platformuna dağıtılabilen OpenAPI hizmet tanımlarını da içerir. Daha fazla bilgi için proje README dosyasına bakın.

JavaScript'in uzaktan getirilmesini geçersiz kılma

Bu özellik, uçtan uca test için kullanılmak üzere tasarlanmıştır. Uzak getirme işlemini geçersiz kılmak için uygulamanız, geliştirici seçenekleri etkinleştirilmiş olarak hata ayıklama modunda çalışmalıdır.

Uygulamanız için hata ayıklama modunu etkinleştirmek üzere 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 bir örnek için GitHub'daki Protected Audience API örnek uygulamasına bakı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 kodu örneklerini GitHub deposunda bulabilirsiniz. Protected Audience API örnek uygulaması, bu dosyadan kodu okuma ve geçersiz kılma olarak kullanıma hazırlama yöntemini gösterir.

Satış tarafı ve satın alma tarafı JavaScript getirme işlemini bağımsız olarak geçersiz kılmak mümkündür. Ancak geçersiz kılma sağlamadığınız tüm JavaScript'leri sunmak için bir HTTPS uç noktasına ihtiyacınız vardır. Bu durumları işleyen bir sunucunun nasıl ayarlanacağı hakkında bilgi edinmek için README dosyasına bakın.

Yalnızca paketinizin sahibi olduğu özel kitleler için JavaScript getirme işlemi geçersiz kılınabilir.

Satış tarafı JavaScript'ini geçersiz kılma

Satış tarafı JavaScript'i geçersiz kılma özelliğini ayarlamak için aşağıdaki kod örneğinde gösterildiği gibi aşağıdakileri yapın:

1. Bir AdSelectionManager nesnesi başlatın.
2. AdSelectionManager nesnesinden TestAdSelectionManager için bir referans alın.
3. AdSelectionConfig nesnesi oluşturun.
4. AddAdSelectionOverrideRequest nesnesi ve geçersiz kılma olarak kullanmayı planladığınız JavaScript'i temsil eden bir String ile AdSelectionConfig oluşturun.
5. overrideAdSelectionConfigRemoteInfo() yöntemini AddAdSelectionOverrideRequest nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle birlikte eşzamansız olarak çağırın.

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

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

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

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

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

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

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

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

AdSelectionConfig bölümündeki alanların her birinin neyi temsil ettiği hakkında daha fazla bilgi için Reklam seçimi çalıştırma bölümüne bakın. Temel fark, decisionLogicUrl'nin yoksayılacağı için yer tutucu değerine ayarlanabilmesidir.

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 bir örnek için GitHub'daki Protected Audience API örnek uygulamasına bakın.

Asenkron overrideAdSelectionConfigRemoteInfo() yöntemi, API çağrısının sonucunu bildirmek için OutcomeReceiver nesnesini kullanır.

onResult() geri çağırma, geçersiz kılmanın başarıyla uygulandığını gösterir. selectAds() için gelecekteki aramalar, geçersiz kılma olarak ilettiğiniz karar ve raporlama mantığını kullanır.

onError() geri çağırması iki olası durumu gösterir:

• Geçersiz bağımsız değişkenlerle geçersiz kılma işlemi denenirse AdServiceException, IllegalArgumentException'ü neden olarak gösterir.
• Geçersiz kılma işlemi, geliştirici seçenekleri etkinleştirilmişken hata ayıklama modunda çalışmayan bir uygulamayla denenirse AdServiceException, IllegalStateException'ü neden olarak gösterir.

Satış tarafı geçersiz kılma işlemlerini sıfırlama

Bu bölümde, satıcı tarafı JavaScript'i geçersiz kıldığınız ve önceki bölümde kullanılan TestAdSelectionManager ile AdSelectionConfig için bir referansınız olduğu varsayılır.

Tüm AdSelectionConfigs için geçersiz kılmaları sıfırlamak üzere:

1. İlgili OutcomeReceiver nesnesiyle eşzamansız resetAllAdSelectionConfigRemoteOverrides() yöntemini çağırın.

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

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

Satış tarafı geçersiz kılmaları sıfırlandıktan sonra, gerekli JavaScript'i getirmeye çalışmak için AdSelectionConfig içinde depolanan selectAds() use whatever decisionLogicUrl çağrıları yapılır.

resetAllAdSelectionConfigRemoteOverrides() çağrısı başarısız olursa OutComeReceiver.onError() geri çağırma işlevi AdServiceException sağlar. Geçersiz kılmaların kaldırılması, geliştirici seçenekleri etkinleştirilmiş olarak hata ayıklama modunda çalışmayan bir uygulamayla denenirse AdServiceException, IllegalStateException nedenini gösterir.

Satın alma tarafı JavaScript'ini geçersiz kılma

1. Özel bir kitleye katılma adımlarını uygulayın.
2. Geçersiz kılmanız gereken özel kitlenin alıcısı ve adı ile birlikte, geçersiz kılma olarak kullanmak istediğiniz teklif verme mantığı ve verilerin yanı sıra bir AddCustomAudienceOverrideRequest oluşturun.
3. overrideCustomAudienceRemoteInfo() yöntemini AddCustomAudienceOverrideRequest nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle birlikte eşzamansız olarak çağırın.

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

// Join custom audience

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

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

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

// Join custom audience

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

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

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ı içeren JavaScript. Bu JavaScript'te gerekli işlev imzalarına bakın.
• trustedBiddingSignals: Reklam seçimi sırasında kullanılacak teklif sinyalleri. Bu, test amacıyla boş bir dize olabilir.

Asenkron overrideCustomAudienceRemoteInfo() yöntemi, API çağrısının sonucunu bildirmek için OutcomeReceiver nesnesini kullanır.

onResult() geri çağırma, geçersiz kılmanın başarıyla uygulandığını gösterir. selectAds() için sonraki çağrılarda, geçersiz kılma olarak ilettiğiniz teklif verme ve raporlama mantığı kullanılır.

onError() geri çağırma işlevi iki olası durumu gösterir.

• Geçersiz bağımsız değişkenlerle geçersiz kılma işlemi denenirse AdServiceException, IllegalArgumentException'ü neden olarak gösterir.
• Geçersiz kılma işlemi, geliştirici seçenekleri etkinleştirilmişken hata ayıklama modunda çalışmayan bir uygulamayla denenirse AdServiceException, IllegalStateException'ü neden olarak gösterir.

Satın alma tarafı geçersiz kılma işlemlerini sıfırlama

Bu bölümde, satın alma tarafı JavaScript'ini geçersiz kıldığınız ve önceki bölümde kullanılan TestCustomAudienceManager öğesine referansınız olduğu varsayılmaktadır.

Tüm özel kitleler için geçersiz kılmaları sıfırlamak üzere:

1. İlgili Executor ve OutcomeReceiver nesneleriyle eşzamansız resetAllCustomAudienceOverrides() yöntemini çağırın.

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

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

Satın alma tarafı geçersiz kılmaları sıfırladıktan sonra, selectAds() için yapılan sonraki çağrılar, gerekli JavaScript'i getirmeye çalışmak üzere biddingLogicUrl ve trustedBiddingData'ı kullanır.CustomAudience

resetCustomAudienceRemoteInfoOverride() çağrısı başarısız olursa OutComeReceiver.onError() geri çağırma işlevi AdServiceException sağlar. Geçersiz kılmaların kaldırılması, geliştirici seçenekleri etkinleştirilmiş olarak hata ayıklama modunda çalışmayan bir uygulamayla denenirse AdServiceException, IllegalStateException'ü neden olarak gösterir.

Raporlama sunucusu kurma

Uzaktan getirme geçersiz kılmalarını kullandığınızda, raporlama etkinliklerine yanıt vermek için cihazınızın veya emülatörünüzün ulaşabileceği bir sunucu ayarlamanız gerekir. 200 döndüren bir uç nokta, test için yeterlidir. GitHub deposunda, desteklenen bir sahte veya mikro hizmet platformuna dağıtılabilen OpenAPI hizmet tanımları bulunur. Daha fazla bilgi için proje README dosyasına bakın.

OpenAPI tanımlarını ararken reporting-server.json dosyasını bulun. Bu dosya, bir HTTP yanıt kodunu temsil eden 200 döndüren bir uç nokta içerir. Bu uç nokta selectAds() sırasında kullanılır ve gösterim raporlamasının başarıyla tamamlandığını Protected Audience API'ye bildirir.

Test edilecek işlev

• Katılma veya ayrılma alıştırması yapın ve önceki kullanıcı işlemlerine göre özel bir kitle oluşturun.
• Uzakta barındırılan JavaScript'ler aracılığıyla cihaz üzerinde reklam seçimi başlatma işlemini uygulayın.
• Bir uygulamanın özel kitle ayarlarıyla ilişkilendirilmesinin reklam seçimi sonuçlarını nasıl etkileyebileceğini gözlemleyin.
• Reklam seçildikten sonra gösterim raporlaması yapın.

Sınırlamalar

Aşağıdaki tabloda Protected Audience API işleme sınırlamaları listelenmiştir. Gösterilen sınırlar, geri bildirimlere bağlı olarak değişebilir. Devam eden özellikler için sürüm notlarını okuyun.

Hata ve sorun bildirme

Geri bildiriminiz, Android'de Özel Korumalı Alan'ın önemli bir parçasıdır. Android'de Özel Korumalı Alan'ı iyileştirmek için bulduğunuz sorunları veya fikirleri bize bildirin.