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

إنشاء حزمة SDK يتم تفعيلها في وقت التشغيل

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

1. إعداد بنية مشروعك
2. إعداد مشروعك وتبعيات الوحدات
3. إضافة منطق نشاطك التجاري إلى حزمة تطوير البرامج (SDK)
4. تحديد واجهات برمجة التطبيقات في حزمة SDK
5. تحديد نقطة دخول لحزمة SDK

إعداد بنية مشروعك

ننصحك بتنظيم مشروعك في الوحدات التالية:

1. وحدة التطبيق: هي تطبيق الاختبار الذي تستخدمه لاختبار حزمة SDK وتطويرها، ويمثّل ما سيحصل عليه عملاء تطبيقك الفعلي. يجب أن يعتمد تطبيقك على وحدة مكتبة الإعلانات الحالية (حزمة SDK المتوافقة مع وقت التشغيل).
2. وحدة مكتبة الإعلانات الحالية (حزمة SDK متوافقة مع وقت التشغيل): هي وحدة مكتبة Android تحتوي على منطق حزمة SDK الحالية "غير المتوافقة مع وقت التشغيل"، وهي حزمة SDK مرتبطة بشكل ثابت.
   • في البداية، يمكن تقسيم الإمكانات. على سبيل المثال، يمكن أن تعالج حزمة SDK الحالية بعض الرموز، ويمكن توجيه بعضها إلى حزمة SDK التي يتم تفعيلها في وقت التشغيل.
3. وحدة مكتبة الإعلانات المفعَّلة في وقت التشغيل: تحتوي على منطق نشاطك التجاري في حزمة SDK المفعَّلة في وقت التشغيل. ويمكن إنشاء هذا النوع من الوحدات في "استوديو Android" كوحدة مكتبة Android.
4. وحدة حزمة تطوير البرامج (SDK) لنظام التشغيل Android ‏(ASB) التي يتم تفعيلها في وقت التشغيل: تحدّد بيانات الحزمة لتجميع رمز حزمة تطوير البرامج (SDK) التي يتم تفعيلها في وقت التشغيل في حزمة ASB.
   • يجب إنشاء هذا النوع يدويًا باستخدام النوع com.android.privacy-sandbox-sdk. يمكنك إجراء ذلك من خلال إنشاء دليل جديد.
   • يجب ألا تحتوي هذه الوحدة على أي رمز، بل على ملف build.gradle فارغ فقط يتضمّن التبعيات على وحدة مكتبة الإعلانات التي يمكن تشغيلها في وقت التنفيذ. يتم تحديد محتوى هذا الملف في مقالة إعداد حزمة SDK.
   • تذكَّر تضمين هذه الوحدة في ملف settings.gradle وفي وحدة مكتبة الإعلانات الحالية.

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

إعداد حزمة تطوير البرامج (SDK)

لإعداد مشروعك لتطوير حِزم SDK التي يتم تفعيلها في وقت التشغيل، عليك أولاً تحديد بعض الأدوات واعتماديات المكتبة:

• مكتبات التوافق مع الإصدارات القديمة من "وقت تشغيل حزمة تطوير البرامج"، والتي توفّر الدعم للأجهزة التي لا تتضمّن "مبادرة حماية الخصوصية" (الإصدار 13 من نظام التشغيل Android والإصدارات الأقدم) (androidx.privacysandbox.sdkruntime:)
• مكتبات واجهة المستخدم لعرض الإعلانات (androidx.privacysandbox.ui:)
• أدوات المطوّرين في حزمة تطوير البرامج (SDK) التي تتيح بيان واجهة برمجة التطبيقات لحزمة تطوير البرامج (SDK) وإنشاء رمز التوافق (androidx.privacysandbox.tools:)

1. أضِف هذا العلامة إلى ملف gradle.properties الخاص بمشروعك لتفعيل إمكانية إنشاء حِزم SDK يتم تفعيلها في وقت التشغيل.

   # This enables the Privacy Sandbox for your project on Android Studio.
   android.experimental.privacysandboxsdk.enable=true
   android.experimental.privacysandboxsdk.requireServices=false
   

2. عدِّل ملف build.gradle الخاص بمشروعك لتضمين مكتبات Jetpack المساعدة والتبعيات الأخرى:

   // Top-level build file where you can add configuration options common to all sub-projects/modules.
   buildscript {
       ext.kotlin_version = '1.9.10'
       ext.ksp_version = "$kotlin_version-1.0.13"
       ext.privacy_sandbox_activity_version = "1.0.0-alpha01"
       ext.privacy_sandbox_sdk_runtime_version = "1.0.0-alpha13"
       ext.privacy_sandbox_tools_version = "1.0.0-alpha09"
       ext.privacy_sandbox_ui_version = "1.0.0-alpha09"
       repositories {
           mavenCentral()
       }
       dependencies {
           classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
       }
   }
   
   plugins {
       id 'com.android.application' version '8.4.0-alpha13' apply false
       id 'com.android.library' version '8.4.0-alpha13' apply false
   
       // These two plugins do annotation processing and code generation for the sdk-implementation.
       id 'androidx.privacysandbox.library' version '1.0.0-alpha02' apply false
       id 'com.google.devtools.ksp' version "$ksp_version" apply false
   
       id 'org.jetbrains.kotlin.jvm' version '1.9.10' apply false
   }
   
   task clean(type: Delete) {
       delete rootProject.buildDir
   }
   

3. عدِّل ملف build.gradle في وحدة مكتبة الإعلانات التي يتم تفعيلها في وقت التشغيل (RE SDK) لتضمين هذه الملحقات.

   dependencies {
       // This allows Android Studio to parse and validate your SDK APIs.
       ksp "androidx.privacysandbox.tools:tools-apicompiler:$privacy_sandbox_tools_version"
   
       // This contains the annotation classes to decorate your SDK APIs.
       implementation "androidx.privacysandbox.tools:tools:$privacy_sandbox_tools_version"
   
       // This is runtime dependency required by the generated server shim code for
       // backward compatibility.
       implementation "androidx.privacysandbox.sdkruntime:sdkruntime-provider:$privacy_sandbox_sdk_runtime_version"
   
       // These are runtime dependencies required by the generated server shim code as
       // they use Kotlin.
       implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.1"
       implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.1'
   
       // This is the core part of the UI library to help with UI notifications.
       implementation "androidx.privacysandbox.ui:ui-core:$privacy_sandbox_ui_version"
   
       // This helps the SDK open sessions for the ad.
       implementation "androidx.privacysandbox.ui:ui-provider:$privacy_sandbox_ui_version"
   
       // This is needed if your SDK implements mediation use cases
       implementation "androidx.privacysandbox.ui:ui-client:$privacy_sandbox_ui_version"
   }
   

4. استبدِل ملف build.gradle في وحدة ASB المفعَّلة في وقت التشغيل بما يلي:

   plugins {
       id 'com.android.privacy-sandbox-sdk'
   }
   
   android {
       compileSdk 34
       minSdk 21
   
       bundle {
           // This is the package name of the SDK that you want to publish.
           // This is used as the public identifier of your SDK.
           // You use this later on to load the runtime-enabled SDK
           packageName = '<package name of your runtime-enabled SDK>'
   
           // This is the version of the SDK that you want to publish.
           // This is used as the public identifier of your SDK version.
           setVersion(1, 0, 0)
   
           // SDK provider defined in the SDK Runtime library.
           // This is an important part of the future backwards compatibility
           // support, most SDKs won't need to change it.
           sdkProviderClassName = "androidx.privacysandbox.sdkruntime.provider.SandboxedSdkProviderAdapter"
   
           // This is the class path of your implementation of the SandboxedSdkProviderCompat class.
           // It's the implementation of your runtime-enabled SDK's entry-point.
           // If you miss this step, your runtime-enabled SDK will fail to load at runtime:
           compatSdkProviderClassName = "<your-sandboxed-sdk-provider-compat-fully-qualified-class-name>"
       }
   }
   
   dependencies {
       // This declares the dependency on your runtime-enabled ad library module.
       include project(':<your-runtime-enabled-ad-library-here>')
   }
   

5. عدِّل ملف build.gradle في وحدة مكتبة الإعلانات الحالية (حزمة تطوير البرامج (SDK) الخاصة بـ "إعلانات Google") لتضمين التبعيات التالية:

   dependencies {
       // This declares the client's dependency on the runtime-enabled ASB module.
       //  ⚠️ Important: We depend on the ASB module, not the runtime-enabled module.
       implementation project(':<your-runtime-enabled-asb-module-here>')
   
       // Required for backwards compatibility on devices where SDK Runtime is unavailable.
       implementation "androidx.privacysandbox.sdkruntime:sdkruntime-client:$privacy_sandbox_sdk_runtime_version"
   
       // This is required to display banner ads using the SandboxedUiAdapter interface.
       implementation "androidx.privacysandbox.ui:ui-core:$privacy_sandbox_ui_version"
       implementation "androidx.privacysandbox.ui:ui-client:$privacy_sandbox_ui_version"
   
       // This is required to use SDK ActivityLaunchers.
       implementation "androidx.privacysandbox.activity:activity-core:$privacy_sandbox_activity_version"
       implementation "androidx.privacysandbox.activity:activity-client:$privacy_sandbox_activity_version"
   }
   

إضافة منطق النشاط التجاري لحزمة SDK

نفِّذ منطق النشاط التجاري لحزمة SDK كما تفعل عادةً داخل وحدة مكتبة الإعلانات التي تتيح وقت التشغيل.

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

إذا كنت بحاجة إلى الوصول إلى مساحة التخزين أو معرّف الإعلانات على Google Play أو معرّف مجموعة التطبيقات، يُرجى قراءة الأقسام التالية:

class SdkServiceImpl(private val context: Context) : SdkService {
    override suspend fun getMessage(): String = "Hello from Privacy Sandbox!"

    override suspend fun createFile(sizeInMb: Int): String {
        val path = Paths.get(
            context.dataDir.path, "file.txt"
        )

        withContext(Dispatchers.IO) {
            Files.deleteIfExists(path)
            Files.createFile(path)
            val buffer = ByteArray(sizeInMb * 1024 * 1024)
            Files.write(path, buffer)
        }

        val file = File(path.toString())
        val actualFileSize: Long = file.length() / (1024 * 1024)
        return "Created $actualFileSize MB file successfully"
    }
}

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

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

استخدِم التعليقات التوضيحية لتعريف هذه الواجهات.

التعليقات التوضيحية

يجب تعريف واجهات برمجة التطبيقات الخاصة بحزمة تطوير البرامج (SDK) في Kotlin على أنّها واجهات وفئات بيانات باستخدام التعليقات التوضيحية التالية:

عليك تحديد هذه الواجهات والفئات في أي مكان داخل وحدة مكتبة الإعلانات التي يتم تفعيلها في وقت التشغيل.

يمكنك الاطّلاع على كيفية استخدام هذه التعليقات التوضيحية في الأقسام التالية.

@PrivacySandboxService
interface SdkService {
    suspend fun getMessage(): String

    suspend fun createFile(sizeInMb: Int): String

    suspend fun getBanner(request: SdkBannerRequest, requestMediatedAd: Boolean): SdkSandboxedUiAdapter?

    suspend fun getFullscreenAd(): FullscreenAd
}

@PrivacySandboxInterface
interface SdkSandboxedUiAdapter : SandboxedUiAdapter

@PrivacySandboxValue
data class SdkBannerRequest(
    /** The package name of the app. */
    val appPackageName: String,
    /**
     *  An [SdkActivityLauncher] used to launch an activity when the banner is clicked.
     */
    val activityLauncher: SdkActivityLauncher,
    /**
     * Denotes if a WebView banner ad needs to be loaded.
     */
    val isWebViewBannerAd: Boolean
)

@PrivacySandboxCallback
interface InAppMediateeSdkInterface {
    suspend fun show()
}

الأنواع المتوافقة

تتيح واجهات برمجة التطبيقات لحِزم SDK التي يتم تفعيلها في وقت التشغيل الأنواع التالية:

• جميع الأنواع الأساسية في لغة برمجة Java (مثل int وlong وchar وboolean وما إلى ذلك)
• سلسلة
• واجهات Kotlin التي تمّت إضافة التعليقات التوضيحية إليها باستخدام @PrivacySandboxInterface أو @PrivacySandboxCallback
• فئات بيانات Kotlin التي تمّت إضافة التعليقات التوضيحية إليها باستخدام @PrivacySandboxValue
• java.lang.List - يجب أن تكون جميع العناصر في القائمة من أحد أنواع البيانات المتوافقة

في ما يلي بعض التحذيرات الإضافية:

• لا يمكن أن تحتوي فئات البيانات التي تمّت إضافة التعليقات التوضيحية إليها باستخدام @PrivacySandboxValue على حقول من النوع @PrivacySandboxCallback
• لا يمكن أن تحتوي أنواع الإرجاع على أنواع تمّت إضافة تعليقات توضيحية إليها باستخدام @PrivacySandboxCallback
• لا يمكن أن تحتوي القائمة على عناصر من أنواع تمّت إضافة تعليقات توضيحية إليها باستخدام @PrivacySandboxInterface أو @PrivacySandboxCallback

واجهات برمجة التطبيقات غير المتزامنة

بما أنّ واجهات برمجة التطبيقات في حزمة SDK تُجري دائمًا طلبًا إلى عملية منفصلة، علينا التأكّد من أنّ هذه الطلبات لا تحظر سلسلة طلبات العميل.

لتحقيق ذلك، يجب الإعلان بوضوح عن جميع الطرق في الواجهات التي تمّت إضافة التعليقات التوضيحية إليها باستخدام @PrivacySandboxService و@PrivacySandboxInterface و@PrivacySandboxCallback على أنّها واجهات برمجة تطبيقات غير متزامنة.

يمكن تنفيذ واجهات برمجة التطبيقات غير المتزامنة في Kotlin بطريقتَين:

1. استخدِم وظائف التعليق.
2. قبول عمليات رد الاتصال التي يتم إعلامها عند اكتمال العملية أو عند حدوث أحداث أخرى أثناء تقدّم العملية يجب أن يكون نوع الإرجاع للدالة هو Unit.

الاستثناءات

لا تتيح واجهات برمجة التطبيقات في حزمة تطوير البرامج أي شكل من أشكال الاستثناءات التي تم التحقّق منها.

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

مكتبة واجهة المستخدم

إذا كانت لديك واجهات تمثّل الإعلانات، مثل إعلان بانر، عليك أيضًا تنفيذ واجهة SandboxedUiAdapter لتفعيل جلسات فتح الإعلان الذي تم تحميله.

تشكّل هذه الجلسات قناة جانبية بين العميل وحزمة SDK، وتخدم غرضَين رئيسيَّين:

• تلقّي إشعارات كلما حدث تغيير في واجهة المستخدم
• إبلاغ العميل بأي تغييرات في طريقة عرض واجهة المستخدم

بما أنّ البرنامج يمكنه استخدام الواجهة التي تمّت إضافة التعليق التوضيحي @PrivacySandboxService إليها للتواصل مع حزمة SDK، يمكن إضافة أي واجهات برمجة تطبيقات لتحميل الإعلانات إلى هذه الواجهة.

عندما يطلب العميل تحميل إعلان، حمِّل الإعلان وأرجِع مثيلاً للواجهة التي تنفِّذ SandboxedUiAdapter. يتيح ذلك للعميل طلب فتح جلسات لهذا الإعلان.

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

لتحقيق ذلك، أنشئ فئة تنفّذ واجهة SandboxedUiAdapter.Session، وعند استدعاء SandboxedUiAdapter.openSession()، تأكَّد من استدعاء client.onSessionOpened()، مع تمرير مثيل للفئة Session كمعلَمة.

class SdkSandboxedUiAdapterImpl(
   private val sdkContext: Context,
   private val request: SdkBannerRequest,
) : SdkSandboxedUiAdapter {
   override fun openSession(
       context: Context,
       windowInputToken: IBinder,
       initialWidth: Int,
       initialHeight: Int,
       isZOrderOnTop: Boolean,
       clientExecutor: Executor,
       client: SandboxedUiAdapter.SessionClient
   ) {
       val session = SdkUiSession(clientExecutor, sdkContext, request)
       clientExecutor.execute {
           client.onSessionOpened(session)
       }
   }
}

يتلقّى هذا الصف أيضًا إشعارات كلما حدث تغيير في واجهة المستخدم. يمكنك استخدام هذه الفئة لتغيير حجم الإعلان أو معرفة وقت تغيير الإعدادات، على سبيل المثال.

مزيد من المعلومات عن واجهات برمجة التطبيقات الخاصة بعرض واجهة المستخدم في وقت التشغيل

دعم النشاط

لبدء الأنشطة التي تملكها حزمة SDK من "مبادرة حماية الخصوصية"، عليك تعديل واجهة برمجة التطبيقات لحزمة SDK لتلقّي عنصر SdkActivityLauncher، والذي توفّره أيضًا مكتبة واجهة المستخدم.

على سبيل المثال، يجب أن تطلق واجهة برمجة التطبيقات التالية لحزمة SDK الأنشطة، لذا فهي تتوقّع المَعلمة SdkActivityLauncher:

@PrivacySandboxInterface
interface FullscreenAd {
    suspend fun show(activityLauncher: SdkActivityLauncher)
}

نقطة دخول حزمة تطوير البرامج (SDK)

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

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

لضمان التوافق مع الأنظمة القديمة، قدّمنا الفئات التالية:

• ‫SandboxedSdkProviderAdapter، الذي يوسّع نطاق SandboxedSdkProvider ويتعامل مع طلبات تحميل حزمة تطوير البرامج (SDK) بغض النظر عن توفّر "وقت تشغيل حزمة تطوير البرامج (SDK)". يتم استخدام هذا المعرّف داخليًا، ويتم تعريفه في وحدة ASB.
• ‫SandboxedSdkProviderCompat: فئة مجرّدة تحاكي واجهة SandboxedSdkProvider.

مزيد من المعلومات حول التوافق مع الإصدارات القديمة في بيئة SDK Runtime

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

يوسّع هذا الصف SandboxedSdkProviderCompat ويقع ضمن الحزمة نفسها التي تتضمّن الواجهة التي تمّت إضافة التعليقات التوضيحية إليها.

// Auto-generated code.
abstract class AbstractSandboxedSdkProvider : SandboxedSdkProviderCompat {
    abstract fun createMySdk(context: Context): MySdk
}

يعرض هذا الصف الذي تم إنشاؤه طريقة واحدة مجرّدة لإنشاء المصنع تأخذ Context وتتوقّع عرض الواجهة التي تمّت إضافة التعليقات التوضيحية إليها كنقطة دخول.

يتم تسمية هذه الطريقة باسم واجهة @PrivacySandboxService، مع إضافة البادئة create إلى الاسم. على سبيل المثال، إذا كان اسم الواجهة هو MySdk، ستنشئ الأدوات createMySdk.

لربط نقطة الدخول بالكامل، عليك توفير تنفيذ للواجهة التي تمّت إضافة التعليق التوضيحي @PrivacySandboxService إليها في حزمة تطوير البرامج (SDK) التي يمكن تشغيلها في وقت التشغيل إلى AbstractSandboxedSdkProvider الذي تمّ إنشاؤه.

class MySdkSandboxedSdkProvider : AbstractSandboxedSdkProvider() {
    override fun createMySdk(context: Context): MySdk = MySdkImpl(context)
}

تغييرات على وحدة ASB

عليك الإفصاح عن اسم الفئة المؤهَّل بالكامل لتنفيذ SandboxedSdkProviderCompat في الحقل compatSdkProviderClassName بملف build.gradle الخاص بوحدة ASB.

هذا هو الصف الذي نفّذته في الخطوة السابقة، وعليك تعديل ملف build.gradle في وحدة ASB على النحو التالي:

bundle {
    packageName = '<package name of your runtime-enabled SDK>'
    setVersion(1, 0, 0)

    // SDK provider defined in the SDK Runtime library.
    sdkProviderClassName = "androidx.privacysandbox.sdkruntime.provider.SandboxedSdkProviderAdapter"
    // This is the class that extends AbstractSandboxedSdkProvider,
    // MySdkSandboxProvider as per the example provided.
    compatSdkProviderClassName = "com.example.mysdk.MySdkSandboxProvider"
}

arrow_back_iosالخطوة 2: إعداد بيئة التطوير الخطوة 4: استخدام حزمة SDK التي يمكن تشغيلها في وقت التنفيذarrow_forward_ios