AdSelectionManager

dapatkan

public static AdSelectionManager get (Context context)

Metode factory untuk membuat instance AdSelectionManager.

Parameter
context	Context: Context yang akan digunakan Nilai ini tidak boleh null.

Hasil
AdSelectionManager	Instance AdSelectionManager Nilai ini tidak boleh null.

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 ke server lelang untuk pemilihan iklan. Untuk detail selengkapnya, buka Penjelasan Bidding dan 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 yang dijalankan di sisi server dengan blob yang dihasilkan oleh API ini.

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

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

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

Jika TimeoutException ditampilkan, penyebabnya adalah waktu tunggu habis selama proses bidding, penskoran, atau keseluruhan proses pemilihan untuk menemukan Iklan pemenang.

Jika LimitExceededException ditampilkan, hal ini akan terjadi saat paket panggilan melebihi batas kapasitas yang diizinkan dan dibatasi.

Jika SecurityException ditampilkan, hal ini disebabkan karena pemanggil tidak diberi otorisasi atau tidak meminta izin.
Memerlukan AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parameter
request	GetAdSelectionDataRequest: Nilai ini tidak boleh null.
executor	Executor: Nilai ini tidak boleh null. Peristiwa callback dan pemroses dikirim melalui Executor ini, yang memberikan cara mudah untuk mengontrol thread mana yang digunakan. Untuk mengirim peristiwa melalui thread utama aplikasi, Anda dapat menggunakan Context.getMainExecutor(). Jika tidak, berikan Executor yang dikirimkan ke thread yang sesuai.
receiver	OutcomeReceiver: Nilai ini tidak boleh null.

getTestAdSelectionManager

public TestAdSelectionManager getTestAdSelectionManager ()

Hasil
TestAdSelectionManager	Nilai ini tidak boleh null.

persistenAdSelectionResult

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

Mempertahankan hasil pemilihan iklan dari sisi server. Untuk detail selengkapnya, buka Penjelasan Bidding dan Layanan Lelang

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

Output diteruskan oleh penerima, yang menampilkan AdSelectionOutcome agar berhasil dijalankan, atau Exception menyertakan jenis pengecualian yang ditampilkan dan pesan error yang sesuai.

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

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

Jika TimeoutException ditampilkan, penyebabnya adalah waktu tunggu habis selama proses bidding, penskoran, atau keseluruhan proses pemilihan untuk menemukan Iklan pemenang.

Jika LimitExceededException ditampilkan, hal ini akan terjadi saat paket panggilan melebihi batas kapasitas yang diizinkan dan dibatasi.

Jika SecurityException ditampilkan, hal ini disebabkan karena pemanggil tidak diberi otorisasi atau tidak meminta izin.
Memerlukan AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parameter
request	PersistAdSelectionResultRequest: Nilai ini tidak boleh null.
executor	Executor: Nilai ini tidak boleh null. Peristiwa callback dan pemroses dikirim melalui Executor ini, yang memberikan cara mudah untuk mengontrol thread mana yang digunakan. Untuk mengirim peristiwa melalui thread utama aplikasi, Anda dapat menggunakan Context.getMainExecutor(). Jika tidak, berikan Executor yang dikirimkan ke thread yang sesuai.
receiver	OutcomeReceiver: Nilai ini tidak boleh null.

reportEvent

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 kemunculan yang terjadi pada iklan yang terkait dengan adSelectionId tertentu. Tidak ada jaminan terkait kapan peristiwa iklan akan dilaporkan. Pelaporan peristiwa dapat tertunda dan laporan dapat dikelompokkan.

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

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

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

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

Jika LimitExceededException ditampilkan, hal ini akan terjadi saat paket panggilan melebihi batas kapasitas yang diizinkan dan dibatasi.

Jika SecurityException ditampilkan, hal ini disebabkan karena pemanggil tidak diberi otorisasi atau tidak meminta izin.

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

Parameter
request	ReportEventRequest: Nilai ini tidak boleh null.
executor	Executor: Nilai ini tidak boleh null.
receiver	OutcomeReceiver: Nilai ini tidak boleh null.

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 logika JavaScript penjual dari AdSelectionConfig#getDecisionLogicUri() yang ditemukan di ReportImpressionRequest.getAdSelectionConfig(). Kemudian, layanan akan menjalankan salah satu fungsi yang ditemukan di JS penjual yang disebut reportResult, yang menyediakan sinyal di perangkat 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 pembeli pemenang yang diambil melalui CustomAudience.getBiddingLogicUri() pembeli. Kemudian, layanan akan menjalankan salah satu fungsi yang ditemukan di JS pembeli yang disebut reportWin, yang menyediakan sinyal di perangkat, signals_for_buyer yang dihitung oleh reportResult, dan kolom tertentu 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 tertentu. Untuk melakukannya, klien 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 dikte string ke pasangan string

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

Jika pembeli/penjual telah menambahkan semua pasangan yang ingin mereka terima peristiwanya, mereka dapat memanggil registerAdBeacon(beacons), dengan beacons adalah nama dikte yang telah ditambahi pasangan tersebut.

registerAdBeacon akan menampilkan TypeError dalam situasi berikut:

1. registerAdBeacon dipanggil lebih dari sekali. Jika error ini terdeteksi dalam reportWin/reportResult, kumpulan pasangan asli akan didaftarkan
2. registerAdBeacon tidak memiliki tepat 1 argumen dikte.
3. Konten dari argumen 1 dikte tidak semuanya merupakan pasangan String: String.

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

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

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

Jika LimitExceededException ditampilkan, hal ini akan terjadi saat paket panggilan melebihi batas kapasitas yang diizinkan dan dibatasi.

Jika SecurityException ditampilkan, hal ini disebabkan karena pemanggil tidak diberi otorisasi atau tidak meminta izin.

Tayangan akan dilaporkan maksimal satu kali sebagai upaya upaya terbaik.
Memerlukan AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parameter
request	ReportImpressionRequest: Nilai ini tidak boleh null.
executor	Executor: Nilai ini tidak boleh null.
receiver	OutcomeReceiver: Nilai ini tidak boleh null.

selectIklan

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

Memilih iklan dari hasil pilihan iklan yang dijalankan sebelumnya.

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

Output diteruskan oleh penerima, yang menampilkan AdSelectionOutcome agar berhasil dijalankan, atau Exception menyertakan jenis pengecualian yang ditampilkan dan pesan error yang sesuai.

Input adSelectionFromOutcomesConfig berisi:

• Seller harus berupa 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 menaikkan listingan ID pemilihan iklan yang melanggar.
• Selection logic URI yang dapat mengikuti skema HTTPS atau Pilihan Iklan Bawaan.

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

  URI bawaan adalah cara menggantikan logika bawaan generik untuk JavaScript yang diperlukan untuk selectOutcome. URI bawaan untuk endpoint ini akan 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 <name> yang didukung dan <script-generation-parameters> wajib.

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

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

Jika TimeoutException ditampilkan, penyebabnya adalah waktu tunggu habis selama proses bidding, penskoran, atau keseluruhan proses pemilihan untuk menemukan Iklan pemenang.

Jika LimitExceededException ditampilkan, hal ini akan terjadi saat paket panggilan melebihi batas kapasitas yang diizinkan dan dibatasi.

Jika SecurityException ditampilkan, hal ini disebabkan karena pemanggil tidak diberi otorisasi atau tidak meminta izin.
Memerlukan AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parameter
adSelectionFromOutcomesConfig	AdSelectionFromOutcomesConfig: Nilai ini tidak boleh null.
executor	Executor: Nilai ini tidak boleh null. Peristiwa callback dan pemroses dikirim melalui Executor ini, yang memberikan cara mudah untuk mengontrol thread mana yang digunakan. Untuk mengirim peristiwa melalui thread utama aplikasi, Anda dapat menggunakan Context.getMainExecutor(). Jika tidak, berikan Executor yang dikirimkan ke thread yang sesuai.
receiver	OutcomeReceiver: Nilai ini tidak boleh null.

selectIklan

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

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

Input adSelectionConfig disediakan oleh Ads SDK dan objek AdSelectionConfig ditransfer melalui panggilan Binder. Karena alasan ini, ukuran total objek ini terikat dengan batasan Android IPC. Kegagalan untuk mentransfer AdSelectionConfig akan menampilkan TransactionTooLargeException.

adSelectionConfig input berisi Decision Logic Uri yang dapat mengikuti skema bawaan HTTPS atau Ad Selection.

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

URI bawaan adalah cara menggantikan logika bawaan generik untuk JavaScript yang diperlukan untuk scoreAds. URI bawaan untuk endpoint ini akan 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 <name> yang didukung dan <script-generation-parameters> yang diperlukan.

Output diteruskan oleh penerima, yang menampilkan AdSelectionOutcome agar berhasil dijalankan, atau Exception menyertakan jenis pengecualian yang ditampilkan dan pesan error yang sesuai.

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

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

Jika TimeoutException ditampilkan, penyebabnya adalah waktu tunggu habis selama proses bidding, penskoran, atau keseluruhan proses pemilihan untuk menemukan Iklan pemenang.

Jika LimitExceededException ditampilkan, hal ini akan terjadi saat paket panggilan melebihi batas kapasitas yang diizinkan dan dibatasi.

Jika SecurityException ditampilkan, hal ini disebabkan karena pemanggil tidak diberi otorisasi atau tidak meminta izin.
Memerlukan AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parameter
adSelectionConfig	AdSelectionConfig: Nilai ini tidak boleh null.
executor	Executor: Nilai ini tidak boleh null. Peristiwa callback dan pemroses dikirim melalui Executor ini, yang memberikan cara mudah untuk mengontrol thread mana yang digunakan. Untuk mengirim peristiwa melalui thread utama aplikasi, Anda dapat menggunakan Context.getMainExecutor(). Jika tidak, berikan Executor yang dikirimkan ke thread yang sesuai.
receiver	OutcomeReceiver: Nilai ini tidak boleh null.

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, di mana iklan yang batas frekuensinya terpenuhi atau terlampaui akan dihapus dari proses bidding 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.

IllegalStateException ditampilkan melalui outcomeReceiver jika panggilan tidak berasal dari aplikasi dengan aktivitas latar depan.

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

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

Parameter
updateAdCounterHistogramRequest	UpdateAdCounterHistogramRequest: Nilai ini tidak boleh null.
executor	Executor: Nilai ini tidak boleh null. Peristiwa callback dan pemroses dikirim melalui Executor ini, yang memberikan cara mudah untuk mengontrol thread mana yang digunakan. Untuk mengirim peristiwa melalui thread utama aplikasi, Anda dapat menggunakan Context.getMainExecutor(). Jika tidak, berikan Executor yang dikirimkan ke thread yang sesuai.
outcomeReceiver	OutcomeReceiver: Nilai ini tidak boleh null.