Dukungan mediasi di Runtime SDK

Mediasi adalah cara umum bagi platform iklan sisi jual untuk menawarkan pengelolaan hasil. Dalam alur kerja mediasi, SDK mediasi ('mediator') memanggil beberapa jaringan iklan ('mediatee' atau 'mediatees') untuk mendapatkan iklan terbaik untuk slot tertentu. Dalam beberapa kasus, mediator dan jaringan iklan yang dipanggilnya memerlukan SDK mereka untuk berada di perangkat dan berinteraksi.

Dokumen ini menguraikan perubahan utama pada alur kerja mediasi di Runtime SDK. Panduan ini membahas topik berikut:

• Perbedaan antara alur mediasi sebelumnya dan dukungan mediasi Runtime SDK saat ini
• Menyiapkan tindakan untuk alur kerja mediasi di Runtime SDK, dan berbagai tahap transisi
• Panduan tentang cara menangani skenario saat tidak semua SDK telah dimigrasikan ke Runtime

Dukungan untuk Iklan Mediasi di Runtime SDK tersedia dari AGP 8.5 dan dari versi library Jetpack Runtime SDK berikut:

Library Androidx	Version
androidx.privacysandbox.activity	1.0.0-alpha01
androidx.privacysandbox.sdkruntime	1.0.0-alpha13
androidx.privacysandbox.tools	1.0.0-alpha08
androidx.privacysandbox.ui	1.0.0-alpha09

Glosarium

Istilah berikut adalah kunci untuk memahami mediasi di Runtime SDK:

• SDK dengan dukungan runtime (RE SDK): SDK yang dibuat untuk berjalan di lingkungan Runtime SDK dan berkomunikasi dengan aplikasi melalui komunikasi antarproses (IPC).
• Runtime-aware SDK (RA SDK): SDK non-runtime-enabled, yang ditautkan ke aplikasi secara statis, yang dapat berisi kode SDK yang ada serta kode baru untuk memanggil SDK yang mendukung runtime.
• SDK dalam aplikasi: SDK yang berjalan tertaut ke aplikasi secara statis, dan tidak memiliki pengetahuan tentang Runtime SDK. Hal ini mungkin merupakan jaringan iklan yang belum bertransisi ke Runtime SDK, atau adaptor kustom penayang.
• Mediator: SDK mediasi iklan yang menyediakan layanan mediasi di perangkat dengan berinteraksi dengan SDK jaringan iklan lainnya.
• Mediatee: SDK jaringan iklan yang dipanggil oleh Mediator untuk menyediakan dan merender iklan.
• Adaptor Mediasi: SDK yang digunakan oleh Mediator SDK untuk menyediakan terjemahan antarmuka API agar dapat berinteroperasi dengan berbagai SDK mediasi, biasanya disediakan oleh mediator. Ini dapat berupa runtime aware atau runtime unaware.

Alur mediasi umum

Jika SDK Anda perlu mendukung kasus penggunaan mediasi di Runtime SDK, Anda harus menerapkan beberapa perubahan. Bagian ini meninjau elemen utama alur mediasi sehingga kita dapat mengatasi perubahan yang diperlukan untuk mediator dan pihak yang dimediasi.

Alur yang kami jelaskan mewakili versi sederhana mediasi di perangkat dengan beberapa SDK jaringan iklan, dan berfungsi sebagai dasar diskusi tentang perubahan yang diperlukan untuk membuat perjalanan mediasi kompatibel dengan Runtime SDK.

Mengingat variasi dalam penerapan alur mediasi, kami berfokus pada dua alur utama berikut:

• Inisialisasi (termasuk penemuan jaringan iklan dan komunikasi)
• Presentasi antarmuka pengguna (UI) iklan

Inisialisasi

Berikut ini adalah inisialisasi standar, penemuan jaringan iklan, dan alur komunikasi:

1. Aplikasi klien memulai mediator
2. Mediator menemukan dan menginisialisasi mediasi dan adaptor yang relevan
3. Mediator menggunakan adaptornya untuk berkomunikasi dengan setiap mediasi
4. Aplikasi klien meminta mediator untuk memuat iklan
5. Aplikasi klien meminta mediator untuk menampilkan iklan ini

Catatan: Alur ini mengasumsikan bahwa aplikasi klien memiliki dependensi pada SDK mediator, SDK mediasi, dan adaptor mediasi, dan aplikasi tersebut dibuat dengan SDK tersebut.

Presentasi UI Iklan

Dalam hal merender iklan setelah permintaan akhir di langkah sebelumnya, alurnya bergantung pada jenis iklan:

Iklan banner	Iklan layar penuh	Iklan native
SDK mediator membuat Tampilan iklan, yang menggabungkan Tampilan iklan mediasi yang menang. Peristiwa ini juga dapat menetapkan pemroses di View ini, atau memuat ulang iklan secara otomatis (menggunakan mediasi yang sama atau berbeda).	SDK mediator meminta iklan layar penuh dari mediasi, yang pada akhirnya memulai Aktivitas.	Penayang mengelola penanganan dan inflasi tampilan menggunakan komponen yang ditampilkan oleh SDK mediator.

Alur mediasi di Runtime SDK

Cara kerja mediasi di dalam Runtime SDK berbeda-beda, bergantung pada apakah mediasi diaktifkan runtime atau tidak. Berdasarkan hal ini, kita dapat memiliki skenario berikut:

• Mediator dan mediasi berada di Runtime SDK: Mediasi RE
• Mediator berada di Runtime SDK, dan mediasi berada dalam aplikasi: Mediasi dalam aplikasi

RE Mediatee

Diagram arsitektur berikut menunjukkan ringkasan tingkat tinggi tentang interaksi SDK yang mendukung runtime (RE) dan mengetahui runtime (RA) mediator, adaptor mediasi RE, dan SDK RE mediasi.

Adaptor mediasi harus berada dalam proses yang sama dengan mediasi yang digunakan antarmukanya, sehingga adaptor mediasi juga harus dimigrasikan ke Runtime SDK.

Gambar 1. Mediator dan mediasi adalah RE SDK.

Inisialisasi

Saat mempertimbangkan inisialisasi, penemuan, dan komunikasi mediator dan mediasi yang mengaktifkan runtime, alur akan mengikuti langkah-langkah berikut:

1. Aplikasi (atau RA SDK) memuat dan melakukan inisialisasi SDK mediator menggunakan SdkSandboxManager#loadSdk.
2. Selama inisialisasi, SDK mediator memuat dan menginisialisasi mediasi yang diperlukan di Runtime SDK menggunakan SdkSandboxController#loadSdk.
3. RE SDK dapat menemukan semua SDK yang dimuat di Runtime dengan memanggil SdkSandboxController#getSandboxedSdks.

Gambar 2. Alur untuk melakukan inisialisasi mediasi RE.

Catatan: Gunakan class *Compat Runtime Manager dan Controller untuk memastikan bahwa SDK yang mengaktifkan runtime kompatibel dengan versi sebelumnya.

Presentasi UI Iklan

Bagian berikut membahas pemuatan banner dan iklan layar penuh dari mediator RE.

Iklan banner RE Mediatee

Dengan permintaan dari aplikasi untuk memuat iklan banner, alur untuk menyelesaikan rendering adalah sebagai berikut:

1. Mediator memilih mediasi pemenang untuk iklan ini.
2. Mediator mendapatkan SandboxedUiAdapter dari pihak yang dimediasi.
3. Mediator meneruskan UiAdapter ke aplikasi.

Gambar 3. Alur untuk menyelesaikan rendering iklan banner dari mediasi RE.

Pelajari lebih lanjut penggunaan SandboxedUiAdapter dan Library UI Runtime SDK.

Overlay untuk iklan banner

Jika mediator ingin menambahkan overlay ke iklan, mereka harus mengubah alur sebagai berikut:

1. Mediator membuat tata letak dengan overlay dan SandboxedSdkView.
2. Mediator memilih mediasi pemenang untuk iklan ini.
3. Mediator mendapatkan SandboxedUiAdapter dari pihak yang dimediasi.
4. Mediator menetapkan UiAdapter mediasi ke SandboxedSdkView.
5. Mediator membagikan tampilan yang terisi ke aplikasi.

Alur untuk menempatkan tampilan di atas iklan banner yang diperoleh dari RE Mediatee.

Iklan layar penuh RE Mediatee

Dengan permintaan dari aplikasi untuk memuat iklan layar penuh, alur ini akan mengikuti langkah-langkah berikut:

1. Aplikasi (atau RA SDK) meneruskan SdkActivityLauncher ke mediator dengan permintaan untuk memuat iklan.
   1. Klien dapat membatasi pembuatan aktivitas menggunakan predikat.
2. Mediator memilih mediasi pemenang untuk iklan ini.
3. Mediator meminta mediasi untuk memuat iklan, dengan meneruskan SdkActivityLauncher dari aplikasi.
4. Mediasi mendaftarkan pengendali aktivitas, dan mendapatkan token ID untuk aktivitas yang terdaftar.
5. Mediasi menggunakan SdkActivityLauncher untuk meminta memulai aktivitas menggunakan token ini.
6. Jika predikat aplikasi klien mengizinkannya, Runtime SDK akan memulai aktivitas ini dalam proses khusus.

Gambar 4. Diagram alur yang mengilustrasikan cara memuat iklan layar penuh yang dimediasi dari RE Mediatee.

Catatan: Semua peristiwa siklus proses aktivitas tersedia untuk mediasi menggunakan ActivityHolder yang digunakan saat mendaftarkan pengendali aktivitas.

Pelajari lebih lanjut dukungan Aktivitas untuk iklan layar penuh di Runtime SDK.

Mediatee dalam aplikasi

Diagram arsitektur berikut menunjukkan ringkasan tingkat tinggi tentang interaksi SDK RE dan RA mediator, adaptor mediasi yang tidak mengetahui Runtime SDK, dan SDK mediasi yang ditautkan secara statis ke aplikasi (juga tidak mengetahui runtime).

Gambar 5. Mediasi ditautkan secara statis ke aplikasi, meskipun mengetahui RE SDK.

Inisialisasi

Karena dalam skenario ini, mediasi ditautkan secara statis ke aplikasi dan belum dimigrasikan ke Runtime SDK, SDK yang mengaktifkan runtime mediator harus memiliki proses untuk mendaftarkannya.

Pendaftaran ini harus dapat diakses menggunakan API mediator, tetapi detail penerapannya diserahkan kepada pertimbangan setiap mediator. Kita menyebut API ini MediationSandboxedSdk#registerInAppMediatee.

Saat mempertimbangkan inisialisasi, penemuan, dan komunikasi SDK mediator RE dan SDK mediasi dalam aplikasi, alur akan mengikuti langkah-langkah berikut:

1. Aplikasi memuat dan melakukan inisialisasi SDK yang mendukung runtime mediator.
2. SDK RA mediator:
   1. Melakukan inisialisasi RE SDK mediator menggunakan SdkSandboxManager#loadSdk.
   2. Melakukan inisialisasi semua SDK mediasi dalam aplikasi.
   3. Menemukan dan mendaftarkan SDK mediasi dalam aplikasi menggunakan API yang disediakan oleh RE SDK, MediationSandboxedSdk#registerInAppMediate.

Selain mendaftarkan semua SDK mediasi dalam aplikasi, RE SDK mediator dapat menemukan semua SDK yang dimuat di Runtime SDK menggunakan SdkSandboxController#getSandboxedSdks.

Gambar 6. Perhatikan bahwa kita menggunakan API mediator yang disarankan untuk mendaftarkan referensi ke mediasi dalam aplikasi.

Presentasi UI Iklan

Bagian berikut membahas pemuatan banner dan iklan layar penuh dari mediatee dalam aplikasi.

Iklan banner Mediatee dalam aplikasi

Dengan permintaan dari aplikasi untuk memuat iklan banner, alur untuk menyelesaikan rendering adalah sebagai berikut:

1. SDK yang mendukung runtime mediator meneruskan permintaan aplikasi ke SDK yang mendukung runtime.
2. RE SDK mediator memilih mediasi yang relevan.
3. RE SDK mediator mengambil referensi ke mediasi, dan meminta untuk memuat iklan melalui RA SDK.
4. RA SDK mendapatkan View dari mediasi dalam aplikasi.
5. RA SDK membuat SandboxedUiAdapter untuk View yang diterimanya.
6. RA SDK meneruskan UiAdapter ke RE SDK.
7. RE SDK meneruskan UiAdapter ke aplikasi.

Perhatian: Karena SandboxedUiAdapter ini diterima dari proses aplikasi, sebaiknya jangan tambahkan overlay ke View ini karena dapat menyebabkan masalah latensi, performa, dan perilaku.

Gambar 7. Perhatikan bahwa mediator tidak boleh menempatkan tampilan di atas V1 saat mendapatkannya dari mediasi dalam aplikasi.

Iklan layar penuh Mediatee dalam aplikasi

Dengan permintaan dari aplikasi untuk memuat iklan layar penuh, alur ini akan mengikuti langkah-langkah berikut:

1. Aplikasi meneruskan SdkActivityLauncher ke RA SDK mediator dengan permintaan untuk memuat iklan.
   1. Klien dapat membatasi pembuatan aktivitas menggunakan predikat.
2. RA SDK mediator meneruskan permintaan aplikasi ke RE SDK-nya.
3. RE SDK mediator:
   1. Memilih mediasi yang relevan.
   2. Mengambil referensi ke mediasi dalam aplikasi.
   3. Meminta untuk memuat iklan melalui RA SDK.
4. RA SDK meminta mediasi untuk memuat iklan.
5. Mediasi memulai aktivitas secara langsung. Predikat aplikasi tidak akan dihormati.

Gambar 8. Predikat akan diabaikan oleh mediasi dalam aplikasi.

Catatan: Semua peristiwa di sekitar aktivitas tersedia untuk mediasi seperti sebelum Runtime SDK.

Berinteraksi dan memberikan masukan

Privacy Sandbox di Android adalah project yang sedang berlangsung, dan dokumen ini mencerminkan desainnya saat ini. Masukan Anda sangat penting bagi kami seiring upaya kami untuk terus mengembangkan dan meningkatkan kualitas fiturnya. Laporkan bug untuk memberikan masukan.