إنشاء واستخدام حزمة تطوير برامج (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) المعلَن عنها في وقت التشغيل والتي تم تفعيلها في وقت التشغيل.

في هذا الدليل، نشير إلى وحدة حزمة 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) التي أعلنت عنها في الخطوة السابقة.

// 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 المتوافقة مع وقت التشغيل.

تحميل إعلان بانر باستخدام SandboxedSdkView

تقدّم androidx.privacysandbox.ui:ui-client ViewGroup جديدًا يُسمى SandboxedSdkView لاستضافة واجهة مستخدم تم إنشاؤها بواسطة حزمة تطوير برامج (SDK) مفعّلة في وقت التشغيل.

setAdapter() يفتح جلسة باستخدام حزمة تطوير البرامج (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) الواعية لوقت التشغيل عند تغيُّر حالة الجلسة في العرض التقديمي لواجهة المستخدم. ولإجراء ذلك:

  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. يمكنك إضافة أداة استماع لتغيير الحالة إلى SandboxedSdkView الذي أنشأت مثيلاً له في السابق. يتم استدعاء المستمع فورًا بالحالة الحالية فور إرفاقه بالعرض.

يُرجى ملاحظة ما يلي:

  • إذا استدعيت حزمة تطوير البرامج (SDK) الواعية لوقت التشغيل طرق SandboxedSdkView بينما لم ينتهِ فتح الجلسة، سيتم تطبيق جميع التأثيرات بعد انتهاء فتح الجلسة.
    • طرق مثل SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop)
  • لا تتوفّر طرق الاتصال التي تضيف عرضًا إلى SandboxedSdkView أو تزيله منه (مثل addView() أو removeView() أو removeViewAt() أو غير ذلك)، ويؤدي استخدامها إلى طرح UnsupportedOperationException.
    • فقط استخدِم setAdapter() لعرض الإعلان.
  • يُستخدَم الخيار SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop) لتفعيل/إيقاف ترتيب Z، ما يؤثر في ما إذا كان سيتم إرسال MotionEvents من تفاعل المستخدِم إلى حزمة SDK المفعَّلة في وقت التشغيل أو حزمة SDK المتوافقة مع وقت التشغيل.

بدء الأنشطة

لبدء الأنشطة التي تمتلكها حزمة SDK التي يتم تفعيلها في وقت التشغيل، يمكنك استخدام الإضافة createSdkActivityLauncher لإنشاء مشغّل تطبيقات في حزمة SDK الواعية لوقت التشغيل.

ويمكن بعد ذلك نقل مشغّل التطبيقات هذا إلى حزمة تطوير البرامج (SDK) التي يتم تفعيلها في وقت التشغيل، ما يسمح له ببدء الأنشطة حسب الحاجة.

ويمكنك استخدام فلتر للتحكّم في ما إذا كان سيتم إطلاق النشاط أم لا. يجب أن يعرض العنصر النائب قيمة 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 التي تم تفعيلها في وقت التشغيل إمكانية الوصول إلى مراحل النشاط.

وتوفّر أيضًا واجهة برمجة التطبيقات getOnBackPressedDispatcher، والتي يمكن استخدامها لتسجيل مثيلات getOnBackPressedCallback من أجل التعامل مع سلوك زر الرجوع داخل النشاط.


الخطوة 3: إنشاء حزمة SDK مفعَّلة في وقت التشغيل الخطوة 5: الاختبار والإنشاء للتوزيع