פיתוח וצריכה של ערכת 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 שתואם לזמן הריצה

בקטע הזה נסביר איך לקוחות יכולים לקיים אינטראקציה עם ממשקי ה-API של ה-SDK (RE) שהוצהרו כפעילים בסביבת זמן ריצה.

במדריך הזה, אנחנו מתייחסים למודול ה-SDK הקיים (או ל-SDK שמבוסס על זמן ריצה) בתור הלקוח.

אם רוצים להטמיע את ה-SDK התואם לזמן הריצה ישירות באפליקציה, מודול האפליקציה הוא הלקוח.

טעינת ערכת ה-SDK שתואמת לזמן ריצה

הדבר הראשון שצריך לעשות ב-SDK או באפליקציית הלקוח עם תמיכה בסביבת זמן הריצה הוא לטעון את ה-SDK שתומך בסביבת זמן הריצה.

המחלקה SdkSandboxManager עוזרת לטעון ערכות SDK שתואמות לזמן ריצה, ומחזירה מחלקה IBinder שה-SDK מבוסס-זמן הריצה יכול לקשר לממשק שהוצהר ב-SDK שמופעלת בו סביבת זמן ריצה.

צריך לוודא שטוענים כל ערכת SDK שתואמת לזמן ריצה רק פעם אחת, אחרת מנהל ה-SDK יחזיר תוצאות חריגות.

הכלים ליצירת ספריית shim יוצרים מחלקות עוזרים שממירים את ממשק IBinder שמוחזר על ידי SdkSandboxManager חזרה לממשק ה-API של ה-SDK שהוצהר.

הכלים משתמשים בממשק עם הערות @PrivacySandboxService כדי ליצור מחלקה *Factory.

המחלקה הזו מכילה פונקציית wrapTo* סטטית שממירה אובייקט IBinder למכונה של ממשק ה-SDK שמותאם לזמן ריצה.

ה-SDK המותאם לסביבת זמן הריצה יכול לתקשר עם ה-SDK המותאם לסביבת זמן הריצה באמצעות הממשק הזה, ולהפעיל את ממשקי ה-API של ה-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 התואם את זמן הריצה מקבל גישה למחזור החיים של הפעילות.

הוא גם מספק את ה-API של getOnBackPressedDispatcher, שאפשר להשתמש בו כדי לרשום מכונות getOnBackPressedCallback לטיפול בהתנהגות של לחצן החזרה לאחור בתוך הפעילות.


שלב 3: פיתוח SDK שתואם לזמן ריצה שלב 5: בדיקה ובנייה של הפצה