AdSelectionManager

get

public static AdSelectionManager get (Context context)

Metode setelan pabrik untuk membuat instance AdSelectionManager.

getAdSelectionData

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

Mengumpulkan data audiens kustom dari perangkat. Menampilkan blob yang dikompresi dan dienkripsi untuk dikirim server lelang untuk pemilihan iklan. Untuk detail lebih lanjut, kunjungi Bidding dan Penjelasan Layanan Lelang.

Iklan audiens kustom harus memiliki ad_render_id agar memenuhi syarat untuk dikumpulkan.

Lihat AdSelectionManager#persistAdSelectionResult untuk mengetahui cara memproses hasil pemilihan iklan akan berjalan di sisi server dengan blob yang dihasilkan oleh API ini.

Output diteruskan oleh penerima, yang akan menampilkan GetAdSelectionDataOutcome agar operasi berhasil, atau Exception menyertakan jenis pengecualian yang ditampilkan dan pesan error yang terkait.

Jika IllegalArgumentException ditampilkan, hal tersebut disebabkan oleh argumen input yang tidak valid yang diterima API untuk menjalankan pemilihan iklan.

Jika IllegalStateException ditampilkan dengan pesan error "Failure of AdSelection layanan.", hal ini disebabkan oleh kegagalan internal layanan pemilihan iklan.

Jika TimeoutException ditampilkan, error tersebut disebabkan saat waktu tunggu habis selama proses bidding, penskoran, atau keseluruhan proses pemilihan untuk menemukan Iklan pemenang.

Jika LimitExceededException ditampilkan, hal itu akan terjadi saat paket panggilan melebihi batas kapasitas yang diizinkan dan akan di-throttle.

Jika SecurityException ditampilkan, error tersebut akan muncul saat pemanggil tidak diberi otorisasi atau izin tidak diminta.
Memerlukan AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

getTestAdSelectionManager

public TestAdSelectionManager getTestAdSelectionManager ()

persistenAdSelectionResult

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

Mempertahankan hasil pemilihan iklan dari sisi server. Untuk detail lebih lanjut, kunjungi Bidding dan Penjelasan Layanan Lelang

Lihat AdSelectionManager#getAdSelectionData guna mengetahui cara membuat blob terenkripsi untuk menjalankan pemilihan iklan di sisi server.

Output diteruskan oleh penerima, yang akan menampilkan AdSelectionOutcome agar operasi berhasil, atau Exception menyertakan jenis pengecualian yang ditampilkan dan pesan {i>error<i} yang terkait.

Jika IllegalArgumentException ditampilkan, hal tersebut disebabkan oleh argumen input yang tidak valid yang diterima API untuk menjalankan pemilihan iklan.

Jika IllegalStateException ditampilkan dengan pesan error "Failure of AdSelection layanan.", hal ini disebabkan oleh kegagalan internal layanan pemilihan iklan.

Jika TimeoutException ditampilkan, error tersebut disebabkan saat waktu tunggu habis selama proses bidding, penskoran, atau keseluruhan proses pemilihan untuk menemukan Iklan pemenang.

Jika LimitExceededException ditampilkan, hal itu akan terjadi saat paket panggilan melebihi batas kapasitas yang diizinkan dan akan di-throttle.

Jika SecurityException ditampilkan, error tersebut akan muncul saat pemanggil tidak diberi otorisasi atau izin tidak diminta.
Memerlukan AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

peristiwalaporan

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

Memberi tahu layanan bahwa ada peristiwa iklan baru yang akan dilaporkan untuk iklan yang dipilih oleh proses pemilihan iklan yang diidentifikasi oleh adSelectionId. Peristiwa iklan adalah setiap kejadian yang terjadi pada iklan yang terkait dengan adSelectionId yang ditentukan. Tidak ada jaminan tentang kapan peristiwa iklan akan dilaporkan. Pelaporan peristiwa bisa tertunda dan laporan dapat dikelompokkan.

Dengan ReportEventRequest#getKey(), layanan akan mengambil reportingUri yang terdaftar di registerAdBeacon. Lihat dokumentasi reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) untuk detail selengkapnya terkait registerAdBeacon. Kemudian, layanan akan melampirkan ReportEventRequest#getData() ke isi permintaan dari permintaan POST dan kirim permintaan. Isi permintaan POST akan memiliki content-type dari text/plain, dan data akan dikirim di charset=UTF-8.

Output diteruskan oleh penerima, yang akan menampilkan Object kosong untuk berhasil dijalankan, atau Exception menyertakan jenis pengecualian yang ditampilkan dan pesan error yang sesuai.

Jika IllegalArgumentException ditampilkan, hal tersebut disebabkan oleh argumen input yang tidak valid API yang diterima untuk melaporkan peristiwa iklan.

Jika IllegalStateException ditampilkan dengan pesan error "Failure of AdSelection layanan.", hal ini disebabkan oleh kegagalan internal layanan pemilihan iklan.

Jika LimitExceededException ditampilkan, hal itu akan terjadi saat paket panggilan melebihi batas kapasitas yang diizinkan dan akan di-throttle.

Jika SecurityException ditampilkan, error tersebut akan muncul saat pemanggil tidak diberi otorisasi atau izin tidak diminta.

Peristiwa akan dilaporkan paling banyak sekali sebagai upaya terbaik.
Memerlukan AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

laporanTayangan

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

Memberi tahu layanan bahwa ada tayangan baru yang akan dilaporkan untuk iklan yang dipilih oleh proses pemilihan iklan yang diidentifikasi oleh adSelectionId. Tidak ada jaminan terkait kapan tayangan iklan akan dilaporkan. Pelaporan tayangan dapat tertunda dan laporan dapat dikelompokkan.

Untuk menghitung URL pelaporan penjual yang menang, layanan mengambil JavaScript penjual logika dari AdSelectionConfig#getDecisionLogicUri() yang ditemukan di ReportImpressionRequest.getAdSelectionConfig(). Kemudian, layanan mengeksekusi salah satu yang ditemukan di JS penjual yang disebut reportResult, yang memberikan sinyal di perangkat sebagai serta ReportImpressionRequest#getAdSelectionConfig() sebagai parameter input.

Definisi fungsi reportResult adalah:

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

Untuk menghitung URL pelaporan pembeli yang menang, layanan ini mengambil Logika JavaScript yang diambil melalui CustomAudience.getBiddingLogicUri() pembeli. Kemudian, layanan mengeksekusi salah satu fungsi yang ditemukan di JS pembeli yang disebut reportWin, yang menyediakan sinyal di perangkat, signals_for_buyer yang dihitung oleh reportResult, dan spesifik dari ReportImpressionRequest#getAdSelectionConfig() sebagai parameter input.

Definisi fungsi reportWin adalah:

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

Selain itu, pembeli dan penjual memiliki opsi untuk mendaftar guna menerima laporan tentang peristiwa iklan. Untuk melakukannya, mereka dapat memanggil fungsi registerAdBeacon yang disediakan platform di dalam reportWin dan reportResult masing-masing untuk pembeli dan penjual.

Definisi fungsi registerBeacon adalah:

function registerAdBeacon(beacons), dengan beacons adalah dict dari string untuk pasangan string

Untuk setiap peristiwa iklan yang ingin dilaporkan oleh pembeli/penjual, mereka akan menambahkan pasangan event_key: event_reporting_uri ke dikte beacons, dengan event_key adalah ID untuk peristiwa spesifik tersebut. event_key ini harus cocok ReportEventRequest#getKey() saat SDK memanggil reportEvent(ReportEventRequest, Executor, OutcomeReceiver). Selain itu, setiap event_reporting_uri harus diurai dengan benar ke dalam Uri. Ini akan menjadi Uri yang dilaporkan saat SDK memanggil reportEvent(ReportEventRequest, Executor, OutcomeReceiver).

Saat pembeli/penjual telah menambahkan semua pasangan yang ingin mereka terima peristiwanya, mereka dapat panggil registerAdBeacon(beacons), dengan beacons adalah nama dikte yang yang ditambahkan pasangan.

registerAdBeacon akan menampilkan TypeError dalam situasi ini:

1. registerAdBeacon dipanggil lebih dari sekali. Jika {i>error<i} ini ditemukan dalam reportWin/reportResult, kumpulan pasangan asli akan didaftarkan
2. registerAdBeacon tidak memiliki tepat 1 argumen dict.
3. Konten argumen 1 dikte bukan semua pasangan String: String.

Output diteruskan oleh receiver, yang menampilkan Object kosong agar operasi berhasil, atau Exception menyertakan jenis pengecualian yang ditampilkan dan pesan {i>error<i} yang terkait.

Jika IllegalArgumentException ditampilkan, hal tersebut disebabkan oleh argumen input yang tidak valid yang diterima API untuk melaporkan tayangan iklan.

Jika IllegalStateException ditampilkan dengan pesan error "Failure of AdSelection layanan.", hal ini disebabkan oleh kegagalan internal layanan pemilihan iklan.

Jika LimitExceededException ditampilkan, hal itu akan terjadi saat paket panggilan melebihi batas kapasitas yang diizinkan dan akan di-throttle.

Jika SecurityException ditampilkan, error tersebut akan muncul saat pemanggil tidak diberi otorisasi atau izin tidak diminta.

Tayangan akan dilaporkan maksimal sekali sebagai upaya upaya terbaik.
Memerlukan AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

selectAds

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

Memilih iklan dari hasil pemilihan iklan yang dijalankan sebelumnya.

adSelectionFromOutcomesConfig input disediakan oleh Ads SDK dan objek AdSelectionFromOutcomesConfig ditransfer melalui panggilan Binder. Karena alasan ini, ukuran total objek ini terikat pada batasan IPC Android. Kegagalan saat mentransfer AdSelectionFromOutcomesConfig akan menampilkan TransactionTooLargeException.

Output diteruskan oleh penerima, yang akan menampilkan AdSelectionOutcome agar operasi berhasil, atau Exception menyertakan jenis pengecualian yang ditampilkan dan pesan {i>error<i} yang terkait.

adSelectionFromOutcomesConfig input berisi:

• Seller harus menjadi AdTechIdentifier yang terdaftar. Jika tidak, IllegalStateException akan ditampilkan.
• List of ad selection ids harus ada dan berasal dari panggilan selectAds(AdSelectionConfig, Executor, OutcomeReceiver) yang berasal dari aplikasi yang sama. Jika tidak, IllegalArgumentException untuk validasi input akan melaporkan listingan yang melanggar iklan ID pemilihan.
• Selection logic URI yang dapat mengikuti HTTPS atau Pilihan Iklan Bawaan skema.

  Jika URI mengikuti skema HTTPS, host harus cocok dengan seller. Jika tidak, IllegalArgumentException akan ditampilkan.

  URI bawaan adalah cara menggantikan logika bawaan generik dengan JavaScript untuk selectOutcome. Uri bawaan untuk endpoint ini harus mengikuti;

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

  Jika URI bawaan yang tidak didukung diteruskan atau fitur URI bawaan dinonaktifkan oleh layanan, IllegalArgumentException akan ditampilkan.

  Lihat AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri untuk informasi yang didukung <name> dan <script-generation-parameters> yang diperlukan.

Jika IllegalArgumentException ditampilkan, hal tersebut disebabkan oleh argumen input yang tidak valid yang diterima API untuk menjalankan pemilihan iklan.

Jika IllegalStateException ditampilkan dengan pesan error "Failure of AdSelection layanan.", hal ini disebabkan oleh kegagalan internal layanan pemilihan iklan.

Jika TimeoutException ditampilkan, error tersebut disebabkan saat waktu tunggu habis selama proses bidding, penskoran, atau keseluruhan proses pemilihan untuk menemukan Iklan pemenang.

Jika LimitExceededException ditampilkan, hal itu akan terjadi saat paket panggilan melebihi batas kapasitas yang diizinkan dan akan di-throttle.

Jika SecurityException ditampilkan, error tersebut terjadi saat pemanggil tidak diberi otorisasi atau izin tidak diminta.
Memerlukan AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

selectAds

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

Menjalankan proses pemilihan iklan di perangkat untuk memilih iklan pemasaran ulang untuk pemanggil aplikasi.

adSelectionConfig input disediakan oleh Ads SDK dan objek AdSelectionConfig ditransfer melalui panggilan Binder. Karena alasan ini, ukuran total objek ini terikat pada batasan IPC Android. Jika gagal mentransfer AdSelectionConfig, TransactionTooLargeException akan ditampilkan.

Input adSelectionConfig berisi Decision Logic Uri yang dapat mengikuti baik skema HTTPS atau Bawaan Pilihan Iklan.

Jika URI mengikuti skema HTTPS, host harus cocok dengan seller. Jika tidak, IllegalArgumentException akan ditampilkan.

URI bawaan adalah cara menggantikan logika bawaan generik dengan JavaScript untuk scoreAds. Uri bawaan untuk endpoint ini harus mengikuti;

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

Jika URI bawaan yang tidak didukung diteruskan atau fitur URI bawaan dinonaktifkan oleh layanan, IllegalArgumentException akan ditampilkan.

Lihat AdSelectionConfig.Builder#setDecisionLogicUri untuk mengetahui <name> dan <script-generation-parameters> diperlukan.

Output diteruskan oleh penerima, yang akan menampilkan AdSelectionOutcome agar operasi berhasil, atau Exception menyertakan jenis pengecualian yang ditampilkan dan pesan {i>error<i} yang terkait.

Jika IllegalArgumentException ditampilkan, hal tersebut disebabkan oleh argumen input yang tidak valid yang diterima API untuk menjalankan pemilihan iklan.

Jika IllegalStateException ditampilkan dengan pesan error "Failure of AdSelection layanan.", hal ini disebabkan oleh kegagalan internal layanan pemilihan iklan.

Jika TimeoutException ditampilkan, error tersebut disebabkan saat waktu tunggu habis selama proses bidding, penskoran, atau keseluruhan proses pemilihan untuk menemukan Iklan pemenang.

Jika LimitExceededException ditampilkan, hal itu akan terjadi saat paket panggilan melebihi batas kapasitas yang diizinkan dan akan di-throttle.

Jika SecurityException ditampilkan, error tersebut akan muncul saat pemanggil tidak diberi otorisasi atau izin tidak diminta.
Memerlukan AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

updateAdCounterHistogram

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

Memperbarui histogram penghitung untuk iklan yang sebelumnya dipilih oleh panggilan ke selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver).

Histogram penghitung digunakan dalam pemilihan iklan untuk menginformasikan pemfilteran pembatasan frekuensi pada iklan kandidat. Iklan yang batas frekuensinya terpenuhi atau terlampaui akan dihapus dari yang sama selama pemilihan iklan.

Histogram penghitung hanya dapat diperbarui untuk iklan yang ditentukan oleh adSelectionId tertentu yang ditampilkan oleh panggilan terbaru ke pemilihan iklan FLEDGE dari aplikasi pemanggil yang sama.

SecurityException ditampilkan melalui outcomeReceiver jika:

1. aplikasi belum menyatakan izin yang benar dalam manifesnya, atau
2. aplikasi atau entitas yang diidentifikasi oleh callerAdTechIdentifier tidak diizinkan untuk menggunakan API.

LimitExceededException ditampilkan melalui outcomeReceiver jika panggilan melebihi throttle API aplikasi pemanggil.

Dalam semua kasus kegagalan lainnya, outcomeReceiver akan menampilkan Object kosong. Perlu diperhatikan bahwa untuk melindungi privasi pengguna, error internal tidak akan dikirim kembali melalui pengecualian.
Memerlukan AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE