สร้างและใช้ SDK ที่เปิดใช้รันไทม์

สร้าง SDK ที่เปิดใช้รันไทม์

คุณต้องทำตามขั้นตอนต่อไปนี้เพื่อสร้าง SDK ที่เปิดใช้รันไทม์

1. ตั้งค่าโครงสร้างโปรเจ็กต์
2. เตรียมโปรเจ็กต์และการอ้างอิงโมดูล
3. เพิ่มตรรกะทางธุรกิจของ SDK
4. กำหนด API ของ SDK
5. ระบุจุดแรกเข้าสำหรับ SDK

ตั้งค่าโครงสร้างโปรเจ็กต์

เราขอแนะนำให้จัดระเบียบโปรเจ็กต์เป็นโมดูลต่อไปนี้

1. โมดูลแอป - แอปทดสอบที่คุณใช้เพื่อทดสอบและพัฒนา SDK ซึ่งแสดงถึงสิ่งที่ไคลเอ็นต์แอปจริงของคุณจะมี แอปของคุณควรมีทรัพยากร Dependency ในโมดูลไลบรารีโฆษณาที่มีอยู่ (SDK ที่รับรู้รันไทม์)
2. โมดูลไลบรารีโฆษณาที่มีอยู่ (SDK ที่รับรู้รันไทม์) - โมดูลไลบรารี Android ที่มีตรรกะ SDK "ที่ไม่ได้เปิดใช้รันไทม์" ที่มีอยู่ ซึ่งเป็น SDK ที่ลิงก์แบบคงที่
   • คุณสามารถแบ่งความสามารถออกเป็นส่วนๆ เพื่อเริ่มต้นใช้งาน ตัวอย่างเช่น โค้ดบางส่วนอาจ จัดการโดย SDK ที่มีอยู่ และบางส่วนอาจกำหนดเส้นทางไปยัง SDK ที่เปิดใช้รันไทม์
3. โมดูลไลบรารีโฆษณาที่เปิดใช้รันไทม์ - มีตรรกะทางธุรกิจของ SDK ที่เปิดใช้รันไทม์ ซึ่งสร้างได้ใน Android Studio เป็นโมดูลไลบรารี Android
4. โมดูล ASB ที่เปิดใช้รันไทม์ - กำหนดข้อมูลแพ็กเกจเพื่อรวม โค้ด SDK ที่เปิดใช้รันไทม์ไว้ใน ASB
   • คุณต้องสร้างด้วยตนเองโดยใช้ประเภท com.android.privacy-sandbox-sdk ซึ่งทำได้โดยการสร้าง ไดเรกทอรีใหม่
   • โมดูลนี้ไม่ควรมีโค้ดใดๆ และควรมีเพียงไฟล์ build.gradle ที่ว่างเปล่าพร้อมทรัพยากร Dependency ไปยังโมดูลไลบรารีโฆษณาที่เปิดใช้รันไทม์ เนื้อหาของไฟล์นี้มีการกำหนดไว้ใน เตรียม SDK
   • อย่าลืมรวมโมดูลนี้ไว้ในไฟล์ settings.gradle และในโมดูลคลังโฆษณาที่มีอยู่

โครงสร้างโปรเจ็กต์ในคู่มือนี้เป็นเพียงคำแนะนำ คุณอาจเลือกโครงสร้างอื่นสำหรับ SDK และใช้หลักการทางเทคนิคเดียวกันได้ คุณสร้างโมดูลเพิ่มเติมอื่นๆ เพื่อแยกโค้ดในแอปและโมดูลไลบรารีออกเป็นโมดูลได้เสมอ

เตรียม SDK

หากต้องการเตรียมโปรเจ็กต์สำหรับการพัฒนา SDK ที่เปิดใช้รันไทม์ คุณต้อง กำหนดทรัพยากร Dependency ของเครื่องมือและไลบรารีบางอย่างก่อน

• ไลบรารีความเข้ากันได้แบบย้อนหลังของ SDK Runtime ซึ่งรองรับ อุปกรณ์ที่ไม่มี Privacy Sandbox (Android 13 และต่ำกว่า) (androidx.privacysandbox.sdkruntime:)
• ไลบรารี UI เพื่อรองรับการแสดงโฆษณา (androidx.privacysandbox.ui:)
• เครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ SDK เพื่อรองรับการประกาศ SDK API และการสร้าง Shim (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 ตัวช่วยและทรัพยากร Dependency อื่นๆ ดังนี้

   // 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) เพื่อรวมทรัพยากร Dependency เหล่านี้

   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 ในโมดูลไลบรารีโฆษณาที่มีอยู่ (RA SDK) เพื่อรวมทรัพยากร Dependency ต่อไปนี้

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

ประกาศ API ของ SDK

หากต้องการให้ SDK ที่เปิดใช้รันไทม์เข้าถึงได้ภายนอกรันไทม์ คุณต้องกำหนด API ที่ไคลเอ็นต์ (RA SDK หรือแอปไคลเอ็นต์) ใช้ได้

ใช้คำอธิบายประกอบเพื่อประกาศอินเทอร์เฟซเหล่านี้

คำอธิบายประกอบ

ต้องประกาศ SDK API ใน 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()
}

ประเภทที่รองรับ

API ของ SDK ที่เปิดใช้รันไทม์รองรับประเภทต่อไปนี้

• ประเภทข้อมูลพื้นฐานทั้งหมดในภาษาโปรแกรม Java (เช่น int, long, char, boolean และอื่นๆ)
• สตริง
• อินเทอร์เฟซ Kotlin ที่มีคำอธิบายประกอบ @PrivacySandboxInterface หรือ @PrivacySandboxCallback
• คลาสข้อมูล Kotlin ที่มีคำอธิบายประกอบ @PrivacySandboxValue
• java.lang.List - องค์ประกอบทั้งหมดใน List ต้องเป็นประเภทข้อมูลที่รองรับ

ข้อควรระวังเพิ่มเติมมีดังนี้

• คลาสข้อมูลที่อธิบายประกอบด้วย @PrivacySandboxValue ต้องไม่มีฟิลด์ประเภท @PrivacySandboxCallback
• ประเภทการคืนค่าต้องไม่มีประเภทที่อธิบายประกอบด้วย @PrivacySandboxCallback
• รายการต้องไม่มีองค์ประกอบประเภทที่มีคำอธิบายประกอบ @PrivacySandboxInterface หรือ @PrivacySandboxCallback

API แบบอะซิงโครนัส

เนื่องจาก API ของ SDK จะเรียกใช้กระบวนการแยกต่างหากเสมอ เราจึงต้อง ตรวจสอบว่าการเรียกเหล่านี้จะไม่บล็อกเธรดการเรียกของไคลเอ็นต์

หากต้องการดำเนินการนี้ เมธอดทั้งหมดในอินเทอร์เฟซที่มีคำอธิบายประกอบ @PrivacySandboxService, @PrivacySandboxInterface และ @PrivacySandboxCallback ต้องประกาศอย่างชัดเจนว่าเป็น API แบบไม่พร้อมกัน

คุณสามารถใช้ API แบบไม่พร้อมกันใน Kotlin ได้ 2 วิธี ดังนี้

1. ใช้ฟังก์ชันระงับ
2. ยอมรับการเรียกกลับที่จะได้รับการแจ้งเตือนเมื่อการดำเนินการเสร็จสมบูรณ์ หรือเมื่อมี เหตุการณ์อื่นๆ ในระหว่างความคืบหน้าของการดำเนินการ ประเภทการคืนค่าของฟังก์ชัน ต้องเป็น Unit

ข้อยกเว้น

API ของ SDK ไม่รองรับข้อยกเว้นที่ตรวจสอบแล้วในรูปแบบใดๆ

โค้ด Shim ที่สร้างขึ้นจะตรวจจับข้อยกเว้นรันไทม์ที่ SDK สร้างขึ้นและ ส่งเป็น PrivacySandboxException ไปยังไคลเอ็นต์พร้อมข้อมูลเกี่ยวกับ สาเหตุที่ห่อหุ้มอยู่ภายใน

ไลบรารี UI

หากมีอินเทอร์เฟซที่แสดงโฆษณา เช่น แบนเนอร์ คุณจะต้องใช้SandboxedUiAdapter อินเทอร์เฟซเพื่อเปิดใช้เซสชันการเปิดสำหรับโฆษณาที่โหลดแล้วด้วย

เซสชันเหล่านี้จะสร้างช่องทางด้านข้างระหว่างไคลเอ็นต์กับ SDK และมีวัตถุประสงค์หลัก 2 ประการ ดังนี้

• รับการแจ้งเตือนทุกครั้งที่มีการเปลี่ยนแปลง UI
• แจ้งให้ไคลเอ็นต์ทราบถึงการเปลี่ยนแปลงใดๆ ในการนำเสนอ UI

เนื่องจากไคลเอ็นต์สามารถใช้อินเทอร์เฟซที่มีคำอธิบายประกอบ @PrivacySandboxService เพื่อ สื่อสารกับ SDK ของคุณ จึงสามารถเพิ่ม API ใดก็ได้สำหรับการโหลดโฆษณาลงในอินเทอร์เฟซนี้

เมื่อไคลเอ็นต์ขอโหลดโฆษณา ให้โหลดโฆษณาและแสดงอินสแตนซ์ของ อินเทอร์เฟซที่ใช้ 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)
       }
   }
}

นอกจากนี้ คลาสนี้ยังได้รับการแจ้งเตือนทุกครั้งที่ UI มีการเปลี่ยนแปลงด้วย คุณสามารถ ใช้คลาสนี้เพื่อปรับขนาดโฆษณา หรือทราบเมื่อมีการเปลี่ยนแปลงการกำหนดค่า เป็นต้น

ดูข้อมูลเพิ่มเติมเกี่ยวกับ UI Presentation API ในรันไทม์

การสนับสนุนกิจกรรม

หากต้องการเริ่มกิจกรรมที่ SDK เป็นเจ้าของจาก Privacy Sandbox คุณต้องแก้ไข SDK API เพื่อรับออบเจ็กต์ SdkActivityLauncher ซึ่งไลบรารี UI ก็มีให้เช่นกัน

ตัวอย่างเช่น API ของ SDK ต่อไปนี้ควรเปิดใช้กิจกรรม ดังนั้นจึงคาดหวังพารามิเตอร์ SdkActivityLauncher

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

จุดแรกเข้าของ SDK

คลาส Abstract SandboxedSdkProvider ห่อหุ้ม API ที่รันไทม์ของ SDK ใช้เพื่อโต้ตอบกับ SDK ที่โหลดลงในรันไทม์

SDK ที่เปิดใช้รันไทม์ต้องใช้คลาสแอบสแทร็กต์นี้เพื่อสร้างจุดแรกเข้าสำหรับรันไทม์ของ SDK เพื่อให้สื่อสารกับ SDK ได้

เราได้เปิดตัวคลาสต่อไปนี้เพื่อรองรับการทำงานร่วมกับเวอร์ชันก่อนหน้า

• SandboxedSdkProviderAdapter ซึ่งขยาย SandboxedSdkProvider และจัดการคำขอโหลด SDK โดยไม่คำนึงถึงความพร้อมใช้งานของ SDK Runtime ซึ่งใช้ภายในระบบและประกาศในโมดูล ASB
• SandboxedSdkProviderCompat ซึ่งเป็นคลาสแบบนามธรรมที่เลียนแบบอินเทอร์เฟซของ SandboxedSdkProvider

ดูข้อมูลเพิ่มเติมเกี่ยวกับความเข้ากันได้แบบย้อนหลังสำหรับรันไทม์ SDK

เครื่องมือสร้าง Shim จะเพิ่มเลเยอร์การแยกข้อมูลอีกชั้นหนึ่ง โดยจะสร้างคลาสแบบนามธรรมที่ชื่อ AbstractSandboxedSdkProvider โดยใช้อินเทอร์เฟซที่คุณใส่คำอธิบายประกอบด้วย @PrivacySandboxService

คลาสนี้ขยาย SandboxedSdkProviderCompat และอยู่ภายใต้แพ็กเกจเดียวกันกับอินเทอร์เฟซที่มีคำอธิบายประกอบ

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

คลาสที่สร้างขึ้นนี้จะแสดงเมธอด Factory แบบนามธรรมเดียวที่รับ 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