AdSelectionManager
public
class
AdSelectionManager
extends Object
java.lang.Object | |
↳ | android.adservices.adselection.AdSelectionManager |
AdSelection Manager menyediakan API untuk SDK iklan dan aplikasi agar dapat menjalankan proses pemilihan iklan serta melaporkan tayangan.
Ringkasan
Metode publik | |
---|---|
static
AdSelectionManager
|
get(Context context)
Metode factory untuk membuat instance AdSelectionManager. |
void
|
getAdSelectionData(GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)
Mengumpulkan data audiens kustom dari perangkat. |
TestAdSelectionManager
|
getTestAdSelectionManager()
|
void
|
persistAdSelectionResult(PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
Mempertahankan hasil pemilihan iklan dari sisi server. |
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 |
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 |
void
|
selectAds(AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
Memilih iklan dari hasil pilihan iklan yang dijalankan sebelumnya. |
void
|
selectAds(AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
Menjalankan proses pemilihan iklan di perangkat untuk memilih iklan pemasaran ulang untuk aplikasi pemanggil. |
void
|
updateAdCounterHistogram(UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, Executor executor, OutcomeReceiver<Object, Exception> outcomeReceiver)
Memperbarui histogram penghitung untuk iklan yang sebelumnya dipilih oleh panggilan ke |
Metode turunan | |
---|---|
Metode publik
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:
registerAdBeacon
dipanggil lebih dari sekali. Jika error ini terdeteksi dalam reportWin/reportResult, kumpulan pasangan asli akan didaftarkanregisterAdBeacon
tidak memiliki tepat 1 argumen dikte.- 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 berupaAdTechIdentifier
yang terdaftar. Jika tidak,IllegalStateException
akan ditampilkan.List of ad selection ids
harus ada dan berasal dari panggilanselectAds(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:
- aplikasi belum menyatakan izin yang benar dalam manifesnya, atau
- 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 . |