Aktywność związana z reklamami pełnoekranowymi

Uwaga: Piaskownica prywatności na urządzeniach z Androidem to projekt w toku, a ten dokument odzwierciedla jego obecną wersję. Twoja opinia jest dla nas bardzo ważna, ponieważ stale rozwijamy i ulepszamy te funkcje.

Środowisko wykonawcze pakietu SDK narzuca ograniczenia dotyczące uruchamiania nowych działań przez pakiety SDK. Stanowi to wyzwanie dla formatów reklam pełnoekranowych, które zwykle wymagają uruchomienia osobnej aktywności w celu zwiększenia kontroli i wygody użytkowników. Aby rozwiązać ten problem, środowisko wykonawcze SDK wprowadza nowy mechanizm dla działań w piaskownicy.

Pakiety SDK wczytane w środowisku wykonawczym SDK nie mogą bezpośrednio definiować tagów <activity> w swoim pliku manifestu ani inicjować własnych działań. Zamiast tego wprowadzamy nowe działanie związane z zamiarem START_SANDBOXED_ACTIVITY.

Pakiety SDK nie mogą też uruchamiać intencji z tym działaniem, ale mogą poprosić aplikację klienta o jej zainicjowanie. Następnie system tworzy 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 implementacji reklamy pełnoekranowej i zarządzania nią.

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

Uwaga: udostępniona aktywność (android.app.Activity) ma ograniczone wsparcie w przypadku niektórych bibliotek AndroidX po stronie pakietu SDK, zwłaszcza Compose.

Uwaga: Context tej aktywności nie należy używać bezpośrednio w pakiecie SDK. Zamiast tego pakiety SDK muszą używać interfejsu SandboxedSdkProvider#getContext(), aby uzyskać odpowiedni kontekst operacji.

Tworzenie aktywności w środowisku wykonawczym pakietu SDK

Istnieją 2 podstawowe metody tworzenia aktywności: za pomocą uproszczonych bibliotek aktywności Jetpacka lub bezpośrednio za pomocą interfejsów Platform API.

Zalecamy korzystanie z bibliotek aktywności, ponieważ upraszczają one tworzenie aktywności, abstrahując od złożoności leżącej u podłoża.

Biblioteki aktywności

Biblioteki aktywności mają wiele zalet:

• Ukrywanie wewnętrznych szczegółów rejestrowania modułów obsługi aktywności i udostępniania ich identyfikatorów aplikacjom klienta.
• Daje deweloperom 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.
• Utworzenie ujednoliconego sposobu definiowania interfejsów API, które uruchamiają działania, w pakietach SDK.

Istnieją 3 biblioteki aktywności: główna, klienta i dostawcy.

• Biblioteka podstawowa udostępnia interfejsy używane przez aplikacje klienta i biblioteki dostawców.
• Biblioteka dostawcy udostępnia interfejsy API dla pakietów SDK, które umożliwiają uruchamianie działań.
• Biblioteka klienta udostępnia interfejsy API, które umożliwiają aplikacjom klienta tworzenie inicjatora aktywności, którego pakiety SDK mogą używać do wysyłania aplikacji do uruchamiania aktywności.

Te biblioteki wprowadzają te interfejsy API:

• SdkActivityLauncher: Launcher aktywności umożliwia pakietom SDK obsługę uruchamiania aktywności z aplikacji klienta. Aplikacje klienta powinny utworzyć launcher 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 klienta może wywoływać z działań, aby tworzyć inicjatory.
• SdkActivityLauncher.launchSdkActivity(IBinder): metoda używana przez pakiet SDK do żądania uruchomienia aktywności przez aplikację.

Proces uruchamiania aktywności z bibliotekami aktywności wygląda tak:

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

Uwaga: jeśli aplikacja kliencka chce dodać warunek dla pakietów SDK, aby tworzyć czynności, może przekazać wyrażenie predykatu podczas tworzenia programu uruchamiającego. Jeśli aplikacja nie chce warunkować tworzenia aktywności, może spowodować, że predykat zwróci zawsze wartość true.

Na diagramie poniżej widać proces w przypadku korzystania z bibliotek aktywności.

Diagram sekwencji pokazujący proces uruchamiania aktywności przy użyciu bibliotek aktywności

Interfejsy Platform API

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

• SdkSandboxActivityHandler: obsługa aktywności służy do powiadamiania pakietu SDK o tworzeniu aktywności i jej rejestrowaniu przez ten pakiet.
• Aby ułatwić rejestrowanie metod 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): wyrejestrowanie zarejestrowanej instancji SdkSandboxActivityHandler za pomocą jej identyfikatora.
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): wywoływana z aplikacji klienckiej, ta metoda powoduje tworzenie działań dla pakietu SDK. Aplikacja klienta musi jako parametry przekazać wybraną aktywność uruchamiającą i identyfikator modułu obsługi aktywności w SDK.

Aby rozpocząć działanie przy użyciu interfejsów API platformy, pakiety SDK muszą przestrzegać tej procedury:

1. Pakiet SDK rejestruje moduł obsługi aktywności za pomocą udostępnionych interfejsów API i uzyskiwanie identyfikatora.
2. Pakiet SDK udostępnia ten identyfikator aplikacji klienta.
3. Aplikacja klienta wywołuje metodę uruchamiania aktywności w czasie działania pakietu SDK za pomocą interfejsu API platformy startSdkSandboxActivity(Activity, IBinder), przekazując jako parametry wybraną początkową aktywność dla tej nowej aktywności i identyfikator modułu obsługi aktywności.
4. Platforma uruchamia aktywność i powiadamia pakiet SDK za pomocą wywołania zwrotnego w obiekcie Activity Handler (SdkSandboxActivityHandler.onActivityCreated(Activity)).
5. Pakiet SDK używa aktywności do wypełniania jej reklamą.

Uwaga: onActivityCreated(Activity) jest wywoływany przez Activity.onCreate(Bundle), na tym etapie pakiety SDK powinny wypełnić widok treści.

Korzystanie z interfejsów Platform API sprawia, że pakiet SDK odpowiada za udostępnienie identyfikatora SdkSandboxActivityHandler aplikacji klienta za pomocą interfejsów API w odpowiednim momencie oraz za udzielenie aplikacjiom klienta wskazówek dotyczących jego użycia.

W tym diagramie przepływu przykładowy pakiet SDK ma metodę launchActivity(AppCallback), która oczekuje wywołania zwrotnego (zdefiniowanego jako część interfejsu API pakietu SDK). Ta metoda wywołania zwrotnego jest używana przez pakiet SDK do udostępniania identyfikatora modułu Activity Handler (SdkSandboxActivityHandler) aplikacji klienta.

Diagram sekwencji pokazujący przepływ uruchamiania aktywności za pomocą interfejsów API platformy.

Widoczność

W środowisku wykonawczym pakietu SDK reklamy zintegrowane z hierarchią widoków aplikacji klienta korzystają z kanałów pobocznych, aby renderować widoki pakietu SDK z procesu pakietu SDK do procesu aplikacji klienta.

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

Z kolei aktywność udostępniana przez platformę działa natywnie w ramach procesu środowiska wykonawczego pakietu SDK, co eliminuje potrzebę korzystania z kanałów dodatkowych i pozwala pakietom SDK używać standardowych interfejsów API Activity i View na Androida.

Z powodu tych różnych implementacji prowadzimy obecnie prace nad ujednoliceniem interfejsów, aby pobierać sygnały widoczności niezależnie od kontekstu wczytywania reklamy.

Lifecycle

ActivityHolderprzekazany do pakietu SDK przezSdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder)implementujeLifecycleOwneri może służyć do uzyskiwania informacji o Lifecycle.Event.

Nawigacja wstecz

Metoda ActivityHolder.getOnBackPressedDispatcher() zwraca OnBackPressedDispatcher które można wykorzystać do rejestrowania instancji OnBackPressedCallback w celu obsługi nawigacji wstecz.