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

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

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

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

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

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

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

• مكتبات التوافق مع الإصدارات السابقة من "وقت تشغيل حزمة تطوير البرامج (SDK)"، والتي توفر دعمًا الأجهزة التي لا تتضمّن "مبادرة حماية الخصوصية" (لنظام التشغيل Android 13 والإصدارات الأقدم) (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) الحالية لمكتبة الإعلانات لتضمين الاعتماديات التالية:

   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) التي يتم تفعيلها في وقت التشغيل خارج بيئة التشغيل، عليك لتحديد واجهات برمجة التطبيقات التي يمكن للعملاء (RA 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، ومنطقي، وما إلى ذلك)
• سلسلة
• واجهات Kotlin التي تمت إضافة تعليقات توضيحية إليها باستخدام @PrivacySandboxInterface أو @PrivacySandboxCallback
• فئات بيانات Kotlin التي تمت إضافة تعليقات توضيحية إليها باستخدام @PrivacySandboxValue
• java.lang.List - يجب أن تكون جميع العناصر في القائمة واحدة من البيانات المتوافقة الأنواع

هناك بعض التنبيهات الإضافية:

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

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

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

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

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

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

الاستثناءات

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

ترصد كود shim الذي تم إنشاؤه أي استثناءات وقت تشغيل تم وضعها بواسطة SDK يطرحها على أنه PrivacySandboxException للعميل مع معلومات عن السبب ملفوف بداخلها.

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

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

تشكِّل هذه الجلسات قناة جانبية بين العميل وحزمة تطوير البرامج (SDK)، تحقيق غرضين رئيسيين:

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

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

عندما يطلب العميل تحميل إعلان، حمِّل الإعلان وأعِد مثيلًا للواجهة التي تُنفِّذ 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 API من أجل تلقّي عنصر 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