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 SDK Runtime. Bagian ini membahas topik berikut:

• Perbedaan antara alur mediasi sebelumnya dan dukungan mediasi SDK Runtime 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 yang Dimediasi di Runtime SDK tersedia dari AGP 8.5 dan dari library Jetpack Runtime SDK versi 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 penting untuk memahami mediasi di Runtime SDK:

• SDK dengan dukungan runtime (RE SDK): SDK yang dibuat untuk berjalan di lingkungan SDK Runtime dan berkomunikasi dengan aplikasi melalui komunikasi antar-proses (IPC).
• SDK yang kompatibel dengan runtime (RA SDK): SDK yang tidak kompatibel dengan runtime, ditautkan ke aplikasi secara statis, yang dapat berisi kode SDK yang ada serta kode baru untuk memanggil SDK yang kompatibel dengan runtime.
• SDK dalam aplikasi: SDK yang berjalan tertaut ke aplikasi secara statis, dan tidak mengetahui Runtime SDK. Hal ini mungkin merupakan jaringan iklan yang belum beralih ke SDK Runtime, 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 beroperasi dengan berbagai SDK yang dimediasi, 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 menangani 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 dan komunikasi jaringan iklan)
• Presentasi antarmuka pengguna (UI) iklan

Inisialisasi

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

1. Aplikasi klien memulai perantara
2. Mediator menemukan dan menginisialisasi mediatee 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

Presentasi UI Iklan

Terkait rendering iklan setelah permintaan terakhir pada langkah sebelumnya, alur bergantung pada jenis iklan:

Iklan banner	Iklan layar penuh	Iklan native
SDK mediator membuat View iklan, yang membungkus View iklan mediasi yang menang. Hal ini juga dapat menyetel pendengar di Tampilan ini, atau memuat ulang iklan secara otomatis (menggunakan mediatee yang sama atau berbeda).	SDK mediator meminta iklan layar penuh dari mediasi, yang pada gilirannya memulai Aktivitas.	Penayang mengelola penanganan dan perluasan tampilan menggunakan komponen yang ditampilkan oleh mediator SDK.

Alur mediasi di Runtime SDK

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

• Mediator dan mediatee berada di SDK Runtime: Mediatee RE
• Mediator berada di Runtime SDK, dan mediatee berada dalam aplikasi: Mediatee dalam aplikasi

RE Mediatee

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

Adaptor mediasi harus berada dalam proses yang sama dengan mediatee yang berinteraksi dengannya, sehingga adaptor tersebut juga harus dimigrasikan ke Runtime SDK.

Inisialisasi

Saat mempertimbangkan inisialisasi, penemuan, dan komunikasi mediator dan mediatee yang diaktifkan runtime, alurnya akan mengikuti langkah-langkah berikut:

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

Presentasi UI Iklan

Bagian berikut membahas cara memuat banner dan iklan layar penuh dari RE mediatee.

Iklan banner RE Mediatee

Mengingat 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.

Pelajari lebih lanjut penggunaan SandboxedUiAdapter dan Library UI Runtime SDK.

Overlay pada iklan banner

Jika mediator ingin menambahkan overlay ke iklan, mereka harus mengubah alurnya 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 mediatee ke SandboxedSdkView.
5. Mediator membagikan tampilan yang diisi dengan aplikasi.

Iklan layar penuh RE Mediatee

Mengingat permintaan dari aplikasi untuk memuat iklan layar penuh, alurnya 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 mediatee untuk memuat iklan, dengan meneruskan SdkActivityLauncher dari aplikasi.
4. Mediatee mendaftarkan handler aktivitas, dan mendapatkan token ID untuk aktivitas yang terdaftar.
5. Mediatee menggunakan SdkActivityLauncher untuk meminta memulai aktivitas menggunakan token ini.
6. Jika predikat aplikasi klien mengizinkannya, SDK Runtime akan memulai aktivitas ini dalam proses khusus.

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 SDK Runtime, dan SDK yang dimediasi yang ditautkan secara statis ke aplikasi (juga tidak mengetahui runtime).

Inisialisasi

Karena dalam skenario ini, mediatee ditautkan secara statis ke aplikasi dan belum dimigrasikan ke Runtime SDK, SDK dengan dukungan runtime mediator harus memiliki proses untuk mendaftarkannya.

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

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

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

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

Presentasi UI Iklan

Bagian berikut membahas cara memuat banner dan iklan layar penuh dari mediasi dalam aplikasi.

Iklan banner mediasi dalam aplikasi

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

1. SDK yang kompatibel dengan runtime mediator meneruskan permintaan aplikasi ke SDK yang kompatibel dengan runtime.
2. SDK RE mediator memilih mediasi yang relevan.
3. RE SDK mediator mengambil referensi ke mediatee, dan meminta untuk memuat iklan melalui RA SDK.
4. SDK RA mendapatkan Tampilan 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.

Iklan layar penuh yang dimediasi dalam aplikasi

Mengingat permintaan dari aplikasi untuk memuat iklan layar penuh, alurnya mengikuti langkah-langkah berikut:

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

Berinteraksi dan memberikan masukan

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