AdSelectionManager

public class AdSelectionManager
extends Object

java.lang.Object
🎃 android.adservices.adselection.AdSelectionManager

AdSelection Manager, reklam seçim işlemlerinin yanı sıra uygulama ve reklam SDK'ları için API'ler de sunar. Rapor gösterimleri.

Özet

Herkese açık yöntemler

static AdSelectionManager get(Context context)

AdSelectionManager'ın bir örneğini oluşturmak için kullanılan fabrika yöntemi.

void getAdSelectionData(GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)

Cihazdan özel kitle verileri toplar.

TestAdSelectionManager getTestAdSelectionManager()
void persistAdSelectionResult(PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Sunucu tarafındaki reklam seçimi sonuçlarının kalıcı olmasını sağlar.

void reportEvent(ReportEventRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)

Reklam öğesi tarafından seçilen reklam için raporlanacak yeni bir reklam etkinliği olduğunu adSelectionId tarafından tanımlanan reklam seçimi.

void reportImpression(ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)

Reklam öğesi tarafından seçilen reklam için raporlanacak yeni bir gösterim olduğunu adSelectionId tarafından tanımlanan reklam seçimi.

void selectAds(AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Daha önce yapılan reklam seçimlerinin sonuçlarından bir reklam seçer.

void selectAds(AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Arayan için yeniden pazarlama reklamı seçmek üzere cihazda reklam seçim sürecini yürütür bir uygulamadır.

void updateAdCounterHistogram(UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, Executor executor, OutcomeReceiver<Object, Exception> outcomeReceiver)

Daha önce selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver) çağrısıyla seçilen bir reklamın sayaç histogramlarını günceller.

Devralınan yöntemler

Herkese açık yöntemler

get

API düzeyi 34'e eklendi
Ayrıca Ad Services Extensions 6'da da 
public static AdSelectionManager get (Context context)

AdSelectionManager'ın bir örneğini oluşturmak için kullanılan fabrika yöntemi.

Parametreler
context Context: Kullanılacak Context Bu değer null olamaz.
İlerlemeler
AdSelectionManager AdSelectionManager örneği Bu değer null olamaz.

getReklamSeçimiVerisi

public void getAdSelectionData (GetAdSelectionDataRequest request, 
                Executor executor, 
                OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)

Cihazdan özel kitle verileri toplar. Gönderilecek sıkıştırılmış ve şifrelenmiş bir blob'u döndürür reklam seçimi için açık artırma sunucuları. Daha fazla bilgi için lütfen Teklif Verme bölümünü ziyaret edin ve Açık Artırma Hizmetleri Açıklaması.

Özel kitle reklamlarının toplanmaya uygun olması için bir ad_render_id olması gerekir.

Sonuçların nasıl işleneceğini öğrenmek için AdSelectionManager#persistAdSelectionResult adresine göz atın bu API tarafından oluşturulan blob ile sunucu tarafında çalıştırılan reklam seçimi.

Çıkış, alıcı tarafından iletilir. Bu alıcı, başarılı bir çalıştırma için GetAdSelectionDataOutcome döndürür veya Exception öğesi istisna atılır ve ilgili hata mesajı gösterilir.

IllegalArgumentException atlanırsa geçersiz giriş bağımsız değişkeninden kaynaklanmaktadır reklam seçimini çalıştırmak için alınan API'dir.

IllegalStateException, "Reklam Seçimi Başarısız Oldu" hata mesajıyla atılırsa hizmet." hatası, reklam seçim hizmetindeki dahili bir hatadan kaynaklanır.

TimeoutException atılırsa bu, zaman aşımıyla karşılaşıldığında ortaya çıkar teklif verme, puanlama veya genel seçim sürecinde kazanan reklamı bulabilirsiniz.

LimitExceededException atlanırsa arama paketi izin verilen oran sınırlarını aşıyor ve kısıtlanıyor.

SecurityException atlanırsa arayanın yetkilendirilmemiş olması gerekir veya izin istenmez.
. AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE gerektirir

Parametreler
request GetAdSelectionDataRequest: Bu değer null olamaz.
executor Executor: Bu değer null olamaz. Geri çağırma ve işleyici etkinlikleri bu Executor kullanılır. Etkinlikleri oluşturmak için Context.getMainExecutor() Aksi takdirde, uygun bir ileti dizisine yönlendiren bir Executor sağlayın.
receiver OutcomeReceiver: Bu değer null olamaz.

getTestAdSelectionManager

API düzeyi 34'e eklendi
Ayrıca Ad Services Extensions 4'e de eklendi 
public TestAdSelectionManager getTestAdSelectionManager ()

İlerlemeler
TestAdSelectionManager Bu değer null olamaz.

kalıcıAdSeçimiSonuç

public void persistAdSelectionResult (PersistAdSelectionResultRequest request, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Sunucu tarafındaki reklam seçimi sonuçlarının kalıcı olmasını sağlar. Daha fazla bilgi için lütfen Teklif Verme bölümünü ziyaret edin ve Açık Artırma Hizmetleri Açıklaması

Şunlar için şifrelenmiş blob oluşturacağınızı öğrenmek amacıyla AdSelectionManager#getAdSelectionData adresine bakın sunucu tarafında bir reklam seçimi çalıştırmanız gerekir.

Çıkış, alıcı tarafından iletilir. Bu işlem, AdSelectionOutcome değerini döndürür. veya Exception hatası atılan istisna türünü içerir ve hata iletisiyle karşılaşırsınız.

IllegalArgumentException atlanırsa geçersiz giriş bağımsız değişkeninden kaynaklanmaktadır reklam seçimini çalıştırmak için alınan API'dir.

IllegalStateException, "Reklam Seçimi Başarısız Oldu" hata mesajıyla atılırsa hizmet." hatası, reklam seçim hizmetindeki dahili bir hatadan kaynaklanır.

TimeoutException atılırsa bu, zaman aşımıyla karşılaşıldığında ortaya çıkar teklif verme, puanlama veya genel seçim sürecinde kazanan reklamı bulabilirsiniz.

LimitExceededException atlanırsa arama paketi izin verilen oran sınırlarını aşıyor ve kısıtlanıyor.

SecurityException atlanırsa arayanın yetkilendirilmemiş olması gerekir veya izin istenmez.
. AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE gerektirir

Parametreler
request PersistAdSelectionResultRequest: Bu değer null olamaz.
executor Executor: Bu değer null olamaz. Geri çağırma ve işleyici etkinlikleri bu Executor kullanılır. Etkinlikleri oluşturmak için Context.getMainExecutor() Aksi takdirde, uygun bir ileti dizisine yönlendiren bir Executor sağlayın.
receiver OutcomeReceiver: Bu değer null olamaz.

reportEvent

public void reportEvent (ReportEventRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

Reklam öğesi tarafından seçilen reklam için raporlanacak yeni bir reklam etkinliği olduğunu adSelectionId tarafından tanımlanan reklam seçimi. Reklam etkinliği, kullanıcının belirtilen adSelectionId ile ilişkili bir reklama ne olduğu. Paydaşların kullanımına ilişkin reklam etkinliğinin bildirileceği zamanı gösterir. Olay raporlaması gecikebilir ve raporlar gruplandırılır.

Hizmet, ReportEventRequest#getKey() kullanılarak reportingUri öğesini getirir (registerAdBeacon genelinde kayıtlı) registerAdBeacon hakkında daha fazla bilgi için reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) dokümanlarına bakın. Ardından hizmet, ReportEventRequest#getData() öğesini bir POST isteğinin istek gövdesine ekler ve isteği gönder. POST isteğinin gövdesinde content-type değeri text/plain bulunur ve veriler charset=UTF-8 içinde iletilir.

Çıkış, alıcı tarafından iletilir. Bu işlem, alıcı için boş bir Object hatası döndürür. olup olmadığını kontrol etmek için bir Exception, atılan istisna türünü ve mesajı gönderebilirsiniz.

IllegalArgumentException atlanırsa geçersiz giriş bağımsız değişkeninden kaynaklanmaktadır reklam etkinliğini bildirmek için alınan API.

IllegalStateException, "Reklam Seçimi Başarısız Oldu" hata mesajıyla atılırsa hizmet." hatası, reklam seçim hizmetindeki dahili bir hatadan kaynaklanır.

LimitExceededException atlanırsa arama paketi izin verilen oran sınırlarını aşıyor ve kısıtlanıyor.

SecurityException atlanırsa arayanın yetkilendirilmemiş olması gerekir veya izin istenmez.

Etkinlikler, elimizden gelenin en iyisini yapmak için en fazla bir kez raporlanır.
. AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE gerektirir

Parametreler
request ReportEventRequest: Bu değer null olamaz.
executor Executor: Bu değer null olamaz.
receiver OutcomeReceiver: Bu değer null olamaz.

raporGösterimi

API düzeyi 34'e eklendi
Ayrıca Ad Services Extensions 4'e de eklendi 
public void reportImpression (ReportImpressionRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

Reklam öğesi tarafından seçilen reklam için raporlanacak yeni bir gösterim olduğunu adSelectionId tarafından tanımlanan reklam seçimi. URL'lerin ne zaman gösterim raporlanır. Gösterim raporlaması gecikebilir ve raporlar gruplandırılır.

Kazanan satıcı raporlama URL'sini hesaplamak için hizmet, satıcının JavaScript'ini getirir ReportImpressionRequest.getAdSelectionConfig() bağlantısında bulunan AdSelectionConfig#getDecisionLogicUri() mantığı. Daha sonra hizmet, satıcı JS'sinde bulunan ve cihaz üzerindeki sinyalleri reportResult olarak sağlayan işlevler ve giriş parametrelerinin yanı sıra ReportImpressionRequest#getAdSelectionConfig().

reportResult işlevinin fonksiyon tanımı:

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

Kazanan alıcı raporlama URL'sini hesaplamak için hizmet, kazanan alıcının Alıcının CustomAudience.getBiddingLogicUri() aracılığıyla getirilen JavaScript mantığı. Ardından hizmet, alıcı JS'sinde bulunan reportWin adlı işlevlerden birini yürütür ve cihaz üzerindeki sinyaller, reportResult tarafından hesaplanan signals_for_buyer ve belirli ReportImpressionRequest#getAdSelectionConfig() içindeki alanları giriş parametreleri olarak kullanın.

reportWin işlevinin fonksiyon tanımı:

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

Ayrıca, alıcılar ve satıcılar, belirli alışverişler hakkında raporlar almak için reklam etkinlikleri. Bunun için platform tarafından sağlanan registerAdBeacon işlevini çağırabilirler. alıcılar ve satıcılar için sırasıyla reportWin ve reportResult içinde.

registerBeacon işlevinin fonksiyon tanımı:

function registerAdBeacon(beacons); burada beacons, dizenin dize çiftleri

Alıcı/satıcı, rapor oluşturmak istediği her reklam etkinliği için beacons komutuna event_key: event_reporting_uri çifti ekler. Burada event_key, söz konusu etkinliğin tanımlayıcısıdır. Bu event_key, eşleşmelidir SDK reportEvent(ReportEventRequest, Executor, OutcomeReceiver) yöntemini çağırdığında ReportEventRequest#getKey(). Ayrıca, her event_reporting_uri düzgün bir şekilde Uri olarak ayrıştırılmalıdır. Bu SDK reportEvent(ReportEventRequest, Executor, OutcomeReceiver) yöntemini çağırdığında bildirilen Uri olur.

Alıcı/satıcı, etkinlik almak istediği tüm eşlemeleri eklediğinde registerAdBeacon(beacons) yöntemini çağırın. Burada beacons söylenen hükmün adıdır. , çiftleri ekledi.

registerAdBeacon, şu durumlarda TypeError atar:

  1. registerAdBeaconbirden fazla kez çağrıldı. Bu hata reportWin/reportResult, orijinal eşleme kümesi kaydedilir
  2. registerAdBeacon alanında tam olarak 1 dict bağımsız değişkeni yok.
  3. 1 dict bağımsız değişkeninin içeriği String: String eşlemelerinin tümü değil.

Çıkış, boş bir Object döndüren receiver tarafından iletilir yoksa bir Exception oluşturulan istisnanın türünü ve hata iletisiyle karşılaşırsınız.

IllegalArgumentException atlanırsa geçersiz giriş bağımsız değişkeninden kaynaklanmaktadır gösterimi bildirmek için alınan API'dir.

IllegalStateException, "Reklam Seçimi Başarısız Oldu" hata mesajıyla atılırsa hizmet." hatası, reklam seçim hizmetindeki dahili bir hatadan kaynaklanır.

LimitExceededException atlanırsa arama paketi izin verilen oran sınırlarını aşıyor ve kısıtlanıyor.

SecurityException atlanırsa arayanın yetkilendirilmemiş olması gerekir veya izin istenmez.

Gösterimler en fazla bir kez en iyi çaba olarak raporlanır.
. AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE gerektirir

Parametreler
request ReportImpressionRequest: Bu değer null olamaz.
executor Executor: Bu değer null olamaz.
receiver OutcomeReceiver: Bu değer null olamaz.

selectAds

public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Daha önce yapılan reklam seçimlerinin sonuçlarından bir reklam seçer.

adSelectionFromOutcomesConfig girişi, Ads SDK'sı tarafından sağlanır ve AdSelectionFromOutcomesConfig nesnesi bir Bağlayıcı çağrısı aracılığıyla aktarılır. Bu nedenle, bu nesnelerin toplam boyutu Android IPC sınırlamalarına bağlıdır. AdSelectionFromOutcomesConfig TransactionTooLargeException atacak.

Çıkış, alıcı tarafından iletilir. Bu işlem, AdSelectionOutcome değerini döndürür. veya Exception hatası atılan istisna türünü içerir ve hata iletisiyle karşılaşırsınız.

adSelectionFromOutcomesConfig girişi şunları içeriyor:

  • Seller alanının kayıtlı bir AdTechIdentifier olması gerekir. Aksi halde, IllegalStateException atılır.
  • List of ad selection ids mevcut olmalı ve aynı uygulamadan gelen selectAds(AdSelectionConfig, Executor, OutcomeReceiver) aramadan gelmelidir. Aksi halde Giriş doğrulaması için IllegalArgumentException, girişi ihlal eden reklamı yükseltecek seçim kimlikleri.
  • HTTPS veya Önceden Oluşturulmuş Reklam Seçimi'ni uygulayabilecek Selection logic URI oluşturabilirsiniz.

    URI, HTTPS şemasını takip ediyorsa ana makine seller ile eşleşmelidir. Aksi takdirde, IllegalArgumentException atılır.

    Önceden oluşturulmuş URI'lar, gerekli komut dosyası için önceden oluşturulmuş genel bir mantığı selectOutcome için JavaScript'ler. Bu uç nokta için önceden oluşturulmuş URI izlemelidir;

    • ad-selection-prebuilt://ad-selection-from-outcomes/<name>?<script-generation-parameters>

    Desteklenmeyen önceden oluşturulmuş URI atlanırsa veya önceden oluşturulmuş URI özelliği hizmeti ile birlikte IllegalArgumentException atılır.

    Desteklenen içerikler için AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri sayfasını inceleyin <name> ve <script-generation-parameters> zorunlu.

IllegalArgumentException atlanırsa geçersiz giriş bağımsız değişkeninden kaynaklanmaktadır reklam seçimini çalıştırmak için alınan API'dir.

IllegalStateException, "Reklam Seçimi Başarısız Oldu" hata mesajıyla atılırsa hizmet." hatası, reklam seçim hizmetindeki dahili bir hatadan kaynaklanır.

TimeoutException atılırsa bu, zaman aşımıyla karşılaşıldığında ortaya çıkar teklif verme, puanlama veya genel seçim sürecinde kazanan reklamı bulabilirsiniz.

LimitExceededException atlanırsa arama paketi izin verilen oran sınırlarını aşıyor ve kısıtlanıyor.

SecurityException atlanırsa arayanın yetkilendirilmemiş olması gerekir veya izin istenmez.
. AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE gerektirir

Parametreler
adSelectionFromOutcomesConfig AdSelectionFromOutcomesConfig: Bu değer null olamaz.
executor Executor: Bu değer null olamaz. Geri çağırma ve işleyici etkinlikleri bu Executor kullanılır. Etkinlikleri oluşturmak için Context.getMainExecutor() Aksi takdirde, uygun bir ileti dizisine yönlendiren bir Executor sağlayın.
receiver OutcomeReceiver: Bu değer null olamaz.

selectAds

API düzeyi 34'e eklendi 
public void selectAds (AdSelectionConfig adSelectionConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Arayan için yeniden pazarlama reklamı seçmek üzere cihazda reklam seçim sürecini yürütür bir uygulamadır.

adSelectionConfig girişi, Ads SDK'sı tarafından sağlanır ve AdSelectionConfig nesnesi bir Bağlayıcı çağrısı aracılığıyla aktarılır. Bu nedenle, toplam boyut Android IPC sınırlamalarına tabidir. AdSelectionConfig, aktarılmazsa TransactionTooLargeException hatası verilir.

adSelectionConfig girişi, takip edebilecek Decision Logic Uri içeriyor HTTPS veya Reklam Seçimi Önceden Oluşturulmuş şemalarını kullanabilir.

URI, HTTPS şemasını takip ediyorsa ana makine seller ile eşleşmelidir. Aksi halde IllegalArgumentException atılacak.

Önceden oluşturulmuş URI'lar, gerekli komut dosyası için önceden oluşturulmuş genel bir mantığı scoreAds için JavaScript'ler. Bu uç nokta için önceden oluşturulmuş URI izlemelidir;

  • ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>

Desteklenmeyen önceden oluşturulmuş URI atlanırsa veya önceden oluşturulmuş URI özelliği hizmeti ile birlikte IllegalArgumentException atılır.

Desteklenen <name> ve kaynaklar için AdSelectionConfig.Builder#setDecisionLogicUri adresini ziyaret edin <script-generation-parameters> zorunlu.

Çıkış, alıcı tarafından iletilir. Bu işlem, AdSelectionOutcome değerini döndürür. veya Exception hatası atılan istisna türünü içerir ve hata iletisiyle karşılaşırsınız.

IllegalArgumentException atlanırsa geçersiz giriş bağımsız değişkeninden kaynaklanmaktadır reklam seçimini çalıştırmak için alınan API'dir.

IllegalStateException, "Reklam Seçimi Başarısız Oldu" hata mesajıyla atılırsa hizmet." hatası, reklam seçim hizmetindeki dahili bir hatadan kaynaklanır.

TimeoutException atılırsa bu, zaman aşımıyla karşılaşıldığında ortaya çıkar teklif verme, puanlama veya genel seçim sürecinde kazanan reklamı bulabilirsiniz.

LimitExceededException atlanırsa arama paketi izin verilen oran sınırlarını aşıyor ve kısıtlanıyor.

SecurityException atlanırsa arayanın yetkilendirilmemiş olması gerekir veya izin istenmez.
. AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE gerektirir

Parametreler
adSelectionConfig AdSelectionConfig: Bu değer null olamaz.
executor Executor: Bu değer null olamaz. Geri çağırma ve işleyici etkinlikleri bu Executor kullanılır. Etkinlikleri oluşturmak için Context.getMainExecutor() Aksi takdirde, uygun bir ileti dizisine yönlendiren bir Executor sağlayın.
receiver OutcomeReceiver: Bu değer null olamaz.

güncellemeAdCounterHistogramı

public void updateAdCounterHistogram (UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> outcomeReceiver)

Daha önce selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver) çağrısıyla seçilen bir reklamın sayaç histogramlarını günceller.

Sayaç histogramları, reklam seçiminde sıklık sınırı filtrelemesini bildirmek için kullanılır Bu reklamlarda, sıklık sınırlarına ulaşılan veya aşılan reklamların Arama Ağı reklam seçimi sırasındaki teklif sürecidir.

Sayaç histogramları yalnızca aynı arayan uygulamasından FLEDGE reklam seçimi için yakın zamanda yapılan bir çağrı tarafından döndürülen, belirtilen adSelectionId tarafından belirtilen reklamlar için güncellenebilir.

Aşağıdaki durumlarda outcomeReceiver aracılığıyla SecurityException döndürülür:

  1. Uygulama, manifest dosyasında doğru izinleri beyan etmemişse veya
  2. callerAdTechIdentifier tarafından tanımlanan uygulama veya tüzel kişi yetkili değil API'yi kullanmak.
ziyaret edin. Çağrı şu durumda outcomeReceiver aracılığıyla IllegalStateException döndürülür: ön planda etkinliği olan bir uygulamadan gelmemelidir.

Çağrı, outcomeReceiver aracılığıyla LimitExceededException döndürülür çağrı yapan uygulamanın API kısıtlamasını aşıyor.

Diğer tüm hata durumlarında outcomeReceiver, boş bir Object döndürür. Kullanıcı gizliliğini korumak amacıyla dahili hataların kabul edersiniz.
. AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE gerektirir

Parametreler
updateAdCounterHistogramRequest UpdateAdCounterHistogramRequest: Bu değer null olamaz.
executor Executor: Bu değer null olamaz. Geri çağırma ve işleyici etkinlikleri bu Executor kullanılır. Etkinlikleri oluşturmak için Context.getMainExecutor() Aksi takdirde, uygun bir ileti dizisine yönlendiren bir Executor sağlayın.
outcomeReceiver OutcomeReceiver: Bu değer null olamaz.