Protected Audience API geliştirici kılavuzu

Android'de Özel Korumalı Alan dokümanlarını okurken, talimatlar değişiklik gösterebileceğinden, üzerinde ç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, tanımlayıcıların uygulamalar arasında paylaşılmasını ve kullanıcının uygulama etkileşim bilgilerinin üçüncü taraflarla paylaşılmasını sınırlandıran önceki uygulama etkileşimine dayalı özel reklamlar yayınlamak için bu API'leri kullanabilir.

Custom Audience API, ortak amaçlara sahip bir kullanıcı grubunu temsil eden "özel kitle" soyutlama kavramına odaklanmıştır. Reklamverenler, bir kullanıcıyı özel kitleye kaydedebilir ve alakalı reklamları bununla 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. Sistem bunu sağlamak için özel kitleyle ilişkili reklamları dikkate alır 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ı da dahil olmak üzere ek kullanım alanlarına yönelik destek sunulması planlanmaktadır. Tasarım teklifinde, Android'deki Protected Audience API hakkında daha fazla bilgi edinebilirsiniz.

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

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

Başlamadan önce

Başlamadan önce aşağıdaki adımları tamamlayın:

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

3. Bir terminalde aşağıdaki adb komutunu kullanarak 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. Bir terminalde, aşağıdaki adb komutlarıyla işaretçi raporlamasını 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 bir ACCESS_ADSERVICES_CUSTOM_AUDIENCE izni ekleyin:

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

6. Manifest'inizin <application> öğesinde bir reklam hizmetleri yapılandırmasına başvurun:

     <property android:name="android.adservices.AD_SERVICES_CONFIG"
               android:resource="@xml/ad_services_config" />
   

7. Manifest'inizde başvurulan reklam hizmetleri XML kaynağını (ör. res/xml/ad_services_config.xml) belirtin. Reklam hizmetleri izinleri ve SDK erişim denetimi hakkında daha fazla bilgi edinin.

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

8. Varsayılan olarak Reklam Seçimi API'si, bir açık artırmanın veya gösterim raporlama komut dosyasının ayırabileceği maksimum bellek miktarı için sınırlar uygular. Bellek sınırlaması özelliği, WebView 105.0.5195.58 veya sonraki sürümünü gerektirir. Platform, sürüm kontrolü uygular ve bundan memnun kalmazsanız selectAds ve reportImpression API'lerine yapılan çağrılar başarısız olur. Bu ayarı iki şekilde yapabilirsiniz:

   • 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üme eşit veya daha yüksek olmalıdır.

Özel bir kitleye katılma

Özel kitle, reklamveren uygulaması tarafından karar verilen ortak amaçları veya ilgi alanlarını paylaşan bir kullanıcı grubunu temsil eder. Bir uygulama veya SDK, belirli bir kitleyi (ör. alışveriş sepetine ürün ekleyip alışverişi tamamlamayan kullanıcılar) belirtmek için özel kitle kullanabilir. Aşağıdaki adımları uygulayarak özel kitleleri eşzamansız olarak oluşturabilir veya bu kitlelere katılabilir:

1. CustomAudienceManager nesnesini başlatın.
2. Alıcının paketi ve alakalı bir ad gibi anahtar 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 birlikte asenkron joinCustomAudience()'ü ç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, cihazdaki her bir CustomAudience nesnesini benzersiz şekilde tanımlar:

• owner: Sahip uygulamanın paket adı. Bu ad, doğrudan arayan uygulamanın paket adına ayarlanır.
• buyer: Bu özel kitleye yönelik 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 örneğinin farklı bir örneğiyle joinCustomAudience()'ü tekrar tekrar çağırmak, mevcut tüm CustomAudience öğelerini eşleşen owner, buyer ve name parametreleriyle günceller. Gizliliğin korunmasına yardımcı olmak için API, "oluşturma" ve "güncelleme" arasında bir ayrım yapmaz.

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

• Günlük güncelleme URL'si: Özel bir kitlenin kullanıcı teklifli sistem sinyallerini, güvenilir teklifli sistem verilerini güncellemek ve reklamlar için URL'leri ve meta verileri oluşturmak amacıyla arka planda günlük olarak sorgulanan bir HTTPS URL'sidir.
• Teklif verme mantığı URL'si: 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'de gerekli işlev imzalarına bakın.
• 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 bir kitle, yalnızca etkinleştirme zamanından sonra reklam seçimine ve günlük güncellemelere katılabilir. Örneğin bu, bir uygulamayı uzun süredir kullanmayan kullanıcıların ilgisini çekmek için faydalı olabilir.
• Sona erme zamanı: Özel kitlenin cihazdan kaldırılacağı gelecekteki bir zaman.
• Kullanıcı teklif verme sinyalleri: Alıcının tercih edilen yerel ayarı gibi, alıcının teklif mantığı JavaScript'inin reklam seçim sürecinde teklif oluşturmak için kullandığı 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 tüketimi kolaylaştırır.
• Güvenilir teklif verileri: Güvenilir bir anahtar/değer hizmetinden teklif sinyalleri getiren reklam seçimi sürecinde kullanılan bir HTTPS URL'si ve dize listesi.
• Reklamlar: Reklam seçiminde yer alan reklamlara karşılık gelen AdData nesnelerinin listesi. Her AdData nesnesi şunları içerir:
  • Oluşturma URL'si: Nihai reklamı oluşturmak için sorgulanan bir HTTPS URL'si.
  • Meta veri: Reklam seçim işlemi sırasında alıcı teklif verme mantığı tarafından tüketilecek bilgileri içeren bir 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ırı için gerekli tüm bilgileri içeren bir sınıf.

CustomAudience nesnesi ö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ğırma, özel kitlenin başarıyla oluşturulduğunu veya güncellendiğini gösterir.
• onError() geri çağırması iki olası koşulu belirtir.
  • JoinCustomAudienceRequest geçersiz bağımsız değişkenlerle başlatıldıysa neden olarak AdServicesException durumu IllegalArgumentException gösterilir.
  • Diğer tüm hatalar, nedeni IllegalStateException olan bir AdServicesException alır.

Aşağıda, joinCustomAudience() sonucunun ele alınmasına dair bir örnek verilmiştir:

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 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 parametrelerine göre 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 bir kitleye katılma" başlıklı makaleyi okuyun.
3. LeaveCustomAudienceRequest nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle birlikte asenkron leaveCustomAudience() yöntemini ç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, API çağrısının sonunu gösterir. Gizliliğin korunmasına yardımcı olmak için, hata sonuçları dahili hatalar ile geçersiz bağımsız değişkenleri birbirinden ayırmaz. 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 için Protected Audience API'yi kullanmak üzere selectAds() yöntemini çağırın:

1. Bir AdSelectionManager nesnesini başlatın.
2. AdSelectionConfig nesnesi oluşturun.
3. AdSelectionConfig nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle birlikte asenkron selectAds() yöntemini ç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 bir 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ı reklam ağının JavaScript mantığını almak için sorgulanan bir HTTPS URL'sidir.
  • HTTPS URL'si: Satıcı reklam ağının JavaScript mantığını almak için sorgulandı. Gerekli işlev imzalarına bakın.
  • Önceden oluşturulmuş URI: FLEDGE'in reklam seçim biçimini izler. Desteklenmeyen veya hatalı biçimlendirilmiş bir URI iletilirse IllegalArgumentException atlanı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ının tanımlayıcılarının tam listesi. Bu alıcı tanımlayıcıları, katılan özel kitlelerin CustomAudience.getBuyer() oranına 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() konumundan 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()'den aldığı JavaScript karar mantığı tarafından kullanılan sinyalleri içeren, dize olarak serileştirilmiş bir JSON nesnesi.
• Alıcı başına sinyaller: CustomAudience.getBiddingLogicUrl()'den getirilen ve belirli alıcıların teklif verme mantığı JavaScript'i tarafından kullanılacak sinyalleri içeren, dize olarak serileştirilmiş JSON nesnelerinin haritası. Bu sinyaller, katılan özel kitlelerin alıcı alanlarıyla tanımlanır.
• İç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 bir reklam adayları koleksiyonu.

Bir reklam seçildikten sonra sonuçlar, teklifler ve sinyaller raporlama için dahili olarak devam ettirilir. OutcomeReceiver.onResult() geri çağırması, ş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 özgü bir reklam seçim 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 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, nedeni IllegalArgumentException olarak gösterir.
• Diğer tüm hatalar için IllegalStateException nedeniyle AdServicesException gösterilir.

Bağlama dayalı reklamlar

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

Uygulama içi içeriğe dayalı 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 öğenizi oluştururken 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 reklamı filtreleme, cihazda zaten yüklü olan uygulamalar için yükleme reklamlarını filtrelemenize yardımcı olur.

Bu sürecin ilk adımı, yüklü pakette filtreleme yapabilen reklamverenleri tanımlamaktır. Bu işlemin, reklamla hedeflemek istediğiniz uygulamada yapılması gerekir.

//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, 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 bilgileri kaldırılmış şekilde bu kodu tekrar çalıştırın.

Sonraki adım, yayıncı uygulamasında reklam filtrelemeyi ayarlamaktır. Yayıncı uygulamasında reklam yayınlayan taraf (muhtemelen bir tedarik tarafı SDK'sı), AdFilters nesnesini, uygulamayla ilgili hangi reklamları filtrelemek istedikleriyle ilgili 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 kitlelerinin içinde bulunan reklamlar için bir AdFilter de ayarlayabilir.

AdFilters, yeni bir AdData nesnesi örneklendirilirken 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ını sağlar. Sıklık sınırı filtreleme, reklamlara aşırı maruz kalma olasılığı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 etkinliği türü ve reklam sayacı anahtarı. Kullanılabilen reklam etkinliği türleri şunlardır:

• Kazan: Kazanma etkinliği, reklamın 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ülebilir.
• Gösterim: Cihaz üzerinde çağrı yapan (SSP veya MMP), reportImpression özelliğinden ayrı olarak, gösterim etkinliklerini seçtikleri kodda çağırmak için updateAdCounterHistogram() özelliğini 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ünüm: Etkinlik, cihazda arayan kullanıcı (SSP veya MMP) tarafından, seçtikleri kod noktasında updateAdCounterHistogram() numaralı telefona yapılan bir çağrı kullanılarak ç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, cihaz üzerinde arayan tarafından (SSP veya MMP), seçtiği kodda updateAdCounterHistogram() numaralı telefona yapılan bir çağrı kullanılarak çağrılır. Tıklama etkinlikleri, belirli bir DSP'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ı, gelecekteki açık artırmalarda kullanıcının belirli bir reklamla karşılaşma durumuyla ilgili güncel bilgilerin yer alması için artırılır. Reklam etkinliği türleri, ilgili kullanıcı işlemine zorunlu olarak bağlı değildir ve çağrıyı yapanların etkinlik sistemlerini yapılandırmasına yardımcı olmak için verilen yönergelerdir. Cihaz üzerindeki aktör, bir etkinlik sırasında reklam sayıcılarını artırmak için kazanan reklam açık artırmasının reklam seçim kimliğini sağlar.

Reklam sayacı anahtarları, bir alıcı reklam teknolojisi tarafından atanan rastgele 32 bitlik işaretli tam sayılardır ve DSP tarafından tanımlanan belirli bir reklam grubuna karşılık gelir. Reklam sayıcı anahtarları yalnızca belirli bir DSP'ye ait reklamlarla sınırlı olduğundan bu anahtarlar, başka bir reklam teknolojisindeki histogramlerle çakışma olmadan seçilebilir. Reklam sayıcı anahtarları, DSP'ye özgü tanımlayıcıları bir DSP'nin reklamlarında veya gelecekteki açık artırmalardaki reklamları filtrelemek için belirli bir özel kitle içinde artırmak için kullanılır.

Sayaç anahtarları, belirli bir alıcı reklam teknolojisinden gelen diğer reklamlarla etkileşimine 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ından, görüntülemelerden 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 için: sol elini kullananlara yönelik golf sopaları reklamı, kullanıcının sağ elini kullananlara yönelik sopalarla ilgilenmediğini gösterebilir. Sol elini kullananlara 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ırlamasını kullanmak için önce aşağıda gösterildiği gibi 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 geçirilebilir:

// 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ı filtresi sınırlarını aşan reklamlar açık artırmadan filtrelenir. Filtreleme, cihaz üzerinde açık artırmalar için teklif verme mantığı uygulanmadan önce ve teklif verme ve açık artırma hizmetleri açık artırmaları için yükü oluştururken gerçekleşir. Bu araç seti, reklam teknolojisi uzmanlarına reklamların aşırı gösterilmesini en aza indirirken reklam hedeflemeye odaklanmak için kullanıcılar ile özel kitlelerindeki reklamlar arasındaki etkileşimleri kullanma esnekliği sunar.

Ağ çağrıları olmadan içeriğe dayalı reklam filtreleme

Cihazda yeniden pazarlama talebi yoksa ağ çağrıları içermeyen içeriğe dayalı reklamlar için reklam seçimi yayınlayabilirsiniz. Platform, önceden oluşturulmuş URI'ler ve teklif içeren bağlamsal reklamların listesiyle teklif verme mantığını, teklif sinyallerini ve puanlama sinyallerini almayı 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 azaltmak için ağ çağrıları olmadan yalnızca reklam filtreleme işlevine sahip bağlama dayalı reklamlar içeren bir reklam seçimi akışı yayınlayabilir. Bu özellik, puanlama sinyalleri için önceden oluşturulmuş URI'lar kullanılarak gerçekleştirilir. scoreAdsuygulamaları 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:

1. Reklam filtrelemeyi ayarlama
2. İçeriğe dayalı reklamlarınızı oluşturma

3. Aşağıdakileri 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çimini çalıştır:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

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

Günümüzde Özel Korumalı Alan platformunda, önceden oluşturulmuş URI'ler için yalnızca temel raporlama JavaScript uygulaması mevcuttur. Düşük gecikmeli bir 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'lar kullanarak içeriğe dayalı reklamlar için reklam seçimi çalıştırmaya yönelik adımları çalıştırın

2. Raporlama işlemini çalıştırmadan önce AdSelectionConfig'ünüzün bir kopyasını oluşturun

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

3. Gösterim raporları ç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ır

Şelale uyumlulaştırması, birden fazla üçüncü taraf SDK'nın (3. taraf ağlar) 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 hizmetlerinde (B&A) gerçekleşip gerçekleşmediğine bakılmadan aynı şekilde yapılır.

3. taraf ağlar

3. taraf ağların, uyumlulaştırma ağının açık artırma yürütmek için gerekli yöntemleri çağırmasına olanak tanıyan bir bağdaştırıcı sağlaması gerekir:

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

Uyumlulaştırma ağı bağdaştırıcısı örneğini aşağıda görebilirsiniz:

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 hizmet yöneticileri ve müşterileri, kendi selectAds ve reportImpressions uygulaması vardır. SDK sağlayıcılar, cihaz üzerinde açık artırmalar için reklam seçiminin nasıl yayınlanacağı ile ilgili bölümlere veya B&A açık artırmaları için B&A açıklayıcısına bakabilir. Reklam gösterimlerinin nasıl raporlanacağını uygulayın (raporlama için tek STP gösterimi raporlamasından yararlanın).

Uyumlulaştırma ağı

Üçüncü taraf ağlara benzer şekilde, uyumlulaştırma ağlarının selectAds ve reportImpression uygulamalarının olması gerekir. Daha fazla bilgi için reklam seçimini ve reklam gösterimlerini raporlamayı anlatan 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. Bir sonraki bölümde bu sürecin nasıl kurulacağı ve yürütüleceği ele alınmaktadır.

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

Birinci taraf (1. taraf) bağlama dayalı reklamları, uyumlulaştırma zincirini ve üçüncü taraf ağların teklif tabanlarını (3. taraf) almak uyumlulaştırma ağının sorumluluğundadır. 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ında nasıl iterasyon yapılacağını belirler ve teklif tabanları açık artırma sürecine adSelectionSignals olarak iletilebilir.

Uyumlulaştırma zincirinde ağ yerleşimi

Uyumlulaştırma SDK'sı, birinci taraf reklam tekliflerinin etkin eBGBM'sine göre kendisini uyumlulaştırma zincirine yerleştirebilir. Protected Audience API'de reklam teklifleri opaktır. Belirli bir birinci taraf reklamının teklifini zincirdeki bir sonraki 3. taraf ağın teklif tabanıyla karşılaştırabilmek için uyumlulaştırma SDK'sı AdSelectionFromOutcomesConfig kullanmalıdır. Birinci taraf teklifi, teklif tabanından yüksekse uyumlulaştırma SDK'sı söz konusu 3. taraf ağın önüne yerleştirilir.

Reklam seçimini yayınla

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

AdSelectionFromOutcomesConfig oluşturma

AdSelectionFromOutcomesConfig, uyumlulaştırma ağının AdSelectionIds (önceki açık artırmalardan elde edilen sonuçlar) listesi, reklam seçimi sinyalleri ve birden fazla aday arasından reklam seçen JavaScript'i almak için bir URI iletmesine olanak tanır. AdSelectionId'lerin listesi, teklifleri ve sinyalleriyle birlikte JavaScript'e iletilir. JavaScript, teklif tabanını geçerse AdSelectionIds özelliklerinden birini, uyumlulaştırma zincirinin devam etmesi durumunda ise hiçbirini döndürmeyebilir.

Uyumlulaştırma ağları, önceki bölümdeki birinci taraf AdSelectionId'ı ve üçüncü taraf ağının teklif tabanını dikkate alarak 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 uyumlulaştırması için selectAds() yöntemini geçersiz kılma işlemi, aşağıdaki gerekli parametreleri belirtmeniz gereken bir 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 tekli 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, belirli bir üçüncü taraf ağı için alınan teklif taban fiyatını ekleyin.
• Seçim mantığı URI'si: Kazanan bir reklamın seçilmesi amacıyla uyumlulaştırma ağının JavaScript'ini getirmek için 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 üçüncü taraf reklamını, aksi takdirde null değerini döndürmelidir. Bu sayede uyumlulaştırma SDK'sı, bir kazanan bulunduğunda uyumlulaştırma zincirini kısaltabilir.

Oluşturulan AdSelectionOutcomesConfig ile zincirde ilk olan üçüncü 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, uyumlulaştırma sürecinde yapılacak işlem sırası verilmiştir.

1. Birinci taraf reklam seçimini çalıştırın.
2. Uyumlulaştırma zincirinde yineleme yapın. Her bir 3. taraf ağ için aşağıdakileri yapın:
   1. 1. taraf outcomeId ve 3. taraf SDK'sının teklif tabanı dahil olmak üzere AdSelectionFromOutcomeConfig oluşturun.
   2. Önceki adımdaki yapılandırmayı kullanarak selectAds() öğesini çağırın.
   3. Sonuç boş değilse reklamı döndürün.
   4. Geçerli SDK ağ bağdaştırıcının selectAds() yöntemini çağırın. Sonuç boş değilse reklamı döndürün.
3. Zincirde kazanan bulunamazsa birinci taraf reklamı 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 bildirme

Açık artırmanın nasıl yürütüldüğüne bağlı olarak bir reklam gösterimini raporlamak için iki akış vardır. Açık artırma çalıştıran tek bir SSP'yseniz bu bölümü uygulayın. Şelale uyumlulaştırmasını uygulayacaksanız şelale uyumlulaştırması gösterim raporlama bölümünde bulunan adımları izleyin.

Tek STP gösterimi raporlama

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

1. Bir AdSelectionManager nesnesini başlatın.
2. Reklam seçim kimliğiyle bir ReportImpressionRequest nesnesi oluşturun.
3. ReportImpressionRequest nesnesi ve ilgili Executor ile OutcomeReceiver nesneleriyle eşzamansız reportImpression() yöntemini ç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 hizmetini aşağıdaki gerekli parametrelerle başlatın:

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

Asenkron reportImpression() yöntemi, API çağrısının sonucunu bildirmek 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ı gösterir.
• onError() geri çağırması, aşağıdaki olası koşulları belirtir:
  • Çağrı geçersiz bir giriş bağımsız değişkeniyle başlatılırsa AdServicesException, neden olarak IllegalArgumentException değerini gösterir.
  • Diğer tüm hatalar için IllegalStateException nedeniyle AdServicesException gösterilir.

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

Bir arabuluculuk SDK'sının, raporlama akışlarını tetiklemek için kazanan SDK'yı takip etmesi gerekir. Uyumlulaştırma zincirinde yer alan SDK'lar, arabulucunun kendi raporlama akışlarını tetiklemek üzere ç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, uyumlulaştırma akışlarına nasıl katılacaklarına dair bir prototip olarak bu üçüncü taraf SDK kod örneğini 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ım tarafı platform tarafından sağlanan uç noktalara HTTPS GET istekleri gönderir:

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

• API, gösterim raporlama URL'si döndürmek için mantık içeren, alıcı tarafından sağlanan JavaScript'i almak üzere ö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 almak 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.

Teklifli sistem ve açık artırma hizmetlerini raporlama

Teklif ve Açık Artırma hizmetlerinde yürütülen bir açık artırma, sunucu tarafı açık artırmadan gelen şifrelenmiş yanıta dahil edilen reklam etkileşimi raporlaması için oluşturulan URL'ler de dahil olmak üzere gerekli tüm raporlama bilgilerini içerir. Yanıtın şifresi çözüldüğünde uygun URL'ler platforma kaydedilir. Böylece reklam ve gösterim raporlamasında yukarıda listelenen adımlar izlenir.

En iyi çabayla gösterim raporlama

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 reklam için daha ayrıntılı etkileşimler hakkında rapor oluşturma desteği sağlar. Görüntüleme süresi, tıklama, fareyle üzerine gelme gibi etkileşimler veya toplanabilecek diğer yararlı metrikler buna dahildir. Bu raporları alma işlemi iki adımdan oluşur. Öncelikle alıcılar ve satıcılar, bu raporları raporlama JavaScript'lerinde almak için kaydolmalıdır. Daha sonra istemcinin bu etkinlikleri bildirmesi gerekir.

Etkileşim etkinlikleri almak için kaydolun

Etkileşim etkinliklerine kaydolma işlemi, 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 istiyorsanız raporlama JavaScript'inizden platform JavaScript işlevini çağırmanız yeterlidir. Aşağıdaki snippet bir 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, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

Etkileşim etkinliklerini raporlama

Bir gösterim bildirildikten sonra müşteriler, etkileşimleri AdSelectionManager.reportInteraction() yöntemiyle daha önce kayıtlı olan alıcı ve satış tarafı platformlarına geri bildirebilir. Reklam etkinliğini bildirmek için:

1. Bir AdSelectionManager nesnesini ilk kullanıma hazırlayın.
2. Reklam seçim kimliği, etkileşim anahtarı, etkileşim verileri ve raporlama hedefiyle bir ReportInteractionRequest nesnesi oluşturun.
3. request nesnesi ve ilgili Executor ile OutcomeReceiver nesneleriyle eşzamansız reportInteraction() yöntemini ç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 hizmetini aşağıdaki gerekli 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, müşteri 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 bir bit maskesi. Bu işaretler platform tarafından sağlanır ve son hedef maskesi bit tabanlı işlemler kullanılarak oluşturulabilir. Bir hedefe rapor göndermek için doğrudan platform tarafından sağlanan işareti kullanabilirsiniz. Birden fazla hedefe rapor göndermek için işaret değerlerini birleştirmek üzere bitsel VEYA (|) operatörünü kullanabilirsiniz.

Asenkron reportInteraction() yöntemi, API çağrısının sonucunu bildirmek 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ğırma işlevi, aşağıdaki olası koşulları gösterir:
  • Çağrı, uygulama arka planda çalışırken yapılırsa hatanın açıklamasını içeren bir IllegalStateException döndürülür.
  • İstemci reportInteraction() çağrısı yapmaktan kısıtlanmışsa bir LimitExceededException döndürülür.
  • Paket, Gizliliği Koruma API'lerini çağırmak için kaydedilmemişse bir SecurityException() döndürülür.
  • Uygulama raporlama etkileşimleri selectAds() adlı uygulamadan farklıysa bir IllegalStateException döndürülür.
• Kullanıcı, Özel Korumalı Alan API'lerinin etkinleştirilmesine izin vermezse çağrı, sessiz bir şekilde başarısız olur.

Etkileşim raporlama uç noktaları

Rapor etkileşimi API'si, satış tarafı platformu ve kazanan alıcı tarafı platformu tarafından sağlanan uç noktalara HTTPS POST istekleri gönderir. Protected Audience, etkileşim anahtarlarını raporlama JavaScript'inde tanımlanan URI'lerle eşleştirir ve raporlanan her etkileşim için her uç noktaya bir POST isteği gönderir. İsteğin içerik türü düz metindir. Gövde ise Etkileşim Verileri'dir.

En iyi sonuç etkileşim raporlaması

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, günlük arka plan güncelleme işlemiyle aşağıdaki özel kitle meta verilerini 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'sine göre sorgu oluşturur ve URL bir JSON yanıtı döndürebilir.

• JSON yanıtı, güncellenmesi gereken desteklenen meta veri alanlarının herhangi birini içerebilir.
• Her JSON alanı bağımsız olarak doğrulanır. Müşteri, hatalı biçimlendirilmiş alanları yoksayar. Bu da yanıtta söz konusu alanda güncelleme yapılmamasına neden olur.
• Boş bir HTTP yanıtı veya boş JSON nesnesi "{}", meta veri güncellemesiyle sonuçlanmaz.
• Yanıt mesajı boyutu 10 KB ile sınırlı olmalıdır.
• Tüm URI'ların HTTPS kullanması gerekir.
• 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 Teklif verme mantığı URL'sinden alınır. 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: var ad = { 'render_url': url, 'metadata': json_metadata }; biçiminde bir JSON nesnesi
• auction_signals, per_buyer_signals: Açık artırma yapılandırması nesnesinde belirtilen JSON nesneleri

• custom_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 ve name, reklam seçimine katılan Özel Kitle ile aynı ada sahip mülklerden alınan bir dizedir
  • activation_time ve expiration_time, özel kitlenin etkinleşme ve geçerlilik bitiş zamanıdır ve Unix sıfır zamanından itibaren saniye cinsinden ifade edilir.
  • ca_user_bidding_signals, CustomAudience öğesinin oluşturulma zamanında userBiddingSignals alanında belirtilen bir JSON dizesidir.
  • trusted_bidding_signals, contextual_signals ve user_signals JSON nesneleridir. Bunlar boş nesneler olarak iletilir ve gelecekteki sürümlerde doldurulur. Biçimlerinin platform tarafından zorunlu kılınmaması ve reklam teknolojisi tarafından yönetilmesi

Sonuç:

• ad: Teklifin ilişkili olduğu reklamdır. Komut dosyasının, aldığı reklamın farklı meta verileriyle bir kopyasını döndürmesine izin verilir. Reklamın render_url özelliğinin değiştirilmemesi beklenir.
• bid: Bu reklamın teklif değerini temsil eden kayan noktalı değer
• status: Aşağıdaki gibi olabilecek 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 işlemi 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 belgelerini göster
• bid: reklamın teklif değeri

• ad_selection_config: selectAds API'nin AdSelectionConfig parametresini temsil eden bir JSON nesnesi. Biçim şu şekildedir:

  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: sellerSignalsAdSelectionConfig API parametresinden okunan JSON nesneleri

• trusted_scoring_signal: AdSelectionConfig API parametresindeki adSelectionSignals alanından okuma

• contextual_signals, user_signals: JSON nesneleri. Şu anda boş nesneler olarak iletiliyorlar ve gelecekteki sürümlerde doldurulacak. 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ını anahtar olarak kullanarak AdSelectionConfig API parametresindeki perBuyerSignal haritasından okunan JSON nesnesi. Harita, belirli bir alıcı için herhangi bir giriş içermiyorsa boş bırakılır.

Çıkış:

• score: Bu reklamın puan değerini temsil eden kayan nokta değeri
• status: Aşağıdaki gibi 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 biri geçersizse
  • Sıfır olmayan tüm değerler işlemin başarısız olmasına neden olur. Değer, oluşturulan istisna türünü belirler.

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ı için 0, başarısızlık için sıfır değerli
• result: İletilen 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ın
• render_url: kazanan reklamın oluşturma URL'si
• bid: kazanan reklam için sunulan teklif
• contextual_signals: generateBid dokümanlarına bakın

Çıkış:

• Başarılı işlemler için status: 0, başarısız işlemler için sıfır olmayan bir değer
• results: Şunları içeren bir JSON nesnesi:
  • signals_for_buyer: reportWin işlevine iletilen bir JSON nesnesi
  • reporting_url: Gösterimi alıcıya bildirmek için platform tarafından 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 belgelerini inceleyin
• signals_for_buyer: reportResult tarafından döndürülen bir JSON nesnesi
• contextual_signals, custom_audience_signals: generateBid ile ilgili dokümanları inceleyin

Çıkış:

• Başarı için status: 0, başarısızlık için sıfır olmamalıdır
• results: Şunları içeren bir JSON nesnesi:
  • reporting_url: Gösterimi satıcıya bildirmek için platform tarafından 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 şu şekildedir:

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

  • interaction_key: Etkinliği temsil eden bir dize. Bu, platform tarafından daha sonra etkinlik etkileşimlerini raporlarken, bilgilendirilmesi gereken reporting_uri öğesini aramak için kullanılır. Bu anahtarın, alıcının veya satıcının kaydettikleri ile satıcının bildirdikleri arasında tutarlı olması gerekir.
  • reporting_uri: Etkinlik raporlarını almak için bir URI. Bu, raporlanan etkinlik türüne özel olmalıdır. Etkinlikle birlikte raporlanan 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 önceden oluşturulmuş URI'leri

Önceden oluşturulmuş URI'ler, reklam teknolojisi uzmanlarına AdSelectionConfig ve AdSelectionFromOutcomesConfig sınıflarında reklam seçimi karar mantığı için JavaScript işlevleri atama olanağı sunar. Önceden oluşturulmuş URI'ler, ilgili JavaScript'i indirmek için ağ çağrıları gerektirmez. Reklam teknolojileri, JavaScript'i barındırmak için kayıtlı bir alan adı oluşturmak zorunda kalmadan önceden oluşturulmuş URI'leri kullanabilir.

Önceden oluşturulmuş URI'ler 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 verilir:

• gerekli parametrelerden hiçbiri URI'de yok
• URI'de tanınmayan parametreler var

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

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

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

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

Önceden oluşturulmuş bu URI, teklif verildikten sonra en yüksek teklife sahip 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 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ı: arama-sonuçlarından-reklam-seçimi

ad-selection-from-outcomes kullanım alanı altında bulunan ö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ırması kesme mantığını uygulayan JavaScript'i sağlar. bid, bid floor değerinden daha yüksek veya ona eşitse JavaScript bir birinci taraf reklamı döndürür ve aksi halde null değerini döndürür.

Gerekli parametreler

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

Kullanım

Reklam seçim sinyalleriniz {"bid_floor": 10} gibi görünüyorsa oluşturulan önceden derlenmiş 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 için örnek uygulamalar oluşturduk. Bu uygulamaları GitHub'da bulabilirsiniz.

Ön koşullar

Protected Audience API, reklam seçimi ve gösterim raporlaması sırasında bazı JavaScript'i 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 getirme işlemini geçersiz kılma

Her iki yaklaşım da gösterim raporlamasını işlemek için HTTPS uç noktası 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:

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

GitHub deposu, kolaylık sağlamak amacıyla test amaçlı temel JavaScript kodu sağlar. Ayrıca, desteklenen bir örnek veya mikro hizmetler platformuna dağıtılabilen OpenAPI hizmet tanımlarını da içerir. Daha fazla bilgi için projenin README dosyasını inceleyin.

JavaScript'in uzaktan getirilmesini geçersiz kıl

Bu özellik, uçtan uca testler için kullanılmak üzere tasarlanmıştır. Uzak 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 aşağıdaki satırı AndroidManifest.xml dosyanızdaki uygulama özelliğine ekleyin:

<application
  android:debuggable="true">

Bu geçersiz kılmaların nasıl kullanılacağıyla ilgili örnek için GitHub'daki Protected Audience API örnek uygulamasına göz atın.

Teklif verme, puanlama kararları ve raporlama gibi reklam seçim rutinlerini yönetmek 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ı, ilgili dosyadan kodun nasıl okunacağını ve geçersiz kılma olarak nasıl hazırlanacağını gösterir.

Satış tarafı ve alıcı tarafı JavaScript getirmesini bağımsız olarak geçersiz kılmak mümkündür. Ancak, geçersiz kılma işlemleri sağlamadığınız JavaScript'leri sunmak için bir HTTPS uç noktasına ihtiyacınız vardır. Bu tür durumlarda işleyen bir sunucunun nasıl kurulacağıyla ilgili bilgi edinmek için lütfen README bölümüne bakın.

JavaScript getirmeyi yalnızca paketinize ait olan özel kitleler için geçersiz kılmak mümkündür.

Satıcı tarafı JavaScript'i geçersiz kılma

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

1. Bir AdSelectionManager nesnesini ilk kullanıma hazırlayın.
2. AdSelectionManager nesnesinden TestAdSelectionManager referansı alın.
3. AdSelectionConfig nesnesi oluşturun.
4. AdSelectionConfig nesnesiyle bir AddAdSelectionOverrideRequest ve geçersiz kılma olarak kullanmak istediğiniz JavaScript'i temsil eden bir String oluşturun.
5. AddAdSelectionOverrideRequest nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle birlikte asenkron overrideAdSelectionConfigRemoteInfo() yöntemini ç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 içindeki her bir alanın neyi temsil ettiği hakkında daha fazla bilgi için Reklam seçimini yayınlama bölümüne bakın. Temel fark, decisionLogicUrl öğesinin yoksayı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. Bir JavaScript dosyasının nasıl dize olarak okunacağına dair örnek için lütfen GitHub'daki Protected Audience API örnek uygulamasına bakın.

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

onResult() geri çağırması, geçersiz kılmanın başarıyla uygulandığını belirtir. selectAds() için gelecekteki çağrılarda, geçersiz kılma olarak ilettiğiniz karar ve raporlama mantığı kullanılır.

onError() geri çağırma, iki olası durumu belirtir:

• Geçersiz kılma işlemi, geçersiz bağımsız değişkenlerle yapılmaya çalışılırsa AdServiceException, neden olarak bir IllegalArgumentException belirtir.
• Geçersiz kılma işlemi, geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulamayla yapılırsa AdServiceException hatanın nedeni olarak IllegalStateException değerini gösterir.

Satıcı 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 ve AdSelectionConfig referanslarına sahip olduğunuz varsayılmaktadır.

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

1. İlgili OutcomeReceiver nesnesi ile asenkron 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ılma işlemlerini sıfırladıktan sonra selectAds() çağrıları, gerekli JavaScript'i getirmeye çalışmak için AdSelectionConfig içinde depolanan decisionLogicUrl değerini 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 uygulamada geçersiz kılmalar kaldırılmaya çalışılırsa AdServiceException bunun nedeni olarak IllegalStateException gösterilir.

Alıcı tarafı JavaScript'i geçersiz kılma

1. Özel bir kitleye katılma adımlarını uygulayın.
2. Geçersiz kılmak istediğiniz özel kitlenin alıcısını ve adını, ayrıca geçersiz kılma olarak kullanmak istediğiniz teklif verme mantığını ve verilerini içeren bir AddCustomAudienceOverrideRequest oluşturun
3. AddCustomAudienceOverrideRequest nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle birlikte asenkron overrideCustomAudienceRemoteInfo() yöntemini ç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ılanlarla aynıdır. Bu alanlar hakkında daha fazla bilgi edinin.

Buna ek olarak, 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 değer 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ğırması, geçersiz kılmanın başarıyla uygulandığını belirtir. selectAds() için yapılan sonraki çağrılar, geçersiz kılma olarak ilettiğiniz teklif verme ve raporlama mantığını kullanır.

onError() geri çağırma, iki olası durumu belirtir.

• Geçersiz bağımsız değişkenlerle geçersiz kılma işlemine çalışılırsa AdServiceException, neden olarak IllegalArgumentException değerini gösterir.
• Geçersiz kılma işlemi, geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulamada denenirse AdServiceException, nedeni IllegalStateException olarak gösterir.

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

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 bir referansınızın olduğu varsayılmıştır.

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

1. Alakalı 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)

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. Geçersiz kılma işlemi, geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulamada yapılmaya çalışılırsa AdServiceException, nedeni IllegalStateException olarak gösterir.

Raporlama Sunucusu Kurma

Uzaktan getirme geçersiz kılmaları kullandığınızda yine de cihazınızın veya emülatörünüzün raporlama etkinliklerine yanıt vermek için erişebileceği bir sunucu ayarlamanız gerekir. Test için 200 döndüren basit bir uç nokta yeterlidir. GitHub deposu, desteklenen bir örnek veya mikro hizmet platformuna dağıtılabilen OpenAPI hizmet tanımları içerir. Daha fazla bilgi için projenin README dosyasını inceleyin.

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() sırasında kullanılır ve Protected Audience API'ye gösterim raporlamasının başarıyla tamamlandığını bildirir.

Test edilecek işlevsellik

• Önceki kullanıcı işlemlerine göre özel bir kitleye katılma veya kitleden ayrılma ve özel kitle oluşturma alıştırması yapın.
• Uzaktan barındırılan JavaScript'ler aracılığıyla cihaz üzerinde reklam seçiminin başlatılmasını uygulayın.
• Bir uygulamanın özel kitle ayarlarıyla ilişkisinin reklam seçimi sonuçlarını nasıl etkileyebileceğini gözlemleyin.
• Reklam seçiminin ardından gösterim raporlamasını kullanın.

Sınırlamalar

Aşağıdaki tabloda, Protected Audience API işlemeyle ilgili sınırlamalar listelenmiştir. Sunulan sınırlar geri bildirime göre değiştirilebilir. Devam eden özellikler için sürüm notlarını okuyun.

Hataları ve sorunları bildirin

Geri bildiriminiz, Android'de Özel Korumalı Alan'ın önemli bir parçasıdır. Karşılaştığınız sorunları veya Android'deki Özel Korumalı Alan'ı iyileştirmeye yönelik fikirlerinizi bizimle paylaşın.