Interfejsy API do prezentacji interfejsu środowiska wykonawczego SDK

Ś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:

1. 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.
2. 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.
3. Obejmuje podstawowe konstrukcje platformy używane do wyświetlania UI w różnych procesach. (Platforma używa obecnie SurfaceControlViewhost i generuje z niego SurfacePackage).
4. 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ć.
5. Synchronizuje zmiany rozmiaru interfejsu reklamy i kontenera reklamy bez zakłóceń widocznych dla użytkowników.
6. 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ć elementu SurfacePackage 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.
7. 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.

Relacje między interfejsami API do prezentacji interfejsu środowiska wykonawczego SDK.

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.

Uzyskaj interfejs użytkownika z pakietu SDK.

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"].

Zmiana interfejsu zainicjowana przez wydawcę.

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().

Zmiana interfejsu inicjowana przez pakiet SDK.

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().

Zamykam sesję interfejsu.

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:

1. 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.
2. 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 jak loadAd. Metoda openSession() 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łanie SandboxedUiAdapter.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 metody Session.

Wydawca powinien wykonać te czynności:

1. Utwórz SandboxedSdkView za pomocą pliku XML lub automatycznie.
2. Dołącz SandboxedSdkUiSessionStateChangedListener do elementu SandboxedSdkView, aby obserwować zmiany w interfejsie.
3. Dołącz pakiet SDK dostarczony przez SandboxedUiAdapter do SandboxedSdkView.
4. Dodaj SandboxedSdkView do okna w zwykły sposób, a biblioteka klienta zajmie się utworzeniem i obsługą sesji UI za pomocą pakietu SDK.
5. 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ć obiekt SandboxedSdkView obrazem statycznym lub usunąć go ze swojej hierarchii widoków.
6. 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łaj orderProviderUiAboveClientUi pod numerem true.

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

1. Czy są jakieś typowe przypadki użycia interfejsu reklam, które biblioteki interfejsu powinny obsługiwać automatycznie?
2. Z jakich platform interfejsu korzystacie do wyświetlania interfejsu reklam. Czy spodziewacie się problemów z integracją bibliotek interfejsu z tymi platformami?
3. 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?