สร้างและใช้ SDK ที่เปิดใช้รันไทม์

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

ใช้ SDK ที่เปิดใช้รันไทม์

ส่วนนี้จะอธิบายวิธีที่ไคลเอ็นต์สามารถโต้ตอบกับ SDK API ที่เปิดใช้รันไทม์ (RE) ที่ประกาศไว้

ในกรณีของคู่มือนี้ เราจะเรียกโมดูล SDK ที่มีอยู่ (หรือ SDK รับรู้รันไทม์) ที่มีอยู่ว่าเป็นไคลเอ็นต์

หากต้องการใช้ SDK ที่เปิดใช้รันไทม์ในแอปโดยตรง โมดูลแอปก็คือไคลเอ็นต์

โหลด SDK ที่เปิดใช้รันไทม์

สิ่งแรกที่คุณต้องทำใน SDK หรือแอปไคลเอ็นต์ที่รับรู้รันไทม์คือโหลด SDK ที่เปิดใช้รันไทม์

คลาส SdkSandboxManager ช่วยในการโหลด SDK ที่เปิดใช้รันไทม์ โดยแสดงผลคลาส IBinder ที่ SDK ที่รู้จักรันไทม์สามารถเชื่อมโยงกับอินเทอร์เฟซที่ประกาศใน SDK ที่เปิดใช้รันไทม์ได้

คุณต้องตรวจสอบว่าได้โหลด SDK ที่เปิดใช้รันไทม์แต่ละรายการเท่านั้น มิฉะนั้นเครื่องมือจัดการ SDK จะส่งกลับข้อยกเว้น

เครื่องมือสร้างชิมจะสร้างคลาสตัวช่วยเพื่อแปลงIBinder อินเทอร์เฟซที่ SdkSandboxManager แสดงกลับเป็นอินเทอร์เฟซ SDK API ที่ประกาศไว้

เครื่องมือใช้อินเทอร์เฟซที่มีคำอธิบายประกอบ @PrivacySandboxService เพื่อสร้างคลาส *Factory

คลาสนี้มีฟังก์ชัน wrapTo* แบบคงที่ซึ่งจะแปลงออบเจ็กต์ IBinder ให้เป็นอินสแตนซ์ของอินเทอร์เฟซ SDK ที่เปิดใช้รันไทม์

SDK ที่รับรู้ถึงรันไทม์จะสื่อสารกับ SDK ที่เปิดใช้รันไทม์โดยใช้อินเทอร์เฟซนี้ และเรียกใช้ SDK API ที่คุณประกาศในขั้นตอนก่อนหน้าได้

// 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
}

การใช้งานไลบรารี UI

หากต้องการใช้ไลบรารี UI เพื่อแสดงโฆษณา ให้ตรวจสอบว่าคุณได้เพิ่ม androidx.privacysandbox.ui:ui-core และ androidx.privacysandbox.ui:ui-client ไปยังทรัพยากร Dependency ใน create.gradle ของ SDK ที่รู้จักรันไทม์แล้ว

โหลดโฆษณาแบนเนอร์โดยใช้ SandboxedSdkView

androidx.privacysandbox.ui:ui-client เปิดตัว ViewGroup ใหม่ที่ชื่อว่า SandboxedSdkView ในโฮสต์ UI ที่สร้างโดย SDK ที่เปิดใช้รันไทม์

setAdapter() เปิดเซสชันด้วย SDK ที่เปิดใช้รันไทม์เพื่อรับการแสดงโฆษณาและการแจ้งเตือนการเปลี่ยนแปลง UI เมื่อ SDK เปิดเซสชัน โฆษณาจะแสดง

ซึ่งสามารถผสานรวมได้ดังนี้

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 ที่รับรู้ถึงรันไทม์จะได้รับการแจ้งเตือนเมื่อสถานะเซสชันเปลี่ยนแปลงสำหรับการนำเสนอ UI ด้วย หากต้องการทำสิ่งต่อไปนี้

  1. สร้างคลาส SessionStateChangeListener() เพื่อจัดการสถานการณ์ต่างๆ ดังนี้

    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. เพิ่ม Listener การเปลี่ยนสถานะลงใน SandboxedSdkView ที่คุณได้สร้างอินสแตนซ์ไว้ก่อนหน้า ระบบจะเรียกฟังเหตุการณ์ทันทีพร้อมสถานะปัจจุบันทันทีที่แนบกับมุมมอง

โปรดทราบดังต่อไปนี้

  • หาก SDK แบบรับรู้รันไทม์เรียกใช้เมธอด SandboxedSdkView เมื่อเซสชันยังเปิดไม่เสร็จ ระบบจะใช้เอฟเฟกต์ทั้งหมดหลังจากเปิดเซสชันเสร็จแล้ว
    • เมธอด เช่น SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop)
  • ระบบไม่รองรับการเรียกใช้เมธอดที่เพิ่มหรือนํามุมมองออกจาก SandboxedSdkView (เช่น addView(), removeView(), removeViewAt() ฯลฯ) และระบบจะแสดง UnsupportedOperationException
    • ใช้ setAdapter() เพื่อแสดงโฆษณาเท่านั้น
  • SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop) สลับการจัดเรียงตามลําดับ Z ซึ่งส่งผลต่อการส่ง MotionEvents จากการโต้ตอบของผู้ใช้ไปยัง SDK ที่เปิดใช้รันไทม์หรือ SDK ที่ทราบรันไทม์

เริ่มกิจกรรม

หากต้องการเริ่มกิจกรรมที่ SDK ที่เปิดใช้รันไทม์เป็นเจ้าของ ให้ใช้ส่วนขยาย createSdkActivityLauncher เพื่อสร้างตัวเปิดใช้งานใน SDK ที่รู้จักรันไทม์

จากนั้นคุณสามารถส่ง Launcher นี้ไปยัง SDK ที่เปิดใช้รันไทม์ได้ ซึ่งจะช่วยให้ SDK เริ่มกิจกรรมได้ตามต้องการ

คุณสามารถใช้พริเนกติกเพื่อควบคุมว่าจะเปิดใช้งานกิจกรรมหรือไม่ ภาคแสดงจำเป็นต้องแสดงผลค่า true กิจกรรมจึงจะได้รับอนุญาต

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

ลงทะเบียน SdkSandboxActivityHandlerCompat ใน SDK ที่เปิดใช้รันไทม์ แล้วส่งให้ 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 ที่ส่งให้กับ SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder)จะใช้งาน LifecycleOwner ซึ่งทำให้ SDK ที่เปิดใช้รันไทม์ของคุณเข้าถึงวงจรชีวิตของกิจกรรมได้

และยังมี getOnBackPressedDispatcher API ซึ่งใช้ลงทะเบียนอินสแตนซ์ getOnBackPressedCallback ในการจัดการการทำงานของปุ่มย้อนกลับภายในกิจกรรมได้อีกด้วย


ขั้นตอนที่ 3: สร้าง SDK ที่เปิดใช้รันไทม์ ขั้นตอนที่ 5: การทดสอบและสร้างสำหรับการจัดจำหน่าย