Środowisko wykonawcze SDK pozwala pakietom SDK do wyświetlania reklam działać w środowisku piaskownicy, co uniemożliwia im dostęp do hierarchii widoków wydawcy. Aby wyświetlać reklamy, platforma udostępnia pakietowi SDK interfejs API SandboxedSdkProvider.getView
w celu uzyskania wyświetlenia reklamy i pakietuje go jako SurfacePackage
, aby go wysłać do aplikacji klienckiej za pomocą IPC (komunikacji między procesami). Ma to kilka wad, które opisujemy poniżej. W tym dokumencie zaprezentujemy proponowaną
bibliotekę jetpacków, która powstała, aby sprostać tym wyzwaniom.
Uzasadnienie rozszerzenia interfejsów API platformy
Platformowe interfejsy API zostały zaprojektowane z myślą o elastyczności i pozwalają na tworzenie osobnego kanału między aplikacją a pakietem SDK, aby umożliwić prezentację UI. Ten kanał boczny wykonuje te działania:
- Pozwala pakietowi SDK zarządzać wieloma wyświetleniami reklam przez cały okres jego istnienia i sprawdzać, co dzieje się z interfejsem reklamy po utworzeniu przez pakiet SDK.
- Rozdziela tworzenie widoku i powiązanie treści. Korzystanie z kanału bocznego umożliwia pakietowi SDK zwrócenie obiektu odpowiadającego żądaniu reklamy skierowanemu do aplikacji (treści), który można powiązać z kontenerem reklamy, kiedy aplikacja uzna to za stosowne.
- Obejmuje podstawowe konstrukcje platformy używane do wyświetlania UI w różnych procesach. (Platforma używa obecnie
SurfaceControlViewhost
i generuje z niegoSurfacePackage
). - Włącza w środowisku wykonawczym SDK pakiety SDK do wyświetlania reklam, aby automatycznie otrzymywać powiadomienia o zmianach interfejsu kontenera reklam. Jeśli wydawca zmieni układ kontenera reklam, pakiet SDK nie wie o tych zmianach, chyba że bezpośrednio wywoła interfejs API, aby go o tym powiadomić.
- Synchronizuje zmiany rozmiaru interfejsu reklamy i kontenera reklamy bez zakłóceń widocznych dla użytkowników.
- Automatycznie zarządza zgodnością wsteczną. Interfejs
SurfacePackage
jest niedostępny przed poziomem API 30. Poza tym na urządzeniach, na których nie ma środowiska wykonawczego SDK, a pakiet SDK jest procesem lokalnym dla wydawcy, nie warto tworzyć elementuSurfacePackage
dla reklamy, jeśli wyświetlenie można uzyskać bezpośrednio z pakietu SDK. Kanał boczny wyodrębnia tę złożoność z pakietu SDK i kodu dewelopera aplikacji. - Umożliwia płynną integrację interfejsu reklam z kompozycyjnymi elementami. Deweloperzy Jetpack Compose, którzy nie obsługują widoków, mogą też nadal hostować interfejs użytkownika wygenerowany przez dewelopera pakietu SDK, który nadal obsługuje widoki danych.
Biblioteki interfejsu
Biblioteki interfejsu umożliwiają wyeliminowanie opisanych powyżej zawiłości i udostępniają kanał boczny, za pomocą którego wydawca i pakiet SDK mogą wyświetlać interfejs użytkownika przez różne procesy oraz aktualizować go w miarę interakcji użytkownika z urządzeniem i z nim.
Dostępne są 3 biblioteki interfejsu: core, client i provider. Biblioteka podstawowa zawiera interfejsy używane przez biblioteki klienta i dostawcy. Dostawca interfejsu użytkownika (zwykle pakiet SDK) zależy od biblioteki dostawcy, a użytkownik UI (zwykle jest to wydawca) zależy od biblioteki klienta. Biblioteki klienta i dostawcy tworzą razem kanał boczny wymagany do tworzenia i obsługiwania sesji UI.
Interfejsy API
Prezentacja interfejsu API środowiska wykonawczego SDK wygląda tak:
SandboxedUiAdapter
: tworzony przez pakiet SDK, co umożliwia pobieranie treści, które mają być wyświetlane w interfejsie wydawcy.
SandboxedSdkView
: tworzony przez wydawcę kontener, który zawiera treści uzyskane za pomocą SandboxedUiAdapter
.
Session
: tworzony przez pakiet SDK w odpowiedzi na SandboxedUiAdapter.openSession()
. Reprezentuje jedną sesję UI. Spowoduje to zakończenie tunelu komunikacji pakietu SDK między pakietem SDK a wydawcą oraz otrzymywanie powiadomień o zmianach w SandboxedSdkView
, takich jak odłączenie okien, zmiana rozmiaru lub zmiany konfiguracji.
SessionClient
: tworzona przez bibliotekę klienta i stanowi koniec tunelu komunikacji między pakietem SDK a wydawcą.
SandboxedSdkUiSessionStateChangedListener
: utworzony przez wydawcę. Rejestrator zmian stanu sesji UI powiązanej z zasobnikiem SandboxedSdkView
.
Więcej informacji o tych interfejsach API znajdziesz w dokumentacji referencyjnej interfejsu Piaskownicy prywatności.
Sterowanie przepływem
Poniższe diagramy pokazują interakcję między bibliotekami interfejsu klienta i dostawcy w różnych scenariuszach:
Na poprzednim diagramie widać, jak wydawca może utworzyć plik SandboxedSdkView
(programowo lub za pomocą kodu XML) i załączyć go do elementu SdkSandboxUiAdapter
uzyskanego z pakietu SDK za pomocą interfejsu API zdefiniowanego przez SDK. Aby obserwować wszystkie zmiany stanu interfejsu, wydawca powinien dodać SandboxedSdkUiSessionStateChangedListener
do elementu SandboxedSdkView
przed dołączeniem elementu SdkSandboxUiAdapter
.
Ten diagram pokazuje, jak jeśli aktywność wydawcy obsługuje zmiany konfiguracji, biblioteka klienta przekazuje tę zmianę do pakietu SDK, aby mógł odpowiednio zaktualizować interfejs. Na przykład ten proces może zostać aktywowany, gdy użytkownik wykona rotację urządzenia, a wydawca zadeklaruje, że w swojej aktywności obsługuje zmiany konfiguracji, ustawiając wartość android:configChanges=["orientation"]
.
Ten diagram pokazuje, jak pakiet SDK może zażądać zmiany w kontenerze reklam za pomocą metod w SessionClient
. Ten interfejs API jest wywoływany, gdy pakiet SDK chce zmienić rozmiar reklamy i wymaga, aby wydawca zmienił rozmiar kontenera reklamy, aby dostosować ją do nowych wymiarów. Może się to zdarzyć w reakcji na interakcję użytkownika, np. mraid.resize()
.
Ten diagram pokazuje, jak sesja jest zamykana po odłączeniu interfejsu SandboxedSdkView
od okna. Sesję można też zakończyć w dowolnym momencie (np. gdy użytkownik utraci połączenie z siecią), używając pakietu SDK, wywołując SessionClient.onSessionError()
.
Kolejność Z
Biblioteka interfejsu klienta używa wewnętrznie SurfaceView
do hostowania interfejsu pakietu SDK.
SurfaceView
może używać kolejności Z, aby wyświetlać swój interfejs nad oknem wydawcy lub pod nim. Decyduje o tym metoda SandboxedSdkView.orderProviderUiAboveClientUi()
, która akceptuje wartość logiczną setOnTop
.
Gdy setOnTop
ma wartość true
, do pakietu SDK wysyłane są wartości android.view.MotionEvent
w SandboxedSdkView
. Gdy false
są wysyłane do wydawcy. Domyślnie zdarzenia ruchu są wysyłane do pakietu SDK.
Wydawcy zwykle nie muszą zmieniać domyślnej kolejności wyświetleń reklam (z). Jednak w przypadku interfejsu zasłaniającego reklamę, np. menu, kolejność nakładania elementów powinna być tymczasowo odwrócona i przywrócona po zamknięciu elementu interfejsu. Sprawdzamy sposoby automatyzacji tego procesu w bibliotece interfejsu klienta.
Przewijanie
Jeśli w interfejsie reklamy ustawiono kolejność Z nad oknem wydawcy, do pakietu SDK wysyłane są pliki MotionEvents
z interfejsu reklamy. Gesty przewijania i przesuwania inicjowane w interfejsie reklamy są traktowane wyjątkowo:
- Gesty przewijania w pionie i przesuwania są wysyłane do kontenera wydawcy i obsługiwane przez niego. Zapewnia to wygodę korzystania, gdy kontener wydawcy, w którym znajduje się interfejs reklamy, umożliwia przewijanie w pionie. Nie wymaga to żadnych dodatkowych działań po stronie SDK ani wydawcy.
- Gesty przewijania w poziomie i przesuwania są wysyłane do pakietu SDK i obsługiwane przez niego. Zapewnia to wygodę korzystania, gdy interfejs reklamy można przewijać w poziomie (np. za pomocą karuzeli reklam).
Przewodnik po implementacji
Pakiet SDK powinien implementować te elementy:
SandboxedUiAdapter
: wartość jest zwracana wydawcy w odpowiedzi na interfejs API zdefiniowany przez pakiet SDK, taki jakloadAd
. MetodaopenSession()
w tej implementacji powinna służyć do wysyłania żądania reklamy do serwerów pakietu SDK i przygotowywania dla niego widoku reklamy.Session**
: zwracany w odpowiedzi na wywołanieSandboxedUiAdapter.openSession
. Umożliwia bibliotece klienta dostęp do interfejsu reklamy i powiadamianie pakietu SDK o zmianach w tym interfejsie API. Tutaj należy zaimplementować wszystkie metodySession
.
Wydawca powinien wykonać te czynności:
- Utwórz
SandboxedSdkView
za pomocą pliku XML lub automatycznie. - Dołącz
SandboxedSdkUiSessionStateChangedListener
do elementuSandboxedSdkView
, aby obserwować zmiany w interfejsie. - Dołącz pakiet SDK dostarczony przez
SandboxedUiAdapter
doSandboxedSdkView
. - Dodaj
SandboxedSdkView
do okna w zwykły sposób, a biblioteka klienta zajmie się utworzeniem i obsługą sesji UI za pomocą pakietu SDK. - W odpowiednich momentach reaguj na zmiany stanu zgłoszone przez:
SandboxedSdkUiSessionChangedListener
. Jeśli na przykład pakiet SDK nieoczekiwanie zamknie sesję, wydawca może zastąpić obiektSandboxedSdkView
obrazem statycznym lub usunąć go ze swojej hierarchii widoków. - Podczas wykonywania przejść, które mogą zasłaniać interfejs reklamy, np. menu, tymczasowo ustaw
orderProviderUiAboveClientUi
na fałsz, aby umieścić interfejs reklamy poniżej okna wydawcy. Po zamknięciu menu wywołajorderProviderUiAboveClientUi
pod numeremtrue
.
Przyszłość interfejsów API platform
Gdy biblioteki interfejsu użytkownika przejdą w wersji beta, planujemy wycofać interfejsy API platformy środowiska wykonawczego SDK powiązane z prezentacją UI. Są to tzw. SdkSandboxManager.requestSurfacePackage()
i SandbxedSdkProvider.getView()
.
Pytania otwarte
- Czy są jakieś typowe przypadki użycia interfejsu reklam, które biblioteki interfejsu powinny obsługiwać automatycznie?
- Z jakich platform interfejsu korzystacie do wyświetlania interfejsu reklam. Czy spodziewacie się problemów z integracją bibliotek interfejsu z tymi platformami?
- Czy interfejs reklam z możliwością przewijania w kontenerze wydawcy z możliwością przewijania jest w Twoim przypadku typowym przypadkiem użycia? Jaka jest w tym przypadku kierunkowość przewijania w interfejsie reklamy i kontenerze? Jakiego działania możesz się spodziewać, gdy użytkownik rozpocznie przewijanie w interfejsie reklamy?