Xây dựng và sử dụng SDK hỗ trợ thời gian chạy

Sử dụng SDK hỗ trợ thời gian chạy

Phần này mô tả cách các ứng dụng có thể tương tác với các API SDK hỗ trợ thời gian chạy (RE) đã khai báo.

Trong hướng dẫn này, chúng ta sẽ gọi mô-đun SDK hiện có (hoặc SDK nhận biết thời gian chạy) là ứng dụng.

Nếu bạn muốn đưa SDK có thể kích hoạt thời gian chạy trực tiếp vào ứng dụng, thì mô-đun ứng dụng là ứng dụng khách.

Tải SDK hỗ trợ thời gian chạy

Việc đầu tiên bạn cần làm trên SDK hoặc ứng dụng khách nhận biết thời gian chạy là tải SDK được kích hoạt bởi thời gian chạy.

Lớp SdkSandboxManager hỗ trợ tải các SDK hỗ trợ thời gian chạy, trả về một lớp IBinder mà SDK nhận biết thời gian chạy có thể liên kết với giao diện được khai báo trong SDK hỗ trợ thời gian chạy.

Bạn cần đảm bảo rằng bạn chỉ tải từng SDK được kích hoạt bởi thời gian chạy một lần, nếu không, trình quản lý SDK sẽ trả về một ngoại lệ.

Các công cụ tạo lớp hỗ trợ tạo các lớp trợ giúp để chuyển đổi giao diện IBinder do SdkSandboxManager trả về thành giao diện API SDK đã khai báo.

Các công cụ này sử dụng giao diện được chú giải bằng @PrivacySandboxService để tạo một lớp *Factory.

Lớp này chứa một hàm wrapTo* tĩnh chuyển đổi một đối tượng IBinder thành một thực thể của giao diện SDK hỗ trợ thời gian chạy.

SDK nhận biết thời gian chạy có thể giao tiếp với SDK hỗ trợ thời gian chạy bằng giao diện này và gọi các API SDK mà bạn đã khai báo ở bước trước.

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

Cách sử dụng thư viện giao diện người dùng

Nếu muốn sử dụng thư viện giao diện người dùng để hiển thị quảng cáo, hãy đảm bảo rằng bạn đã thêm androidx.privacysandbox.ui:ui-core và androidx.privacysandbox.ui:ui-client vào các phần phụ thuộc trong build.gradle của SDK nhận biết thời gian chạy.

Tải quảng cáo biểu ngữ bằng SandboxedSdkView

androidx.privacysandbox.ui:ui-client giới thiệu một ViewGroup mới có tên là SandboxedSdkView để lưu trữ giao diện người dùng do một SDK hỗ trợ thời gian chạy tạo ra.

setAdapter() mở một phiên với SDK hỗ trợ thời gian chạy để nhận thông báo về chế độ xem quảng cáo và các thay đổi về giao diện người dùng. Khi SDK mở phiên, quảng cáo sẽ xuất hiện.

Bạn có thể tích hợp như sau:

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 nhận biết thời gian chạy cũng có thể nhận được thông báo khi trạng thái phiên thay đổi đối với bản trình bày giao diện người dùng. Để thực hiện việc này:

1. Tạo một lớp SessionStateChangeListener() để xử lý các trường hợp khác nhau:

   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. Thêm một trình nghe thay đổi trạng thái vào SandboxedSdkView mà bạn đã tạo thực thể trước đó. Trình nghe sẽ được gọi ngay lập tức với trạng thái hiện tại ngay khi được đính kèm vào khung hiển thị.

Xin lưu ý những điều sau:

• Nếu SDK nhận biết thời gian chạy gọi các phương thức SandboxedSdkView khi phiên vẫn chưa mở xong, thì tất cả hiệu ứng sẽ được áp dụng sau khi phiên mở xong.
  • Các phương thức như SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop)
• Không hỗ trợ việc gọi các phương thức thêm hoặc xoá một khung hiển thị khỏi SandboxedSdkView (chẳng hạn như addView(), removeView(), removeViewAt(), v.v.), dẫn đến việc trả về một UnsupportedOperationException.
  • Chỉ sử dụng setAdapter() để hiển thị quảng cáo.
• SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop) chuyển đổi chế độ sắp xếp Z, ảnh hưởng đến việc MotionEvents từ hoạt động tương tác của người dùng có được gửi đến SDK hỗ trợ thời gian chạy hay SDK nhận biết thời gian chạy hay không.
  • Nếu được đặt thành false, MotionEvents sẽ được gửi đến SDK nhận biết thời gian chạy, nếu không, chúng sẽ được gửi đến SDK hỗ trợ thời gian chạy. Tìm hiểu thêm về cách sắp xếp theo thứ tự Z bằng cách sử dụng API Trình bày giao diện người dùng.

Bắt đầu hoạt động

Để bắt đầu các hoạt động do SDK có hỗ trợ thời gian chạy sở hữu, hãy dùng tiện ích createSdkActivityLauncher để tạo một trình chạy trong SDK có nhận biết thời gian chạy.

Sau đó, bạn có thể truyền trình chạy này đến SDK kích hoạt bởi thời gian chạy, cho phép SDK này khởi tạo các hoạt động khi cần.

Bạn có thể dùng một vị từ để kiểm soát việc hoạt động sẽ được chạy hay không. Vị từ cần trả về giá trị true để cho phép các hoạt động.

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

Trong SDK có hỗ trợ thời gian chạy, hãy đăng ký SdkSandboxActivityHandlerCompat và cung cấp SDK đó cho 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 được truyền đến SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) triển khai LifecycleOwner, cho phép SDK kích hoạt bởi thời gian chạy truy cập vào vòng đời của hoạt động.

API này cũng cung cấp API getOnBackPressedDispatcher mà bạn có thể dùng để đăng ký các thực thể getOnBackPressedCallback nhằm xử lý hành vi của nút quay lại trong hoạt động.

arrow_back_iosBước 3: Tạo một SDK kích hoạt bởi thời gian chạy Bước 5: Kiểm thử và tạo để phân phốiarrow_forward_ios