Tworzenie i wykorzystywanie pakietu SDK z włączonym środowiskiem wykonawczym

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

Korzystanie z pakietu SDK wywoływanego w czasie działania aplikacji

W tej sekcji opisujemy, jak klienci mogą wchodzić w interakcje z zadeklarowanymi interfejsami API pakietu SDK z włączonym środowiskiem wykonawczym.

W tym przewodniku istniejący moduł pakietu SDK (lub pakiet SDK uwzględniający środowisko wykonawcze) nazywamy klientem.

Jeśli chcesz zintegrować pakiet SDK z włączonym środowiskiem wykonawczym bezpośrednio z aplikacją, moduł aplikacji jest klientem.

Wczytywanie pakietu SDK wywoływanego w czasie działania aplikacji

Pierwszą rzeczą, którą musisz zrobić w pakiecie SDK z włączonym środowiskiem wykonawczym lub w aplikacji klienckiej, jest wczytanie pakietu SDK z włączonym środowiskiem wykonawczym.

Klasa SdkSandboxManager pomaga w ładowaniu pakietów SDK używanych w czasie działania aplikacji i zwraca klasę IBinder, do której pakiet SDK używany w czasie działania aplikacji może się wiązać z interfejsem zadeklarowanym w tym pakiecie.

Musisz zadbać o to, aby każdy pakiet SDK z włączoną obsługą środowiska wykonawczego był wczytywany tylko raz. W przeciwnym razie menedżer pakietów SDK zwróci wyjątek.

Narzędzia do generowania warstwy pośredniej tworzą klasy pomocnicze, które przekształcają interfejs IBinder zwracany przez SdkSandboxManager z powrotem w zadeklarowany interfejs API pakietu SDK.

Narzędzia używają interfejsu oznaczonego symbolem @PrivacySandboxService, aby wygenerować klasę *Factory.

Ta klasa zawiera statyczną funkcję wrapTo*, która przekształca obiekt IBinder w instancję interfejsu pakietu SDK z włączoną obsługą środowiska wykonawczego.

Pakiet SDK uwzględniający środowisko wykonawcze może komunikować się z pakietem SDK obsługującym środowisko wykonawcze za pomocą tego interfejsu i wywoływać interfejsy API pakietu SDK zadeklarowane w poprzednim kroku.

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

Korzystanie z biblioteki interfejsu

Jeśli chcesz używać biblioteki interfejsu do wyświetlania reklam, upewnij się, że w pliku build.gradle pakietu SDK uwzględniającego stan środowiska wykonawczego dodano zależności androidx.privacysandbox.ui:ui-core i androidx.privacysandbox.ui:ui-client.

Ładowanie banera reklamowego za pomocą SandboxedSdkView

androidx.privacysandbox.ui:ui-client wprowadza nowy ViewGroup o nazwie SandboxedSdkView, który będzie hostować interfejs użytkownika utworzony przez pakiet SDK używany w czasie działania aplikacji.

setAdapter() otwiera sesję z pakietem SDK z włączonym środowiskiem wykonawczym, aby otrzymywać wyświetlenia reklam i powiadomienia o zmianach interfejsu. Gdy pakiet SDK otworzy sesję, wyświetli reklamę.

Można to zintegrować w ten sposób:

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

Pakiet SDK uwzględniający stan środowiska wykonawczego może też otrzymywać powiadomienia o zmianach stanu sesji w przypadku wyświetlania interfejsu. Aby to zrobić:

  1. Utwórz SessionStateChangeListener()klasę do obsługi różnych scenariuszy:

    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. Dodaj detektor zmiany stanu do utworzonego wcześniej obiektu SandboxedSdkView. Gdy tylko słuchacz zostanie dołączony do widoku, natychmiast zostanie wywołany z bieżącym stanem.

Pamiętaj:

  • Jeśli pakiet SDK uwzględniający czas działania wywołuje metody SandboxedSdkView, gdy sesja nie została jeszcze otwarta, wszystkie efekty zostaną zastosowane po otwarciu sesji.
    • Metody takie jak SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop)
  • Wywoływanie metod, które dodają lub usuwają widok z SandboxedSdkView (np. addView(), removeView(), removeViewAt() itp.), nie jest obsługiwane i powoduje zgłoszenie wyjątku UnsupportedOperationException.
    • Używaj tylko znaku setAdapter(), aby wyświetlać reklamę.
  • SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop) przełącza kolejność, co wpływa na to, czy MotionEvents z interakcji użytkownika są wysyłane do pakietu SDK używanego w czasie działania aplikacji czy do pakietu SDK obsługującego środowisko wykonawcze.

Rozpocznij aktywności

Aby uruchamiać działania należące do pakietu SDK z włączonym środowiskiem wykonawczym, użyj rozszerzenia createSdkActivityLauncher, aby utworzyć program uruchamiający w pakiecie SDK z włączonym środowiskiem wykonawczym.

Ten program uruchamiający można następnie przekazać do pakietu SDK z włączonym środowiskiem wykonawczym, co umożliwi mu inicjowanie aktywności w razie potrzeby.

Za pomocą predykatu możesz określić, czy aktywność zostanie uruchomiona. Aby zezwolić na aktywności, predykat musi zwracać wartość true.

val launchSdkActivityPredicate = {
    // Boolean which has to be true to launch the activities
    }
val launcher = baseActivity.createSdkActivityLauncher(launchSdkActivityPredicate)
fullscreenService.showActivity(launcher)

W pakiecie SDK z włączonym środowiskiem wykonawczym zarejestruj SdkSandboxActivityHandlerCompat i przekaż go do 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 przekazany do SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implementuje LifecycleOwner, co daje pakietowi SDK z włączonym środowiskiem wykonawczym dostęp do cyklu życia aktywności.

Udostępnia też interfejs getOnBackPressedDispatcher API, którego można używać do rejestrowania instancji getOnBackPressedCallback w celu obsługi działania przycisku Wstecz w ramach aktywności.


Krok 3. Utwórz pakiet SDK obsługujący środowisko wykonawcze Krok 5. Testowanie i przygotowywanie do dystrybucji