Proposal desain visibilitas Runtime SDK

SDK Iklan di Runtime SDK tidak dapat mengakses hierarki tampilan penayang. Sebagai gantinya, SDK di Runtime memiliki tampilannya sendiri. SDK tidak dapat menggunakan View API yang sama seperti yang digunakan di luar runtime SDK untuk menentukan apakah iklan terlihat oleh pengguna atau tidak karena tampilan iklan tidak dikaitkan ke jendela aplikasi. Ini mencakup View API Android seperti getLocationOnScreen, getLocationInWindow, atau getVisibility, yang tidak menampilkan nilai yang diharapkan.

Mendukung pengukuran visibilitas iklan adalah persyaratan inti Runtime SDK. Proposal desain ini bertujuan memberikan dukungan untuk Pengukuran Terbuka dan layanan pengukuran serupa. Solusi yang dibahas di sini mungkin juga berlaku untuk Attribution Reporting API. Masukan Anda terkait proposal ini sangat diharapkan.

Kemampuan

Desain ini bertujuan mendukung SDK iklan atau partner pengukuran untuk menghitung data visibilitas berikut (namanya bersifat sementara dan dapat berubah sewaktu-waktu):

Ringkasan Visibilitas Runtime SDK.

• viewport [Rect]: Menampilkan layar perangkat atau geometri jendela aplikasi, bergantung pada kemampuan platform.
• uiContainerGeometry [Rect]: Geometri SandboxedSdkView yang dirender.
• alpha [float]: Opasitas SandboxedSdkView yang dirender.
• onScreenGeometry [Rect]: Subset uiContainerGeometry yang tidak terpotong oleh tampilan induk, hingga dan termasuk viewport).
• occludedGeometry [Rect]: Bagian onScreenGeometry yang terhalang oleh tampilan dalam hierarki aplikasi. Menyertakan Rect untuk setiap oklusi, yang sesuai dengan nol, satu, atau beberapa tampilan aplikasi yang berpotongan dengan SandboxedSdkView onScreenGeometry

Persyaratan

• Nilai untuk uiContainerGeometry, onScreenGeometry, dan occludedGeometry dinyatakan dalam ruang koordinat viewport.
• Pelaporan perubahan visibilitas terjadi dengan latensi minimal.
• Visibilitas dapat diukur untuk keseluruhan siklus proses tampilan iklan, dari kemunculan pertamanya hingga terakhir.

Proposal desain

Proposal ini dibuat berdasarkan cara kerja presentasi UI menggunakan library UI klien dan penyedia. Kami akan memperluas library UI agar SDK dapat mendaftarkan satu atau beberapa observer sesi UI. Observer akan menerima informasi visibilitas setiap kali peristiwa relevan yang mengubah jenis data di bagian capabilities terdeteksi. SDK Pengukuran dalam runtime SDK (penerapan OMID dan MRAID) dapat melampirkan observer ini ke sesi UI sehingga informasi ini dapat dikirim langsung ke SDK Pengukuran. Partner pengukuran dapat menggabungkan informasi yang diperoleh dari library UI dengan data tentang konten yang sudah tersedia (seperti saat menggunakan skrip pengukuran yang dimasukkan dalam materi iklan) untuk menghasilkan peristiwa visibilitas JavaScript.

Alur kontrol untuk visibilitas.

Library klien memproses perubahan dalam UI iklan melalui pemroses peristiwa, seperti ViewTreeObserver. Setiap kali menentukan bahwa UI iklan telah berubah dengan cara yang dapat memengaruhi pengukuran visibilitas, library klien akan memeriksa waktu pengiriman notifikasi terakhir ke observer. Jika update terakhir lebih besar daripada latensi yang diizinkan (dapat dikonfigurasi oleh SDK, hingga minimum 200 ms di perangkat seluler), objek AdContainerInfo baru akan dibuat dan notifikasi akan dikirimkan ke observer. Model berbasis peristiwa ini lebih baik untuk kesehatan sistem dibandingkan polling yang dilakukan oleh sebagian besar penerapan OMID di Android saat ini.

API

Parameter berikut akan ditambahkan ke library privacysandbox.ui.core:

• SessionObserver: Biasanya diterapkan oleh SDK pengukuran yang dilampirkan ke sesi yang ditampilkan oleh SDK melalui privacysandbox.ui. Antarmuka ini juga akan memungkinkan SDK pengukuran ikut serta dalam kategori sinyal visibilitas tertentu. Hal ini kemudian akan memungkinkan library klien UI untuk hanya mengumpulkan sinyal yang menarik bagi observer, yang lebih baik untuk kesehatan sistem secara keseluruhan.
• registerObserver(): Ditambahkan ke class Session, metode ini memungkinkan siapa saja yang memiliki akses ke Sesi untuk mendaftarkan observer. Jika observer didaftarkan setelah sesi UI dibuka, AdContainerInfo yang di-cache akan segera dikirim ke observer. Jika didaftarkan sebelum sesi dibuka, AdContainerInfo akan dikirim ke observer saat sesi dibuka.
• AdContainerInfo: Class dengan pengambil yang memungkinkan observer memperoleh informasi penampung iklan hanya baca untuk jenis data yang tercantum di bagian kemampuan di atas. Nilai hasil dari pengambil ini akan sesuai, jika memungkinkan, dengan nilai hasil parcelable dari pengambil yang ada di View dan subclass-nya. Jika penampung iklan telah dibuat menggunakan Jetpack Compose, properti semantik penampung akan ditampilkan. Class ini dapat digunakan untuk menghitung peristiwa MRAID dan OMID yang terkait dengan visibilitas.
• SessionObserverotifyAdContainerChanged(): Digunakan untuk memberi tahu observer setiap kali visibilitas berubah. Metode ini meneruskan objek AdContainerInfo. Metode ini akan dipanggil setiap kali peristiwa yang memengaruhi jenis data yang tercantum di bagian Kemampuan terdeteksi. Catatan: Metode ini mungkin dipanggil selain metode pada Sesi. Misalnya, Session.notifyResized() dipanggil untuk meminta SDK mengubah ukuran iklan, dan SessionObserver.notifyAdContainerChanged() juga dipanggil saat hal ini terjadi.
• SessionObserverotifySessionClosed(): Memberi tahu observer bahwa sesi telah ditutup.

Catatan: Masa aktif SessionObserver terikat dengan masa aktif sesi. Jika sesi ditutup, SessionObserver akan menerima panggilan notifySessionClosed(), dan tidak ada metode lebih lanjut yang akan dikirim ke sesi tersebut. Karena sesi dapat ditutup oleh SDK penyedia UI, atau saat SandboxedSdkView dilepas dari jendela aplikasi penayang, SDK pengukuran harus dapat membedakan antara sesi UI dan sesi iklan. Mungkin ada beberapa sesi saat iklan ditampilkan. Misalnya, jika penayang tidak menangani rotasi perangkat, aktivitasnya akan dimulai ulang setiap kali perangkat diputar. Saat aktivitas dihancurkan, SandboxedSdkView akan dilepas dari jendela dan Sesi UI ditutup. Jika penayang menyimpan adaptor UI saat aktivitas dimulai ulang, penayang mungkin dapat memasang adaptor yang sama ke SandboxedSdkView baru, dan membuka Sesi baru setelah aktivitas dimulai. Partner pengukuran akan melampirkan observer ke Sesi baru, dan dapat memilih untuk menggunakan kembali observer yang dilampirkan ke sesi sebelumnya agar pengukuran dapat terus berjalan.

Peningkatan mendatang

Setiap kode yang berjalan dalam proses aplikasi, termasuk kode dari library privacysandbox.ui.client, dapat diubah jika aplikasi disusupi. Oleh karena itu, setiap logika pengumpulan sinyal yang berjalan dalam proses aplikasi rentan terhadap gangguan yang disebabkan oleh kode aplikasi. Hal ini juga berlaku untuk kode SDK yang di-deploy sebelum ketersediaan Privacy Sandbox yang berjalan dalam proses aplikasi. Karenanya, pengumpulan sinyal oleh library UI tidak memperburuk situasi keamanan.

Selain itu, kode dalam runtime SDK dapat menggunakan API platform bernama setTrustedPresentationCallback yang dapat memberikan jaminan presentasi UI iklan yang lebih kuat jika dibandingkan dengan framework. setTrustedPresentationCallback berfungsi pada tingkat Platform, dan dapat membantu membuat pernyataan tentang Platform yang berisi UI iklan dengan menentukan nilai minimum presentasi, seperti persentase piksel yang terlihat, waktu di layar, atau skalanya. Data ini dapat diperiksa berdasarkan data visibilitas yang disediakan oleh library klien UI, seperti yang dijelaskan di atas. Karena data yang disediakan framework lebih andal, semua peristiwa dari library UI yang datanya tidak sesuai dengan data dari framework dapat dihapus. Misalnya, jika pemroses yang diberikan ke setTrustedPresentationCallback dipanggil dengan notifikasi bahwa tidak ada piksel UI iklan yang ditampilkan di layar, sementara library UI klien menampilkan jumlah piksel yang bukan nol di layar, data yang terakhir ini bisa dibuang.

Pertanyaan terbuka

Kami menerima masukan pada poin-poin berikut:

1. Sinyal visibilitas apa yang menarik bagi Anda, tetapi belum disebutkan dalam penjelasan ini?
2. Proposal saat ini adalah memperbarui visibilitas setidaknya setiap 200 milidetik, dengan syarat ada perubahan yang relevan di UI. Apakah frekuensi ini dapat Anda terima? Jika tidak, berapa frekuensi yang Anda inginkan?
3. Apakah Anda lebih suka menganalisis informasi dari setTrustedPresentationCallback sendiri, atau menginginkan library UI penyedia menghapus data dari library UI klien, jika tidak cocok dengan data setTrustedPresentationCallback?
4. Bagaimana cara Anda memakai sinyal visibilitas? Bantu kami memahami kasus penggunaan Anda dengan memberikan masukan yang menjawab pertanyaan ini.