Dukungan aktivitas untuk iklan layar penuh

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

Runtime SDK memberlakukan batasan tentang cara SDK dapat meluncurkan aktivitas baru. Hal ini menimbulkan tantangan bagi format iklan layar penuh yang biasanya mengandalkan dimulainya aktivitas terpisah untuk meningkatkan kontrol dan pengalaman pengguna. Untuk mengatasi hal ini, Runtime SDK memperkenalkan mekanisme baru untuk aktivitas dengan sandbox.

SDK yang dimuat dalam lingkungan Runtime SDK tidak dapat menentukan tag <activity> secara langsung dalam manifesnya atau memulai aktivitasnya sendiri. Sebagai gantinya, tindakan intent baru, START_SANDBOXED_ACTIVITY, diperkenalkan.

Meskipun SDK juga dibatasi untuk meluncurkan intent dengan tindakan ini, SDK dapat meminta aplikasi klien untuk memulai intent ini. Kemudian, sistem akan membuat aktivitas yang ditentukan platform dan meneruskannya ke SDK. Aktivitas ini akan berjalan dalam proses yang sama dengan SDK.

SDK kemudian dapat menggunakan aktivitas ini untuk menerapkan dan mengelola pengalaman iklan layar penuh.

Aktivitas yang disediakan oleh platform adalah android.app.Activity standar, yang diluncurkan sebagai bagian dari tugas aplikasi klien.

Perhatian: Aktivitas yang disediakan (android.app.Activity) memiliki dukungan terbatas dengan beberapa library AndroidX di sisi SDK, terutama Compose.

Perhatian: Context aktivitas ini tidak boleh digunakan langsung oleh SDK. Sebagai gantinya, SDK harus menggunakan SandboxedSdkProvider#getContext() untuk mendapatkan konteks yang sesuai untuk operasinya.

Pembuatan aktivitas di Runtime SDK

Anda memiliki dua metode utama untuk membuat aktivitas: menggunakan library Aktivitas Jetpack yang disederhanakan atau berinteraksi langsung dengan Platform API.

Sebaiknya gunakan library Aktivitas karena menyederhanakan pembuatan aktivitas dengan memisahkan kompleksitas yang mendasarinya.

Library aktivitas

Library aktivitas memberikan beberapa keuntungan:

• Mengabstrak detail internal pendaftaran pengendali aktivitas dan membagikan ID-nya dengan aplikasi klien.
• Memberi developer aplikasi kontrol lebih besar atas cara SDK membuat Aktivitas dalam aplikasi mereka dengan memungkinkan mereka menetapkan kondisi (predikat) yang harus dipenuhi.
• Membuat cara terpadu bagi SDK untuk menentukan API yang meluncurkan aktivitas.

Ada tiga library aktivitas: inti, klien, dan penyedia.

• Library inti menyediakan antarmuka yang digunakan oleh aplikasi klien dan library penyedia.
• Library penyedia menyediakan API untuk SDK guna meluncurkan aktivitas.
• Library klien menyediakan API untuk aplikasi klien guna membuat peluncur aktivitas, yang dapat digunakan SDK untuk meminta aplikasi meluncurkan aktivitas.

Library ini memperkenalkan API berikut:

• SdkActivityLauncher: Peluncur aktivitas memungkinkan SDK menangani aktivitas peluncuran dari aplikasi klien. Aplikasi klien harus membuat peluncur dan meneruskannya sebagai parameter ke API SDK yang memulai aktivitas.
• <T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): Fungsi ekstensi yang dapat dipanggil aplikasi klien dari aktivitasnya untuk membuat peluncur.
• SdkActivityLauncher.launchSdkActivity(IBinder): Metode yang digunakan oleh SDK untuk meminta aplikasi meluncurkan aktivitas.

Alur peluncuran aktivitas dengan library aktivitas adalah sebagai berikut:

1. SDK menambahkan parameter jenis SdkActivityLauncher ke API apa pun yang akan memulai aktivitas.
2. Aplikasi klien memanggil createSdkActivityLauncher di salah satu aktivitasnya untuk membuat peluncur yang dapat diteruskan ke SDK pada panggilan API.
3. SDK memanggil SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) dan mengambil token ID.
4. SDK memanggil launchSdkActivity untuk meluncurkan aktivitas.

Catatan: Jika aplikasi klien ingin menambahkan kondisi agar SDK membuat aktivitas, aplikasi tersebut dapat meneruskan ekspresi predikat saat membuat peluncur. Jika tidak ingin mengondisi pembuatan aktivitas, aplikasi dapat membuat predikat selalu menampilkan true.

Diagram berikut menunjukkan alur jika menggunakan library aktivitas.

Diagram urutan yang menunjukkan alur memulai aktivitas menggunakan library aktivitas.

API Platform

Platform ini memperkenalkan API berikut untuk memfasilitasi pembuatan dan pengelolaan aktivitas dengan sandbox dalam Runtime SDK:

• SdkSandboxActivityHandler: Activity Handler digunakan untuk memberi tahu SDK saat Aktivitas dibuat, dan didaftarkan oleh SDK.
• Untuk membantu pendaftaran Pengendali Aktivitas, SDK dapat menggunakan metode berikut di bagian SdkSandboxController:
  • .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): Mendaftarkan instance SdkSandboxActivityHandler, yang menampilkan ID IBinder.
  • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): Membatalkan pendaftaran instance SdkSandboxActivityHandler yang terdaftar menggunakan ID-nya.
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): Dipanggil dari aplikasi klien, metode ini memicu pembuatan aktivitas untuk SDK. Aplikasi klien harus meneruskan sebagai parameter Aktivitas awal yang dipilih dan ID Activity Handler SDK.

Untuk memulai aktivitas menggunakan Platform API, SDK harus mengikuti alur ini:

1. SDK mendaftarkan pengendali aktivitas menggunakan API yang disediakan dan mendapatkan ID.
2. SDK membagikan ID ini dengan aplikasi kliennya.
3. Aplikasi klien memanggil metode untuk memulai aktivitas di Runtime SDK dengan startSdkSandboxActivity(Activity, IBinder) API platform, yang meneruskan sebagai parameter Aktivitas awal yang dipilih untuk Aktivitas baru ini, dan ID Pengendali Aktivitas.
4. Platform memulai Aktivitas, dan memberi tahu SDK melalui callback di Activity Handler (SdkSandboxActivityHandler.onActivityCreated(Activity)).
5. SDK menggunakan aktivitas untuk mengisinya dengan iklan.

Catatan: onActivityCreated(Activity) dipanggil melalui Activity.onCreate(Bundle), SDK diharapkan mengisi tampilan konten pada tahap ini.

Penggunaan Platform API membuat SDK bertanggung jawab untuk membagikan ID SdkSandboxActivityHandler dengan aplikasi klien melalui API-nya pada waktu yang tepat, dan memandu aplikasi klien tentang cara menggunakannya.

Dalam diagram alur berikut, contoh SDK memiliki metode launchActivity(AppCallback) yang mengharapkan callback (ditentukan sebagai bagian dari API SDK). Callback ini digunakan oleh SDK untuk membagikan ID Activity Handler (SdkSandboxActivityHandler) dengan aplikasi klien.

Diagram urutan yang menunjukkan alur memulai aktivitas menggunakan API platform.

Visibilitas

Dalam Runtime SDK, iklan yang terintegrasi ke dalam hierarki tampilan aplikasi klien menggunakan saluran samping untuk merender tampilan SDK dari proses SDK ke proses aplikasi klien.

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 (Visibilitas).

Sebaliknya, aktivitas yang disediakan platform berjalan secara native dalam proses Runtime SDK, sehingga tidak memerlukan saluran samping dan memungkinkan SDK menggunakan API Activity dan View Android standar.

Karena implementasi yang berbeda ini, upaya yang sedang berlangsung bertujuan untuk menyatukan antarmuka untuk mengambil sinyal visibilitas, terlepas dari konteks pemuatan iklan.

Lifecycle

ActivityHolder yang diteruskan ke SDK melalui SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) menerapkan LifecycleOwner dan dapat digunakan untuk mengetahui Lifecycle.Event.

Navigasi kembali

Metode ActivityHolder.getOnBackPressedDispatcher() menampilkan OnBackPressedDispatcher yang dapat digunakan untuk mendaftarkan instance OnBackPressedCallback untuk menangani navigasi kembali.