Saat Anda membaca dokumentasi Privacy Sandbox di Android, gunakan tombol Pratinjau Developer atau Beta untuk memilih versi program yang sedang Anda gunakan, karena petunjuknya dapat bervariasi.
FLEDGE di Android mencakup Custom Audience API dan Ad Selection API. Platform teknologi iklan dan pengiklan dapat menggunakan API ini untuk menayangkan iklan yang disesuaikan berdasarkan interaksi aplikasi sebelumnya sehingga membatasi berbagi ID di seluruh aplikasi dan membatasi berbagi informasi interaksi aplikasi pengguna dengan pihak ketiga.
Custom Audience API berpusat di sekitar abstraksi "audiens kustom" yang mewakili sekelompok pengguna dengan niat yang sama. Pengiklan dapat mendaftarkan pengguna ke audiens kustom dan mengaitkan iklan yang relevan dengan audiens kustom tersebut. Informasi ini disimpan secara lokal dan dapat digunakan untuk menginformasikan bid pengiklan, pemfilteran iklan, dan rendering iklan.
Ad Selection API menyediakan framework yang memungkinkan beberapa developer menjalankan lelang secara lokal untuk audiens kustom. Untuk mencapai hal ini, sistem akan mempertimbangkan iklan yang relevan yang terkait dengan audiens kustom dan melakukan pemrosesan tambahan pada iklan yang ditampilkan oleh platform teknologi iklan ke perangkat.
Platform teknologi iklan dapat mengintegrasikan API ini untuk menerapkan pemasaran ulang yang tetap menjaga privasi pengguna. Dukungan untuk kasus penggunaan tambahan, seperti iklan instal aplikasi, direncanakan untuk rilis mendatang. Pelajari FLEDGE di Android lebih lanjut dalam proposal desain.
Panduan developer ini menjelaskan cara menggunakan FLEDGE di Android untuk melakukan berbagai hal berikut:
- Mengelola audiens kustom
- Menyiapkan dan menjalankan pemilihan iklan di perangkat
- Melaporkan tayangan iklan
Sebelum memulai
Sebelum Anda memulai, selesaikan hal-hal berikut:
- Menyiapkan lingkungan pengembangan Anda untuk Privacy Sandbox di Android.
- Instal image sistem ke perangkat yang didukung atau siapkan emulator yang menyertakan dukungan untuk Privacy Sandbox di Android.
Di terminal, aktifkan akses ke FLEDGE API (dinonaktifkan secara default) dengan perintah adb berikut.
adb shell device_config put adservices ppapi_app_allow_list \"*\"
Sertakan izin
ACCESS_ADSERVICES_CUSTOM_AUDIENCE
dalam manifes aplikasi Anda:<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
Referensikan konfigurasi layanan iklan di elemen
<application>
manifes Anda:<property android:name="android.adservices.AD_SERVICES_CONFIG" android:resource="@xml/ad_services_config" />
Tentukan resource XML layanan iklan yang dirujuk dalam manifes, seperti
res/xml/ad_services_config.xml
. Pelajari izin layanan iklan dan kontrol akses SDK lebih lanjut.<ad-services-config> <custom-audiences allowAllToAccess="true" /> </ad-services-config>
Secara default, Ad Selection API menerapkan batas jumlah maksimum memori yang dapat dialokasikan oleh skrip pelaporan lelang atau tayangan. Fitur pembatasan memori memerlukan WebView versi 105.0.5195.58 atau yang lebih tinggi. Platform ini menerapkan pemeriksaan versi dan panggilan ke API
selectAds
danreportImpression
akan gagal jika hal ini tidak terpenuhi. Ada dua opsi untuk menyiapkannya:Opsi 1: Jalankan perintah adb berikut untuk menonaktifkan pemeriksaan ini:
adb device_config put fledge_js_isolate_enforce_max_heap_size false
Opsi 2: Instal WebView Beta dari Google Play Store. Versi ini harus sama dengan atau lebih tinggi dari versi yang disebutkan di atas.
Bergabung dengan audiens kustom
Audiens kustom mewakili sekelompok pengguna yang memiliki niat atau minat sama seperti yang ditentukan oleh aplikasi pengiklan. Aplikasi atau SDK dapat menggunakan audiens kustom untuk menunjukkan audiens tertentu, seperti seseorang yang telah meninggalkan item dalam keranjang belanja. Untuk membuat atau bergabung dengan audiens kustom secara asinkron, lakukan hal berikut:
- Lakukan inisialisasi objek
CustomAudienceManager
. - Buat objek
CustomAudience
dengan menentukan parameter utama seperti paket pembeli dan nama yang relevan. Lalu, inisialisasi objekJoinCustomAudienceRequest
dengan objekCustomAudience
. - Panggil
joinCustomAudience()
asinkron dengan objekJoinCustomAudienceRequest
dan objekExecutor
danOutcomeReceiver
yang relevan.
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);
Kombinasi parameter berikut secara unik mengidentifikasi setiap
objek CustomAudience
owner
: Nama paket aplikasi pemilik. Secara implisit, nama ini ditetapkan ke nama paket aplikasi pemanggil.buyer
: ID untuk jaringan iklan pembeli yang mengelola iklan untuk audiens kustom ini.name
: Nama atau ID arbitrer untuk audiens kustom.
Memanggil joinCustomAudience()
berulang kali dengan instance
CustomAudience
lain akan mengupdate semua CustomAudience
yang ada dengan
parameter owner, buyer
, dan name
yang cocok. Untuk membantu menjaga privasi,
hasil API tidak membedakan antara "creation" (pembuatan) dan "update".
Selain itu, CustomAudience
harus dibuat dengan parameter
yang diperlukan berikut:
- URL update harian: URL HTTPS dikueri setiap hari di latar belakang untuk mengupdate sinyal bidding pengguna audiens kustom, data bidding tepercaya, serta URL dan metadata render untuk iklan.
- URL logika bidding: URL HTTPS yang dikueri selama pemilihan iklan untuk mengambil logika bidding JavaScript pembeli. Lihat tanda tangan fungsi yang diperlukan dalam JavaScript ini.
Parameter opsional untuk objek CustomAudience
dapat mencakup:
- Waktu aktivasi: Audiens kustom hanya dapat berpartisipasi dalam pemilihan iklan dan update harian setelah waktu aktivasinya. Misalnya, waktu aktivasi bisa berguna untuk melibatkan pengguna aplikasi yang tidak aktif.
- Waktu habis masa berlaku: Waktu mendatang saat audiens kustom akan dihapus dari perangkat.
- Sinyal bidding pengguna: String JSON yang berisi sinyal pengguna, seperti lokalitas pilihan pengguna, yang akan digunakan oleh JavaScript logika bidding pembeli untuk menghasilkan bid selama proses pemilihan iklan. Format ini membantu platform teknologi iklan menggunakan kembali kode di seluruh platform dan memudahkan pemakaian dalam fungsi JavaScript.
- Data bidding tepercaya: URL HTTPS dan daftar string yang digunakan selama proses pemilihan iklan yang mengambil sinyal bidding dari server kunci/nilai yang tepercaya.
- Iklan: Daftar objek
AdData
yang sesuai dengan iklan yang akan berpartisipasi dalam pemilihan iklan. Setiap objekAdData
terdiri dari:- URL Render: URL HTTPS yang dikueri untuk merender iklan akhir.
- Metadata: Objek JSON yang diserialisasi sebagai string yang berisi informasi yang akan digunakan oleh logika bidding pembeli selama proses pemilihan iklan.
Berikut adalah contoh pembuatan instance objek CustomAudience
:
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();
Menangani hasil joinCustomAudience()
Metode joinCustomAudience()
asinkron menggunakan objek OutcomeReceiver
untuk memberi sinyal hasil panggilan API.
- Callback
onResult()
menandakan bahwa audiens kustom berhasil dibuat atau diperbarui. - Callback
onError()
menandakan adanya dua kemungkinan kondisi.- Jika
JoinCustomAudienceRequest
diinisialisasi dengan argumen yang tidak valid,AdServicesException
akan menunjukkanIllegalArgumentException
sebagai penyebabnya. - Semua error lainnya akan menerima
AdServicesException
denganIllegalStateException
sebagai penyebabnya.
- Jika
Berikut adalah contoh penanganan hasil joinCustomAudience()
:
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);
}
};
Keluar dari audiens kustom
Jika pengguna tidak lagi memenuhi kriteria bisnis untuk audiens
kustom tertentu, aplikasi atau SDK dapat memanggil leaveCustomAudience()
untuk menghapus audiens
kustom dari perangkat. Untuk menghapus CustomAudience
berdasarkan parameter
uniknya, lakukan hal berikut:
- Lakukan inisialisasi objek
CustomAudienceManager
. - Lakukan inisialisasi
LeaveCustomAudienceRequest
denganbuyer
danname
audiens kustom. Untuk mempelajari kolom input ini lebih lanjut, baca "Bergabung dengan audiens kustom". - Panggil metode
leaveCustomAudience()
asinkron dengan objekLeaveCustomAudienceRequest
serta objekExecutor
danOutcomeReceiver
yang relevan.
Kotlin
val customAudienceManager: CustomAudienceManager =
context.getSystemService(CustomAudienceManager::class.java)
// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
JoinCustomAudienceRequest.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 JoinCustomAudienceRequest.Builder()
.setBuyer(buyer)
.setName(name)
.build();
// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
leaveCustomAudienceRequest,
executor,
outcomeReceiver);
Seperti halnya memanggil joinCustomAudience()
, OutcomeReceiver
akan
menandakan akhir panggilan API. Untuk membantu melindungi privasi, hasil error tidak akan
membedakan antara error internal dan argumen yang tidak valid. Callback onResult()
dipanggil saat panggilan API telah selesai, baik audiens kustom
yang cocok berhasil dihapus maupun tidak.
Menjalankan pemilihan iklan
Untuk menggunakan FLEDGE agar dapat memilih iklan, panggil metode selectAds()
:
- Lakukan inisialisasi objek
AdSelectionManager
. - Buat objek
AdSelectionConfig
. - Panggil metode
selectAds()
asinkron dengan objekAdSelectionConfig
serta objekExecutor
danOutcomeReceiver
yang relevan.
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)
.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)
.build();
// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
adSelectionConfig,
executor,
outcomeReceiver);
Metode selectAds()
memerlukan input AdSelectionConfig
, dan
Anda harus menentukan parameter wajib berikut:
- Penjual: ID untuk jaringan iklan penjual yang memulai pemilihan iklan.
- URL logika keputusan: URL HTTPS yang dikueri untuk mendapatkan logika JavaScript jaringan iklan penjual. Lihat tanda tangan fungsi yang diperlukan dalam JavaScript ini.
- Pembeli audiens kustom: Daftar lengkap ID untuk jaringan iklan pembeli yang diizinkan oleh penjual untuk berpartisipasi dalam proses pemilihan iklan. ID pembeli ini sesuai dengan CustomAudience.getBuyer() dari audiens kustom yang berpartisipasi.
Parameter berikut dapat ditentukan secara opsional untuk pemilihan iklan yang lebih disesuaikan:
- Sinyal pemilihan iklan: Objek JSON, yang diserialisasi sebagai string, berisi
sinyal yang akan digunakan oleh JavaScript logika bidding pembeli yang diambil dari
CustomAudience.getBiddingLogicUrl()
. - Sinyal penjual: Objek JSON, yang diserialisasi sebagai string, yang berisi sinyal
yang digunakan oleh logika keputusan JavaScript yang diambil penjual dari
AdSelectionConfig.getDecisionLogicUrl()
. - Sinyal per pembeli: Peta objek JSON, yang diserialisasi sebagai string,
yang berisi sinyal untuk digunakan oleh JavaScript logika bidding pembeli tertentu
yang diambil dari
CustomAudience.getBiddingLogicUrl()
, yang diidentifikasi oleh kolom pembeli pada audiens kustom yang berpartisipasi.
Setelah iklan dipilih, hasil, bid, dan sinyal akan dipertahankan secara internal
untuk pelaporan di lain waktu. Dari callback OutcomeReceiver.onResult()
, Anda akan mendapatkan
kembali AdSelectionOutcome
yang berisi:
- URL render untuk iklan pemenang yang diperoleh dari
AdData.getRenderUrl()
. - ID pemilihan iklan yang unik untuk pengguna perangkat. ID ini digunakan untuk melaporkan tayangan iklan.
Jika pemilihan iklan tidak berhasil diselesaikan karena alasan seperti
argumen tidak valid, waktu tunggu habis, atau konsumsi resource berlebih, callback
OutcomeReceiver.onError()
akan memberikan AdServicesException
dengan perilaku berikut:
- Jika pemilihan iklan dimulai dengan argumen yang tidak valid,
AdServicesException
akan menunjukkanIllegalArgumentException
sebagai penyebabnya. - Semua error lainnya akan menerima
AdServicesException
denganIllegalStateException
sebagai penyebabnya.
Melaporkan tayangan iklan
Setelah iklan yang menang dipilih dari alur kerja pemilihan iklan, Anda dapat
melaporkan kembali tayangan ke platform sisi jual dan sisi beli yang berpartisipasi
dengan metode AdSelectionManager.reportImpression()
. Untuk melaporkan
tayangan iklan:
- Lakukan inisialisasi objek
AdSelectionManager
. - Buat objek
ReportImpressionRequest
dengan ID pemilihan iklan. - Panggil metode
reportImpression()
asinkron dengan objekAdSelectionConfig
serta objekExecutor
danOutcomeReceiver
yang relevan.
Java
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
// Initialize a ReportImpressionRequest
ReportImpressionRequest adSelectionConfig =
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)
Lakukan inisialisasi ReportImpressionRequest
dengan parameter yang diperlukan berikut:
- ID pemilihan iklan: ID unik hanya untuk pengguna perangkat yang mengidentifikasi pemilihan iklan yang berhasil.
- Konfigurasi pemilihan iklan: Konfigurasi yang sama yang digunakan dalam panggilan
selectAds()
yang diidentifikasi oleh ID pemilihan iklan yang disediakan.
Metode reportImpression()
asinkron menggunakan objek OutcomeReceiver
untuk memberi sinyal hasil panggilan API.
- Callback
onResult()
menunjukkan apakah pemilihan iklan telah selesai. - Callback
onError()
menunjukkan kemungkinan kondisi berikut:- Jika panggilan diinisialisasi dengan argumen input yang tidak valid,
AdServicesException
akan menunjukkanIllegalArgumentException
sebagai penyebabnya. - Semua error lainnya akan menerima
AdServicesException
denganIllegalStateException
sebagai penyebabnya.
- Jika panggilan diinisialisasi dengan argumen input yang tidak valid,
Endpoint pelaporan tayangan
API tayangan laporan akan menerbitkan permintaan GET HTTPS ke endpoint yang disediakan oleh platform sisi jual dan platform sisi beli yang menang:
Endpoint platform sisi beli:
- API ini akan menggunakan URL logika bidding yang ditentukan dalam audiens kustom untuk mengambil JavaScript logika bidding pembeli.
- Panggil fungsi JavaScript
reportResult()
yang diharapkan akan menampilkan URL pelaporan tayangan pembeli.
Endpoint platform sisi jual:
- Gunakan URL logika keputusan yang ditentukan dalam objek
AdSelectionConfig
untuk mengambil JavaScript logika keputusan penjual. - Panggil fungsi JavaScript
reportWin()
yang diharapkan akan menampilkan URL pelaporan tayangan pembeli.
Upaya terbaik Pelaporan tayangan
reportImpression()
dirancang untuk menawarkan upaya penyelesaian pelaporan yang paling
mudah.
Update latar belakang harian
Saat membuat audiens kustom, aplikasi atau SDK Anda dapat menginisialisasi metadata audiens kustom. Selain itu, platform ini dapat mengupdate bagian dari metadata audiens kustom berikut dengan proses update di latar belakang harian.
- Sinyal bidding pengguna
- Data bidding tepercaya
- Daftar
AdData
Proses ini mengajukan kueri terhadap URL Update harian yang ditentukan dalam audiens kustom dan URL tersebut dapat menampilkan respons JSON.
- Respons JSON mungkin berisi salah satu kolom metadata yang didukung dan perlu diperbarui.
- Setiap kolom JSON divalidasi secara terpisah. Klien akan mengabaikan kolom yang rusak yang akan mengakibatkan tidak ada update pada kolom tertentu dalam respons.
- Respons HTTP kosong atau objek JSON kosong “
{}
” tidak akan menghasilkan update metadata. - Ukuran pesan respons harus dibatasi hingga 10 KB.
- Semua URI diperlukan untuk menggunakan HTTPS.
trusted_bidding_uri
harus memiliki ETLD+1 yang sama dengan pembeli.
Contoh: Respons JSON untuk update harian latar belakang
{
"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
},
...
]
}
Biasanya pengambilan latar belakang ini terjadi sekali setiap 24 jam. Saat menguji, Anda dapat memicu tugas ini secara manual dengan menjalankan perintah berikut:
adb shell cmd jobscheduler run -f com.google.android.adservices.api 9
JavaScript untuk pemilihan iklan
Alur kerja pemilihan iklan mengatur eksekusi JavaScript yang disediakan pembeli dan yang disediakan penjual.
JavaScript yang disediakan pembeli diambil dari URL logika Bidding yang ditentukan dalam audiens kustom. JavaScript yang ditampilkan harus menyertakan fungsi berikut:
JavaScript yang disediakan penjual diambil dari URL logika keputusan yang ditentukan dalam
parameter AdSelectionConfig
untuk ad selection API. JavaScript
yang ditampilkan harus menyertakan fungsi berikut:
generateBid()
function generateBid(
ad,
auction_signals,
per_buyer_signals,
trusted_bidding_signals,
contextual_signals,
user_signals,
custom_audience_signals) {
return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}
Parameter input:
ad
: objek JSON dengan var format berikutad = { 'render_url': url, 'metadata': json_metadata }
;auction_signals, per_buyer_signals
: Objek JSON, objek ini ditetapkan dalam objek konfigurasi lelangcustom_audience_signals
: Objek JSON yang dihasilkan oleh platform. Format untuk objek JSON ini adalah: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" }
dalam hal ini:
owner, buyer
, danname
adalah string yang diambil dari properti dengan nama Audiens Kustom sama yang berpartisipasi dalam pemilihan iklanactivation_time
danexpiration_time
adalah waktu aktivasi dan berakhirnya masa berlaku audiens kustom yang dinyatakan sebagai detik sejak epoch Unixca_user_bidding_signals
adalah string JSON yang ditentukan dalam kolomuserBiddingSignals
dariCustomAudience
pada waktu pembuatantrusted_bidding_signals, contextual_signals
danuser_signals
adalah objek JSON. Saat ini objek tersebut diteruskan sebagai objek kosong dan akan diisi di rilis mendatang. Formatnya tidak diterapkan oleh platform dan dikelola oleh teknologi iklan.
Hasil:
ad
: adalah iklan yang dirujuk oleh bid. Skrip ini diizinkan untuk menampilkan salinan iklan yang diterima dengan metadata berbeda. Propertirender_url
iklan tidak akan diubah.bid
: nilai float yang mewakili nilai bid untuk iklan inistatus
: nilai bilangan bulat yang dapat berupa:- 0: untuk keberhasilan eksekusi
- 1: (atau nilai apa pun yang bukan nol) jika sinyal input apa pun tidak valid. Jika nilai bukan nol ditampilkan oleh generate-bid, proses bidding untuk semua iklan CA menjadi tidak valid
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 };
}
Parameter input:
ad
: lihat dokumentasigenerateBid
bid
: nilai bid untuk iklanad_selection_config
: objek JSON yang mewakili parameterAdSelectionConfig
selectAds
API. Formatnya adalah: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
: Objek JSON yang dibaca dari parameter APIsellerSignals
AdSelectionConfig
trusted_scoring_signal
: yang dibaca dari kolomadSelectionSignals
di parameter APIAdSelectionConfig
contextual_signals, user_signals
: Objek JSON. Saat ini objek tersebut diteruskan sebagai objek kosong dan akan diisi di rilis mendatang. Formatnya tidak diterapkan oleh platform dan dikelola oleh teknologi iklan.per_buyer_signals
: Objek JSON dibaca dari petaperBuyerSignal
dalam parameter APIAdSelectionConfig
menggunakan kunci sebagai pembeli Audiens Kustom saat ini. Kosong jika peta tidak berisi entri untuk pembeli tertentu.
Output:
score
: nilai float yang mewakili nilai skor untuk iklan inistatus
: nilai bilangan bulat yang dapat berupa:- 0: untuk keberhasilan eksekusi
- 1: jika
customAudienceSignals
tidak valid - 2: jika
AdSelectionConfig
tidak valid - 3: jika salah satu sinyal lain tidak valid
- Nilai apa pun yang bukan nol menyebabkan kegagalan proses, nilai tersebut akan menentukan jenis pengecualian yang ditampilkan
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 }
};
}
Parameter input:
ad_selection_config
: lihat dokumentasiscoreAds
render_url
: URL render iklan pemenangbid
: bid yang ditawarkan untuk iklan pemenangcontextual_signals
: lihat dokumentasigenerateBid
Output:
status: 0
untuk berhasil dan bukan nol untuk gagalresults
: objek JSON yang berisi:signals_for_buyer
: objek JSON yang diteruskan ke fungsireportWin
reporting_url
: URL yang digunakan oleh platform untuk memberi tahu tayangan kepada pembeli
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 } };
}
Parameter input:
ad_selection_signals, per_buyer_signals
: lihat dokumentasi untukscoreAd
signals_for_buyer
: objek JSON yang ditampilkan olehreportResult
contextual_signals, custom_audience_signals
: lihat dokumentasi untukgenerateBid
Output:
status: 0
untuk berhasil dan bukan nol untuk gagalresults
: objek JSON yang berisi:reporting_url
: URL yang digunakan oleh platform untuk memberi tahu tayangan kepada penjual
Pengujian
Untuk membantu Anda memulai FLEDGE, kami telah membuat aplikasi contoh di Kotlin dan Java yang dapat ditemukan di GitHub.
Prasyarat
FLEDGE memerlukan beberapa JavaScript selama pemilihan iklan dan pelaporan tayangan. Ada dua metode untuk menyediakan JavaScript ini di lingkungan pengujian:
- Menjalankan server dengan endpoint HTTPS yang diperlukan yang menampilkan JavaScript
- Mengganti pengambilan jarak jauh dengan memberikan kode yang diperlukan dari sumber lokal
Salah satu pendekatan tersebut memerlukan penyiapan endpoint HTTPS untuk menangani pelaporan tayangan.
Endpoint HTTPS
Untuk menguji pemilihan iklan dan pelaporan tayangan, Anda harus menyiapkan 7 endpoint HTTPS yang dapat diakses oleh perangkat pengujian atau emulator Anda:
- Endpoint pembeli yang menayangkan JavaScript logika bidding.
- Endpoint yang menayangkan sinyal bidding.
- Endpoint penjual yang menayangkan JavaScript logika keputusan.
- Endpoint yang menyalurkan sinyal skor.
- Endpoint pelaporan tayangan pembeli yang menang.
- Endpoint pelaporan tayangan penjual.
- Endpoint untuk menayangkan update harian untuk audiens kustom.
Demi kemudahan, repo GitHub menyediakan kode JavaScript dasar untuk tujuan pengujian. Repo GitHub ini juga mencakup definisi layanan OpenAPI yang dapat di-deploy ke platform tiruan atau microservice yang didukung. Untuk mengetahui detail selengkapnya, lihat README project.
Mengganti pengambilan JavaScript jarak jauh
Fitur ini dimaksudkan untuk digunakan dalam pengujian menyeluruh. Untuk mengganti pengambilan jarak jauh, aplikasi Anda harus berjalan dalam mode debug dengan opsi developer diaktifkan.
Guna mengaktifkan mode debug untuk aplikasi Anda, tambahkan baris berikut ke atribut aplikasi dalam AndroidManifest.xml:
<application
android:debuggable="true">
Untuk contoh cara menggunakan penggantian ini, lihat aplikasi contoh FLEDGE di GitHub.
Anda harus menambahkan JavaScript kustom Anda sendiri untuk menangani rutinitas pemilihan iklan, seperti bidding, keputusan skor, dan pelaporan. Anda dapat menemukan contoh kode JavaScript dasar yang menangani semua permintaan yang diperlukan di repo GitHub. Aplikasi contoh FLEDGE menunjukkan cara membaca kode dari file tersebut dan menyiapkannya untuk digunakan sebagai penggantian.
Anda dapat mengganti pengambilan JavaScript sisi jual dan sisi beli secara terpisah, meskipun Anda memerlukan endpoint HTTPS untuk menayangkan JavaScript apa pun yang tidak diberi penggantian. Lihat README untuk mengetahui informasi cara menyiapkan server yang menangani kasus ini.
Anda hanya dapat mengganti pengambilan JavaScript untuk audiens kustom yang dimiliki oleh paket Anda.
Mengganti JavaScript sisi jual
Untuk menyiapkan penggantian JavaScript sisi jual, lakukan hal berikut seperti yang ditunjukkan dalam contoh kode di bawah:
- Lakukan inisialisasi objek
AdSelectionManager
. - Dapatkan referensi ke
TestAdSelectionManager
dari objekAdSelectionManager
. - Buat objek
AdSelectionConfig
. - Buat
AddAdSelectionOverrideRequest
dengan objekAdSelectionConfig
danString
yang mewakili JavaScript yang ingin Anda gunakan sebagai penggantian. - Panggil metode
overrideAdSelectionConfigRemoteInfo()
asinkron dengan objekAddAdSelectionOverrideRequest
dan objekExecutor
danOutcomeReceiver
yang relevan.
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);
Lihat bagian Menjalankan pemilihan iklan untuk mengetahui informasi selengkapnya tentang apa yang
direpresentasikan oleh setiap kolom dalam AdSelectionConfig
. Perbedaan utamanya adalah bahwa
decisionLogicUrl dapat ditetapkan ke nilai placeholder karena akan
diabaikan.
Untuk mengganti JavaScript yang digunakan selama pemilihan iklan,
decisionLogicJs
harus berisi tanda tangan fungsi sisi penjual yang sesuai.
Untuk contoh cara membaca file JavaScript sebagai string, lihat
aplikasi contoh FLEDGE di GitHub.
Metode overrideAdSelectionConfigRemoteInfo()
asinkron menggunakan
objek OutcomeReceiver
untuk memberi sinyal hasil panggilan API.
Callback onResult()
menandakan bahwa penggantian berhasil diterapkan.
Panggilan ke selectAds()
di masa mendatang akan menggunakan logika pengambilan keputusan dan
pelaporan yang Anda teruskan sebagai penggantian.
Callback onError()
menandakan adanya dua kemungkinan kondisi:
- Jika penggantian dicoba dengan argumen yang tidak valid,
AdServiceException
akan menunjukkanIllegalArgumentException
sebagai penyebabnya. - Jika penggantian dicoba dengan aplikasi yang tidak berjalan dalam mode debug dengan
opsi developer yang diaktifkan,
AdServiceException
akan menunjukkanIllegalStateException
sebagai penyebabnya.
Mereset penggantian sisi jual
Bagian ini mengasumsikan bahwa Anda telah mengganti JavaScript sisi jual dan
memiliki referensi ke TestAdSelectionManager
dan
AdSelectionConfig
yang digunakan di bagian sebelumnya.
Untuk mereset penggantian bagi semua AdSelectionConfigs
:
- Panggil metode
resetAllAdSelectionConfigRemoteOverrides()
asinkron dengan objekOutcomeReceiver
yang relevan.
Kotlin
// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver)
Java
// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver);
Setelah Anda mereset penggantian sisi jual, panggilan ke selectAds()
akan menggunakan
decisionLogicUrl apa pun yang disimpan di AdSelectionConfig
untuk mencoba
mengambil JavaScript yang diperlukan.
Jika panggilan ke resetAllAdSelectionConfigRemoteOverrides()
gagal,
callback OutComeReceiver.onError()
akan memberikan AdServiceException
.
Jika penghapusan penggantian dicoba dengan aplikasi yang tidak berjalan dalam mode debug
dengan opsi developer yang diaktifkan, AdServiceException
akan menunjukkan
IllegalStateException
sebagai penyebabnya.
Mengganti JavaScript sisi beli
- Ikuti langkah-langkah untuk bergabung dengan audiens kustom
- Buat
AddCustomAudienceOverrideRequest
dengan pembeli dan nama audiens kustom yang ingin Anda ganti, selain logika bidding dan data yang ingin Anda gunakan sebagai penggantian - Panggil metode
overrideCustomAudienceRemoteInfo()
asinkron dengan objekAddCustomAudienceOverrideRequest
dan objekExecutor
danOutcomeReceiver
yang relevan
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);
Nilai untuk pembeli dan nama adalah nilai yang sama dengan yang digunakan untuk membuat audiens kustom. Pelajari kolom ini lebih lanjut.
Selain itu, Anda dapat menentukan dua parameter tambahan:
biddingLogicJs
: JavaScript yang menyimpan logika pembeli yang digunakan selama pemilihan iklan. Lihat tanda tangan fungsi yang diperlukan dalam JavaScript ini.trustedBiddingSignals
: Sinyal bidding yang akan digunakan selama pemilihan iklan. Untuk tujuan pengujian, sinyal ini bisa berupa string kosong.
Metode overrideCustomAudienceRemoteInfo()
asinkron menggunakan objek OutcomeReceiver
untuk memberi sinyal hasil panggilan API.
Callback onResult()
menandakan bahwa penggantian berhasil diterapkan.
Panggilan berikutnya ke selectAds()
akan menggunakan logika bidding dan pelaporan apa pun
yang telah Anda teruskan sebagai penggantian.
Callback onError()
menandakan adanya dua kemungkinan kondisi.
- Jika penggantian dicoba dengan argumen yang tidak valid,
AdServiceException
akan menunjukkanIllegalArgumentException
sebagai penyebabnya. - Jika penggantian dicoba dengan aplikasi yang tidak berjalan dalam mode debug dengan
opsi developer yang diaktifkan,
AdServiceException
akan menunjukkanIllegalStateException
sebagai penyebabnya.
Mereset penggantian sisi beli
Bagian ini mengasumsikan bahwa Anda telah mengganti JavaScript sisi beli dan
memiliki referensi ke TestCustomAudienceManager
dan yang digunakan di
bagian sebelumnya.
Untuk mereset penggantian bagi semua audiens kustom:
- Panggil metode
resetAllCustomAudienceOverrides()
asinkron dengan objekExecutor
danOutcomeReceiver
yang relevan.
Kotlin
// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
executor,
outComeReceiver)
Java
// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
executor,
outComeReceiver)
Setelah Anda mereset penggantian sisi beli, panggilan berikutnya keselectAds()
menggunakan biddingLogicUrl
dan trustedBiddingData
apa pun
disimpan di dalam CustomAudience
untuk mencoba mengambil
JavaScript yang diperlukan.
Jika panggilan ke resetCustomAudienceRemoteInfoOverride()
gagal,
callback OutComeReceiver.onError()
akan memberikan AdServiceException
.
Jika penghapusan penggantian dicoba dengan aplikasi yang tidak berjalan dalam mode debug
dengan opsi developer yang diaktifkan, AdServiceException
akan menunjukkan
IllegalStateException
sebagai penyebabnya.
Menyiapkan Server Pelaporan
Saat menggunakan penggantian pengambilan jarak jauh, Anda masih harus menyiapkan server yang dapat dijangkau oleh perangkat atau emulator untuk merespons peristiwa pelaporan. Endpoint sederhana yang menampilkan 200 sudah cukup untuk pengujian. Repo GitHub mencakup definisi layanan OpenAPI yang dapat di-deploy ke platform tiruan atau microservice yang didukung. Untuk mengetahui detail selengkapnya, lihat README project.
Saat mencari definisi OpenAPI, cari reporting-server.json.
File ini berisi endpoint sederhana yang menampilkan 200, yang mewakili kode
respons HTTP. Endpoint ini digunakan selama selectAds()
dan memberikan sinyal ke
FLEDGE bahwa pelaporan tayangan berhasil diselesaikan.
Fungsi yang akan diuji
- Melakukan praktik saat bergabung atau keluar dan menyiapkan audiens kustom berdasarkan tindakan pengguna sebelumnya.
- Melakukan praktik inisiasi pemilihan iklan di perangkat melalui JavaScript yang dihosting dari jarak jauh.
- Amati bagaimana pengaitan aplikasi dengan setelan audiens kustom dapat memengaruhi hasil pemilihan iklan.
- Melatih pelaporan tayangan setelah pemilihan iklan.
Batasan
Tabel berikut mencantumkan batasan untuk pemrosesan FLEDGE. Batas yang ditampilkan dapat berubah berdasarkan masukan. Untuk kemampuan yang sedang berlangsung, baca catatan rilis.
Komponen | Deskripsi Batas | Nilai Batas |
---|---|---|
Audiens kustom (CA) | Jumlah iklan maksimum per CA | 100 |
Jumlah maksimum CA per aplikasi | 1000 | |
Jumlah maksimum aplikasi yang dapat membuat CA | 1000 | |
Penundaan maksimum dalam waktu aktivasi CA dari waktu pembuatannya | 60 hari | |
Waktu habis masa berlaku maksimum CA dari waktu aktivasinya | 60 hari | |
Jumlah maksimum CA di perangkat | 4000 | |
Ukuran maksimum nama CA | 200 byte | |
Ukuran maksimum URI pengambilan harian | 400 byte | |
Ukuran maksimum URI logika bidding | 400 byte | |
Ukuran maksimum data bidding tepercaya | 10 KB | |
Ukuran maksimum sinyal bidding pengguna | 10 KB | |
Tarif panggilan maksimum untuk leaveCustomAudience per pembeli |
1 per detik | |
Tarif panggilan maksimum untuk joinCustomAudience per pembeli |
1 per detik | |
Pengambilan Latar Belakang CA | Waktu tunggu koneksi habis | 5 detik |
Waktu tunggu pembacaan HTTP habis | 30 detik | |
Total ukuran download maksimum | 10 KB | |
Durasi maksimum iterasi pengambilan | 5 menit | |
Jumlah maksimum CA yang diperbarui per tugas | 1000 | |
Pemilihan Iklan | Jumlah maksimum pembeli | Ditentukan Nanti |
Jumlah maksimum CA per pembeli | Ditentukan Nanti | |
Jumlah maksimum iklan dalam lelang | Ditentukan Nanti | |
Waktu tunggu koneksi awal habis | 5 detik | |
Waktu tunggu pembacaan koneksi habis | 5 detik | |
Waktu eksekusi maksimum AdSelection secara keseluruhan |
10 detik | |
Waktu eksekusi maksimum bidding per CA di AdSelection |
5 detik | |
Waktu eksekusi skor maksimum di AdSelection |
5 detik | |
Waktu eksekusi maksimum untuk per pembeli di AdSelection |
Ditentukan Nanti | |
Ukuran maksimum sinyal pemilihan iklan/penjual/per pembeli | Ditentukan Nanti | |
Ukuran maksimum skrip penjual/pembeli | Ditentukan Nanti | |
Tarif panggilan maksimum untuk selectAds |
1 QPS | |
Pelaporan tayangan | Waktu minimum sebelum menghapus pilihan iklan dari persistensi | 24 jam |
Jumlah maksimum pemilihan iklan penyimpanan | Ditentukan Nanti | |
Ukuran maksimum URL output pelaporan | Ditentukan Nanti | |
Waktu maksimum untuk pelaporan tayangan | Ditentukan Nanti | |
Jumlah maksimum percobaan ulang untuk panggilan notifikasi | Ditentukan Nanti | |
Waktu tunggu koneksi habis | 5 detik | |
Waktu eksekusi keseluruhan maksimum untuk reportImpression |
2 detik | |
Tarif panggilan maksimum untuk reportImpressions |
1 QPS | |
Iklan | Ukuran maksimum daftar iklan | 10 KB digunakan bersama oleh semua
AdData
dalam satu CA untuk konteks |
URL | Panjang maksimum string URL apa pun yang diambil sebagai input | Ditentukan Nanti |
Javascript | Waktu eksekusi maksimum | 1 detik untuk bidding dan penskoran untuk pelaporan tayangan |
Memori maksimum yang digunakan | 10 MB |
Melaporkan bug dan masalah
Masukan Anda adalah bagian penting dari Privacy Sandbox di Android. Beri tahu kami jika Anda menemukan masalah atau memiliki ide untuk meningkatkan kualitas Privacy Sandbox di Android.