Android'de Protected Audience API geliştirici kılavuzu

Geliştirici Önizlemesi Beta

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

---

Geri bildirim gönderin

Android'deki Protected Audience API (eski adıyla FLEDGE), Özel Kitle API'sini ve Reklam Seçimi API'sini içerir. Reklam teknolojisi platformları ve reklamverenler bu API'leri kullanarak önceki uygulama etkileşimlerine dayalı olarak, uygulamalar arasında tanımlayıcıların paylaşımını sınırlandıran ve kullanıcının uygulama etkileşimi bilgilerinin üçüncü taraflarla paylaşımını sınırlandıran özel reklamlar yayınlayabilir.

Özel Kitle API'si, ortak amaçları olan bir kullanıcı grubunu temsil eden "özel kitle" soyutlamasının merkezindedir. Bir reklamveren, bir kullanıcıyı özel bir kitleye kaydedebilir ve alakalı reklamları bu kitleyle ilişkilendirebilir. Bu bilgiler yerel olarak depolanır ve reklamveren teklifleri, reklam filtreleme ve reklam oluşturma konuları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 çalıştırmasına olanak tanıyan bir çerçeve sağlar. Sistem, bunu başarmak için özel kitleyle ilişkili reklamları değerlendirir ve 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ı için destek verilmesi planlanmaktadır. Tasarım teklifinde Android'de Protected Audience API hakkında daha fazla bilgi edinebilirsiniz.

Bu kılavuzda, aşağıdaki işlemleri gerçekleştirmek için Android'de Protected Audience API ile nasıl çalışabileceğiniz açıklanmaktadır:

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 görüntüsü yükleyin veya Android'de Özel Korumalı Alan desteği içeren bir emülatör kurun.

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

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. Uygulama manifestinize bir ACCESS_ADSERVICES_CUSTOM_AUDIENCE izni ekleyin:

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

5. Manifest'inizin <application> öğesindeki bir reklam hizmetleri yapılandırmasına referans verin:

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

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

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

7. Varsayılan olarak Reklam Seçimi API'si, bir açık artırma veya gösterim raporlama komut dosyasının ayırabileceği maksimum bellek miktarı için sınırlar uygular. Bellek sınırlama özelliği, WebView'un 105.0.5195.58 veya sonraki bir sürümünü gerektirir. Platform, sürüm kontrolünü zorunlu kılar ve istek yerine getirilmezse selectAds ve reportImpression API'lerine yapılan çağrılar başarısız olur. Bunu iki farklı şekilde ayarlayabilirsiniz:

   • 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 bundan daha yüksek olmalıdır.

Özel bir kitleye katılın

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

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. Eşzamansız joinCustomAudience() öğesini, JoinCustomAudienceRequest nesnesi ve alakalı Executor ile OutcomeReceiver nesneleriyle çağırın.

Kotlin

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

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

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

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

Java

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

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

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

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

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

• owner: Sahip uygulamanın paket adı. Bu, dolaylı olarak arayan uygulamanın paket adı olarak ayarlanır.
• buyer: Bu özel kitle için reklamları yöneten alıcı reklam ağının tanımlayıcısı.
• name: Özel kitle için rastgele bir ad veya tanımlayıcı.

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

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

• Günlük güncelleme URL'si: Özel bir kitlenin kullanıcı teklif sinyallerini ve güvenilir teklif verilerini güncellemek için arka planda her gün sorgulanan HTTPS URL'si, ayrıca reklamlara ait URL'ler ve meta veriler oluşturulur.
• Teklif 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'te gereken 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.

Bir CustomAudience nesnesi için isteğe bağlı parametreler aşağıdakileri içerebilir:

• Etkinleştirme zamanı: Özel bir kitle, reklam seçimine ve günlük güncellemelere yalnızca etkinleştirme zamanından sonra katılabilir. Bu, örneğin bir uygulamanın eski kullanıcılarıyla etkileşim kurmak için yararlı olabilir.
• Son kullanma zamanı: Özel kitlenin cihazdan kaldırılacağı gelecekteki bir zaman.
• Kullanıcı teklif verme sinyalleri: Bir alıcının teklif mantığı JavaScript'inin reklam seçim süreci sırasında teklif oluşturmak için kullandığı, kullanıcının tercih ettiği yerel ayar gibi kullanıcı sinyallerini içeren bir JSON dizesidir. 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 verme verileri: Bir HTTPS URL'si ve reklam seçim sürecinde kullanılan ve güvenilir bir Anahtar/Değer hizmetinden teklif sinyalleri getiren dizelerin listesi.
• 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ı oluşturmak için sorgulanan bir HTTPS URL'si.
  • Meta veri: Reklam seçim süreci sırasında alıcı teklif verme mantığı tarafından kullanılacak bilgileri içeren bir dize olarak serilenmiş 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.

Not: "Kullanıcı teklif sinyalleri", "Güvenilir teklif verileri" ve "Reklamlar" özelliklerinin değerleri toplam 10 KB'ı aşmamalıdır. Özel bir kitlenin reklam seçimine katılabilmesi için bu 3 alanın doldurulması gerekir.

Aşağıda, bir CustomAudience nesne örneklendirmesi örneği verilmiştir:

Kotlin

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

Java

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

addCustomAudience() sonuçlarını ele alma

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

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

joinCustomAudience() sonucunun ele alındığı bir örnek aşağıda verilmiştir:

Kotlin

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

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

Java

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

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

Özel bir kitleden ayrılma

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

1. CustomAudienceManager nesnesini başlatın.
2. LeaveCustomAudienceRequest öğesini özel kitlenin buyer ve name ayarlarıyla başlatın. Bu giriş alanları hakkında daha fazla bilgi edinmek için "Özel bir kitleye katılma" bölümünü okuyun.
3. Eşzamansız leaveCustomAudience() yöntemini LeaveCustomAudienceRequest nesnesi ve ilgili Executor ile OutcomeReceiver nesneleriyle çağırın.

Kotlin

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

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

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

Java

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

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

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

joinCustomAudience() çağrısına benzer şekilde, OutcomeReceiver de bir API çağrısının sonunu işaret eder. Gizliliğin korunmasına yardımcı olmak amacıyla, hata sonucu, dahili hatalar ile geçersiz bağımsız değişkenler arasında ayrım yapmaz. Eşleşen bir özel kitlenin başarıyla kaldırılıp kaldırılmadığına bakılmaksızın, API çağrısı tamamlandığında onResult() geri çağırması çağrılır.

Reklam seçimini yayınla

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

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

Kotlin

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

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

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

Java

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

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

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

selectAds() yöntemi, aşağıdaki gerekli parametreleri belirtmeniz gereken bir AdSelectionConfig girişi gerektirir:

• Satıcı: Reklam seçimini başlatan satıcı reklam ağının tanımlayıcısı.
• Karar mantığı URL'si: Satıcı reklam ağının JavaScript mantığını almak için sorgulanan bir HTTPS URL'si.
  • HTTPS URL'si: Satıcı reklam ağının JavaScript mantığını almak için sorgulanmıştır. Gerekli işlev imzalarını inceleyin.
  • Önceden oluşturulmuş URI: FLEDGE'in reklam seçimi biçimini takip eder. Desteklenmeyen veya hatalı oluşturulmuş önceden oluşturulmuş bir URI aktarılırsa IllegalArgumentException hatası verilir.
• Özel kitle alıcıları: Satıcının reklam seçim sürecine katılmasına izin verilen alıcı reklam ağları için tanımlayıcıların tam listesi. Bu alıcı tanımlayıcıları, katılan özel kitlelerin CustomAudience.getBuyer() oranına karşılık geliyor.

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 nesnesidir.
• Satıcı sinyalleri: Dize olarak serileştirilmiş, satıcının AdSelectionConfig.getDecisionLogicUrl() kaynağından getirilen JavaScript karar mantığı tarafından tüketilen sinyalleri içeren bir JSON nesnesi.
• Alıcı başına sinyaller: Belirli alıcıların CustomAudience.getBiddingLogicUrl() adresinden getirilen ve katılımcı özel kitlelerin alıcı alanları tarafından tanımlanan teklif mantığı JavaScript'i tarafından kullanılacak sinyalleri içeren, dize olarak serilenmiş JSON nesnelerinin haritası.
• İçeriğe dayalı reklamlar: Korunan Kitle açık artırmasının dışında gerçekleşen bir açık artırma sırasında doğrudan alıcılardan toplanan reklam adayları koleksiyonu.

Bir reklam seçildikten sonra sonuçlar, teklifler ve sinyaller raporlama için dahili olarak saklanır. OutcomeReceiver.onResult() geri çağırması, aşağıdakileri içeren bir AdSelectionOutcome döndürür:

• Kazanan reklamın AdData.getRenderUrl() adresinden alınan oluşturma 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.

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ğırması aşağıdaki davranışlarla bir AdServicesException sağlar:

• Reklam seçimi geçersiz bağımsız değişkenlerle başlatılırsa AdServicesException neden olarak bir IllegalArgumentException belirtir.
• Diğer tüm hatalar, neden olarak IllegalStateException içeren bir AdServicesException alır.

İçeriğe dayalı reklamlar

Korunan kitle, içeriğe dayalı reklamları, korunan açık artırmaya dahil edebilir. İçeriğe dayalı reklamların, reklam teknolojisi sunucusunda seçilmesi ve Protected Audience API'lerin dışında cihaza döndürülmesi gerekir. İçeriğe dayalı reklamlar daha sonra AdSelectionConfig kullanılarak açık artırmaya dahil edilebilir. Bu noktada negatif reklam filtrelemesi için uygunluk da dahil olmak üzere cihaz reklamlarıyla aynı şekilde işlev görürler. Korunan Kitle açık artırması tamamlandıktan sonra reportImpression() yöntemini çağırmanız gerekir. Bu, bir cihazda kazanan reklamı almak için kazanan içeriğe dayalı reklamda, gösterim raporlaması ile aynı kalıpta reportWin() çağrısı yapar. Her içeriğe dayalı reklamda bir alıcı, bir teklif, bir raporlama mantığı bağlantısı, bir oluşturma URL'si ve reklam meta verileri bulunmalıdır.

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

Kotlin

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

Java

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

Böylece, sonuç olarak elde edilen ContextualAds nesnesi AdSelectionConfig dosyanızı oluştururken iletilebilir:

Kotlin

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

Java

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

Uygulama yükleme reklam filtrelemesi

Uygulama yükleme reklamlarını filtreleme, cihazda halihazırda yüklü olan uygulamalar için yükleme reklamlarını filtrelemenize yardımcı olur.

Bu işlemin ilk adımı, hangi reklamverenlerin yüklü pakette filtreleme yapabileceğini tanımlamaktır. Bu işlemin, reklamla hedeflemek istediğiniz uygulamada gerçekleşmesi gerekir.

Kotlin

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

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

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

Java

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

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

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

Önceki kod yürütüldüğünde, iletilen reklamverenler teklif oluşturma işlemi sırasında belirttiğiniz yüklü uygulamaları filtreleyebilir. Bir reklamverenin bu uygulamanın yükleme durumuna erişimini kaldırmanız gerekiyorsa reklamveren bilgilerini kaldırarak bu kodu tekrar çalıştırın.

Sonraki adım, yayıncı uygulamasında reklam filtrelemeyi ayarlamaktır. Reklamı yayıncı uygulamasının içinde sunan tarafın (büyük olasılıkla, arz tarafı SDK'sı olması muhtemeldir) AdFilters nesnesini, filtrelemek istediği uygulamalarla alakalı reklamlarla ilgili bilgi vererek başlatması gerekir:

Kotlin

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

Java

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

Talep tarafı yayıncıları, özel kitlelerinin içinde yer alan reklamlar için bir AdFilter ayarlayabilir.

AdFilters, yeni bir AdData nesnesinin örneklendirme noktasında da geçirilebilir:

Kotlin

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

Java

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

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

Sıklık sınırı filtreleme, reklam teknisyenlerinin bir reklamın gösterilme sayısını sınırlandırabilmesini sağlar. Sıklık sınırı filtreleme, reklamın aşırı maruz kalma oranı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ı. Kullanabileceğiniz reklam etkinliği türleri şunlardır:

• Kazan (yakında): Kazanma etkinliği, reklamın bir açık artırmayı kazandığını gösterir. Kazanma etkinlikleri, Protected Audience API tarafından otomatik olarak güncellenir ve doğrudan geliştirici tarafından çağrılamaz. Kazanma verileri, yalnızca belirli bir özel kitle içindeki reklamlar tarafından görüntülenebilir.
• Gösterim: reportImpression'dan farklı olarak, cihaz üzerinde arayan (STP veya MMP), gösterim etkinliklerini seçtikleri kodda çağırmak için updateAdCounterHistogram() 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, cihaz üzerinde arayan (SSP veya MMP) tarafından updateAdCounterHistogram() numaralı telefona yapılan bir aramayla seçtiği kodda bir noktada ç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 Kitle'deki reklamlarla sınırlı değildir.
• Tıklama: Etkinlik, cihaz üzerinde arayan (SSP veya MMP) tarafından updateAdCounterHistogram() numaralı telefona yapılan bir arama ile koddaki bir noktada çağrılır. Tıklama etkinlikleri, belirli bir TTP'ye ait tüm reklamlar tarafından görülebilir ve aynı Özel Kitle'deki reklamlarla sınırlı değildir.

Yayıncı uygulamasında, cihazda varlığı olan bir STP veya MMP reklam etkinliklerini çağırır. updateAdCounterHistogram() çağrıldığında, sıklık sınırı filtresinin sayacı artırılarak gelecekteki açık artırmaların bir kullanıcının belirli bir reklamla karşılaşmasıyla ilgili güncel bilgilere sahip olması sağlanır. Reklam etkinliği türleri, doğrudan ilgili kullanıcı işlemine bağlı değildir ve arayanların kendi etkinlik sistemlerini yapılandırmalarına yardımcı olmak için verilen yönergelerdir. Cihaz üzerinde işlemi gerçekleştiren, reklam sayaçlarını etkinlik sırasında artırmak için kazanan reklam açık artırmasının reklam seçimi kimliğini sağlar.

Reklam sayacı anahtarları, alıcı reklam teknolojisi tarafından atanan rastgele 32 bit imzalı tam sayılardır ve TTP tarafından tanımlanan belirli bir reklam grubuna karşılık gelir. Reklam sayacı anahtarları yalnızca belirli bir TTP'ye ait olan reklamlarla sınırlı olduğundan, bu anahtarlar başka bir reklam teknolojisinin histogramlarıyla çakışmadan seçilebilir. Reklam sayaç anahtarları, gelecekteki açık artırmaların reklamlarını filtrelemek amacıyla bir TTP'nin reklamlarında veya belirli bir özel kitle içinde TTP'ye özgü tanımlayıcıları artırmak için kullanılır.

Belirli bir kullanıcının, belirli bir alıcı reklam teknolojisindeki diğer reklamlarla olan etkileşimlerine göre ilgi çekme olasılığı daha yüksek olan reklamlara öncelik vermek için sayaç anahtarlarından yararlanılabilir. Örneğin, kazanan reklam açık artırmaları, görüntülemeler ve tıklamalardan yüksek düzeyde etkileşim alan bir reklam, tahmin edilen bir veri noktasını temsil eder. Bu noktayı daha iyi açıklamak gerekirse: Sol elle kullanılan golf sopalarıyla ilgili bir reklam, kullanıcının sağ elle ilgilenen golf sopalarıyla ilgilenmeyeceğini gösterebilir. Sol elle kullanılan reklamlara atanan bir sayaç anahtarı için ayarlanan sıklık sınırı filtresi, sağ elle kullanan kulüpler için reklamları filtreleyebilir.

Açık artırmada sıklık sınırı kullanmak için önce aşağıda gösterildiği gibi KeyedFrequencyCap nesne oluşturmanız gerekir:

Kotlin

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

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

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

Java

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

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

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

KeyedFrequencyCap nesneleri oluşturulduktan sonra bunları bir AdFilters nesnesine geçirebilirsiniz.

Kotlin

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

Java

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

AdFilters nesnesi sıklık sınırı filtreleriyle doldurulduğunda, özel kitle oluşturulduğunda bu nesne geçirilebilir:

Kotlin

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

Java

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

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

Kotlin

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

Java

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

Önceden belirlenmiş sıklık sınırı filtre sınırlarına ulaşan reklamlar filtrelenerek açık artırmanın dışında tutulur. Filtreleme, cihaz üzerinde açık artırmalarda teklif verme mantığının uygulanmasından önce ve yük, Teklif Verme ve Açık Artırma hizmetleri açık artırmaları için oluşturulurken gerçekleşir.Bu araç seti, reklam teknisyenlerine, aşırı reklam gösterimini en aza indirirken reklam hedeflemesine odaklanmak amacıyla kullanıcılar ile özel kitlelerindeki reklamlar arasındaki etkileşimleri kullanma esnekliği sağlar.

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

Cihazda yeniden pazarlama talebi yoksa, ağ çağrıları olmadan içeriğe dayalı reklamlar için reklam seçimi yayınlayabilirsiniz. Önceden oluşturulmuş URI'lar ve teklifler içeren içeriğe dayalı reklamların listesi sayesinde platform; teklif verme mantığını, teklif sinyallerini ve puanlama sinyallerini atlayabilir. Platform, en yüksek teklife sahip içeriğe dayalı reklamı seçmek için önceden oluşturulmuş bir URI kullanır.

Reklam teknolojileri, gecikmeyi iyileştirmek için ağ çağrıları olmadan yalnızca reklam filtreleme işlevine sahip içeriğe dayalı reklamları içeren bir reklam seçimi akışı çalıştırabilir. Bu, puanlama sinyalleri için önceden oluşturulmuş URI'lar kullanılarak gerçekleştirilir. scoreAds uygulama listesi için desteklenen, önceden oluşturulmuş URI kullanım alanları ve adları bölümüne bakın.

Reklam seçimini ağ çağrıları olmadan çalıştırmak için:

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

3. Aşağıdakilerle bir AdSelectionConfig nesnesi oluşturun:

   1. Boş alıcı listesi
   2. En yüksek teklifi seçmek için önceden oluşturulmuş URI
   3. İçeriğe dayalı reklamlar
   4. Puanlama sinyalleri için boş bir URI. Boş URI'nin, puanlama için güvenilir sinyallerin getirilmesini kullanmak istemediğinizi belirtmesine izin verilir:

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

4. Reklam seçimini yayınlayın:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Önceden oluşturulmuş URI'ları kullanırken kendi raporlama JavaScript'inizi çalıştırın

Bugün, Özel Korumalı Alan platformu yalnızca önceden oluşturulmuş URI'lar için kullanılabilen temel bir raporlama JavaScript uygulamasına sahiptir. Düşük gecikmeli reklam seçimi için önceden oluşturulmuş URI'ları kullanmaya devam ederken kendi raporlama JavaScript'inizi çalıştırmak isterseniz reklam seçimi ve raporlama çalıştırmaları arasında 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ırma adımlarını uygulayın

2. Raporlamayı çalıştırmadan önce AdSelectionConfig verilerinizin bir kopyasını oluşturun

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

3. Gösterim raporlaması ç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ında birden çok üçüncü taraf SDK'nın (3. taraf ağlar) birinci taraf SDK uyumlulaştırma ağı tarafından düzenlenmesi gerekir. Şelale uyumlulaştırması, açık artırmanın cihazda veya teklifli sistem ve açık artırma hizmetlerinde (B&A) olup olmamasına bakılmaksızın aynı şekilde gerçekleştirilir.

Üçüncü taraf ağları

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

• Reklam seçimini yayınla
• Rapor gösterimleri

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

Kotlin

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

Java

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Her SDK'nın kendi reklam seçimi hizmet yöneticileri ve istemcileri, ayrıca kendi selectAds ve reportImpressions uygulamaları vardır. SDK sağlayıcılar, cihaz üzerinde açık artırmalar için reklam seçiminin çalıştırılması ile ilgili bölümlere veya B&A açık artırmaları için B&A açıklamacısına başvurabilir. Reklam gösterimlerini nasıl raporlayacağınızı (raporlama için tek STP gösterim raporlamasını izleyerek) uygulayın.

Uyumlulaştırma ağı

Üçüncü taraf ağlarda olduğu gibi, uyumlulaştırma ağlarında da selectAds ve reportImpression uygulamaları gerekir. Daha fazla bilgi için reklam seçimini çalıştırma ve reklam gösterimlerini bildirme ile ilgili bölümlere bakın.

Uyumlulaştırma ağları, uyumlulaştırma zincirini çalıştırmaktan ve kendilerini uyumlulaştırma zincirine yerleştirmekten sorumludur. Bir sonraki bölümde bu sürecin nasıl oluşturulacağı ve yürütüleceği ele alınmaktadır.

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

Uyumlulaştırma ağı, birinci taraf içeriğe dayalı reklamları, uyumlulaştırma zincirini ve üçüncü taraf ağların teklif tabanlarını (3. taraf) almaktan sorumludur. Bu, uyumlulaştırma ağı tarafından yürütülen içeriğe dayalı reklamlar alma isteğinde gerçekleşebilir. Uyumlulaştırma zinciri, Üçüncü Taraf Ağlar üzerinden nasıl yineleme 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 tekliflerindeki etkin eBGBM'ye göre kendini uyumlulaştırma zincirine yerleştirebilir. Protected Audience API'de reklam teklifleri opaktır. Uyumlulaştırma SDK'sı, belirli bir birinci taraf reklamın teklifini zincirdeki bir sonraki üçüncü taraf ağın teklif tabanıyla karşılaştırabilmek için AdSelectionFromOutcomesConfig kullanmalıdır. Birinci taraf teklifi, teklif tabanından yüksekse uyumlulaştırma SDK'sı söz konusu üçüncü taraf ağının önüne yerleştirilir.

Reklam seçimini yayınla

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

AdSelectionFromResultsConfig oluşturma

AdSelectionFromOutcomesConfig, uyumlulaştırma ağının bir AdSelectionIds listesini (önceki açık artırmaların sonuçları), reklam seçimi sinyallerini ve birden fazla aday arasından reklam seçen JavaScript'i getirmek için bir URI aktarmasını sağlar. AdSelectionId'ler listesi, teklifleri ve sinyallerle birlikte JavaScript'e iletilir. Bu liste, teklif tabanını geçerse AdSelectionIds değerlerinden birini döndürebilir veya uyumlulaştırma zincirinin devam etmesi gerekiyorsa hiçbirini döndürebilir.

Uyumlulaştırma Ağları, önceki bölümde yer alan birinci taraf AdSelectionId ve dikkate alınan üçüncü taraf ağı için teklif tabanını kullanarak bir AdSelectionFromOutcomesConfig oluşturur. Uyumlulaştırma zincirindeki her adım için yeni bir AdSelectionFromOutcomesConfig oluşturulmalıdır.

Kotlin

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

Java

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

    return adSelectionClient.selectAds(config){}
}

Şelale uyumlulaştırması için selectAds() yöntemini geçersiz kılma, aşağıdaki gerekli parametreleri belirtmeniz gereken 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 bir önceki selectAds() çalıştırmanın tekil listesi.
• Reklam seçimi sinyalleri: Dize olarak serileştirilmiş, alıcı teklif verme mantığı tarafından kullanılacak sinyalleri içeren bir JSON nesnesi. Bu durumda, ilgili üçüncü taraf ağı için alınan teklif tabanını dahil edin.
• Seçim Mantık URI'si: Kazanan bir reklamı seçmek için uyumlulaştırma ağının JavaScript'ini getirmek üzere reklam seçimi sırasında sorgulanan bir HTTPS URL'si. Bu JavaScript'te gereken işlev imzalarına bakın. Teklif, teklif tabanından yüksekse JavaScript'in üçüncü taraf reklamı döndürmesi gerekir. Aksi halde, null değerini döndürür. Bu, bir kazanan bulunduğunda uyumlulaştırma SDK'sının uyumlulaştırma zincirini kısaltmasını sağlar.

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

Kotlin

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

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

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

Java

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

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

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

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

Uyumlulaştırma süreci boyunca çalıştırılacak işlemlerin sırası aşağıda verilmiştir.

1. Birinci taraf reklam seçimini çalıştırın.
2. Uyumlulaştırma zinciri üzerinde tekrarlayın. Her bir üçüncü taraf ağı için aşağıdakileri yapın:
   1. Birinci taraf outcomeId ve üçüncü taraf SDK'nın teklif tabanı dahil olmak üzere AdSelectionFromOutcomeConfig oluşturun.
   2. Önceki adımdaki yapılandırma ile selectAds() işlevini çağırın.
   3. Sonuç boş değilse reklamı döndürün.
   4. Geçerli 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 bulunmazsa birinci taraf reklamı döndürün.

Kotlin

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

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

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

Java

class MediationNetwork {
    AdSelectionManager adSelectionManager;

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

    public void runAdSelection() {...}

    public void reportImpressions() {...}

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

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

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

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

Reklam gösterimlerini raporla

Açık artırmanın nasıl yapıldığına bağlı olarak bir reklam gösterimini raporlamak için iki akış vardır. Açık artırma yapan tek bir STP iseniz bu bölümü takip edin. Şelale uyumlulaştırmasını uygulayacaksanız şelale uyumlulaştırması gösterim raporlama bölümündeki adımları uygulayın.

Tek STP gösterim raporlaması

Reklam seçimi iş akışından kazanan reklam seçildikten sonra, AdSelectionManager.reportImpression() yöntemini kullanarak gösterimi katılımcı alıcı ve satış tarafı platformlara geri raporlayabilirsiniz. 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. Eşzamansız reportImpression() yöntemini ReportImpressionRequest nesnesi ve ilgili Executor ile OutcomeReceiver nesneleriyle çağırın.

Java

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

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

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

Kotlin

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

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

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

Aşağıdaki gerekli parametrelerle ReportImpressionRequest'i başlatın:

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

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

• onResult() geri çağırması, gösterim raporlama URL'lerinin oluşturulup oluşturulmadığını ve isteğin planlanıp planlanmadığını gösterir.
• onError() geri çağırması, aşağıdaki olası koşulları gösterir:
  • Çağrı, geçersiz bir giriş bağımsız değişkeniyle başlatılırsa AdServicesException neden olarak bir IllegalArgumentException belirtir.
  • Diğer tüm hatalar, neden olarak IllegalStateException içeren bir AdServicesException alır.

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

Raporlama akışlarını tetiklemek için bir uyumlulaştırma SDK'sının kazanan SDK'yı takip etmesi gerekir. Bir uyumlulaştırma zincirine katılan SDK'lar, arabulucunun kendi raporlama akışını tetiklemek için çağırması için bir yöntem sağlamalıdır. Uyumlulaştırılmış açık artırmaya katılan bir SDK, kendi raporlamasını uygulamak için yukarıdaki adımları izleyebilir.

STP'ler, uyumlulaştırma akışlarına nasıl katılacakları konusunda 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ış tarafı platformu ve kazanan alıcı tarafı platformu tarafından sağlanan uç noktalara HTTPS GET istekleri gönderir:

Satın alma tarafı platform uç noktası:

• API, alıcı tarafından sağlanan ve gösterim raporlama URL'si döndürme mantığını içeren JavaScript'i getirmek için özel kitlede belirtilen Teklif verme mantığı URL'sini kullanır.
• Alıcının gösterim raporlama URL'sini döndürmesi beklenen reportWin() JavaScript işlevini çağırın.

Satış tarafı platform uç noktası:

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

Teklif verme ve açık artırma hizmetleri raporları

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

En iyi sonuç Gösterim raporlama

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

Not:

• API, JavaScript işlevlerinden gösterim raporlama URL'lerini belirleyemezse bir hata döndürür.
• URL'lere yapılan çağrı başarısız olursa mevcut Geliştirici Önizleme sürümü herhangi bir hata üretmez. Gelecekteki sürümlerde geçici hatalar için yeniden deneme mantığı planlanmıştır.
• Aynı parametrelerle birden fazla reportImpression() çağrısı yapılması, reklam seçimi sonuçlarınızın birden çok kez raporlanmasına neden olabilir.

Reklam Etkileşimlerini Rapor Etme

Korunan Kitle, oluşturulan bir reklam için daha ayrıntılı etkileşimler hakkında rapor oluşturmayı destekler. Görüntüleme süresi, tıklama, fareyle üzerine gelme gibi etkileşimler veya toplanabilecek diğer faydalı metrikler bu etkileşim kapsamındadır. Bu raporları alma süreci iki adım gerektirir. Öncelikle, alıcı ve satıcıların bu raporları raporlama JavaScript'lerinde almak için kaydolmaları gerekir. Ardından, müşterinin bu etkinlikleri raporlaması gerekir.

Etkileşim etkinliklerini almak için kaydolma

Etkileşim etkinliklerine kayıt, platform (registerAdBeacon) tarafından sağlanan bir JavaScript işlevini kullanarak alıcının reportWin() ve satıcı reportResult() JavaScript işlevlerinde yapılır. Bir etkinlik raporu almak üzere kaydolmak için raporlama JavaScript'inizden platform JavaScript İşlevini çağırmanız yeterlidir. Aşağıdaki snippet, alıcının reportWin() parametresini kullanmaktadır, ancak aynı yaklaşım reportResult() için de geçerlidir.

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri
    registerAdBeacon("click", clickUri)
    registerAdBeacon("view", viewUri)
    registerAdBeacon("hover", hoverUri)

    return reportingUrl;
}

Not: Raporları almak için etkileşim anahtarı dizelerinin satıcının raporladıklarıyla eşleşmesi gerekir.

Etkileşim etkinliklerini raporlama

Müşteriler bir gösterimi bildirdikten sonra AdSelectionManager.reportInteraction() yöntemini kullanarak etkileşimleri daha önce kaydedilmiş olan kazanan alıcı ve satış tarafı platformlara geri raporlayabilir. Bir reklam etkinliğini bildirmek için:

1. Bir AdSelectionManager nesnesini başlatı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);

Aşağıdaki gerekli parametrelerle ReportInteractionRequest'i 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ı: Müşteri tarafından tanımlanan ve raporlanmakta olan işlemi açıklayan bir dize anahtarı. Bu değer, satıcı veya alıcı tarafından raporlama JavaScript işlevlerinde kaydedilen anahtarla eşleşmelidir.
• Etkileşim Verileri: Raporlama sunucularına POST edilecek ve etkinlik raporuna dahil edilecek verileri içeren bir dize.
• Raporlama Hedefleri: Etkinliklerin alıcıya, satıcıya veya her ikisine de bildirilmesi gerektiğini belirten bir bit maskesi. Bu işaretler platform tarafından sağlanır ve son hedef maskesi, bit tabanlı işlemler kullanılarak oluşturulabilir. Tek bir hedefe bildirmek için doğrudan platform tarafından sağlanan işareti kullanabilirsiniz. Birden fazla hedefe raporlama yapmak için işaret değerlerini birleştirmek için bit tabanlı VEYA (|) kullanabilirsiniz.

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

• onResult() geri çağırması, rapor etkileşim çağrısının geçerli olduğunu gösterir.
• onError() geri çağırması, aşağıdaki olası koşulları gösterir:
  • Arama, uygulama arka planda çalışırken yapılırsa hatanın açıklamasını içeren bir IllegalStateException döndürülür.
  • İstemcinin reportInteraction() çağrısı yapması kısıtlanırsa LimitExceededException döndürülür.
  • Paket, Gizliliği Koruma API'lerini çağırmak için kaydedilmemişse SecurityException() döndürülür.
  • Uygulama raporlama etkileşimleri, selectAds() adlı uygulamadan farklıysa IllegalStateException döndürülür.
• Kullanıcı, Özel Korumalı Alan API'lerini etkinleştirmek için izin vermezse çağrı sessizce başarısız olur.

Not: Hata olmaması raporlamanın yapıldığı anlamına gelmez. Daha ziyade, Korunan Kitlenin bir noktada etkileşimleri bildirmeye çalışacağını garanti eder.

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 yayınlar. Korunan Kitle, etkileşim anahtarlarını raporlama JavaScript'inde belirtilen URI'lerle eşleştirir ve raporlanan her etkileşim için her bir uç noktaya POST isteği gönderir. İsteğin içerik türü düz metindir. Gövde metni, 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 verisi parçalarını güncelleyebilir.

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

Bu işlem, özel kitlede tanımlanan Günlük Güncelleme URL'sini temel alır ve URL bir JSON yanıtı döndürebilir.

• JSON yanıtı, güncellenmesi gereken desteklenen meta veri alanlarının herhangi birini içerebilir.
• Her JSON alanı bağımsız olarak doğrulanır. İstemci hatalı biçimlendirilmiş alanları yoksayar. Bu durum, yanıttaki söz konusu alanda güncelleme yapılmasına neden olmaz.
• Boş bir HTTP yanıtı veya boş JSON nesnesi olan "{}", meta veri güncellemesiyle sonuçlanmaz.
• Yanıt iletisi boyutu 10 KB ile sınırlı olmalıdır.
• HTTPS kullanmak için tüm URI'ler 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ı ve satıcı tarafından sağlanan JavaScript'in yürütülmesini düzenler.

Alıcı tarafından sağlanan JavaScript, özel kitlede belirtilen Teklifli Sistem mantığı URL'sinden getirilir. Döndürülen JavaScript aşağıdaki işlevleri içermelidir:

• generateBid()
• reportResult()

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

• scoreAd()
• reportWin()

createBid()

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

Giriş parametreleri:

• ad: var ad = { 'render_url': url, 'metadata': json_metadata }; biçiminde bir JSON nesnesi
• 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 ş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"
  }
  

  burada:

  • owner, buyer ve name, reklam seçimine katılan Özel Kitle ile aynı ada sahip mülklerden alınan dizelerdir
  • activation_time ve expiration_time, özel kitlenin etkinleştirilmesi ve geçerlilik süresidir. Unix döneminden bu yana, 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. Bunlar boş nesneler olarak aktarılır ve gelecekteki sürümlerde doldurulur. Bu biçimlerin biçimi platform tarafından zorunlu kılınmaz, reklam teknolojisi tarafından yönetilir.

Sonuç:

• ad: Teklifin ilgili olduğu reklamdır. Komut dosyasının, aldığı reklamın farklı meta verilerle bir kopyasını döndürmesine izin verilir. Reklamın render_url özelliğinin değiştirilmemiş olması beklenir.
• bid: Bu reklam için teklif değerini temsil eden bir kayan değer
• status: Şu olabilecek bir tam sayı değeridir:
  • 0: yürütmenin başarıyla tamamlanması için
  • 1: (veya sıfır dışında herhangi bir değer). Teklif oluşturma yönteminin sıfır dışında bir değer döndürmesi durumunda, teklif süreci tüm CA reklamları için geçersiz kılınır.

puanReklam()

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'nin AdSelectionConfig parametresini temsil eden bir JSON nesnesidir. Biçim şöyledir:

  var ad_selection_config = {
    'seller': 'seller',
    'decision_logic_url': 'url_of_decision_logic',
    'custom_audience_buyers': ['buyer1', 'buyer2'],
    'auction_signals': auction_signals,
    'per_buyer_signals': per_buyer_signals,
    'contextual_ads': [ad1, ad2]
  }
  

• seller_signals: sellerSignals AdSelectionConfig API parametresinden okunan JSON nesneleri

• trusted_scoring_signal: AdSelectionConfig API parametresindeki adSelectionSignals alanından okur

• contextual_signals, user_signals: JSON nesneleri. Bunlar şu anda boş nesneler olarak iletilir ve sonraki sürümlerde doldurulacaktır. Bu biçimlerin biçimi platform tarafından zorunlu kılınmaz ve reklam teknolojisi tarafından yönetilir.

• per_buyer_signals: Mevcut Özel Kitle alıcısı anahtar olarak kullanılarak AdSelectionConfig API parametresindeki perBuyerSignal haritasından okunan JSON nesnesi. Haritada belirli bir alıcı için herhangi bir giriş yoksa boş bırakılır.

Ses çıkışı:

• score: Bu reklamın puan değerini temsil eden kayan bir değer
• status: Şu olabilecek bir tam sayı değeridir:
  • 0: yürütmenin başarılı olması 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, atılan istisna türünü

SelectResult()

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

Ses çıkışı:

• status: Başarı için 0, başarısızlık için sıfır dışında
• result: Geçilen 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 teklif edilen teklif
• contextual_signals: generateBid belgelerine bakın

Ses çıkışı:

• Başarılı olmak için status: 0 ve başarısızlık için sıfır dışında bir değer
• results: Şunları içeren bir JSON nesneleri:
  • signals_for_buyer: reportWin işlevine geçirilen bir JSON nesnesi
  • reporting_url: Platform tarafından gösterimi alıcıya bildirmek için kullanılan URL

reportWin()

function reportWin(
   ad_selection_signals,
   per_buyer_signals,
   signals_for_buyer,
   contextual_signals,
   custom_audience_signals) {
   return {'status': 0, 'results': {'reporting_url': reporting_url } };
}

Giriş parametreleri:

• ad_selection_signals, per_buyer_signals: scoreAd belgelerine bakın
• signals_for_buyer: reportResult tarafından döndürülen bir JSON nesnesi
• contextual_signals, custom_audience_signals: generateBid belgelerini inceleyin

Ses çıkışı:

• Başarılı olmak için status: 0 ve başarısızlık için sıfır dışında bir değer
• results: Şunları içeren bir JSON nesnesi:
  • reporting_url: Platform tarafından gösterimi satıcıya bildirmek için kullanılan URL

recordAdBeacon()

Not: Bu özellik Android platformu tarafından sağlanır ve reklam teknolojisi tarafından uygulanmamalıdır.

function registerAdBeacon(
  interaction_key,
  reporting_uri
)

Giriş Parametreleri:

• interaction_key: Etkinliği temsil eden bir dize. Bu özellik, daha sonra etkinlik etkileşimleri bildirilirken bildirilecek reporting_uri olup olmadığını bulmak için platform tarafından kullanılır. Bu anahtarın, alıcının veya satıcının kaydettiği ve satıcının bildirdiği bilgiler arasında eşleşmesi gerekir.
• reporting_uri: Etkinlik raporlarını alacak URI. Bu, raporlanan etkinlik türüne özgü olmalıdır. Etkinlikle birlikte bildirilen tüm verileri işlemek için bir POST isteğini kabul etmesi gerekir.

Reklam Seçimi'nin önceden oluşturulmuş URI'ları

Önceden oluşturulmuş URI'lar, reklam teknisyenlerinin AdSelectionConfig ve AdSelectionFromOutcomesConfig sınıflarında reklam seçimi karar mantığı için JavaScript işlevleri atamasına olanak tanır. Önceden oluşturulmuş URI'lar, ilgili JavaScript'i indirmek için ağ çağrıları gerektirmez. Reklam teknisyenleri, JavaScript'i barındırmak için kayıtlı bir alan adı oluşturmak zorunda kalmadan önceden oluşturulmuş URI'ları kullanabilir.

Önceden oluşturulmuş bir URI, aşağıdaki biçim kullanılarak oluşturulur:

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

Özel Korumalı Alan platformu, çalışma zamanında bu URI'daki bilgileri kullanarak JavaScript sağlar.

Aşağıdaki durumlarda IllegalArgumentException gönderilir:

• gerekli parametrelerden herhangi biri URI'da bulunmuyor
• URI'da 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ındaki önceden oluşturulmuş URI'lar selectAds(AdSelectionConfig) akışında desteklenir.

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

Bu önceden oluşturulmuş URI, teklif verdikten sonra en yüksek teklifi seçen bir JavaScript sağlar. Ayrıca kazananın render_uri ve bid değerlerini rapor etmek 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ı: reklam seçimi-sonuçları

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

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

Önceden oluşturulmuş waterfall-mediation-truncation URI'si, bid değeri bid floor değerinden yüksek veya ona eşitse JavaScript'in birinci taraf reklamı döndürdüğü ve aksi takdirde null döndürdüğü, şelale uyumlulaştırmasını kesme mantığını uygulayan JavaScript'i sağlar.

Gerekli parametreler

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

Kullanım

Reklam seçimi sinyalleriniz {"bid_floor": 10} gibi görünüyorsa sonuç olarak elde edilen önceden oluşturulmuş URI şöyle olur:

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

Test

Protected Audience API'yi kullanmaya başlamanıza yardımcı olmak için Kotlin ve Java'da örnek uygulamalar oluşturduk. Bunları GitHub'da bulabilirsiniz.

Ön koşullar

Protected Audience API, reklam seçimi ve gösterim raporlaması sırasında bazı JavaScript kodları gerektirir. Bu JavaScript'i bir test ortamında sağlamanın iki yöntemi vardır:

• JavaScript'i döndüren gerekli HTTPS uç noktalarına sahip bir sunucu çalıştırın
• Yerel bir kaynaktan gerekli kodu sağlayarak uzaktan getirmeyi geçersiz kılın

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

HTTPS uç noktaları

Reklam seçimini ve gösterim raporlamasını test etmek için test cihazınızın veya emülatörünüzün erişebileceği 7 HTTPS uç noktası ayarlamanız gerekir:

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

GitHub deposu, testlerde kolaylık sağlamak amacıyla temel JavaScript kodu sağlar. Ayrıca, desteklenen bir sahte veya mikro hizmet platformuna dağıtılabilen OpenAPI hizmet tanımları da içerir. Daha fazla bilgi için README projesine göz atın.

JavaScript'in uzaktan getirilmesini geçersiz kıl

Bu özellik, uçtan uca test için kullanılmak üzere tasarlanmıştır. Uzaktan getirmeyi geçersiz kılmak için uygulamanızın geliştirici seçenekleri etkinleştirilen hata ayıklama modunda çalışması gerekir.

Uygulamanızda hata ayıklama modunu etkinleştirmek için AndroidManifest.xml dosyanızdaki uygulama özelliğine aşağıdaki satırı ekleyin:

<application
  android:debuggable="true">

Not: Başvurunuzu göndermeden önce android:debuggable="true dokümanını kaldırdığınızdan emin olun.

Bu geçersiz kılmaların nasıl kullanılacağına dair bir örnek için GitHub'daki Protected Audience API örnek uygulamasını inceleyin.

Teklif verme, puanlama kararları ve raporlama gibi reklam seçimi rutinlerini işlemek için kendi özel JavaScript'inizi eklemeniz gerekir. Gerekli tüm istekleri işleyen temel JavaScript kod örneklerini GitHub deposunda bulabilirsiniz. Protected Audience API örnek uygulaması, bu dosyadaki kodun nasıl okunacağını ve geçersiz kılma olarak kullanılmak üzere nasıl hazırlanacağını gösterir.

Satış tarafı ve alıcı 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 JavaScript'leri sunmak için bir HTTPS uç noktasına ihtiyacınız vardır. Bu tür durumları işleyen bir sunucunun nasıl ayarlanacağı hakkında bilgi edinmek için lütfen BENİOKU bölümüne bakın.

Yalnızca paketinize ait özel kitleler için JavaScript getirme işlemini geçersiz kılmak mümkündür.

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

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

1. Bir AdSelectionManager nesnesini başlatın.
2. AdSelectionManager nesnesinden TestAdSelectionManager referansı alın.
3. AdSelectionConfig nesnesi oluşturun.
4. AdSelectionConfig nesnesiyle ve geçersiz kılma olarak kullanmak istediğiniz JavaScript'i temsil eden bir String ile bir AddAdSelectionOverrideRequest oluşturun.
5. Eşzamansız overrideAdSelectionConfigRemoteInfo() yöntemini AddAdSelectionOverrideRequest nesnesi ve alakalı Executor ile OutcomeReceiver nesneleriyle çağırın.

Kotlin

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

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

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

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

Java

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

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

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

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

AdSelectionConfig içindeki alanların her birinin neyi temsil ettiği hakkında daha fazla bilgi için Reklam seçimini çalıştırma bölümüne bakın. Temel fark, decisionLogicUrl öğesinin yok sayılacağı için bir yer tutucu değerine ayarlanmasıdır.

Reklam seçimi sırasında kullanılan JavaScript'i geçersiz kılmak için decisionLogicJs, uygun satıcı tarafı işlev imzalarını içermelidir. JavaScript dosyasının dize olarak nasıl okunacağına dair örnek için GitHub'daki Protected Audience API örnek uygulamasına göz atın.

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

onResult() geri çağırması, geçersiz kılmanın başarıyla uygulandığını gösterir. Gelecekteki selectAds() çağrılarında, geçersiz kılma olarak iletmiş olduğunuz karar ve raporlama mantığı kullanılır.

onError() geri çağırması iki olası koşulu ifade eder:

• Geçersiz kılma işlemi, geçersiz bağımsız değişkenlerle denenirse AdServiceException neden olarak bir IllegalArgumentException belirtir.
• Geçersiz kılma işlemi, geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulama ile denenirse neden AdServiceException simgesinde IllegalStateException belirtilir.

Satış tarafı geçersiz kılmalarını sıfırla

Bu bölümde, satış tarafı JavaScript'ini geçersiz kıldığınız ve önceki bölümde kullanılan TestAdSelectionManager ve AdSelectionConfig referanslarına sahip olduğunuz varsayılır.

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

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

Kotlin

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

Java

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

Satış tarafı geçersiz kılmalarını sıfırladıktan sonra selectAds() çağrıları, gerekli JavaScript'i getirmeye çalışmak için AdSelectionConfig içinde depolanan decisionLogicUrl öğelerini kullanır.

resetAllAdSelectionConfigRemoteOverrides() çağrısı başarısız olursa OutComeReceiver.onError() geri çağırması bir AdServiceException sağlar. Geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulama varken geçersiz kılmaları kaldırma girişiminde bulunursanız AdServiceException nedeni, IllegalStateException olarak belirtilir.

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

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

Kotlin

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

// Join custom audience

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

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

Java

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

// Join custom audience

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

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

buyer ve name değerleri, özel kitleyi oluşturmak için kullanılan değerlerle aynıdır. Bu alanlar hakkında daha fazla bilgi edinin.

Ayrıca, iki ek parametre belirtebilirsiniz:

• biddingLogicJs: Reklam seçimi sırasında kullanılan alıcının mantığını barındıran JavaScript. Bu JavaScript'te gerekli işlev imzalarına bakın.
• trustedBiddingSignals: Reklam seçimi sırasında kullanılacak teklif sinyalleri. Test amacıyla bu boş bir dize olabilir.

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

onResult() geri çağırması, geçersiz kılmanın başarıyla uygulandığını gösterir. Sonraki selectAds() çağrılarında, geçersiz kılma olarak geçirdiğiniz teklif ve raporlama mantığı kullanılır.

onError() geri çağırması iki olası koşulu belirtir.

• Geçersiz kılma işlemi, geçersiz bağımsız değişkenlerle denenirse AdServiceException neden olarak bir IllegalArgumentException belirtir.
• Geçersiz kılma işlemi, geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulama ile denenirse neden AdServiceException simgesinde IllegalStateException belirtilir.

Alıcı tarafı geçersiz kılmaları sıfırla

Bu bölümde, alıcı tarafı JavaScript'i geçersiz kıldığınız ve önceki bölümde kullanılan TestCustomAudienceManager referansına sahip olduğunuz varsayılır.

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

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

Kotlin

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

Java

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

Alıcı tarafı geçersiz kılmalarını sıfırladıktan sonra selectAds() için yapılan sonraki çağrılar, gerekli JavaScript'i getirmeye çalışmak için CustomAudience bölümünde depolanan biddingLogicUrl ve trustedBiddingData öğelerini kullanır.

resetCustomAudienceRemoteInfoOverride() çağrısı başarısız olursa OutComeReceiver.onError() geri çağırması bir AdServiceException sağlar. Geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulama varken geçersiz kılmaları kaldırma girişiminde bulunursanız AdServiceException neden olarak IllegalStateException gösterilir.

Raporlama Sunucusu Kurma

Uzaktan getirme geçersiz kılmalarını kullandığınızda, yine de raporlama etkinliklerine yanıt vermek için cihazınızın veya emülatörünüzün ulaşabileceği bir sunucu oluşturmanız gerekir. 200 değerini döndüren basit bir uç nokta test için yeterlidir. GitHub deposu, desteklenen bir sahte veya mikro hizmet platformuna dağıtılabilen OpenAPI hizmet tanımları içerir. Daha fazla bilgi için README projesine göz atın.

OpenAPI tanımlarını ararken reporting-server.json dosyasını bulun. Bu dosya, HTTP yanıt kodunu temsil eden 200 değerini döndüren basit bir uç nokta içerir. Bu uç nokta, selectAds() 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şlevler

• Katılma veya ayrılma alıştırması yapın ve önceki kullanıcı işlemlerine dayalı olarak özel bir kitle oluşturun.
• Uzaktan barındırılan JavaScript'ler aracılığıyla cihaz üzerinde reklam seçiminin başlatılmasını sağlayın.
• Bir uygulamanın özel kitle ayarlarıyla ilişkilendirmesinin reklam seçimi sonuçlarını nasıl etkileyebileceğini gözlemleyin.
• Reklam seçiminden sonra gösterim raporlaması 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 bildirimlere göre değiştirilebilir. Devam eden özellikler için sürüm notlarını okuyun.

Bileşen	Sınır Açıklaması	Sınır Değeri
Özel kitle (Kanada)	CA başına maksimum reklam sayısı	100
	Uygulama başına maksimum CA sayısı	1.000
	CA oluşturabilecek maksimum uygulama sayısı	1.000
	CA'nın oluşturulma zamanından itibaren etkinleştirme süresindeki maksimum gecikme	60 gün
	CA'nın etkinleştirme zamanından itibaren maksimum geçerlilik süresi	60 gün
	Cihazdaki maksimum CA sayısı	4.000
	Maksimum CA adı boyutu	200 bayt
	Günlük getirme URI'sının maksimum boyutu	400 bayt
	Maksimum teklif mantığı URI'si boyutu	400 bayt
	Güvenilir teklif verilerinin maksimum boyutu	10 KB
	Kullanıcı teklif sinyallerinin maksimum boyutu	10 KB
	Alıcı başına leaveCustomAudience için maksimum arama ücreti	Saniyede 1
	Alıcı başına joinCustomAudience için maksimum arama ücreti	Saniyede 1
CA Arka Planda Getirme	Bağlantı zaman aşımı	5 saniye
	HTTP okuma zaman aşımı	30 saniye
	Maksimum toplam indirme boyutu	10 KB
	Getirme yinelemesinin maksimum süresi	5 dakika
	İş başına güncellenen maksimum CA sayısı	1.000
Reklam Seçimi	Maksimum alıcı sayısı	Henüz belli değil
	Alıcı başına maksimum CA sayısı	Henüz belli değil
	Açık artırmadaki maksimum reklam sayısı	Henüz belli değil
	İlk bağlantı zaman aşımı	5 saniye
	Bağlantı okuma zaman aşımı	5 saniye
	Toplam AdSelection maksimum yürütme süresi	10 saniye
	AdSelection ayında CA başına maksimum teklif yürütme süresi	5 saniye
	AdSelection içinde puanlamanın maksimum yürütme süresi	5 saniye
	AdSelection ayında alıcı başına maksimum yürütme süresi	Henüz belli değil
	Reklam seçimi/satıcı/alıcı başına maksimum sinyal boyutu	Henüz belli değil
	Satıcı/alıcı komut dosyalarının maksimum boyutu	Henüz belli değil
	selectAds için maksimum arama ücreti	1 QPS
Gösterim raporlaması	Reklam seçiminin kalıcılıktan kaldırılması için gereken minimum süre	24 saat
	Maksimum depolama alanı reklam seçimi sayısı	Henüz belli değil
	Maksimum raporlama çıkış URL'si boyutu	Henüz belli değil
	Gösterim raporlama için maksimum süre	Henüz belli değil
	Bildirim aramaları için maksimum yeniden deneme sayısı	Henüz belli değil
	Bağlantı zaman aşımı	5 saniye
	reportImpression için maksimum genel yürütme süresi	2 saniye
	reportImpressions için maksimum arama ücreti	1 QPS
Etkinlik raporlaması	Açık artırma başına alıcı başına maksimum işaretçi sayısı	10
	Açık artırma başına satıcı başına maksimum işaretçi sayısı	10
	Maksimum etkinlik anahtarı boyutu	40 bayt
	Etkinlik verilerinin maksimum boyutu	64KB
Reklamlar	Reklam listesinin maksimum boyutu	İçerik için tek bir CA'da tüm AdData tarafından paylaşılan 10 KB
URL'ler	Girdi olarak alınan herhangi bir URL dizesinin maksimum uzunluğu	Henüz belli değil
JavaScript	Maksimum yürütme süresi	Gösterim raporlamasında teklif verme ve puanlama için 1 saniye
	Kullanılan maksimum bellek	10 MB

Hataları ve sorunları bildirme

Geri bildirimleriniz, Android'de Özel Korumalı Alan için çok önemlidir. Karşılaştığınız sorunları veya Android'de Özel Korumalı Alan'ın iyileştirilmesiyle ilgili fikirlerinizi bize bildirebilirsiniz.