Membangun dan menggunakan SDK yang Mendukung Runtime

1
 Key concepts
2
 Set up your development environment
3
 Build an RE SDK
4
 Consume the RE SDK
5
 Testing, and building for distribution

Menggunakan SDK yang mendukung runtime

Bagian ini menjelaskan cara klien dapat berinteraksi dengan API SDK yang diaktifkan runtime (RE) yang dideklarasikan.

Dalam panduan ini, kami menyebut modul SDK yang ada (atau SDK yang kompatibel dengan runtime) sebagai klien.

Jika Anda ingin menggunakan SDK yang mendukung runtime secara langsung ke dalam aplikasi, modul aplikasi adalah kliennya.

Memuat SDK yang mendukung runtime

Hal pertama yang ingin Anda lakukan di SDK atau aplikasi klien yang kompatibel dengan runtime adalah memuat SDK yang mendukung runtime.

Class SdkSandboxManager membantu memuat SDK yang mendukung runtime, menampilkan class IBinder yang dapat diikat oleh SDK yang kompatibel dengan runtime ke antarmuka yang dideklarasikan di SDK yang mendukung runtime.

Anda harus memastikan bahwa Anda hanya memuat setiap SDK yang mendukung runtime satu kali, atau pengelola SDK akan menampilkan pengecualian.

Alat pembuatan shim menghasilkan class helper untuk mengonversi antarmuka IBinder yang ditampilkan oleh SdkSandboxManager kembali ke antarmuka API SDK yang dideklarasikan.

Alat ini menggunakan antarmuka yang diberi anotasi dengan @PrivacySandboxService untuk menghasilkan class *Factory.

Class ini berisi fungsi wrapTo* statis yang mengonversi objek IBinder menjadi instance antarmuka SDK yang mendukung runtime.

SDK yang kompatibel dengan runtime dapat berkomunikasi dengan SDK yang kompatibel dengan runtime menggunakan antarmuka ini, dan memanggil API SDK yang Anda deklarasikan pada langkah sebelumnya.

// Name of the SDK to be loaded, defined in your ASB module
private const val SDK_NAME = "com.example.sdk"

try {
    // SdkSandboxManagerCompat is used to communicate with the sandbox and load SDKs with backward compatibility.
    val sandboxManagerCompat = SdkSandboxManagerCompat.from(context)
    val sandboxedSdk = sandboxManagerCompat.loadSdk(SDK_NAME, Bundle.EMPTY)
    val mySdk = MySdkFactory.wrapToMySdk(sandboxedSdk.getInterface()!!)
} catch (e: LoadSdkCompatException) {
    Log.e(TAG, "Failed to load SDK, error code: ${e.loadSdkErrorCode}", e)
    return null
}

Penggunaan library UI

Jika Anda ingin menggunakan library UI untuk menampilkan iklan, pastikan Anda telah menambahkan androidx.privacysandbox.ui:ui-core dan androidx.privacysandbox.ui:ui-client ke dependensi di build.gradle SDK yang kompatibel dengan runtime.

Memuat iklan banner menggunakan SandboxedSdkView

androidx.privacysandbox.ui:ui-client memperkenalkan ViewGroup baru yang disebut SandboxedSdkView untuk menghosting UI yang dibuat oleh SDK yang mendukung runtime.

setAdapter() membuka sesi dengan SDK yang diaktifkan runtime untuk menerima tampilan iklan dan notifikasi perubahan UI. Saat SDK membuka sesi, iklan akan ditampilkan.

Hal ini dapat diintegrasikan sebagai berikut:

class BannerAd(context: Context, attrs: AttributeSet) : LinearLayout(context, attrs) {
    suspend fun loadAd() {
        // mySdk is the previously loaded SDK in the SDK Runtime.
        val bannerAd = mySdk.loadAd()
        val sandboxedSdkView = SandboxedSdkView(context)
        addViewToLayout(sandboxedSdkView)

        // This renders the ad.
        sandboxedSdkView.setAdapter(bannerAd)
        return
    }
    private fun addViewToLayout(view: View) {
        view.layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)
        super.addView(view)
    }
}

SDK yang kompatibel dengan runtime juga dapat menerima notifikasi saat status sesi berubah untuk presentasi UI. Untuk melakukannya:

  1. Buat class SessionStateChangeListener() untuk menangani berbagai skenario:

    private class SessionStateChangeListener() : SandboxedSdkUiSessionStateChangedListener {
    override fun onStateChanged(state: SandboxedSdkUiSessionState) {
        if (state is SandboxedSdkUiSessionState.Error) {
        // Some error has occurred while opening the session. Handle
        // accordingly.
        Log.e(TAG, state.throwable.message!!);
        } else if (state is SandboxedSdkUiSessionState.Loading) {
            // The session is attempting to be opened.
        } else if (state is SandboxedSdkUiSessionState.Active) {
            // The session is open and the UI presentation was successful.
        } else if (state is SandboxedSdkUiSessionState.Idle) {
            // There is no open session.
        }
    }
}

  2. Tambahkan pemroses perubahan status ke SandboxedSdkView yang telah Anda buat sebelumnya. Pemroses segera dipanggil dengan status saat ini segera setelah dilampirkan ke tampilan.

Perhatikan hal berikut:

  • Jika SDK yang kompatibel dengan runtime memanggil metode SandboxedSdkView saat sesi belum selesai dibuka, semua efek akan diterapkan setelah sesi selesai dibuka.
    • Metode seperti SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop)
  • Memanggil metode yang menambahkan atau menghapus tampilan dari SandboxedSdkView (seperti addView(), removeView(), removeViewAt(), dll.) tidak didukung, dan akan memunculkan UnsupportedOperationException.
    • Hanya gunakan setAdapter() untuk menampilkan iklan.
  • SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop) mengalihkan pengurutan Z yang memengaruhi apakah MotionEvents dari interaksi pengguna dikirim ke SDK yang mendukung runtime atau SDK yang kompatibel dengan runtime.

Mulai aktivitas

Untuk memulai aktivitas yang dimiliki oleh SDK yang kompatibel dengan runtime, gunakan ekstensi createSdkActivityLauncher untuk membuat peluncur di SDK yang kompatibel dengan runtime.

Peluncur ini kemudian dapat diteruskan ke SDK yang mendukung runtime, sehingga SDK dapat memulai aktivitas sesuai kebutuhan.

Anda dapat menggunakan predikat untuk mengontrol apakah aktivitas akan diluncurkan atau tidak. Predikat harus menampilkan nilai true agar aktivitas diizinkan.

val launchSdkActivityPredicate = {
    // Boolean which has to be true to launch the activities
    }
val launcher = baseActivity.createSdkActivityLauncher(launchSdkActivityPredicate)
fullscreenService.showActivity(launcher)

Dalam SDK yang mendukung runtime, daftarkan SdkSandboxActivityHandlerCompat, dan berikan ke SdkActivityLauncher.LaunchSdkActivity(IBinder).

fun showActivity(activityLauncher: SdkActivityLauncher) {
    val handler = object : SdkSandboxActivityHandlerCompat {
        override fun onActivityCreated(activityHolder: ActivityHolder) {
            activityHolder.getActivity().setContentView(contentView)
        }
    }

    val token = controller.registerSdkSandboxActivityHandler(handler)
    activityLauncher.launchSdkActivity(token)
}

ActivityHolder yang diteruskan ke SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) mengimplementasikan LifecycleOwner, sehingga SDK yang mendukung runtime Anda memiliki akses ke siklus proses aktivitas.

Library ini juga menyediakan getOnBackPressedDispatcher API, yang dapat digunakan untuk mendaftarkan instance getOnBackPressedCallback guna menangani perilaku tombol kembali dalam aktivitas.


Langkah 3: Buat SDK yang kompatibel dengan runtime Langkah 5: Menguji dan membangun untuk distribusi