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ılık gösterebilir.

---

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 önceki uygulama etkileşimine göre özel reklamlar yayınlamak için kullanabilir. Bu özel reklamlar, uygulamalar arasında tanımlayıcıların paylaşımını ve kullanıcının uygulama etkileşimi bilgilerinin üçüncü taraflarla paylaşımını sınırlandırır.

Custom Audience API, ortak amaçları olan bir kullanıcı grubunu temsil eden "özel kitle" soyutlamasının merkezindedir. Bir reklamveren, bir kullanıcıyı özel bir kitleye kaydedebilir ve alakalı reklamları bu kitleyle ilişkilendirebilir. Bu bilgiler yerel olarak depolanır ve reklamveren teklifleri, reklam filtreleme ve reklam oluşturma işlemlerinde kullanılabilir.

Reklam Seçimi API'si, birden fazla geliştiricinin özel bir kitle için yerel olarak açık artırma yürütmesine olanak tanıyan bir çerçeve sağlar. Sistem, bunu başarmak için özel kitleyle ilişkili reklamları değerlendirir ve bir reklam teknolojisi platformunun cihaza döndürdüğü reklamlar üzerinde ek işlemler gerçekleştirir.

Reklam teknolojisi platformları, kullanıcı gizliliğini koruyan yeniden pazarlamayı uygulamak için bu API'leri entegre edebilir. Gelecekteki sürümlerde, uygulama yükleme reklamları dahil olmak üzere ek kullanım alanları için destek verilmesi planlanmaktadır. Tasarım teklifinde, Android'de Protected Audience API hakkında daha fazla bilgi edinebilirsiniz.

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

1. Özel kitleleri yönetme
2. Bir cihazda reklam seçimini ayarlayıp yayınlama
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 oluşturun.

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> öğesinde 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 sürümünü gerektirir. Platform bir sürüm kontrolü uygular ve bu yerine getirilmezse selectAds ve reportImpression API'lerine yapılan çağrılar başarısız olur. Bunu iki şekilde ayarlayabilirsiniz:

   • 1. Seçenek: Bu denetimi devre dışı bırakmak için aşağıdaki adb komutunu çalıştırın:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • 2. Seçenek: Google Play Store'dan WebView Beta'yı yükleyin. Bu sayı, daha önce belirtilen sürüme eşit veya bundan daha yüksek olmalıdır.

Özel bir kitleye katılma

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

1. CustomAudienceManager nesnesini başlatın.
2. Alıcının paketi ve ilgili ad gibi anahtar parametreleri belirterek bir CustomAudience nesnesi oluşturun. Ardından JoinCustomAudienceRequest nesnesini CustomAudience nesnesiyle başlatın.
3. Eşzamansız joinCustomAudience() yöntemini JoinCustomAudienceRequest nesnesi ve ilgili 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 bir CustomAudience nesnesini benzersiz şekilde tanımlar:

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

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

Ayrıca, CustomAudience şu gerekli parametrelerle oluşturulmalıdır:

• Günlük güncelleme URL'si: Özel kitlenin kullanıcı teklif sinyallerini, güvenilir teklif verme verilerini ve reklamların URL'lerini ve meta verilerini oluşturmak için arka planda her gün sorgulanan HTTPS URL'si.
• Teklif mantığı URL'si: Alıcının JavaScript teklif verme mantığını getirmek için reklam seçimi sırasında sorgulanan HTTPS URL'si. Bu JavaScript'te gerekli işlev imzalarına bakın.
• Reklam Oluşturma Kimlikleri: Alıcı reklam teknolojisi tarafından ayarlanan rastgele kimliktir. Bu, B&A için yükü oluşturmaya yönelik bir optimizasyondur.

CustomAudience nesnesi için isteğe bağlı parametreler şunları içerebilir:

• Etkinleştirme zamanı: Özel bir kitle, yalnızca etkinleştirme zamanından sonra reklam seçimine ve günlük güncellemelere katılabilir. Bu, örneğin bir uygulamayı eski kullanıcılarıyla etkileşime almak için yararlı olabilir.
• Sona erme süresi: Özel kitlenin cihazdan kaldırılması için gelecekteki bir zaman.
• Kullanıcı teklif verme sinyalleri: Bir alıcının teklif mantığı JavaScript'inin reklam seçim sürecinde teklif oluşturmak için kullandığı, kullanıcının tercih edilen yerel ayarı gibi kullanıcı sinyallerini içeren bir JSON dizesi. Bu biçim, reklam teknolojisi platformlarının kodu platformlar arasında yeniden kullanmasına yardımcı olur ve JavaScript işlevlerinde kullanımı kolaylaştırır.
• Güvenilir teklif verileri: Reklam seçim sürecinde kullanılan ve güvenilir bir Anahtar/Değer hizmetinden teklif sinyalleri getiren bir HTTPS URL'si ve dizelerin listesi.
• Reklamlar: Reklam seçiminde yer alan reklamlara karşılık gelen AdData nesnelerinin listesi. 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ürecinde alıcı teklif verme mantığı tarafından kullanılabilecek bilgileri içeren dize olarak serileştirilmiş bir JSON nesnesi.
  • Reklam Filtreleri: Reklam seçimi sırasında uygulama yükleme reklam filtrelemesi ve sıklık sınırı için gerekli tüm bilgileri içeren bir sınıf.

Not: "Kullanıcı teklif sinyalleri", "Güvenilir teklif verileri" ve "Reklamlar" özelliklerinin değerleri toplamda 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 verilmiştir:

Kotlin

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

Java

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

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

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

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

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

Kotlin

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

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

Java

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

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

Özel bir kitleden ayrılma

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

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 =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

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

Java

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

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

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

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

Reklam seçimini yayınla

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

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ı edinmek için sorgulanan HTTPS URL'si.
  • HTTPS URL'si: Satıcı reklam ağının JavaScript mantığını elde etmek için sorgulanır. Gerekli işlev imzalarını inceleyin.
  • Önceden oluşturulmuş URI: FLEDGE'in reklam seçimi biçimine göre hareket eder. Desteklenmeyen veya hatalı biçimlendirilmiş önceden oluşturulmuş bir URI aktarılırsa IllegalArgumentException döndürülür.
• Özel kitle alıcıları: Satıcının reklam seçim sürecine katılmasına izin verdiği alıcı reklam ağları için tanımlayıcıların tam listesi. Bu alıcı tanımlayıcıları, katılan özel kitlelerin CustomAudience.getBuyer() oranındaki kısmına karşılık gelir.

Daha özelleştirilmiş reklam seçimi için isteğe bağlı olarak aşağıdaki parametreler belirtilebilir:

• Reklam seçimi sinyalleri: CustomAudience.getBiddingLogicUrl() adresinden getirilen alıcı teklif verme mantığı JavaScript'i tarafından kullanılacak sinyalleri içeren, dize olarak serileştirilmiş bir JSON nesnesi.
• Satıcı sinyalleri: Dize olarak serileştirilmiş, satıcının AdSelectionConfig.getDecisionLogicUrl() kaynağından getirilen JavaScript karar mantığı tarafından kullanılan sinyalleri içeren bir JSON nesnesi.
• Alıcıya göre sinyaller: Dize olarak serileştirilmiş, katılımcı özel kitlelerin alıcı alanları tarafından tanımlanan ve CustomAudience.getBiddingLogicUrl()'den getirilen belirli alıcıların teklif mantığı JavaScript'i tarafından kullanılacak sinyalleri içeren JSON nesnelerinin haritası.
• İçeriğe dayalı reklamlar: Protected Audience açık artırmasının dışında gerçekleşen bir açık artırma sırasında doğrudan alıcılardan toplanan reklam adayları koleksiyonu.

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

• Kazanan reklam için AdData.getRenderUrl() adresinden alınan oluşturma URL'si.
• Cihaz kullanıcısına özel bir reklam seçimi kimliği. Bu kimlik, reklam gösterimini raporlamak için kullanılır.

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

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

Bağlama dayalı reklamlar

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

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

Kotlin

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

Java

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

Ardından elde edilen ContextualAds nesnesi, AdSelectionConfig oluşturulurken bu nesneye aktarılabilir:

Kotlin

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

Java

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

Uygulama yükleme reklam filtrelemesi

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

Bu süreçteki ilk adım, hangi reklamverenlerin yüklü paket üzerinde filtreleme yapabileceğini tanımlamaktır. Bunun, bir reklamla hedeflemek istediğiniz uygulamada gerçekleşmesi gerekir.

Kotlin

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

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

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

Java

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

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

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

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

Sonraki adım, yayıncı uygulamasının içinde reklam filtrelemesini ayarlamaktır. Reklamı yayıncı uygulamasının içinde sunan taraf (büyük olasılıkla bir arz tarafı SDK'sı olabilir) AdFilters nesnesini, filtrelemek istediği uygulamalarla alakalı reklamlarla ilgili bilgilerle başlatmalıdır:

Kotlin

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

Java

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

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

Yeni bir AdData nesnesi örneklenirken de AdFilters geçirilebilir:

Kotlin

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

Java

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

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

Sıklık sınırı filtreleme, reklam teknolojisinin bir reklamın gösterilme sayısını sınırlamasına olanak tanır. Sıklık sınırı filtreleme, reklamın aşırı maruz kalmasını azaltır ve belirli bir reklam kampanyası için alternatif reklam seçimini optimize eder.

Sıklık sınırı filtresinin iki ana bileşeni vardır: reklam etkinlik türü ve reklam sayacı anahtarı. Kullanılabilecek mevcut reklam etkinliği türleri şunlardır:

• Kazan (yakında): Kazanma etkinliği, reklamın bir açık artırmayı kazandığını gösterir. Kazanma etkinlikleri Protected Audience API tarafından otomatik olarak güncellenir ve doğrudan geliştirici tarafından çağrılamaz. Kazanma verileri, yalnızca belirli bir özel kitledeki reklamlar tarafından görüntülenebilir.
• Gösterim: Cihaz üzerinde bir arayan (STP veya MMP), reportImpression'den ayrı olarak, gösterim etkinliklerini seçtikleri kod noktasında çağırmak için updateAdCounterHistogram() kullanır. Gösterim etkinlikleri, belirli bir TTP'ye ait olan tüm reklamlar tarafından görülebilir ve aynı özel kitledeki reklamlarla sınırlı değildir.
• Görüntüleme: Etkinlik, cihaz üzerinde arayan kişi (SSP veya MMP) tarafından updateAdCounterHistogram() numaralı telefonu arayarak kodda seçtikleri bir noktada çağrılır. Görüntüleme etkinlikleri, belirli bir TTP'ye ait olan tüm reklamlar tarafından görülebilir ve aynı Özel Kitle'deki reklamlarla sınırlı değildir.
• Tıklama: Etkinlik, cihaz üzerinde arayan (SSP veya MMP) tarafından updateAdCounterHistogram() numaralı telefonu arayarak kodda seçtikleri bir noktada çağrılır. Tıklama etkinlikleri, belirli bir TTP'ye ait tüm reklamlar tarafından görülebilir ve aynı Özel Kitledeki reklamlarla sınırlı değildir.

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

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

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

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

Kotlin

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

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

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

Java

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

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

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

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

Kotlin

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

Java

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

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

Kotlin

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

Java

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

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

Kotlin

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

Java

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

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

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

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

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

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

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. Bağlama dayalı reklamlar
   4. Puanlama sinyalleri için boş URI. Boş URI'nın, puanlama için güvenilir sinyallerin getirilmesini kullanmak istemediğinizi belirtmesine izin verilir:

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

4. Reklam seçimini yayınla:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

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

Bugün, Özel Korumalı Alan platformunda yalnızca önceden oluşturulmuş URI'lar için kullanılabilen temel bir raporlama JavaScript uygulaması bulunmaktadır. Düşük gecikmeli bir reklam seçimi için önceden oluşturulmuş URI'ları kullanmaya devam ederken kendi raporlama JavaScript'inizi çalıştırmak isterseniz reklam seçimi ile raporlama çalıştırmaları arasında DecisionLogicUri geçersiz kılınabilirsiniz.

1. Önceden oluşturulmuş URI'lar kullanarak içeriğe dayalı reklamlar için reklam seçimini çalıştırma adımlarını çalıştırın

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ını çalıştırma

   // adSelectionId is from the result of the previous selectAds run
   ReportImpressionRequest request = new ReportImpressionRequest(
     adSelectionId,
     adSelectionConfigWithYourReportingJS);
   adSelectionManager.reportImpression(
     request,
     executor,
     outcomeReceiver);
   

Şelale uyumlulaştırmasını çalıştır

Şelale uyumlulaştırması, birden fazla üçüncü taraf SDK'nın (3. taraf ağ) birinci taraf SDK uyumlulaştırma ağı tarafından düzenlenmesini gerektirir. Şelale uyumlulaştırması, açık artırmanın cihazda veya Teklifli Sistem ve Açık Artırma hizmetlerinde (B&A) çalıştırılmasından bağımsız olarak aynı şekilde gerçekleştirilir.

Üçüncü taraf ağları

Üçüncü taraf ağlarının, uyumlulaştırma ağının açık artırma yürütmek için gerekli yöntemleri çağırmasını sağlayan bir bağdaştırıcı sağlaması gerekir:

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

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

Kotlin

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

Java

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

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

Uyumlulaştırma ağı

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

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

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

Uyumlulaştırma ağı, birinci taraf içeriğe dayalı reklamlarını, uyumlulaştırma zincirini ve üçüncü taraf ağların teklif tabanlarını (3. taraf) almaktan sorumludur. Bu durum, uyumlulaştırma ağı tarafından yürütülen içeriğe dayalı reklamlar alma isteğinde gerçekleşebilir. Uyumlulaştırma zinciri, Üçüncü Taraf Ağlar üzerinden nasıl yineleneceğini belirler ve teklif tabanları açık artırma sürecine adSelectionSignals olarak aktarılabilir.

Uyumlulaştırma zincirinde ağ yerleşimi

Uyumlulaştırma SDK'sı, birinci taraf reklam tekliflerindeki etkin eBGBM değerine göre kendisini uyumlulaştırma zincirine yerleştirebilir. Protected Audience API'de reklam teklifleri opaktır. Uyumlulaştırma SDK'sının, belirli bir birinci taraf reklamın teklifini zincirde bir sonraki üçüncü taraf ağın teklif tabanıyla karşılaştırabilmesi için AdSelectionFromOutcomesConfig kullanılması gerekir. Birinci taraf teklifinin teklif tabanından yüksek olması, uyumlulaştırma SDK'sının söz konusu üçüncü taraf ağının önüne yerleştirildiği anlamına gelir.

Reklam seçimini yayınla

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

AdSelectionFromResultsConfig oluşturma

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

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

Kotlin

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

Java

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

    return adSelectionClient.selectAds(config){}
}

Şelale uyumlulaştırması için selectAds() yöntemini geçersiz kılma, aşağıdaki gerekli parametreleri belirtmeniz gereken AdSelectionFromOutcomesConfig girişi gerektirir:

• Satıcı: Reklam seçimini başlatan, satıcı reklam ağının tanımlayıcısı.
• AdSelectionIds: Birinci taraf reklam için önceki selectAds() çalıştırmasının tekil listesi.
• Reklam seçimi sinyalleri: Dize olarak serileştirilmiş, alıcı teklif verme mantığı tarafından kullanılacak sinyalleri içeren bir JSON nesnesi. Bu durumda, belirtilen 3. taraf ağ için alınan teklif tabanını ekleyin.
• Selection Logic URI'si (Seçim Mantığı URI'si): Kazanan bir reklamı seçmek için uyumlulaştırma ağının JavaScript'ini getirmek üzere reklam seçimi sırasında sorgulanan HTTPS URL'si. Bu JavaScript'te gerekli işlev imzalarına bakın. Teklif, teklif tabanından yüksekse JavaScript'in üçüncü taraf reklamı döndürmesi veya null değerini döndürmesi gerekir. Bu, uyumlulaştırma SDK'sının bir kazanan bulunduğunda uyumlulaştırma zincirini kısaltmasını sağlar.

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

Kotlin

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

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

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

Java

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

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

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

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

Aşağıda, uyumlulaştırma süreciyle yürütülecek işlemlerin sırası verilmiştir.

1. Birinci taraf reklam seçimini yayınla.
2. Uyumlulaştırma zincirini tekrarlayın. Her üçüncü taraf ağ için aşağıdakileri yapın:
   1. Birinci taraf outcomeId ve 3. taraf SDK'nın teklif tabanı dahil 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. Mevcut SDK ağ bağdaştırıcısının selectAds() yöntemini çağırın. Sonuç boş olmazsa reklamı döndürün.
3. Zincirde kazanan bulunamazsa birinci taraf reklamı döndürün.

Kotlin

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

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

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

Java

class MediationNetwork {
    AdSelectionManager adSelectionManager;

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

    public void runAdSelection() {...}

    public void reportImpressions() {...}

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

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

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

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

Reklam gösterimlerini raporla

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

Tek STP gösterim raporlaması

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

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: Başarılı bir reklam seçimini tanımlayan, yalnızca cihaz kullanıcısına özgü bir kimlik.
• Reklam seçimi yapılandırması: Sağlanan reklam seçimi kimliği ile tanımlanan selectAds() çağrısında kullanılan yapılandırmanın aynısıdır.

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

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

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

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

STP'ler, bu üçüncü taraf SDK kodu örneğini uyumlulaştırma akışlarına nasıl katılacakları konusunda prototip olarak kullanabilir:

Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
         mediationSdk.orchestrateMediation(mediationChain);

if (winner.first.hasOutcome()) {
      winner.second.reportImpressions(winner.first.getAdSelectionId());

Gösterim raporlama uç noktaları

Rapor gösterimi API'si, satıcı tarafı platformu ve kazanan alıcı tarafı platformu tarafından sağlanan uç noktalara HTTPS GET istekleri gönderir:

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

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

Satış tarafı platform uç noktası:

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

Teklifli sistem ve açık artırma hizmetleri raporları

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

En yüksek çaba Gösterim raporlaması

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

Not:

• API, gösterim raporlama URL'lerini JavaScript işlevlerinden belirleyemezse 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ümler için geçici hatalar için yeniden deneme mantığı planlanmaktadır.
• Aynı parametrelerle reportImpression() için birden fazla çağrı, reklam seçimi sonuçlarınızın birden çok kez raporlanmasına neden olabilir.

Reklam Etkileşimlerini Rapor Etme

Korunan Kitle, oluşturulan reklam için daha ayrıntılı etkileşimler hakkında rapor oluşturma desteği sağlar. Buna görüntüleme süresi, tıklama sayısı, fareyle üzerine gelme sayısı gibi etkileşimler veya toplanabilecek diğer faydalı metrikler dahildir. Bu raporları alma süreci iki adımdan oluşur. Öncelikle, alıcılar ve satıcıların raporlama JavaScript'inde bu raporları almak için kaydolması gerekir. Ardından, istemcinin bu etkinlikleri raporlaması gerekir.

Etkileşim etkinliklerini almak için kaydolma

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

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

    return reportingUrl;
}

Not: Raporları almak için etkileşim anahtarı dizelerinin satıcının raporladıkları dizeyle 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ıcı 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 hedefine sahip bir ReportInteractionRequest nesnesi oluşturun.
3. Eşzamansız reportInteraction() yöntemini request nesnesiyle ve ilgili Executor ile OutcomeReceiver nesneleriyle çağırın.

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

// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
  new ReportInteractionRequest.Builder()
    .setAdSelectionId(adSelectionId)
    .setInteractionKey("view")
    .setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
    .setReportingDestinations(
      FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
    )
    .build();

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

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

• Reklam seçimi kimliği: Daha önce döndürülen bir AdSelectionOutcome reklam seçimi kimliği.
• Etkileşim Anahtarı: Müşteri tarafından tanımlanan ve raporlanmakta olan işlemi açıklayan bir dize anahtarı. Bu değer, satıcı veya alıcı tarafından raporlama JavaScript işlevlerine kaydedilen anahtarla eşleşmelidir.
• Etkileşim Verileri: Raporlama sunucularına POSTlanacak ve etkinlik raporuna dahil edilecek verileri içeren bir dize.
• Raporlama Hedefleri: Etkinliklerin alıcıya, satıcıya veya her ikisine de bildirilmesi gerektiğini belirten bir bit maskesi. Bu işaretler platform tarafından sağlanır ve son hedef maskesi bit tabanlı işlemler kullanılarak oluşturulabilir. Tek bir hedefe bildirmek için doğrudan platform tarafından sağlanan işareti kullanabilirsiniz. Birden fazla hedefe yönelik rapor oluşturmak için bit tabanlı VEYA (|) kullanarak işaret değerlerini birleştirebilirsiniz.

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

• onResult() geri çağırması, rapor etkileşim çağrısının geçerli olduğunu gösterir.
• onError() geri çağırması aşağıdaki olası koşulları gösterir:
  • Uygulama arka planda çalışırken çağrı yapılırsa hatanın açıklamasını içeren bir IllegalStateException döndürülür.
  • İstemcinin reportInteraction() çağrısı yapması kısıtlanırsa LimitExceededException döndürülür.
  • Paket, Gizliliği Koruma API'lerini çağırmak için kayıtlı değilse SecurityException() döndürülür.
  • Uygulama raporlama etkileşimleri, selectAds() çağrısı yapan uygulamadan farklı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 Kitle'nin bir noktada etkileşimleri bildirmeye çalışacağını garanti eder.

Etkileşim raporlama uç noktaları

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

En iyi çaba Etkileşim raporlaması

reportInteraction(), HTTP POST aracılığıyla raporlamanın en iyi şekilde tamamlanmasını sağlamak için tasarlanmıştır.

Günlük arka plan güncellemesi

Özel kitle oluştururken uygulamanız veya SDK'nız, özel kitle meta verilerini başlatabilir. Ayrıca platform, aşağıdaki özel kitle meta verisi parçalarını günlük bir arka plan güncelleme işlemiyle güncelleyebilir.

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

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

• JSON yanıtı, güncellenmesi gereken desteklenen meta veri alanlarından herhangi birini içerebilir.
• Her JSON alanı bağımsız olarak doğrulanır. İstemci, hatalı biçimlendirilmiş alanları yoksayar. Bu durum, yanıttaki söz konusu alanda güncelleme yapılmasına neden olmaz.
• Boş bir HTTP yanıtı veya boş bir JSON nesnesi ("{}"), meta veri güncellemesine neden olmaz.
• Yanıt iletisi boyutu 10 KB ile sınırlı olmalıdır.
• HTTPS kullanmak için tüm URI'ler gereklidir.
• trusted_bidding_uri, alıcı ile aynı ETLD+1'i paylaşmalıdır.

Örnek: Arka planda günlük güncelleme için JSON yanıtı

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

Reklam seçimi için JavaScript

Reklam seçimi iş akışı, alıcı ve satıcı tarafından sağlanan JavaScript'in yürütülmesini düzenler.

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

• generateBid()
• reportWin()

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()
• reportResult()

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

  Bu örnekte:

  • 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ştirme ve geçerlilik bitiş zamanıdır. Unix dönemi'nden bu yana saniye olarak ifade edilir.
  • ca_user_bidding_signals, oluşturulma sırasında CustomAudience öğesinin userBiddingSignals alanında belirtilen bir JSON dizesidir
  • trusted_bidding_signals, contextual_signals ve user_signals, JSON nesneleridir. Bunlar boş nesne olarak aktarılır ve gelecekteki sürümlerde doldurulur. Biçimleri platform tarafından zorunlu kılınmaz ve reklam teknolojisi tarafından yönetilir.

Sonuç:

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

puanAd()

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

Giriş parametreleri:

• ad: generateBid belgelerini inceleyin
• bid: reklamın teklif değeri

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

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

• seller_signals: sellerSignals AdSelectionConfig API parametresinden okunan JSON nesneleri

• trusted_scoring_signal: AdSelectionConfig API parametresindeki adSelectionSignals alanından okur

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

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

Çıkış:

• score: Bu reklamın puan değerini temsil eden bir kayan değer
• status: Şu olabilecek bir tam sayı değeri:
  • 0: başarılı bir yürütme için
  • 1: customAudienceSignals geçersizse
  • 2: AdSelectionConfig geçersizse
  • 3: diğer sinyallerden herhangi birinin geçersiz olması durumunda
  • Sıfır olmayan herhangi bir değer işlemin başarısız olmasına neden olur. Değer, işlemden etkilenen

selectOutcome()

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

Giriş parametreleri:

• outcomes: Bir JSON nesnesi {"id": id_string, "bid": bid_double}
• selection_signals: Açık artırma yapılandırma nesnesinde belirtilen JSON nesneleri

Çıkış:

• status: Başarılı için 0, başarısız için sıfır değil
• result: Geçirilen sonuçlardan biri veya null

reportResult()

function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
   return {
      'status': status,
      'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
   };
}

Giriş parametreleri:

• ad_selection_config: scoreAds belgelerine bakın
• render_url: kazanan reklamın oluşturma URL'si
• bid: kazanan reklam için sunulan teklif
• contextual_signals: generateBid belgelerine bakın

Çıkış:

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

reportWin()

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

Giriş parametreleri:

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

Çıkış:

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

registerAdBeacon()

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 bilgi, daha sonra etkinlik etkileşimleri bildirilirken bildirilecek reporting_uri olup olmadığına bakmak için platform tarafından kullanılır. Bu anahtarın, alıcının veya satıcının kaydettikleri ile satıcının bildirdikleri arasında eşleşmesi gerekir.
• reporting_uri: Etkinlik raporlarını alacak bir URI. Bu, raporlanan etkinlik türüne özel olmalıdır. Etkinlikle birlikte bildirilen tüm verileri işlemek için POST isteğini kabul etmelidir.

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

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

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

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

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

Aşağıdaki durumlarda IllegalArgumentException atılır:

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

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

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

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

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

Bu önceden oluşturulmuş URI, teklif verdikten sonra en yüksek teklife sahip reklamı seçen bir JavaScript sağlar. Ayrıca kazananın render_uri ve bid değerlerini raporlayan temel bir raporlama işlevi sağlar.

Gerekli parametreler

reportingUrl: Kazanan reklamın render_uri ve bid ile parametreleştirilmiş temel raporlama URL'si:

<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>

Kullanım

Temel raporlama URL'niz https://www.ssp.com/reporting ise önceden oluşturulmuş URI şöyle olur:

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

2. kullanım alanı: reklam seçimi-sonuçları

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

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

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

Gerekli parametreler

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

Kullanım

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

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

Test

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

Ön koşullar

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

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

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

HTTPS uç noktaları

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

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

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

JavaScript'in uzaktan getirilmesini geçersiz kıl

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

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

<application
  android:debuggable="true">

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

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

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

Geçersiz kılma sağlamadığınız JavaScript'leri sunmak için bir HTTPS uç noktasına ihtiyacınız olsa da, satıcı tarafı ve alıcı tarafı JavaScript getirme işlemini bağımsız olarak geçersiz kılmak mümkündür. Bu tür durumları ele alacak bir sunucunun nasıl ayarlanacağı hakkında bilgi edinmek için lütfen BENİOKU sayfasına bakın.

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

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

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

1. Bir AdSelectionManager nesnesini başlatın.
2. AdSelectionManager nesnesinden TestAdSelectionManager referansı alın.
3. AdSelectionConfig nesnesi oluşturun.
4. AdSelectionConfig nesnesiyle bir AddAdSelectionOverrideRequest ve geçersiz kılma olarak kullanmayı düşündüğünüz JavaScript'i temsil eden bir String oluşturun.
5. Eşzamansız overrideAdSelectionConfigRemoteInfo() yöntemini AddAdSelectionOverrideRequest nesnesi ve ilgili 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 her bir alanın neyi temsil ettiği hakkında daha fazla bilgi için Reklam seçimini çalıştırma bölümüne bakın. Aradaki temel fark, decisionLogicUrl öğesinin yok sayılacağı için bir yer tutucu değere ayarlanmasıdır.

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

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

onResult() geri çağırması, geçersiz kılma işleminin başarıyla uygulandığını belirtir. Gelecekteki selectAds() çağrıları, geçersiz kılma olarak iletmiş olduğunuz kararı ve raporlama mantığını kullanacaktır.

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

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

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

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

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

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 getirmek için AdSelectionConfig içinde depolanan decisionLogicUrl öğelerini kullanır.

resetAllAdSelectionConfigRemoteOverrides() çağrısı başarısız olursa OutComeReceiver.onError() geri çağırması bir AdServiceException sağlar. Geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulama varken geçersiz kılmaların kaldırılması girişiminde bulunursa AdServiceException neden olarak IllegalStateException değerini belirtir.

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

1. Özel bir kitleye katılma adımlarını uygulayın
2. Teklif verme mantığı ve geçersiz kılma olarak kullanmak istediğiniz verilere ek olarak geçersiz kılmak istediğiniz özel kitlenin alıcısı ve adı ile bir AddCustomAudienceOverrideRequest oluşturun.
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ılma işleminin başarıyla uygulandığını belirtir. selectAds() için yapılan sonraki çağrılar, geçersiz kılma olarak geçirdiğiniz teklif ve raporlama mantığını kullanır.

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

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

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

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

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

1. Alakalı 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, sonraki selectAds() çağrıları, gerekli JavaScript'i getirmeye çalışmak için CustomAudience içinde depolanan biddingLogicUrl ve trustedBiddingData öğelerini kullanır.

resetCustomAudienceRemoteInfoOverride() çağrısı başarısız olursa OutComeReceiver.onError() geri çağırması bir AdServiceException sağlar. Geliştirici seçenekleri etkinken hata ayıklama modunda çalışmayan bir uygulama varken geçersiz kılmaların kaldırılması denenirse neden AdServiceException simgesi olarak IllegalStateException belirtilir.

Raporlama Sunucusu Kurma

Uzaktan getirme geçersiz kılma işlemlerini kullandığınızda, raporlama etkinliklerine yanıt vermek için cihazınızın veya emülatörünüzün erişebileceği bir sunucu ayarlamanız gerekir. 200 döndüren basit bir uç nokta test için yeterlidir. GitHub deposu, desteklenen bir örnek veya mikro hizmet platformuna dağıtılabilen OpenAPI hizmet tanımları içerir. Daha fazla bilgi için BENİOKU projesine göz atın.

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

Test edilecek işlev

• Katılma veya ayrılma ve önceki kullanıcı işlemlerine dayalı özel bir kitle oluşturma alıştırması yapın.
• Cihaz üzerinde reklam seçiminin başlatılmasını, uzaktan barındırılan JavaScript'ler aracılığıyla gerçekleştirin.
• Bir uygulamanın özel kitle ayarlarıyla ilişkilendirmesinin reklam seçimi sonuçlarını nasıl etkileyebileceğini gözlemleyin.
• Reklam seçiminden sonra gösterim raporlaması yapın.

Sınırlamalar

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

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

Hataları ve sorunları bildirme

Geri bildirimleriniz, Android'deki Özel Korumalı Alan için çok önemlidir. Android'de Özel Korumalı Alan'ın iyileştirilmesiyle ilgili sorunları veya fikirlerinizi bizimle paylaşabilirsiniz.