Protected Audience API geliştirici kılavuzu

Android'de Özel Korumalı Alan'ı okurken dokümanlarında, Geliştirici Önizlemesi veya Beta düğmesini kullanarak program sürümüne geçiş yapabilirsiniz. Bunun için talimatlar farklılık gösterebilir.

Geri bildirim gönderin

Android'deki Protected Audience API (eski adıyla FLEDGE) şunları içerir: Custom Audience API ve Reklam Seçimi API'si. Reklam teknolojisi platformları ve reklamverenler önceki uygulama etkileşimine dayalı özel reklamlar sunmak için bu API'leri kullanabilir. Tanımlayıcıların uygulamalar arasında paylaşımını ve bir kullanıcının uygulamasının paylaşımını sınırlar üçüncü taraflarla olan etkileşim bilgileri.

Custom Audience API "özel kitle" merkezlidir soyutlama, ortak amaçlara sahip bir kullanıcı grubunu temsil eder. Reklamveren, bir kullanıcıyı özel bir kitleye kaydedebilir ve alakalı reklamları ilişkilendirebilir gerçekleşebilir. Bu bilgiler, yerel olarak depolanır ve reklamvereni bilgilendirmek için kullanılabilir. ve reklam oluşturmayı kapsar.

Reklam Seçimi API'si birden fazla geliştiricinin şunları yapmasına olanak tanıyan bir çerçeve sağlar: Özel bir kitle için yerel olarak açık artırma düzenleyebilirsiniz. Bunun için sistem özel kitleyle ilişkili reklamları dikkate alır ve Bir reklam teknolojisi platformunun cihaza döndürdüğü reklamlar üzerinde ek işlemler.

Reklam teknolojisi platformları, yeniden pazarlamayı uygulamak için bu API'leri Kullanıcı gizliliğini korur. Uygulama yükleme gibi ek kullanım alanları için destek reklamların yayınlanması planlanmaktadır. Protected Audience hakkında daha fazla bilgi API'yi Android'de tasarım teklifinde bulabilirsiniz.

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

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

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

      adb shell device_config put adservices ppapi_app_allow_list \"*\"

  4. Uygulamanıza ACCESS_ADSERVICES_CUSTOM_AUDIENCE izni ekleyin manifesto:

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

  5. Şu öğenin <application> öğesinde bir reklam hizmetleri yapılandırmasına başvuruda bulun: manifest dosyanız:

      <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. Örneğin: res/xml/ad_services_config.xml Reklam hizmetleri izinleri hakkında daha fazla bilgi SDK erişim denetimi.

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

  7. Reklam Seçimi API'si varsayılan olarak sınırları zorunlu kılar bir açık artırmanın veya gösterimin raporladığı maksimum bellek miktarına göre ayırabilir. Bellek sınırlaması özelliği için WebView sürümü gereklidir 105.0.5195.58 veya sonraki sürümler. Platformda sürüm kontrolü zorunlu kılınır ve Bu durumda selectAds ve reportImpression API'leri başarısız olur. memnun kalmadığından emin olun. Bunu iki ş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 daha önce belirtilen sürüme eşit veya bundan daha yüksek olması gerekir.

Özel kitleye katılın

Özel kitle, ortak amaçlara sahip veya reklamveren uygulaması tarafından belirlenen ilgi alanları. Bir uygulama veya SDK, belirli bir kitleyi belirtmek için kullanılır (örneğin, yalnızca hakkında daha fazla bilgi edindiniz. Eşzamansız olarak bir özel kitle oluşturmak veya bir özel kitleye katılmak için takip etmek için:

  1. CustomAudienceManager nesnesini başlatın.
  2. Şu gibi anahtar parametreleri belirterek bir CustomAudience nesnesi oluşturun: paketine ve alakalı bir ada yer verilmelidir. Ardından, CustomAudience içeren JoinCustomAudienceRequest nesnesi nesnesini tanımlayın.
  3. Eş zamansız joinCustomAudience() çağrısı için JoinCustomAudienceRequest nesnesi ile alakalı Executor ve OutcomeReceiver nesneleri.

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 her bir parametrenin her birini benzersiz bir şekilde Cihazda CustomAudience nesnesi:

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

joinCustomAudience(), farklı bir örnekle tekrar tekrar çağrılıyor CustomAudience, mevcut CustomAudience öğesini şununla günceller: eşleşen owner, buyer ve name parametreleri. Gizliliğin korunmasına yardımcı olmak için "üreme" kavramını birbirinden ayırt edememesi nedeniyle ve "güncelle".

Ayrıca, CustomAudience bu gereklilerle oluşturulmalıdır parametre:

  • Günlük güncelleme URL'si: Bir HTTPS URL'si için arka planda her gün sorgulanan Özel bir kitlenin kullanıcı teklif sinyallerini, güvenilir teklif verilerini ve reklamlar için URL'ler ve meta veriler oluşturun.
  • Teklif verme mantığı URL'si: Reklam seçimi sırasında alıcının JavaScript teklif verme mantığını temel alır. Gerekli işlev imzalarına bakın işleyeceğiz.
  • Reklam Oluşturma Kimlikleri: Alıcı reklam teknolojisi tarafından ayarlanan rastgele bir kimlik. Bu bir B&A yükünü oluşturma optimizasyonu.

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

  • Etkinleştirme süresi: Özel kitleler yalnızca reklam seçimine katılabilir. ve günlük güncellemelerden haberdar olmanız gerekir. Bu yöntem, bir iş görüşmesinde Örneğin uygulamanın etkin olmayan kullanıcıları.
  • Geçerlilik bitiş zamanı: Özel kitlenin cihazdan kaldırılır.
  • Kullanıcı teklif verme sinyalleri: Kullanıcı sinyallerini içeren bir JSON dizesi (ör. kullanıcının teklif verme mantığı JavaScript'inin kullandığı, kullanıcının tercih ettiği yerel ayar reklam seçim sürecinde teklifler oluşturmak için. Bu biçim, reklam teknolojisinin platformlar, kodları farklı platformlarda yeniden kullanır ve JavaScript'te kullanımı kolaylaştırır işlevlerine dahildir.
  • Güvenilir teklif verileri: Bir HTTPS URL'si ve güvenilir bir Anahtar/Değerden teklif sinyalleri getiren reklam seçim süreci geliştirmenizi sağlar.
  • Reklamlar: Gösterilen reklamlara karşılık gelen AdData nesnelerinin listesi Reklam seçimine katılmalıdır. Her AdData nesnesi şunlardan oluşur:
    • Oluşturma URL'si: Nihai reklamı oluşturmak için sorgulanan bir HTTPS URL'si.
    • Meta veri: Şu bilgileri içeren bir dize olarak serileştirilmiş bir JSON nesnesi: tarafından tüketilir.
    • Reklam Filtreleri: Uygulama için gerekli tüm bilgileri içeren bir sınıf Reklam seçimi sırasında reklam filtreleme ve sıklık sınırı uygulayın.
ziyaret edin.

Aşağıda, CustomAudience nesnesi örneklendirmesi için bir örnek 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, OutcomeReceiver yöntemini kullanır nesnesini ifade eder.

  • onResult() geri çağırması, özel kitlenin başarıyla tamamlandığını belirtir oluşturabilir veya güncelleyebilir.
  • onError() geri çağırması iki olası koşulu belirtir.

Aşağıda, joinCustomAudience() sonucunun ele alınmasına dair 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 kitleden ayrılma

Kullanıcı belirli bir özel için iş ölçütlerini artık karşılamıyorsa bir uygulama veya SDK, özel öğeyi kaldırmak için leaveCustomAudience() gerçekleşebilir. Benzersiz değerine göre bir CustomAudience kaldırmak için parametreleri için şunları yapın:

  1. CustomAudienceManager nesnesini başlatın.
  2. LeaveCustomAudienceRequest grubunu özel kitlenin buyer ve name. Bu giriş alanları hakkında daha fazla bilgi edinmek için "Özel bir kitleye katılın."
  3. Eşzamansız leaveCustomAudience() yöntemini LeaveCustomAudienceRequest nesnesi ile alakalı Executor ve OutcomeReceiver nesneleri.

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 sinyalleri sona ermelidir. Gizliliğin korunmasına yardımcı olmak için yapılan hatalar, dahili hatalar ile geçersiz bağımsız değişkenleri birbirinden ayırt etmeye çalışın. onResult() geri çağırma, eşleşen bir eşleşme olup olmadığına bakılmaksızın API çağrısı tamamlandığında çağrılır özel kitle başarıyla kaldırıldı.

Reklam seçimini yayınla

Reklam seçmek üzere Protected Audience API'yi kullanmak için 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 ile alakalı Executor ve OutcomeReceiver nesneleri.

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 bir AdSelectionConfig girişi gerektirir. Burada aşağıdaki gerekli parametreleri belirtmelisiniz:

  • 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ığı.
    • HTTPS URL'si: Satıcı reklam ağının JavaScript mantığını almak için sorgulandı. Gerekli işlev imzalarına bakın.
    • Önceden oluşturulmuş URI: FLEDGE'in reklam seçim biçimini takip eden. Desteklenmeyen veya hatalı bir dosyaysa IllegalArgumentException atlanır önceden oluşturulmuş URI iletildi.
  • Özel kitle alıcıları: Alıcı reklam ağları için tanımlayıcıların tam listesi Satıcı tarafından reklam seçim sürecine katılmasına izin verilen reklamlar. Bu alıcı tanımlayıcıların CustomAudience.getBuyer() kadarı dahil olan özel kitlelerdir.

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

  • Reklam seçimi sinyalleri: Dize olarak serileştirilmiş bir JSON nesnesi; şunları içerir: JavaScript'in getirdiği alıcı teklif mantığı tarafından tüketilecek sinyaller: CustomAudience.getBiddingLogicUrl().
  • Satıcı sinyalleri: Sinyaller içeren, dize olarak serileştirilmiş bir JSON nesnesi tarafından getirilen JavaScript karar mantığı, AdSelectionConfig.getDecisionLogicUrl().
  • Alıcı başına sinyaller: Dize olarak serileştirilmiş JSON nesnelerinin bir haritası Belirli alıcılar tarafından tüketilecek sinyalleri içeren teklif mantığı JavaScript'i getirme kaynağı CustomAudience.getBiddingLogicUrl() olan katılımcı özel kitlelerin alıcı alanları
  • İçeriğe dayalı reklamlar: Doğrudan toplanan bir dizi reklam adayı Protected Audience dışında gerçekleşen bir açık artırma sırasında alıcılardan açık artırmadır.

Bir reklam seçildikten sonra sonuçlar, teklifler ve sinyaller dahili olarak korunur. raporlama için kullanılır. OutcomeReceiver.onResult() geri çağırması, Şunları içeren AdSelectionOutcome:

  • Kazanan reklam için AdData.getRenderUrl() adresinden elde edilen oluşturma URL'si.
  • Cihaz kullanıcısına özgü bir reklam seçim kimliği. Bu kimlik raporlama için kullanılır reklam gösterimini artırır.

Reklam seçimi, veya aşırı kaynak tüketimi ya da geçersiz kaynakların kullanımının neden olduğu OutcomeReceiver.onError() geri çağırması, AdServicesException sağlar aşağıdaki davranışlarla:

  • Reklam seçimi geçersiz bağımsız değişkenlerle başlatılırsa AdServicesException, bir IllegalArgumentException öğesinin pek çok yolu vardır.
  • Diğer tüm hatalar için AdServicesException IllegalStateException nedeni gösterilir.

Bağlama dayalı reklamlar

Korunan kitle, korumalı açık artırmalara bağlamsal reklamlar ekleyebilir. İçeriksel reklamların reklam teknolojisi sunucusunda seçilmesi ve Protected Audience API'lerin dışındaki cihazlarda. İçeriğe dayalı reklamlar, AdSelectionConfig kullanarak açık artırmaya girerler. Bu noktada negatif reklam filtrelemesine uygunluk dahil olmak üzere, cihaz reklamlarıyla aynıdır. Bir Protected Audience açık artırması tamamlandı. reportImpression() Bu, kazanan içeriksel reklamda reportWin() çağrısı kazanan reklamı almak için gösterim raporlaması ile aynı kalıbı olanak tanır. Her içeriksel reklam için bir alıcı, teklif, raporlama mantığı için bir bağlantı, oluşturma URL'sini ve reklam meta verilerini içerir.

İçeriğe dayalı reklamları uygulamada dağıtmak için hedef uygulamanın ContextualAds nesne:

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();

Elde edilen ContextualAds nesnesi daha sonra AdSelectionConfig:

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ı filtreleme

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

Bu süreçteki ilk adım, hangi reklamverenlerin bu hedefe ulaşmak için yüklü paketi filtrelemeniz gerekir. Bu işlemin istediğiniz uygulamada yapılması gerekir hedeflemenize olanak tanır.

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, aktarılan reklamverenler daha sonra teklif oluştururken belirttiğiniz yüklü uygulamaları filtreleyerek hariç tutabilir. Eğer bir reklamverenin bu uygulamanın yükleme işlemlerine erişimini kaldırmanız gerekiyor durumunda, reklamverenin bilgileri kaldırılmış olarak bu kodu tekrar çalıştırın.

Bir sonraki adım, yayıncı uygulamasında reklam filtrelemeyi ayarlamaktır. Projenin gidişatını Reklamı, yayıncı uygulamasının içinde yayınlar (büyük olasılıkla arz tarafı SDK'sı olur) AdFilters nesnesini, hangi reklamlarla ilgili bilgilerle başlatmalı? ilgili başka bir örnek:

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ı,AdFilter kitlesine nasıl ulaşılacağını gösterir.

AdFilters, yeni bir AdData örneklendirme aşamasında da iletilebilir. nesne:

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 teknolojilerinin bir reklamın gösterilme sayısını sınırlamasını sağlar. gösteriliyor. Sıklık sınırı filtreleme, reklamlara aşırı maruz kalmayı azaltır ve alternatif reklamları optimize eder belirli bir reklam kampanyası için reklam seçimi

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

  • Kazan (çok 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ılması gerekir. Kazanma verileri yalnızca şuradaki reklamlara görünür: elde edebilirsiniz.
  • Gösterim: Cihaz üzerinde bir arayan (SSP veyareportImpression MMP),updateAdCounterHistogram() bir seçenek belirleyin. Gösterim etkinlikleri, ait olan tüm reklamlar tarafından görülebilir belirli bir TTP ile uyumludur ve aynı özel kitledeki reklamlarla sınırlı değildir.
  • Görünüm: Etkinlik, cihazda arayan kişi (SSP veya MMP) tarafından belirli bir noktada çağrılır. updateAdCounterHistogram() numaralı telefona çağrı yaparak seçtikleri kod. Etkinlikleri görüntüle: belirli bir TTP'ye ait olan tüm reklamlar tarafından görülebilir ve aynı Özel Kitle.
  • Tıklama: Etkinlik, cihazda arayan kişi (SSP veya MMP) tarafından belirli bir noktada çağrılır. updateAdCounterHistogram() numaralı telefona çağrı yaparak seçtikleri kod. Tıklama etkinlikleri Belirli bir TTP'ye ait tüm reklamlar tarafından görülebilir ve aynı Özel Kitle.

Yayıncı uygulamasında, cihazda varlığı olan bir STP veya MMP, reklamı çağırır. etkinlikler. updateAdCounterHistogram() çağrıldığında, bir frekansın sayacı teklif sınırlama filtresi, gelecekteki açık artırmaların güncel olması için Kullanıcının belirli bir reklamla karşılaşmasıyla ilgili bilgiler. Reklam etkinliği türleri kullanıcıları eyleme zorlamak için kullandıkları yönergelerdir ve yapılandırmalarına yardımcı olur. Reklam sayaçlarını şu zamanda artırmak için: Bir etkinlikte, cihaz üzerindeki aktör, kazanan reklam açık artırmasının reklam seçim kimliğini sağlar.

Reklam sayacı anahtarları, alıcı reklamı 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. Reklamdan bu yana Sayaç anahtarları yalnızca belirli bir TTP'ye ait reklamlarla sınırlıdır. Bu anahtarlar başka bir reklam teknolojisine ait histogramlarla çakışmadan seçilir. Reklam sayacı anahtarlar, bir TTP'nin reklamları genelinde veya belirli bir bölümde DSP'ye özel tanımlayıcıları artırmak için kullanılır gelecekteki açık artırmalarda yer alan reklamları filtrelemek için belirli bir özel kitleyi kullanabilirsiniz.

Sayaç anahtarları, yayınlanma olasılığı daha yüksek olan reklamlara öncelik vermek için kullanılabilir belirli bir cihazdaki diğer reklamlarla olan etkileşimine dayalı olarak, belirli bir kullanıcının teknolojisinin aynısını kullanın. Örneğin, yüksek seviyede puan alan bir reklam ve tıklamalardan elde edilen etkileşimlerin, reklam açık artırmalarının, görüntüleme veri noktası. Bu noktayı daha ayrıntılı açıklamak gerekirse: sol elle golf sopalarına ilişkin bir reklam kullanıcının sağ elini kullanmak istemeyeceğine işaret edebilir. CEVAP sol yönlü reklamlara atanan bir sayaç tuşu için sıklık sınırı filtresi sağ elle tutuşan sopalarla ilgili reklamları filtreleyin.

Açık artırmanızda sıklık sınırını kullanmak için öncelikle Aşağıda gösterildiği gibi KeyedFrequencyCap nesne var:

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 nesne oluşturulduktan sonra bunları bir AdFilters nesne algılandı.

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 aktarılır:

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, SSP ve ardından gerekli tıklama, görüntüleme veya gösterim etkinliklerini çağırır.

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 filtrelenir elde etmeye başladı. Filtreleme, teklif mantığı yürütülmeden önce gerçekleşir. cihaz üzerinde açık artırmalar yapabilir ve Teklif Verme ve Açık artırma açık artırmaları kullanır.Bu araç seti, reklam teknisyenlerine her bir elektronik tabloda Reklama odaklanmak için kullanıcılarla ve özel kitlelerindeki reklamlar arasındaki etkileşimler hem de reklama aşırı maruz kalma oranını en aza indirir.

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

Cihazda yeniden pazarlama talebi yoksa şunun için reklam seçimi çalıştırabilirsiniz: ağ aramaları içermeyen bağlamsal reklamlar Önceden oluşturulmuş URI'lar ve bağlamsal reklamları tekliflerle birlikte kullandığınızda, platform teklif mantığı ve teklif sinyalleri ve puanlama sinyalleri gibi. Platform, seçmek için önceden oluşturulmuş bir URI kullanır en yüksek teklifi veren içeriğe dayalı reklam

Gecikmeyi iyileştirmek için reklam teknolojileri yalnızca şunları içeren bir reklam seçimi akışı çalıştırabilir: (ağ çağrıları olmadan reklam filtreleme işlevine sahip içeriğe dayalı reklamlar) Bu , puanlama sinyalleri için önceden oluşturulmuş URI'lar kullanılarak elde edilir. Daha fazla bilgi için Desteklenen scoreAds listesi için önceden oluşturulmuş URI kullanım alanları ve adları bölümü hakkında bilgi edindiniz.

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

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

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

    1. Boş alıcı listesi
    2. En yüksek teklifi seçmek için önceden oluşturulmuş bir URI
    3. Bağlama dayalı reklamlar
    4. Puanlama sinyalleri için boş bir URI. Boş URI, kullanabilirsiniz:
    Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting");
// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUri(prebuiltURIScoringUri)
    .setCustomAudienceBuyers(Collections.emptyList())
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(buyerContextualAds)
    .setTrustedScoringSignalsUri(Uri.EMPTY)
    .build();

  4. Reklam seçimini çalıştır:

    adSelectionManager.selectAds(
    adSelectionConfig,
    executor,
    outcomeReceiver);

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

Şu anda Özel Korumalı Alan platformunda yalnızca temel raporlama JavaScript'i vardır. önceden oluşturulmuş URI'lar için uygulanabilir. Kendi kampanyalarınızı Düşük gecikmeli bir reklam için önceden oluşturulmuş URI'lar kullanırken JavaScript raporlaması yapma reklam seçimi ile reklam seçimi arasındaki DecisionLogicUri değerini geçersiz kılabilirsiniz. raporlamanın nasıl çalıştığını gösterir.

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

  2. 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 raporları çalıştırma

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

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

Şelale uyumlulaştırması, birden fazla üçüncü taraf SDK'nın (3. taraf ağlar) birinci taraf SDK uyumlulaştırma ağı tarafından düzenlenir. Şelale uyumlulaştırması veya açık artırmanın cihaz üzerinde ya da cihazda gerçekleştirilmiş Teklif verme ve Açık artırma hizmetleri (B&A).

3. taraf ağlar

3. taraf ağların, uyumlulaştırma ağının Açık artırma yürütmek için gerekli yöntemleri çağırmak

  • 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 vardır. selectAds ve reportImpressions uygulaması. SDK sağlayıcılar, cihaz üzerinde açık artırmalar için reklam seçiminin nasıl yayınlanacağı veya B&A açıklayıcısı ele alacağız. Reklam bildirme işleminin nasıl yapılacağını izleyin gösterim (daha sonra tek STP gösterimi raporlaması raporlama.

Uyumlulaştırma ağı

3. taraf ağlara benzer şekilde, uyumlulaştırma ağları için selectAds ve reportImpression uygulama. Reklam yayınlamayla ilgili bölümlere bakın seçimi ve reklam gösterimlerinin nasıl raporlanacağı hakkında daha fazla bilgi edinin.

Uyumlulaştırma ağları, uyumlulaştırma zincirini çalıştırmaktan ve uyumlulaştırma zincirinde yer alır. Sonraki bölümde, ayarlarınızı nasıl ve ne zaman bu süreci yürütür.

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

Uyumlulaştırma ağı, birinci tarafın (birinci taraf) alınmasından sorumludur bağlamsal reklamlar, uyumlulaştırma zinciri ve üçüncü taraf ağlar teklif tabanları (3. taraf). Bu uyumlulaştırma tarafından yürütülen bağlamsal reklamları alma isteğinde gerçekleşebilir ağ. 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ı, yayındaki eBGBM'sine göre kendisini uyumlulaştırma zincirine yerleştirebilir %41 daha yüksek. Protected Audience API'de reklam teklifleri opaktır. Arabuluculuk SDK, birinci taraf karşılaştırması yapabilmek için AdSelectionFromOutcomesConfig kullanmalıdır. reklamın teklifini, zincirdeki bir sonraki 3. taraf ağının teklif tabanına göre ayarlayabilirsiniz. Birinci taraf teklifi teklif tabanının üzerinde olması, uyumlulaştırma SDK'sının ön plana yerleştirilir. arasında yer alır.

Reklam seçimini yayınla

Uyumlulaştırma ağı, birinci taraf reklam adayını almak için cihaz üzerinde bir anlaşma yürütebilir. reklam seçimini yayınlama bölümündeki adımları uygulayarak açık artırmayı etkinleştirin. Bu, 1. taraf reklam adayı, teklif ve uyumlulaştırmada kullanılan AdSelectionId bahsedeceğim.

AdSelectionFromResultsConfig oluşturma

AdSelectionFromOutcomesConfig, uyumlulaştırma ağının listeyi aktarmasına olanak tanır AdSelectionIds (önceki açık artırmaların sonuçları), reklam seçimi sinyalleri ve Birden çok aday arasından bir reklam seçen JavaScript'i getirmek için bir URI. Liste teklifleri ve sinyalleri ile birlikte AdSelectionId'nin Teklifi geçerse AdSelectionIds özelliklerinden birini döndürebilen JavaScript taban veya "yok" değerini seçin.

Uyumlulaştırma Ağları birinci taraf kullanarak bir AdSelectionFromOutcomesConfig oluşturur Önceki bölümden AdSelectionId ve Üçüncü Taraf Ağı için teklif tabanı düşünmeleri gerekir. Yeni bir AdSelectionFromOutcomesConfig oluşturulmalıdır her adım için ayrı ayrı gösterilir.

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 işlemi için bir Aşağıdakileri belirtmeniz gereken AdSelectionFromOutcomesConfig girişi gerekli parametreler:

  • Satıcı: Reklam seçimini başlatan satıcı reklam ağının tanımlayıcısı.
  • AdSelectionIds: Birinci taraf için önceki selectAds() çalıştırmasının tekli listesi reklam.
  • Reklam seçimi sinyalleri: Dize olarak serileştirilmiş bir JSON nesnesi; şunları içerir: sinyallerine geçiş yapacaktır. Bu durumda, belirtilen 3. taraf ağı için alındı.
  • Selection Logic URI (Seçim Mantığı URI'si): Reklam seçimi sırasında kazanan reklamı seçmek için uyumlulaştırma ağının JavaScript'ini kullanır. Şunlara bakın: işlev imzalarını kullanmanız gerekir. JavaScript, Teklif, teklif tabanından yüksekse 3. taraf reklamı veya aksi takdirde null değerini döndürür. Bu, bir kazanan olduğunda uyumlulaştırma SDK'sının uyumlulaştırma zincirini kesmesine olanak tanır. bulundu.

AdSelectionOutcomesConfig oluşturulduktan sonra, şunun selectAds() yöntemini çağırın: zincirdeki ilk sırada yer alan 3. taraf ağıdır.

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 üzerinden yürütülen işlem sırası verilmiştir bahsedeceğim.

  1. Birinci taraf reklam seçimini yayınla.
  2. Uyumlulaştırma zincirinde yineleme yapın. Her bir 3. taraf ağı için aşağıdakileri yapın:
    1. Birinci taraf outcomeId veAdSelectionFromOutcomeConfig 3. taraf SDK'sının teklif tabanı.
    2. Önceki adımdaki yapılandırmayı kullanarak selectAds() öğesini çağırın.
    3. Sonuç boş değilse reklamı döndürün.
    4. Geçerli SDK ağ bağdaştırıcısının selectAds() yöntemini çağırın. Sonuç boş değilse reklamı döndürün.
  3. Zincirde kazanan bulunamazsa birinci taraf reklamı 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 gerçekleştiğine bağlı olarak bir reklam gösterimini raporlamak için iki akış vardır çalıştırılıyor. Açık artırma yürüten tek bir STP iseniz bu bölümü takip edin. Eğer Şelale uyumlulaştırmasını uygulayacaksanız şu adımları izleyin: şelale uyumlulaştırması gösterim raporlama bölümünü inceleyin.

Tek STP gösterimi raporlama

Reklam seçimi iş akışında kazanan reklam seçildikten sonra, Gösterimi katılımcı alıcı ve satış tarafı platformlarına bildirir AdSelectionManager.reportImpression() yöntemiyle deneyin. Bir reklamı bildirmek için gösterim:

  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 ile alakalı Executor ve OutcomeReceiver nesneleri.

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)

ReportImpressionRequest hizmetini aşağıdaki gerekli bilgilerle başlatın parametre:

  • Reklam seçimi kimliği: Yalnızca bir cihaz kullanıcısına özel, başarılı reklam seçimi.
  • Reklam seçimi yapılandırması: selectAds() içinde kullanılan aynı yapılandırma sağlanan reklam seçim kimliğiyle tanımlanan çağrıdır.

Eşzamansız reportImpression() yöntemi, OutcomeReceiver yöntemini kullanır nesnesini ifade eder.

  • onResult() geri çağırması, gösterim raporlama URL'lerinin ve istek planlandı.
  • onError() geri çağırması aşağıdaki olası koşulları belirtir:
    • Çağrı, geçersiz bir giriş bağımsız değişkeniyle başlatılırsa AdServicesException, IllegalArgumentException öğesini şu şekilde belirtir: neden olabilir.
    • Diğer tüm hatalar için AdServicesException IllegalStateException nedeni gösterilir.

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

Uyumlulaştırma SDK'sının, kendi dönüşüm izleme özelliğini tetiklemesi için kazanan SDK'yı raporlama akışlarından faydalanır. Uyumlulaştırma zincirinde yer alan SDK'lar yöntemini çağırın. SDK Uyumlulaştırılmış bir açık artırmaya katıldığınızda, dönüşüm işlemini uygulamak için yukarıdaki adımları raporlayabilir.

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

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:

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

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

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

  • AdSelectionConfig içinde belirtilen Karar mantığı URL'sini kullanın Nesnesi'ni tanımlayın.
  • reportResult() Satıcının gösterim raporlama URL'si.

Teklif verme ve Açık artırma hizmetlerini raporlama

Teklifli sistem ve Açık artırma hizmetlerinde, reklam etkileşimi raporlaması için oluşturulan URL'ler dahil olmak üzere raporlama bilgilerini sunucu tarafı açık artırmadan gelen şifrelenmiş yanıta dahil edilir. şifresi çözülürse uygun URL'ler platforma kaydedilir. reklam ve gösterim raporlamasında yukarıda listelenen adımlar izlenir.

En iyi sonuç Gösterim raporlama

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

Reklam Etkileşimlerini Bildirme

Protected Audience, aşağıdakiler için daha ayrıntılı etkileşimler hakkında rapor oluşturma desteği sağlar: oluşturulmuş reklamdır. Bunlar arasında görüntüleme zamanı, tıklamalar, fareyle üzerine gelme ve veya toplanabilecek başka bir faydalı metrik. Bu alma süreci iki adım gerekir. Öncelikle, alıcıların ve satıcıların bu raporları raporlama JavaScript'ine ekleyin. Ardından müşterinin bu etkinlikleri raporlayabilirsiniz.

Etkileşim etkinliklerini almak için kaydolma

Etkileşim etkinliklerine kaydolma işlemi, alıcının reportWin() ve satıcının reportResult() JavaScript işlevi bir JavaScript işlevi kullanıyor sağlayan: registerAdBeacon. Kaydolarak raporlamanız için platformun JavaScript İşlevini çağırmanız yeterlidir. JavaScript'e dokunun. Aşağıdaki snippet bir alıcının reportWin() özelliğini kullanıyor, ancak yaklaşımı reportResult() için geçerlidir.

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri

    registerAdBeacon({"click": clickUri, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

Etkileşim etkinliklerini raporlama

Bir gösterim bildirildikten sonra, müşteriler etkileşimleri tekrar daha önce kaydedilmiş kazanan alıcı ve satış tarafı platformları AdSelectionManager.reportInteraction() yöntemini çağırın. Bir reklam etkinliğini bildirmek için:

  1. Bir AdSelectionManager nesnesini başlatın.
  2. Reklam seçim kimliğiyle bir ReportInteractionRequest nesnesi oluşturun. etkileşim anahtarı, etkileşim verileri ve raporlama hedefi.
  3. request nesnesiyle eşzamansız reportInteraction() yöntemini çağırın ve alakalı Executor ile OutcomeReceiver nesnelerini kullanabilirsiniz.
AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

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

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

ReportInteractionRequest hizmetini aşağıdaki gerekli bilgilerle başlatın parametre:

  • Reklam seçimi kimliği: Daha önce döndürülen bir reklam seçimi kimliği AdSelectionOutcome.
  • Etkileşim Anahtarı: Müşteri tarafından tanımlanan, işlemi açıklayan bir dize anahtarı raporlanıyor. Bu, satıcı veya satıcı tarafından kaydedilen anahtarla eşleşmelidir raporlama JavaScript işlevlerindeki alıcı.
  • Etkileşim Verileri: Etkinliğe dahil edilecek verileri içeren bir dize raporlama sunucularına geri POSTA gönderilmek üzere gönderilir.
  • Raporlama Hedefleri: Etkinliklerin gerçekleşip gerçekleşmeyeceğini belirten bir bit maskesi alıcıya, satıcıya veya her ikisine birden bildirilir. Bu flag'ler platform ve son hedef maskesi, bit tabanlı yöntemle oluşturulabilir. anlamına gelir. Tek bir hedefe yönelik rapor oluşturmak için platforma doğrudan erişim sağlar. Birden çok hedefe yönelik rapor oluşturmak için bit tabanlı VEYA (|) işaretini kullanın.

Eşzamansız reportInteraction() yöntemi, OutcomeReceiver yöntemini kullanır nesnesini ifade eder.

  • 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ı belirtir:
    • Arama, uygulama arka planda çalışırken yapılırsa Hatanın açıklamasını içeren IllegalStateException döndürülür.
    • İstemcinin reportInteraction() çağrısı yapması kısıtlanırsa LimitExceededException döndürüldü.
    • Paket, gizliliği koruyan API'leri çağırmak üzere kaydedilmemişse SecurityException() döndürüldü.
    • Uygulama raporlama etkileşimleri, selectAds(), bir IllegalStateException döndürülür.
  • Kullanıcı, Özel Korumalı Alan API'lerinin etkinleştirilmesine izin vermediyse çağrının başarısız olur.
ziyaret edin.

Etkileşim raporlama uç noktaları

Rapor etkileşimi API'si, satıcı tarafı platformu ve kazanan alıcı tarafı platformu. Korunan kitle etkileşim anahtarlarını, raporlama JavaScript'inde belirtilen URI'lerle eşleştirir ve bildirilen her etkileşim için her bir uç noktaya bir POST isteği gönderin. İsteğin içerik türü düz metindir ve gövde Etkileşim Verileri.

En iyi sonuç etkileşim raporlaması

reportInteraction(), projenizin tamamlanması için kullanılabilecek en iyi çabayı sunacak şekilde tasarlanmıştır. raporlama için kullanılır.

Günlük arka plan güncellemesi

Özel kitle oluştururken uygulamanız veya SDK'nız özel kitleyi başlatabilir meta verilerdir. Ayrıca, platform aşağıdaki özel parçaları da güncelleyebilir günlük arka plan güncelleme işlemine tabi kitle meta verileri.

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

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

  • JSON yanıtı, desteklenen meta veri alanlarının herhangi birini içerebilir. emin olun.
  • Her JSON alanı bağımsız olarak doğrulanır. İstemci, kullandığı o alanda güncelleme yapılmamasına neden olan hatalı biçimlendirilmiş alanlar yanıt verelim.
  • Boş bir HTTP yanıtı veya boş JSON nesnesi "{}" sonuç "hayır" meta veri güncellemeleri.
  • Yanıt iletisi boyutu 10 KB ile sınırlı olmalıdır.
  • Tüm URI'ların HTTPS kullanması gerekir.
  • trusted_bidding_uri, alıcı ile aynı ETLD+1'i paylaşmalıdır.

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

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

Reklam seçimi için JavaScript

Reklam seçimi iş akışı, alıcı tarafından sağlanan ve Satıcı tarafından sağlanan JavaScript.

Alıcı tarafından sağlanan JavaScript, Özel kitle. Döndürülen JavaScript aşağıdaki işlevleri içermelidir:

Satıcı tarafından sağlanan JavaScript, Reklam seçim API'sinin AdSelectionConfig parametresi. Döndürülen JavaScript aşağıdaki işlevleri içermelidir:

generateBid()

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

Giriş parametreleri:

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

  • custom_audience_bidding_signals: Platform tarafından oluşturulan JSON nesnesi. İlgili içeriği oluşturmak için kullanılan bu JSON nesnesinin biçimi şöyledir:

    var custom_audience_signals = {
  "owner":"ca_owner",
  "buyer":"ca_buyer",
  "name":"ca_name",
  "activation_time":"ca_activation_time_epoch_ms",
  "expiration_time":"ca_expiration_time_epoch_ms",
  "user_bidding_signals":"ca_user_bidding_signals"
}

    Bu örnekte:

    • owner, buyer ve name, reklam seçimine katılan Özel Kitlenin aynı adı
    • activation_time ve expiration_time, etkinleştirme ve özel kitlenin süresinin dolması. Unix'ten bu yana geçen saniye cinsinden ifade edilir. dönem
    • ca_user_bidding_signals, Oluşturma sırasında CustomAudience öğesinin userBiddingSignals alanı
    • trusted_bidding_signals, contextual_signals ve user_signals JSON'dir nesneler'i tıklayın. Bunlar boş nesneler olarak aktarılır ve yayınlayabileceksiniz. Biçimleri platform tarafından zorunlu kılınmaz ve yönetilir ortaya çıkarıyor.

Sonuç:

  • ad: Teklifin ilişkili olduğu reklamdır. Komut dosyasının farklı meta verilere sahip olarak aldığı bir reklamdır. Etiketin render_url özelliği reklamın değiştirilmemiş olması beklenir.
  • bid: Bu reklamın teklif değerini temsil eden kayan noktalı değer
  • status: Aşağıdaki gibi olabilecek bir tam sayı değeri:
    • 0: Başarılı bir yürütme için
    • 1: (veya sıfır olmayan herhangi bir değer) giriş sinyallerinden herhangi birinin geçersiz olması durumunda. İçinde "teklif oluştur-ver" tarafından sıfır dışında bir değer döndürülürse teklif verme süreci tüm CA reklamları için geçersiz kılındı

scoreAd()

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

Giriş parametreleri:

  • ad: generateBid belgelerini göster
  • bid: reklamın teklif değeridir

  • ad_selection_config: temsil eden bir JSON nesnesi selectAds API'nin AdSelectionConfig parametresi. Biçim şununla eşleşir:

    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 öğesinden okunan JSON nesneleri AdSelectionConfig API parametresi

  • trusted_scoring_signal: adSelectionSignals alanından okuma AdSelectionConfig API parametresi

  • contextual_signals, user_signals: JSON nesneleri. Şu anda boş nesnelerden oluşur ve gelecekteki sürümlerde bu alanlar doldurulacaktır. Biçimi şu değil: reklam teknolojisi tarafından yönetilir.

  • per_buyer_signals: Şu sayfadaki perBuyerSignal haritasından okunan JSON nesnesi Geçerli Özel'i anahtar olarak kullanan AdSelectionConfig API parametresi Kitle alıcısı. Haritada, belirtilen belirleyecek olan kişidir.

Çıkış:

  • score: Bu reklamın puan değerini temsil eden kayan noktalı değer
  • status: Aşağıdaki gibi olabilecek bir tam sayı değeri:
    • 0: başarılı bir yürütme için
    • 1: 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. atılan istisna türünü belirler

selectOutcome()

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

Giriş parametreleri:

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

Çıkış:

  • status: Başarı için 0, başarısızlık için sıfır değerli
  • result: Biri veya null olarak aktarılan sonuçlar

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 tekliftir
  • contextual_signals: generateBid belgelerine bakın

Çıkış:

  • Başarı için status: 0, başarısızlık için sıfır olmamalıdır
  • results: Şunları içeren JSON nesneleri:
    • signals_for_buyer: reportWin öğesine geçirilen bir JSON nesnesi işlev
    • reporting_url: Platform tarafından alıcıya gösterim

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: belgelerine bakın scoreAd
  • signals_for_buyer: reportResult tarafından döndürülen bir JSON nesnesi
  • contextual_signals, custom_audience_signals: belgelerine bakın generateBid

Çıkış:

  • Başarı için status: 0, başarısızlık için sıfır olmamalıdır
  • results: Şunları içeren bir JSON nesnesi:
    • reporting_url: Platform tarafından satıcıya gösterim

registerAdBeacon()

function registerAdBeacon(
  beacons
)

Giriş Parametreleri:

  • beacons: Etkileşim anahtarlarının ve anahtar/değer çiftlerinin raporlama URI'leridir. Biçimi şöyledir:

    let beacons = {
  'interaction_key': 'reporting_uri',
  'interaction_key': 'reporting_uri',
  ...
}
    • interaction_key: Etkinliği temsil eden bir dize. Bu, etkinlik etkileşimlerini raporlarken bu platformun reporting_uri. Bu anahtarın şunlarla eşleşmesi gerekir: alıcının veya satıcının kaydettiği bilgiler ve satıcının bildirdiği bilgiler.
    • reporting_uri: Etkinlik raporlarını almak için bir URI. Ürün ayrıntılarıyla raporlamak için de kullanılır. İşlenmesi için bir POST isteğini kabul etmesi gerekir etkinlikle birlikte bildirilen tüm veriler için geçerlidir.

    Örneğin:

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

Reklam Seçimi önceden oluşturulmuş URI'leri

Önceden oluşturulmuş URI'lar, reklam teknisyenlerine reklam için JavaScript işlevleri atama olanağını AdSelectionConfig ve sonraki adımlarda AdSelectionFromOutcomesConfig sınıf. Önceden oluşturulmuş URI'ler ağ gerektirmez çağrılarına karşılık gelen JavaScript komut dosyasını çağırın. Reklam teknolojileri önceden oluşturulmuş URI'lar kullanabilir barındırmak için kayıtlı bir alan adı ayarlamak zorunda kalmadan.

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

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

Özel Korumalı Alan platformu, bu kaynaktaki bilgileri kullanarak JavaScript Çalışma zamanındaki URI.

Aşağıdaki durumlarda IllegalArgumentException verilir:

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

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

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

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

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

Önceden oluşturulmuş bu URI, en yüksek teklife sahip reklamı seçen bir JavaScript sağlar. en iyi uygulamaları görelim. Ayrıca, projenizin her aşamasında kazananın render_uri ve bid.

Gerekli parametreler

reportingUrl: Kazanan reklamın render_uri ve bid:

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

Kullanım

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

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

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

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

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

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

Gerekli parametreler

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

Kullanım

Reklam seçimi sinyalleriniz {"bid_floor": 10} gibi görünüyorsa sonuçta ö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 örnek uygulamaları hakkında bilgi edinin.GitHub

Ön koşullar

Protected Audience API, reklam seçimi sırasında bazı JavaScript gerektirir ve gösterim raporlaması. Bu JavaScript'i bir test ortamı:

  • JavaScript 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österimi işlemek için bir HTTPS uç noktası ayarlanmasını gerektirir raporlama.

HTTPS uç noktaları

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

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

GitHub deposu, kullanım kolaylığı sağlamak için test amacıyla temel JavaScript kodu sağlar amaçlar. Ayrıca, Desteklenen bir örnek veya mikro hizmet platformu. Daha fazla bilgi için projeye bakın BENİOKU.

JavaScript'in uzaktan getirilmesini geçersiz kıl

Bu özellik, uçtan uca testler için kullanılmak üzere tasarlanmıştır. Uzaktan kumandayı geçersiz kılmak için uygulamanız, geliştirici seçenekleri etkin olarak hata ayıklama modunda çalışmalıdır.

Uygulamanızda hata ayıklama modunu etkinleştirmek için aşağıdaki satırı uygulama özelliğini nasıl etkinleştireceğinizi öğrenin:

<application
  android:debuggable="true">

Bu geçersiz kılmaların nasıl kullanılacağına ilişkin bir örnek için lütfen Korunan Audience API örnek uygulamasına gidin.

Aşağıdaki gibi reklam seçimi rutinlerini işlemek için kendi özel JavaScript'inizi eklemeniz gerekir: teklif verme, puanlama kararları ve raporlama gibi. Temel JavaScript kodunu bulabilirsiniz: GitHub deposunda gerekli tüm istekleri işleyen örnekler. Protected Audience API örnek uygulaması, olarak kullanmak üzere hazırlar.

Satıcı tarafı ve alıcı tarafı JavaScript getirmesi geçersiz kılınabilir bağımsız olarak, ancak herhangi bir JavaScript'i sunmak için HTTPS uç noktasına ihtiyacınız reklamlar ve URL'ler. Lütfen şunun için README'u inceleyin: sunucu oluşturma hakkında bilgi edinin.

JavaScript getirmeyi yalnızca özellikleri de paketinize aittir.

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

Satıcı tarafı JavaScript'inin geçersiz kılmasını ayarlamak için aşağıda gösterildiği gibi şunları yapın: şu kod örneğinde:

  1. Bir AdSelectionManager nesnesini başlatın.
  2. Şu kaynaktan TestAdSelectionManager için referans alın: AdSelectionManager nesne.
  3. AdSelectionConfig nesnesi oluşturun.
  4. Aşağıdaki gibi bir AddAdSelectionOverrideRequest oluştur: AdSelectionConfig nesnesi ve JavaScript'i temsil eden bir String kullanmayı planladığınızı varsayalım.
  5. Eşzamansız overrideAdSelectionConfigRemoteInfo() yöntemini AddAdSelectionOverrideRequest nesnesi ve alakalı Executor ve OutcomeReceiver nesneleri anlamına gelir.

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

Reklamın her birinin ne anlama geldiği hakkında daha fazla bilgi edinmek için Reklam seçimini yayınlama bölümüne bakın. AdSelectionConfig içindeki alanlar gösterilir. Aralarındaki temel fark decisionLogicUrl öğesinin daha önce gösterildiği gibi bir yer tutucu değere yoksayıldı.

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

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

onResult() geri çağırması, geçersiz kılmanın başarıyla uygulandığını belirtir. Gelecekteki selectAds() çağrılarında her türlü karar ve raporlama kullanılacaktır mantığını temel alır.

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

  • Geçersiz bağımsız değişkenlerle geçersiz kılma girişiminde bulunursa AdServiceException, bir IllegalArgumentException öğesinin pek çok yolu vardır.
  • Hata ayıklama modunda çalışmayan bir uygulamayla geçersiz kılma girişiminde bulunulduysa geliştirici seçenekleri etkinse AdServiceException IllegalStateException nedeni gösterilir.

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

Bu bölümde satıcı tarafı JavaScript'ini geçersiz kıldığınız ve bu JavaScript'in TestAdSelectionManager ve Önceki bölümde AdSelectionConfig kullanıldı.

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

  1. Eşzamansız resetAllAdSelectionConfigRemoteOverrides() yöntemini çağırın alakalı OutcomeReceiver nesnesiyle değiştirin.

Kotlin

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

Java

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

Satıcı tarafı geçersiz kılmalarını sıfırladıktan sonra, selectAds() çağrılarına decisionLogicUrl, şunları denemek için AdSelectionConfig içinde depolanır: gerekli JavaScript'i getirin.

resetAllAdSelectionConfigRemoteOverrides() çağrısı başarısız olursa OutComeReceiver.onError() geri çağırması, bir AdServiceException sağlar. Hata ayıklama modunda çalışmayan bir uygulamada geçersiz kılmalar kaldırılmaya çalışılırsa geliştirici seçenekleri etkin olduğunda, AdServiceException IllegalStateException nedeni gösterilir.

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

  1. Özel kitleye katılma adımlarını uygulayın
  2. Alıcıyla bir AddCustomAudienceOverrideRequest oluşturun ve geçersiz kılmak istediğiniz özel kitlenin adı ve geçersiz kılma olarak kullanmak istediğiniz teklif mantığı ve veriler
  3. Eşzamansız overrideCustomAudienceRemoteInfo() yöntemini AddCustomAudienceOverrideRequest nesnesi ve alakalı Executor ve OutcomeReceiver nesneleri

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 kitle. Bu alanlar hakkında daha fazla bilgi edinin.

Buna ek olarak, iki ek parametre belirtebilirsiniz:

  • biddingLogicJs: Alıcının mantığını barındıran JavaScript dikkat edin. Gerekli işlev imzalarını JavaScript'e dokunun.
  • 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, OutcomeReceiver nesnesini ifade eder.

onResult() geri çağırması, geçersiz kılmanın başarıyla uygulandığını belirtir. selectAds() için yapılan sonraki çağrılar, ilgili teklif verme ve raporlama mantığını kullanır. geçersiz kılmayı kabul edersiniz.

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

  • Geçersiz bağımsız değişkenlerle geçersiz kılma girişiminde bulunursa AdServiceException, bir IllegalArgumentException öğesinin pek çok yolu vardır.
  • Hata ayıklama modunda çalışmayan bir uygulamayla geçersiz kılma girişiminde bulunulduysa geliştirici seçenekleri etkinse AdServiceException IllegalStateException nedeni gösterilir.

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

Bu bölümde, alıcı tarafı JavaScript'ini geçersiz kıldığınız ve bu JavaScript'in TestCustomAudienceManager önceki bölüm.

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

  1. Eşzamansız resetAllCustomAudienceOverrides() yöntemini şununla birlikte çağırın: alakalı Executor ve OutcomeReceiver nesneleri.

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ı sıfırladıktan sonra selectAds() için yapılan sonraki çağrılar biddingLogicUrl ve trustedBiddingData için hangisi doğru ise taşımak için CustomAudience içinde depolanmaktadır. JavaScript'e dokunun.

resetCustomAudienceRemoteInfoOverride() çağrısı başarısız olursa OutComeReceiver.onError() geri çağırması, bir AdServiceException sağlar. Hata ayıklama modunda çalışmayan bir uygulamada geçersiz kılmalar kaldırılmaya çalışılırsa geliştirici seçenekleri etkinken AdServiceException IllegalStateException nedeni gösterilir.

Raporlama Sunucusu Kurma

Uzaktan getirme geçersiz kılmaları kullanırken yine de bir sunucu ayarlamanız gerekir. cihazınızın veya emülatörünüzün raporlama etkinliklerine yanıt vermek için ulaşabileceği bir web sitesidir. Basit bir 200 değerini döndüren uç nokta test için yeterlidir. GitHub deposunda Desteklenen bir modele dağıtılabilen OpenAPI hizmet tanımları veya mikro hizmetler platformu. Daha fazla bilgi için projeye bakın BENİOKU.

OpenAPI tanımlarını ararken Reporting-server.json dosyasını arayın. Bu dosya 200 döndüren ve HTTP'yi temsil eden basit bir uç nokta içeriyor. yanıt kodu. Bu uç nokta, selectAds() sırasında kullanılır ve gösterim raporlamanın başarıyla tamamlandığı Protected Audience API.

Test edilecek işlevsellik

  • Katılma veya ayrılma alıştırması yapın ve öncekileri temel alarak özel kitle oluşturun. kullanıcı işlemleri.
  • Barındırılan JavaScript'ler aracılığıyla cihaz üzerinde reklam seçiminin başlatılmasına yönelik çalışma bazı ipuçları vereceğim.
  • Bir uygulamanın özel kitle ayarlarıyla ilişkilendirmesinin reklamları nasıl etkileyebileceğini gözlemleme seçim sonuçları.
  • Reklam seçiminden sonra gösterim raporlama uygulayın.

Sınırlamalar

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

Bileşen Sınır Açıklaması Değeri Sınırla
Özel kitle (CA) Sertifika yetkilisi başına maksimum reklam sayısı 100
Uygulama başına maksimum CA sayısı 1000
Sertifika yetkilisi oluşturabilecek maksimum uygulama sayısı 1000
Sertifika yetkilisinin oluşturulma zamanından itibaren etkinleştirme süresinde 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ı 4000
Maksimum CA adı boyutu 200 bayt
Maksimum günlük getirme URI 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 oranı Saniyede 1
Alıcı başına joinCustomAudience için maksimum arama oranı 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
Genel AdSelection için maksimum yürütme süresi 10 saniye
AdSelection bölgesinde sertifika yetkilisi başına maksimum teklif yürütme süresi 5 saniye
AdSelection puanlamada maksimum yürütme süresi 5 saniye
AdSelection cinsinden alıcı başına maksimum yürütme süresi Henüz belli değil
Maksimum reklam seçimi/satıcı/alıcı sinyalleri başına maksimum boyut 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 oranı 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
Raporlama çıkış URL'sinin maksimum boyutu Henüz belli değil
Gösterim raporlama 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 oranı 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

Maksimum etkinlik verisi boyutu

64KB
Reklamlar Reklam listesinin maksimum boyutu Herkes tarafından paylaşılan 10 KB AdData. tek bir CA ile bağlama
URL'ler Giriş 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ı için teklif verme ve puanlama için 1 saniye
Kullanılan maksimum bellek 10 MB

Hataları ve sorunları bildirin

Geri bildirimleriniz, Android'deki Özel Korumalı Alan'ın çok önemli bir parçasıdır. Bizimle paylaşın sorunlar veya Android'de Özel Korumalı Alan'ı iyileştirme konusunda fikirleriniz.

ziyaret edin.