Interfejsy API do prezentacji interfejsu środowiska wykonawczego SDK

Środowisko wykonawcze SDK umożliwia uruchamianie pakietów SDK do wyświetlania reklam 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, który umożliwia uzyskanie widoku reklamy i spakowanie go jako SurfacePackage do wysłania za pomocą IPC (komunikacji międzyprocesowej) do aplikacji klienta. Ma to kilka wad, o których piszemy poniżej. W tym dokumencie przedstawimy proponowaną bibliotekę Jetpack, która jest tworzona w celu rozwiązania tych problemów.

Uzasadnienie rozszerzenia interfejsów API platformy

Interfejsy API platformy zostały zaprojektowane z myślą o elastyczności i pozostawiają zadanie tworzenia kanału bocznego do prezentacji interfejsu aplikacji i pakietowi SDK. Ten kanał pomocniczy wykonuje te czynności:

1. Umożliwia pakietowi SDK zarządzanie wieloma wyświetleniami reklam w okresie ich istnienia i poznawanie tego, co dzieje się z interfejsem reklamy po jego utworzeniu przez pakiet SDK.
2. Oddziela tworzenie widoku od powiązania treści. Korzystanie z kanału bocznego umożliwia pakietowi SDK zwrócenie do aplikacji obiektu odpowiadającego żądaniu reklamy (treści), który można powiązać z kontenerem reklamy, gdy tylko aplikacja uzna to za stosowne.
3. Abstrakcja podstawowych konstrukcji platformy używanych do wyświetlania interfejsu w różnych procesach. (Platforma używa obecnie SurfaceControlViewhost i generuje z niego SurfacePackage).
4. Umożliwia pakietom SDK do reklam w środowisku wykonawczym pakietu SDK automatyczne otrzymywanie powiadomień o zmianach interfejsu kontenera reklamy. Jeśli wydawca zmieni układ kontenera reklamy, pakiet SDK nie będzie o tym wiedzieć, dopóki wydawca nie wywoła interfejsu API, aby go o tym powiadomić.
5. Synchronizuje zmiany rozmiaru interfejsu reklamy i kontenera reklamy bez widocznych dla użytkownika zakłóceń.
6. Automatycznie zarządza zgodnością wsteczną. SurfacePackage jest niedostępny przed poziomem interfejsu API 30. Dodatkowo na urządzeniach, na których nie ma środowiska wykonawczego SDK, a pakiet SDK jest lokalny w stosunku do procesu wydawcy, tworzenie obiektu SurfacePackage na potrzeby reklamy jest nieefektywne, ponieważ widok można uzyskać bezpośrednio z pakietu SDK. Kanał boczny ukrywa tę złożoność przed kodem pakietu SDK i dewelopera aplikacji.
7. Umożliwia płynną integrację interfejsu reklam z funkcjami kompozycyjnymi. Deweloperzy Jetpack Compose, którzy nie pracują z widokami, mogą nadal hostować interfejs użytkownika wygenerowany przez dewelopera pakietu SDK, który nadal pracuje z widokami.

Biblioteki interfejsu

Biblioteki interfejsu użytkownika ukrywają złożoność opisaną powyżej i zapewniają kanał boczny, którego wydawca i pakiet SDK mogą używać do wyświetlania interfejsu użytkownika w różnych procesach oraz do aktualizowania go w miarę interakcji użytkownika z nim i z urządzeniem.

Dostępne są 3 biblioteki interfejsu: core, client i provider. Biblioteka podstawowa udostępnia interfejsy używane przez biblioteki klienta i dostawcy. Dostawca interfejsu (zwykle pakiet SDK) korzysta z biblioteki dostawcy, a użytkownik interfejsu (zwykle wydawca) korzysta z biblioteki klienta. Biblioteki klienta i dostawcy tworzą kanał boczny wymagany do tworzenia i utrzymywania sesji interfejsu.

Interfejsy API

Interfejsy API do prezentacji interfejsu SDK Runtime są następujące:

SandboxedUiAdapter: utworzony przez pakiet SDK, umożliwia uzyskiwanie treści do wyświetlania w interfejsie wydawcy.

SandboxedSdkView: utworzony przez wydawcę kontener, który zawiera treści uzyskane za pomocą SandboxedUiAdapter.

Session: utworzone przez pakiet SDK w odpowiedzi na SandboxedUiAdapter.openSession(). Reprezentuje jedną sesję interfejsu. wywołanie. Stanowi to koniec tunelu komunikacyjnego między pakietem SDK a wydawcą i odbiera powiadomienia o zmianach w SandboxedSdkView, takich jak odłączenie okna, zmiana jego rozmiaru czy zmiany konfiguracji.

SessionClient: utworzony przez bibliotekę klienta, stanowi koniec tunelu komunikacyjnego między pakietem SDK a wydawcą.

SandboxedSdkUiSessionStateChangedListener: utworzone przez wydawcę. Słuchacz zmian stanu sesji interfejsu powiązanej z SandboxedSdkView.

Więcej informacji o tych interfejsach API znajdziesz w dokumentacji referencyjnej privacysandbox-ui.

Kontrola przepływu

Poniższe diagramy przedstawiają interakcję między bibliotekami interfejsu klienta i dostawcy w różnych scenariuszach:

Poprzedni diagram pokazuje, jak wydawca może utworzyć SandboxedSdkView programowo lub za pomocą pliku XML i dołączyć go do SdkSandboxUiAdapter uzyskanego z pakietu SDK za pomocą zdefiniowanego w nim interfejsu API. Aby obserwować wszystkie zmiany stanu interfejsu, wydawca powinien dodać SandboxedSdkUiSessionStateChangedListener do SandboxedSdkView przed dołączeniem SdkSandboxUiAdapter.

Ten diagram pokazuje, że jeśli aktywność wydawcy obsługuje zmiany konfiguracji, biblioteka klienta przekazuje zmianę konfiguracji do pakietu SDK, aby mógł on odpowiednio zaktualizować interfejs. Ten proces może na przykład zostać uruchomiony, gdy użytkownik obróci urządzenie, a wydawca zadeklaruje obsługę zmian konfiguracji w swojej aktywności, ustawiając android:configChanges=["orientation"].

Ten diagram ilustruje, jak pakiet SDK może zażądać zmiany w kontenerze reklamy za pomocą metod w SessionClient. Ten interfejs API jest wywoływany, gdy pakiet SDK chce zmienić rozmiar reklamy i potrzebuje, aby wydawca zmienił rozmiar kontenera reklamy, aby dostosować go do nowych wymiarów. Może to nastąpić w reakcji na interakcję użytkownika, np.mraid.resize().

Ten diagram pokazuje, jak sesja jest zamykana po odłączeniu SandboxedSdkView od okna. Sesję można też zamknąć w dowolnym momencie (np. gdy użytkownik utraci połączenie z siecią) za pomocą pakietu SDK, wywołując funkcję SessionClient.onSessionError().

Kolejność nakładania

Biblioteka interfejsu klienta używa wewnętrznie elementu SurfaceView do hostowania interfejsu pakietu SDK. SurfaceView może używać kolejności Z, aby wyświetlać interfejs użytkownika nad oknem wydawcy lub pod nim. Jest to kontrolowane przez metodę SandboxedSdkView.orderProviderUiAboveClientUi(), która przyjmuje wartość logiczną setOnTop.

Gdy wartość setOnTop to true, każdy parametr android.view.MotionEvent w SandboxedSdkView jest wysyłany do pakietu SDK. Gdy false, są one wysyłane do wydawcy. Domyślnie zdarzenia związane z ruchem są wysyłane do pakietu SDK.

Wydawcy zwykle nie muszą zmieniać domyślnej kolejności wyświetlania reklam. Jeśli jednak wyświetlasz interfejs, który zasłania reklamę, np. menu, kolejność Z powinna zostać tymczasowo odwrócona, a następnie przywrócona, gdy element interfejsu zostanie zamknięty. Szukamy sposobów na zautomatyzowanie tego procesu w bibliotece interfejsu klienta.

Przewijanie

Gdy interfejs reklamy jest ułożony w kolejności Z powyżej okna wydawcy, do pakietu SDK wysyłane są MotionEvents z interfejsu reklamy. Gesty przewijania i szybkiego przesuwania inicjowane w interfejsie reklamy są traktowane w specjalny sposób:

1. Przewijanie w pionie i gesty szybkiego przesunięcia są wysyłane do kontenera wydawcy i przez niego obsługiwane. Zapewnia to dobrą jakość obsługi, gdy kontener wydawcy, w którym umieszczony jest interfejs reklamy, można przewijać w pionie. Nie wymaga to żadnych dodatkowych działań ze strony pakietu SDK ani wydawcy.
2. Przewijanie poziome i gesty szybkiego przesunięcia są wysyłane do pakietu SDK i przez niego obsługiwane. Zapewnia to dobrą wygodę użytkownika, gdy interfejs reklamy można przewijać w poziomie (np. karuzela reklam).

Przewodnik po implementacji

Pakiet SDK powinien implementować te funkcje:

• SandboxedUiAdapter: jest zwracany wydawcy w odpowiedzi na interfejs API zdefiniowany przez pakiet SDK, np. loadAd. Metoda openSession() tej implementacji powinna być używana do wysyłania żądania reklamy do serwerów pakietu SDK i przygotowywania widoku reklamy na potrzeby tego żądania.
• Session**: Jest to zwracane w odpowiedzi na wywołanie SandboxedUiAdapter.openSession. Umożliwia bibliotece klienta uzyskanie interfejsu reklamy i powiadamianie pakietu SDK o zmianach w tym interfejsie API. W tym miejscu należy wdrożyć wszystkie metody Session.

Wydawca powinien wykonać te czynności:

1. Utwórz SandboxedSdkView za pomocą kodu XML lub programowo.
2. Dołącz SandboxedSdkUiSessionStateChangedListener do SandboxedSdkView, aby zobaczyć zmiany w interfejsie.
3. Przymocuj dostarczony pakiet SDK SandboxedUiAdapter do SandboxedSdkView.
4. Dodaj SandboxedSdkView do okna jak zwykle i pozwól bibliotece klienta utworzyć i utrzymywać sesję interfejsu z pakietem SDK.
5. W odpowiednich momentach reaguj na zmiany stanu zgłaszane przez SandboxedSdkUiSessionChangedListener. Jeśli np. pakiet SDK nieoczekiwanie zamknie sesję, wydawca może zastąpić SandboxedSdkView obrazem statycznym lub usunąć go z hierarchii widoków.
6. Podczas dokonywania przejść, które mogą zasłaniać interfejs reklamy, np. menu rozwijanego, tymczasowo ustaw wartość orderProviderUiAboveClientUi na false, aby umieścić interfejs reklamy poniżej okna wydawcy. Po zamknięciu menu zadzwoń orderProviderUiAboveClientUi na numer true.

Przyszłość interfejsów API platformy

Gdy biblioteki interfejsu wejdą w fazę beta, planujemy wycofać interfejsy API platformy środowiska wykonawczego SDK związane z wyświetlaniem interfejsu, czyli SdkSandboxManager.requestSurfacePackage() i SandbxedSdkProvider.getView().

Pytania otwarte

1. Czy istnieją bardziej typowe przypadki użycia interfejsu reklam, którymi biblioteki interfejsu powinny zarządzać automatycznie?
2. Których platform interfejsu używasz do wyświetlania interfejsu reklamy? Czy przewidujesz problemy z integracją bibliotek interfejsu z tymi platformami?
3. Czy interfejs reklamy z możliwością przewijania umieszczony w kontenerze wydawcy z możliwością przewijania jest dla Ciebie typowym przypadkiem użycia? W jakim kierunku można przewijać interfejs reklamy i kontener w tym przypadku? Jakie zachowanie użytkownika jest oczekiwane, gdy rozpocznie on przewijanie interfejsu reklamy?