یک SDK با قابلیت زمان اجرا بسازید و مصرف کنید

RE SDK را مصرف کنید

SDK فعال شده در زمان اجرا را مصرف کنید

این بخش نحوه تعامل کلاینت‌ها با APIهای SDK فعال‌شده در زمان اجرا (RE) اعلام‌شده را شرح می‌دهد.

در این راهنما، ما به ماژول SDK موجود شما (یا SDK آگاه از زمان اجرا) به عنوان کلاینت اشاره می‌کنیم.

اگر می‌خواهید SDK فعال‌شده در زمان اجرا را مستقیماً وارد برنامه خود کنید، ماژول برنامه، کلاینت است.

SDK با قابلیت اجرا را بارگیری کنید

اولین کاری که باید روی SDK یا برنامه‌ی کلاینتِ آگاه از زمان اجرا انجام دهید، بارگذاری SDK فعال‌شده با زمان اجرا است.

کلاس SdkSandboxManager به بارگذاری SDK های فعال در زمان اجرا کمک می‌کند و یک کلاس IBinder را برمی‌گرداند که SDK آگاه از زمان اجرا می‌تواند آن را به رابط اعلام شده در SDK فعال در زمان اجرا متصل کند.

شما باید مطمئن شوید که هر SDK با قابلیت اجرا را فقط یک بار بارگذاری می‌کنید، در غیر این صورت SDK manager یک استثنا برمی‌گرداند.

ابزارهای تولید شیم، کلاس‌های کمکی تولید می‌کنند تا رابط IBinder برگردانده شده توسط SdkSandboxManager را به رابط API SDK اعلام شده تبدیل کنند.

این ابزارها از رابطی که با @PrivacySandboxService حاشیه‌نویسی شده است، برای تولید یک کلاس *Factory استفاده می‌کنند.

این کلاس حاوی یک تابع استاتیک wrapTo* است که یک شیء IBinder را به نمونه‌ای از رابط SDK فعال‌شده در زمان اجرا تبدیل می‌کند.

SDK آگاه از زمان اجرا شما می‌تواند با استفاده از این رابط با SDK فعال‌شده در زمان اجرا ارتباط برقرار کند و APIهای SDK که در مرحله قبل اعلام کرده‌اید را فراخوانی کند.

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

استفاده از کتابخانه رابط کاربری

اگر می‌خواهید از کتابخانه رابط کاربری برای نمایش تبلیغات استفاده کنید، مطمئن شوید که androidx.privacysandbox.ui:ui-core و androidx.privacysandbox.ui:ui-client را به وابستگی‌های موجود در build.gradle از SDK مربوط به runtime-aware خود اضافه کرده‌اید.

بارگذاری بنر تبلیغاتی با استفاده از SandboxedSdkView

androidx.privacysandbox.ui:ui-client یک ViewGroup جدید به نام SandboxedSdkView را برای میزبانی رابط کاربری ایجاد شده توسط یک SDK با قابلیت اجرا در زمان اجرا معرفی می‌کند.

setAdapter() یک جلسه (session) با SDK فعال‌شده در زمان اجرا (runtime-enabled SDK) باز می‌کند تا نمای تبلیغ و اعلان‌های تغییرات رابط کاربری را دریافت کند. وقتی 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 شما که از زمان اجرا آگاه است، می‌تواند هنگام تغییر وضعیت جلسه برای ارائه رابط کاربری، مطلع شود. برای انجام این کار:

یک کلاس 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.
        }
    }
}

یک شنونده‌ی تغییر وضعیت به SandboxedSdkView که قبلاً نمونه‌سازی کرده‌اید اضافه کنید. این شنونده به محض اتصال به نما، فوراً با وضعیت فعلی فراخوانی می‌شود.

به موارد زیر توجه کنید:

اگر SDK آگاه از زمان اجرا، متدهای SandboxedSdkView را زمانی که جلسه هنوز باز نشده است، فراخوانی کند، تمام جلوه‌ها پس از پایان باز شدن جلسه اعمال خواهند شد.
- متدهایی مانند SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop)
فراخوانی متدهایی که یک view را از SandboxedSdkView اضافه یا حذف می‌کنند (مانند addView() ، removeView() ، removeViewAt() و غیره) پشتیبانی نمی‌شود و خطای UnsupportedOperationException را ایجاد می‌کند.
- فقط برای نمایش تبلیغ setAdapter() استفاده کنید.
SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop) ترتیب Z را تغییر می‌دهد که بر ارسال MotionEvents از تعامل کاربر به SDK فعال‌شده در زمان اجرا یا SDK آگاه از زمان اجرا تأثیر می‌گذارد.
- اگر روی false تنظیم شود، MotionEvents به SDK آگاه از زمان اجرا ارسال می‌شوند، در غیر این صورت به SDK فعال‌شده در زمان اجرا ارسال می‌شوند. درباره ترتیب Z با استفاده از APIهای ارائه رابط کاربری بیشتر بیاموزید .

شروع فعالیت‌ها

برای شروع فعالیت‌های متعلق به SDK فعال‌شده در زمان اجرا، از افزونه createSdkActivityLauncher برای ایجاد یک لانچر در SDK آگاه از زمان اجرا استفاده کنید.

سپس این لانچر می‌تواند به SDK فعال‌شده با زمان اجرا منتقل شود و به آن اجازه دهد تا در صورت نیاز، فعالیت‌های لازم را آغاز کند.

شما می‌توانید از یک گزاره (predicate) برای کنترل اینکه آیا فعالیت (activity) اجرا خواهد شد یا خیر، استفاده کنید. گزاره باید مقدار true را برگرداند تا فعالیت‌ها مجاز باشند.

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

در SDK فعال‌شده در زمان اجرا، SdkSandboxActivityHandlerCompat را ثبت کنید و آن را در اختیار 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 فعال‌شده در زمان اجرا، دسترسی به چرخه حیات activity را می‌دهد.

همچنین API مربوط به getOnBackPressedDispatcher را ارائه می‌دهد که می‌تواند برای ثبت نمونه‌های getOnBackPressedCallback جهت مدیریت رفتار دکمه بازگشت در داخل activity مورد استفاده قرار گیرد.

مرحله ۳ : ساخت یک SDK با قابلیت اجرا مرحله ۵ : آزمایش و ساخت برای توزیع