يتم إيقاف بعض تكنولوجيات "مبادرة حماية الخصوصية" تدريجيًا.

اطّلِع على آخر الأخبار حول خطط تكنولوجيات "مبادرة حماية الخصوصية". تقدّم

حالة ميزة "مبادرة حماية الخصوصية" مزيدًا من المعلومات حول حالة كل واجهة من واجهات برمجة التطبيقات وميزات النظام الأساسي.

إنشاء واستخدام حزمة تطوير برامج (SDK) يتم تفعيلها في وقت التشغيل

Consume the RE SDK

استخدام حزمة SDK التي يمكن تفعيلها في وقت التشغيل

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

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

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

تحميل حزمة تطوير البرامج (SDK) التي يتم تفعيلها في وقت التشغيل

أول ما عليك فعله في حزمة تطوير البرامج (SDK) أو تطبيق العميل المتوافق مع وقت التشغيل هو تحميل حزمة تطوير البرامج (SDK) التي يتم تفعيلها في وقت التشغيل.

يساعد صف SdkSandboxManager في تحميل حِزم SDK التي يتم تفعيلها في وقت التشغيل، ويعرض صف IBinder الذي يمكن لحزمة SDK المتوافقة مع وقت التشغيل ربطه بالواجهة المحدّدة في حزمة SDK التي يتم تفعيلها في وقت التشغيل.

عليك التأكّد من عدم تحميل كل حزمة SDK مفعَّلة في وقت التشغيل إلا مرة واحدة، وإلا سيعرض مدير حزمة SDK استثناءً.

تنشئ أدوات إنشاء الرموز الوهمية فئات مساعدة لتحويل واجهة IBinder التي تعرضها الدالة SdkSandboxManager مرة أخرى إلى واجهة برمجة التطبيقات لحزمة SDK المحدّدة.

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

أنشئ فئة 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)
لا تتوافق طرق الاتصال التي تضيف أو تزيل طريقة عرض من SandboxedSdkView (مثل addView() أو removeView() أو removeViewAt() وما إلى ذلك)، ويتم عرض الخطأ UnsupportedOperationException.
- استخدِم setAdapter() فقط لعرض الإعلان.
يؤدي النقر على SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop) إلى تبديل ترتيب Z، ما يؤثر في ما إذا كان سيتم إرسال MotionEvents من تفاعل المستخدم إلى حزمة SDK التي يتم تفعيلها في وقت التشغيل أو حزمة SDK المتوافقة مع وقت التشغيل.
- إذا تم ضبطها على false، سيتم إرسال MotionEvents إلى حزمة SDK التي يمكنها رصد وقت التشغيل، وإلا سيتم إرسالها إلى حزمة SDK التي يتم تفعيلها في وقت التشغيل. مزيد من المعلومات عن ترتيب العناصر حسب محور Z باستخدام واجهات برمجة التطبيقات الخاصة بعرض واجهة المستخدم

بدء الأنشطة

لبدء الأنشطة التي تملكها حزمة تطوير البرامج (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: الاختبار والإنشاء للتوزيع