Aktywność związana z reklamami pełnoekranowymi

Środowisko wykonawcze SDK nakłada ograniczenia na to, jak pakiety SDK mogą uruchamiać nowe działania. Stanowi to wyzwanie dla formatów reklam pełnoekranowych, które zwykle wymagają rozpoczęcia osobnej czynności w celu zwiększenia kontroli i większej wygody użytkownika. Aby rozwiązać ten problem, w środowisku wykonawczym SDK wprowadziliśmy nowatorski mechanizm aktywności w piaskownicy.

Pakiety SDK wczytane w środowisku wykonawczym SDK nie mogą bezpośrednio definiować tagów <activity> w pliku manifestu ani inicjować własnych działań. Zamiast tego wprowadzane jest nowe działanie intencji: START_SANDBOXED_ACTIVITY.

Pakiety SDK nie mogą uruchamiać intencji za pomocą tego działania, ale mogą zażądać, aby aplikacja kliencka zainicjowała tę intencję. System tworzy działanie zdefiniowaną przez platformę i przekazuje je do pakietu SDK. To działanie będzie wykonywane w tym samym procesie co pakiet SDK.

Pakiet SDK może następnie wykorzystać to działanie do implementacji reklam pełnoekranowych i zarządzania nimi.

Aktywność udostępniana przez platformę to standardowa android.app.Activity uruchamiana w ramach zadania aplikacji klienta.

Uwaga: podane działanie (android.app.Activity) obsługuje niektóre biblioteki AndroidaX po stronie SDK, a zwłaszcza funkcję Compose.

Uwaga: elementu Context tej aktywności nie należy używać bezpośrednio w pakiecie SDK. Pakiety SDK muszą używać protokołu SandboxedSdkProvider#getContext(), aby uzyskać odpowiedni kontekst dla swoich działań.

Tworzenie aktywności w środowisku wykonawczym SDK

Aktywności możesz tworzyć na 2 główne sposoby: za pomocą uproszczonych bibliotek aktywności Jetpack oraz w bezpośredniej interakcji z interfejsami API platformy.

Zalecamy korzystanie z bibliotek aktywności, ponieważ upraszczają one tworzenie aktywności przez wyodrębnianie jej złożoności.

Biblioteki aktywności

Biblioteki aktywności mają kilka zalet:

• Omówienie wewnętrznych szczegółów rejestrowania modułów obsługi aktywności i udostępniania ich identyfikatorów aplikacjom klienckim.
• Daje deweloperom aplikacji większą kontrolę nad tym, jak pakiety SDK tworzą aktywności w ich aplikacjach, umożliwiając im określanie warunków (predykatów) do spełnienia.
• Utwórz ujednolicony sposób definiowania interfejsów API uruchamiających działania w pakietach SDK.

Dostępne są 3 biblioteki aktywności: podstawowy, klient i dostawca.

• Biblioteka core udostępnia interfejsy używane przez aplikacje klienckie i biblioteki dostawcy.
• Biblioteka provider udostępnia interfejsy API przeznaczone do uruchamiania działań przez pakiety SDK.
• Biblioteka client udostępnia interfejsy API dla aplikacji klienckich, które pozwalają utworzyć program uruchamiający aktywność, za pomocą którego pakiety SDK mogą wysyłać żądania aplikacji do uruchamiania działań.

Te biblioteki wprowadzają następujące interfejsy API:

• SdkActivityLauncher: program uruchamiający aktywność umożliwia pakietom SDK wykonywanie działań związanych z uruchamianiem aplikacji klienckiej. Aplikacje klienckie powinny utworzyć program uruchamiający i przekazywać go jako parametr do interfejsów API pakietu SDK, które rozpoczynają działania.
• <T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): funkcja rozszerzenia, którą aplikacja kliencka może wywoływać z poziomu swoich działań, aby tworzyć programy uruchamiające.
• SdkActivityLauncher.launchSdkActivity(IBinder): metoda używana przez pakiet SDK do wysyłania żądań uruchamiania działań przez aplikację.

Proces uruchamiania działań za pomocą bibliotek aktywności wygląda tak:

1. Pakiet SDK dodaje parametr typu SdkActivityLauncher do wszystkich interfejsów API, które mają rozpoczynać działania.
2. Aplikacja kliencka wywołuje createSdkActivityLauncher w jednym ze swoich działań, aby utworzyć program uruchamiający, który można przekazać do SDK w przypadku wywołań interfejsu API.
3. Pakiet SDK wywołuje metodę SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) i pobiera token identyfikatora.
4. Aby uruchomić aktywność, pakiet SDK wywołuje metodę launchSdkActivity.

Uwaga: jeśli aplikacja kliencka chce dodać warunek tworzenia działań przez pakiety SDK, może podczas tworzenia programu uruchamiającego przekazywać wyrażenie predykatu. Jeśli aplikacja nie chce uwarunkować tworzenia aktywności, może ustawić zwracanie predykatu zawsze na true.

Poniższy diagram przedstawia przepływ w przypadku korzystania z bibliotek aktywności.

Schemat sekwencji przedstawiający przepływ aktywności z użyciem bibliotek aktywności.

Interfejsy API platformy

Platforma wprowadza poniższe interfejsy API, aby ułatwić tworzenie działań w trybie piaskownicy i zarządzanie nimi w środowisku wykonawczym SDK:

• SdkSandboxActivityHandler: moduł obsługi aktywności służy do powiadamiania SDK o utworzeniu działania i jest rejestrowane przez pakiet SDK.
• Aby ułatwić rejestrację modułów obsługi aktywności, pakiet SDK może korzystać z tych metod w SdkSandboxController:
  • .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): rejestruje instancję SdkSandboxActivityHandler, która zwraca identyfikator IBinder.
  • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): Wyrejestrowuje zarejestrowaną instancję SdkSandboxActivityHandler przy użyciu jej identyfikatora.
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): ta metoda jest wywoływana z aplikacji klienckiej i aktywuje tworzenie działań dla pakietu SDK. Aplikacja kliencka musi przekazywać jako parametry wybraną przez siebie aktywność początkową oraz identyfikator modułu obsługi aktywności pakietu SDK.

Aby rozpocząć aktywność za pomocą interfejsów API platformy, pakiety SDK muszą wykonać ten proces:

1. Pakiet SDK rejestruje moduł obsługi aktywności za pomocą podanych interfejsów API i uzyskuje identyfikator.
2. Pakiet SDK udostępnia ten identyfikator swojej aplikacji klienckiej.
3. Aplikacja kliencka wywołuje metodę rozpoczynania aktywności w środowisku wykonawczym SDK za pomocą interfejsu API platformy startSdkSandboxActivity(Activity, IBinder), przekazując jako parametry wybrane działanie początkowe dla tego nowego działania, a także identyfikator modułu obsługi aktywności.
4. Platforma uruchamia działanie i powiadamia pakiet SDK przez wywołanie zwrotne w module obsługi aktywności (SdkSandboxActivityHandler.onActivityCreated(Activity)).
5. Pakiet SDK używa aktywności, aby wypełnić ją reklamą.

Uwaga: funkcja onActivityCreated(Activity) jest wywoływana przez Activity.onCreate(Bundle). Pakiety SDK powinny na tym etapie zapełniać widok treści.

Korzystanie z interfejsów API platformy sprawia, że pakiet SDK ma w odpowiednim czasie udostępniać identyfikator SdkSandboxActivityHandler aplikacji klienckiej za pomocą jej interfejsów API oraz instruować aplikacje klienckie, jak z niej korzystać.

Na poniższym diagramie przepływu przykładowy pakiet SDK zawiera metodę launchActivity(AppCallback), która oczekuje wywołania zwrotnego (zdefiniowanej w interfejsie API pakietu SDK). To wywołanie zwrotne jest używane przez pakiet SDK do udostępniania identyfikatora modułu obsługi aktywności (SdkSandboxActivityHandler) aplikacji klienckiej.

Schemat sekwencji przedstawiający przepływ aktywności za pomocą interfejsów API platformy.

Widoczność

W środowisku wykonawczym pakietu SDK reklamy zintegrowane z hierarchią widoków aplikacji klienta używają kanałów bocznych do renderowania widoków pakietu SDK z procesu pakietu SDK w procesie aplikacji klienckiej.

Do określenia, czy reklama jest widoczna dla użytkownika, pakiet SDK nie może używać tych samych interfejsów API do wyświetlania, których używa poza środowiskiem wykonawczym SDK, ponieważ widok reklamy nie jest dołączony do okna aplikacji (widoczność).

Natomiast działania dostarczane przez platformę są uruchamiane natywnie w ramach procesu środowiska wykonawczego SDK, eliminując potrzebę korzystania z kanałów bocznych i umożliwiając pakietom SDK używanie standardowych interfejsów API Androida Activity i View.

Ze względu na te różne implementacje stale pracujemy nad ujednoliceniem interfejsów, aby pobierać sygnały o widoczności niezależnie od kontekstu wczytywania reklam.

Lifecycle

Komponent ActivityHolder przekazywany do SDK za pomocą implementacji SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) LifecycleOwner i może być używany do informacji o: Lifecycle.Event.

Nawigacja wstecz

Metoda ActivityHolder.getOnBackPressedDispatcher() zwraca OnBackPressedDispatcher, której można użyć do zarejestrowania instancji OnBackPressedCallback na potrzeby obsługi nawigacji wstecz.