Aktywność związana z reklamami pełnoekranowymi

Środowisko wykonawcze pakietu SDK nakłada ograniczenia na sposób, w jaki pakiety SDK mogą uruchamiać nowe działania. Stanowi to wyzwanie dla formatów reklam pełnoekranowych, które zwykle polegają na rozpoczęciu osobnej aktywności w celu zwiększenia kontroli i poprawy wygody użytkowników. Aby rozwiązać ten problem, środowisko wykonawcze SDK wprowadza nowy 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 wprowadzamy nową czynność związaną z intencją – START_SANDBOXED_ACTIVITY.

Pakietom SDK nie wolno uruchamiać intencji za pomocą tej czynności, ale mogą one poprosić aplikację kliencką o jej zainicjowanie. System tworzy wtedy aktywność zdefiniowaną przez platformę i przekazuje ją do pakietu SDK. Ta aktywność będzie działać w tym samym procesie co pakiet SDK.

Pakiet SDK może następnie użyć tej aktywności do wdrożenia reklamy pełnoekranowej i zarządzania nią.

Aktywność zapewniana przez platformę to standardowy android.app.Activity, uruchamiany w ramach zadania aplikacji klienta.

Tworzenie aktywności w środowisku wykonawczym SDK

Działania możesz tworzyć na 2 główne sposoby: za pomocą uproszczonych bibliotek Activity Jetpack lub bezpośrednio za pomocą interfejsów API platformy.

Zalecamy używanie bibliotek aktywności, ponieważ upraszczają one tworzenie aktywności przez ukrywanie złożoności.

Biblioteki aktywności

Biblioteki aktywności zapewniają kilka zalet:

Abstrakcja 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 aplikacjach, umożliwiając im ustawianie warunków (predykatów), które muszą być spełnione.
Stworzenie ujednoliconego sposobu definiowania przez pakiety SDK interfejsów API, które uruchamiają działania.

Dostępne są 3 biblioteki działań: podstawowa, klienta i dostawcy.

Biblioteka podstawowa udostępnia interfejsy używane przez aplikacje klienckie i biblioteki dostawców.
Biblioteka provider udostępnia interfejsy API, które umożliwiają pakietom SDK uruchamianie działań.
Biblioteka klienta udostępnia interfejsy API, które umożliwiają aplikacjom klienckim tworzenie narzędzia do uruchamiania aktywności. Pakiety SDK mogą używać tego narzędzia do wysyłania do aplikacji próśb o uruchomienie aktywności.

Te biblioteki udostępniają te interfejsy API:

SdkActivityLauncher: moduł uruchamiania aktywności umożliwia pakietom SDK obsługę uruchamiania aktywności z aplikacji klienta. Aplikacje klienta powinny utworzyć moduł uruchamiania i przekazać go jako parametr do interfejsów API pakietu SDK, które uruchamiają aktywności.
<T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): funkcja rozszerzenia, którą aplikacja kliencka może wywoływać ze swoich działań w celu tworzenia menu z aplikacjami.
SdkActivityLauncher.launchSdkActivity(IBinder): metoda używana przez pakiet SDK do wysyłania do aplikacji żądań uruchomienia aktywności.

Przebieg uruchamiania aktywności za pomocą bibliotek aktywności jest następujący:

Pakiet SDK dodaje do wszystkich interfejsów API, które będą uruchamiać aktywności, parametr typu SdkActivityLauncher.
Aplikacja kliencka wywołuje createSdkActivityLauncher w ramach jednej ze swoich aktywności, aby utworzyć program uruchamiający, który można przekazać do pakietu SDK w wywołaniach interfejsu API.
Pakiet SDK wywołuje SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) i pobiera token identyfikatora.
Pakiet SDK wywołuje launchSdkActivity w celu uruchomienia działania.

Na diagramie poniżej przedstawiono przepływ w przypadku korzystania z bibliotek aktywności.

Schemat sekwencji biblioteki aktywności — Diagram sekwencji przedstawiający proces rozpoczynania aktywności za pomocą bibliotek aktywności.

Interfejsy API platformy

Platforma udostępnia te interfejsy API, aby ułatwić tworzenie i zarządzanie aktywnościami w środowisku wykonawczym SDK:

SdkSandboxActivityHandler: moduł obsługi aktywności służy do powiadamiania pakietu SDK o utworzeniu aktywności i jest rejestrowany przez pakiet SDK.
Aby ułatwić rejestrację modułów obsługi aktywności, pakiet SDK może używać tych metod w sekcji SdkSandboxController:
- .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): Rejestruje instancję SdkSandboxActivityHandler, która zwraca identyfikator IBinder.
- .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): wyrejestrowuje zarejestrowaną instancję SdkSandboxActivityHandler za pomocą jej identyfikatora.
SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): Wywoływana z aplikacji klienta, ta metoda powoduje utworzenie działań dla pakietu SDK. Aplikacja klienta musi przekazywać jako parametry wybraną aktywność początkową i identyfikator modułu obsługi aktywności pakietu SDK.

Aby rozpocząć aktywność za pomocą interfejsów API platformy, pakiety SDK muszą wykonać te czynności:

Pakiet SDK rejestruje moduł obsługi aktywności za pomocą udostępnionych interfejsów API i uzyskuje identyfikator.
Pakiet SDK udostępnia ten identyfikator aplikacji klienta.
Aplikacja kliencka wywołuje metodę rozpoczynającą aktywność w środowisku wykonawczym pakietu SDK za pomocą interfejsu API platformy startSdkSandboxActivity(Activity, IBinder), przekazując jako parametry wybraną aktywność początkową dla tej nowej aktywności oraz identyfikator modułu obsługi aktywności.
Platforma rozpoczyna działanie i powiadamia pakiet SDK za pomocą wywołania zwrotnego w obiekcie Activity Handler (SdkSandboxActivityHandler.onActivityCreated(Activity)).
Pakiet SDK wykorzystuje aktywność do wypełnienia jej reklamą.

Korzystanie z interfejsów API platformy sprawia, że pakiet SDK odpowiada za udostępnianie identyfikatora SdkSandboxActivityHandler aplikacji klienckiej za pomocą interfejsów API w odpowiednim czasie oraz za przekazywanie aplikacji klienckich wskazówek dotyczących jego używania.

Na diagramie poniżej przykładowy pakiet SDK ma metodę launchActivity(AppCallback), która oczekuje wywołania zwrotnego (zdefiniowanego w ramach interfejsu API pakietu SDK). To wywołanie zwrotne jest używane przez pakiet SDK do udostępniania aplikacji klienta identyfikatora modułu obsługi aktywności (SdkSandboxActivityHandler).

Diagram sekwencji interfejsów API platformy — Diagram sekwencji przedstawiający przepływ rozpoczynania działania za pomocą interfejsów API platformy.

Widoczność

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

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

Natomiast aktywność dostarczana przez platformę jest uruchamiana natywnie w procesie środowiska wykonawczego SDK, co eliminuje potrzebę korzystania z kanałów bocznych i umożliwia pakietom SDK używanie standardowych interfejsów API Androida Activity i View.

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

Lifecycle

Obiekt ActivityHolder przekazywany do pakietu SDK za pomocą SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implementuje LifecycleOwner i może służyć do uzyskiwania informacji o Lifecycle.Event.

Przechodzenie wstecz

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