API presentasi UI Runtime SDK

Catatan: Privacy Sandbox di Android adalah project yang sedang berlangsung, dan dokumen ini mencerminkan desainnya saat ini. Masukan Anda sangat penting seiring kami terus mengembangkan dan meningkatkan kualitas fiturnya.

Dengan Runtime SDK, SDK iklan dapat berjalan di lingkungan yang di-sandbox sehingga mencegahnya mengakses hierarki tampilan penayang. Untuk menampilkan iklan, platform mengekspos SandboxedSdkProvider.getView API ke SDK untuk mendapatkan tampilan iklan, dan memaketkannya sebagai SurfacePackage untuk dikirim melalui IPC (komunikasi antar-proses) ke aplikasi klien. Cara ini memiliki beberapa kelemahan yang akan dibahas di bawah ini. Selanjutnya, dokumen ini akan menyajikan library Jetpack yang sedang dibangun untuk mengatasi berbagai tantangan ini.

Alasan meningkatkan API platform

API framework dirancang untuk fleksibilitas dan menyerahkan tugas membangun saluran samping antara presentasi UI hingga aplikasi dan SDK. Saluran samping ini bertugas melakukan berbagai hal berikut:

1. Mengizinkan SDK mengelola beberapa tampilan iklan selama masa aktifnya dan memahami proses yang terjadi di UI iklan setelah dibuat oleh SDK.
2. Memisahkan pembuatan tampilan dan binding konten. Menggunakan saluran samping agar SDK dapat menampilkan objek yang sesuai dengan permintaan iklan ke aplikasi (konten) yang dapat diikat ke penampung iklan setiap kali dinilai sesuai oleh aplikasi.
3. Mengabstraksi konstruksi platform dasar yang digunakan untuk menampilkan UI di seluruh proses. (Saat ini platform menggunakan SurfaceControlViewhost dan menghasilkan SurfacePackage darinya.)
4. Mengaktifkan SDK iklan di Runtime SDK untuk menerima notifikasi secara otomatis saat UI penampung iklan berubah. Jika penayang mengubah tata letak penampung iklan, SDK tetap tidak akan mengetahui perubahan ini kecuali jika penayang memanggil API secara eksplisit untuk memberi tahu.
5. Menyinkronkan perubahan ukuran UI iklan dan penampung iklan tanpa adanya jank yang terlihat oleh pengguna.
6. Mengelola kompatibilitas mundur secara otomatis. SurfacePackage tidak tersedia sebelum level API 30. Selain itu, di perangkat yang tidak memiliki runtime SDK dan SDK merupakan proses lokal untuk penayang, maka pembuatan SurfacePackage untuk iklan akan sia-sia jika tampilan dapat langsung diperoleh dari SDK. Saluran samping mengabstraksi kompleksitas ini dari SDK dan kode developer aplikasi.
7. Memungkinkan UI iklan terintegrasi secara lancar dengan Composable. Developer Jetpack Compose yang tidak menangani tampilan juga dapat terus menghosting UI yang dihasilkan oleh developer SDK yang masih menangani tampilan.

Library UI

Library UI mengabstraksi kompleksitas yang dijelaskan di atas dan menyediakan saluran samping yang dapat digunakan penayang dan SDK untuk menampilkan UI di seluruh proses, serta terus mengupdatenya selama pengguna berinteraksi dengan UI dan dengan perangkat.

Ada tiga library UI: inti, klien, dan penyedia. Library inti menyediakan antarmuka yang digunakan library klien dan penyedia. Penyedia UI (biasanya SDK) bergantung pada library penyedia, sementara konsumen UI (biasanya penayang) bergantung pada library klien. Library klien dan penyedia bersama-sama membentuk saluran samping yang diperlukan untuk membuat dan mengelola sesi UI.

API

API untuk presentasi UI Runtime SDK adalah sebagai berikut:

SandboxedUiAdapter: Dibuat oleh SDK, dan memberikan cara untuk mendapatkan konten yang akan ditampilkan di UI penayang.

SandboxedSdkView: Dibuat oleh penayang, dan merupakan penampung yang menyimpan konten yang diperoleh melalui SandboxedUiAdapter.

Session: Dibuat oleh SDK untuk merespons SandboxedUiAdapter.openSession(). Mewakili satu panggilan sesi UI. API ini membentuk sisi SDK dari tunnel komunikasi antara SDK dan penayang, serta menerima notifikasi tentang perubahan dalam SandboxedSdkView, seperti pelepasan jendela, perubahan ukuran, atau perubahan konfigurasi.

SessionClient: Dibuat oleh library klien, API ini membentuk akhir tunnel komunikasi penayang antara SDK dan penayang.

SandboxedSdkUiSessionStateChangedListener: Dibuat oleh penayang. Pemroses untuk perubahan status sesi UI yang terkait dengan SandboxedSdkView.

Hubungan antara API presentasi UI Runtime SDK.

Baca dokumentasi referensi privacysandbox-ui untuk mengetahui detail lengkap semua API ini.

Alur kontrol

Diagram berikut menunjukkan interaksi antara library UI klien dan penyedia dalam berbagai skenario:

Diagram sebelumnya menunjukkan cara penayang dapat membuat SandboxedSdkView secara terprogram atau melalui XML-nya dan melampirkannya ke SdkSandboxUiAdapter yang diperoleh dari SDK melalui API yang ditentukan SDK. Untuk mengamati semua perubahan status UI, penayang harus menambahkan SandboxedSdkUiSessionStateChangedListener ke SandboxedSdkView sebelum melampirkan SdkSandboxUiAdapter.

Mendapatkan UI dari SDK.

Diagram ini menunjukkan bagaimana jika aktivitas penayang menangani perubahan konfigurasi, library klien menangani penerusan perubahan konfigurasi ke SDK, sehingga mereka dapat memperbarui UI-nya. Misalnya, alur ini dapat dipicu saat pengguna merotasi perangkat, dan penayang mendeklarasikan penanganan perubahan konfigurasi dalam aktivitasnya dengan menetapkan android:configChanges=["orientation"].

Perubahan UI yang dimulai penayang.

Diagram ini menggambarkan cara SDK meminta perubahan di penampung iklan menggunakan metode pada SessionClient. API ini dipicu saat SDK ingin mengubah ukuran iklan dan meminta penayang mengubah ukuran penampung iklan agar dapat menampung dimensi baru. Tindakan ini mungkin terjadi sebagai respons terhadap interaksi pengguna, seperti mraid.resize().

Perubahan UI yang dimulai SDK.

Diagram ini menunjukkan cara sesi ditutup saat SandboxedSdkView dilepas dari jendela. Sesi juga dapat ditutup kapan saja (misalnya, saat pengguna kehilangan konektivitas jaringan) oleh SDK dengan memanggil SessionClient.onSessionError().

Menutup sesi UI.

Urutan Z

Library UI klien menggunakan SurfaceView secara internal untuk menghosting UI SDK. SurfaceView dapat menggunakan urutan Z untuk menampilkan UI-nya di atas jendela penayang, atau di bawahnya. Hal ini dikontrol oleh metode SandboxedSdkView.orderProviderUiAboveClientUi(), yang menerima setOnTop boolean.

Ketika setOnTop adalah true, setiap android.view.MotionEvent di SandboxedSdkView akan dikirim ke SDK. Ketika false, semuanya akan dikirim ke penayang. Secara default, peristiwa gerakan dikirim ke SDK.

Penayang biasanya tidak perlu mengubah urutan Z default dari tayangan iklan. Namun, saat menampilkan UI yang mencakup iklan, seperti menu drop-down, urutan Z harus dibalik untuk sementara dari default, lalu dipulihkan saat elemen UI yang menutupi ditutup. Kami sedang mempelajari cara mengotomatiskan proses ini di library UI klien.

Scroll

Saat UI iklan diurutkan Z di atas jendela penayang, MotionEvents dari UI iklan akan dikirim ke SDK. Gestur scroll dan ayunkan jari yang dimulai di UI iklan mendapatkan perlakuan khusus:

1. Gestur scroll dan ayunkan jari dikirim ke dan ditangani oleh penampung penayang. Cara ini memberikan UX yang baik jika penampung penayang tempat UI iklan berada dapat di-scroll secara vertikal. Selain itu, cara ini tidak memerlukan pekerjaan tambahan di pihak SDK atau penayang.
2. Gestur scroll secara horizontal dan ayunkan jari dikirim ke dan ditangani oleh SDK. Cara ini memberikan UX yang baik saat UI iklan dapat di-scroll secara horizontal (seperti carousel iklan).

Panduan penerapan

SDK harus menerapkan hal berikut:

• SandboxedUiAdapter: Ini ditampilkan ke penayang sebagai respons terhadap API yang ditentukan SDK, seperti loadAd. Metode openSession() untuk sebaiknya digunakan untuk membuat permintaan iklan ke server SDK dan menyiapkan tampilan iklan untuk permintaan tersebut.
• Session**: Ini ditampilkan sebagai respons terhadap panggilan SandboxedUiAdapter.openSession. Cara ini memungkinkan klien untuk mendapatkan UI iklan dan memberi tahu SDK tentang perubahan pada API ini. Semua metode Session harus diterapkan di sini.

Penayang harus melakukan tindakan berikut:

1. Membuat SandboxedSdkView, baik melalui XML maupun secara terprogram.
2. Melampirkan SandboxedSdkUiSessionStateChangedListener ke SandboxedSdkView untuk mengamati perubahan di UI.
3. Melampirkan SDK yang disediakan SandboxedUiAdapter ke SandboxedSdkView.
4. Menambahkan SandboxedSdkView ke jendela seperti biasa, dan biarkan library klien menangani pembuatan maupun pengelolaan sesi UI dengan SDK.
5. Pada waktu yang tepat, berikan reaksi terhadap perubahan status yang dilaporkan oleh SandboxedSdkUiSessionChangedListener. Misalnya, jika SDK menutup sesi secara tidak terduga, penayang dapat mengganti SandboxedSdkView dengan gambar statis, atau menghapusnya dari hierarki tampilan.
6. Saat melakukan transisi yang mungkin mencakup UI iklan, seperti menu drop-down, sementara orderProviderUiAboveClientUi ke nilai false untuk memosisikan UI iklan di bawah jendela penayang. Setelah menu drop-down ditutup, panggil orderProviderUiAboveClientUi ke true.

Masa depan API platform

Setelah library UI menjadi versi Beta, kami berencana menghentikan penggunaan API platform runtime SDK yang terkait dengan presentasi UI, yaitu SdkSandboxManager.requestSurfacePackage() dan SandbxedSdkProvider.getView().

Pertanyaan terbuka

1. Adakah kasus penggunaan UI iklan yang lebih umum yang harus ditangani secara otomatis oleh library UI?
2. Framework UI mana yang Anda gunakan untuk menampilkan UI iklan, apakah Anda mengantisipasi munculnya masalah dalam mengintegrasikan library UI dengan framework ini?
3. Apakah UI iklan yang dapat di-scroll dan ditempatkan dalam penampung penayang yang dapat di-scroll adalah kasus penggunaan umum bagi Anda? Bagaimana arah scroll untuk UI iklan dan penampung dalam kasus ini? Perilaku apa yang diharapkan saat pengguna memulai scroll pada UI iklan?