Interfejsy API do prezentacji interfejsu środowiska wykonawczego SDK

Środowisko wykonawcze SDK umożliwia uruchamianie pakietów SDK do wyświetlania reklam w sandboksie, co uniemożliwia im dostęp do hierarchii widoków wydawcy. Do wyświetlania reklam platforma udostępnia interfejs API SandboxedSdkProvider.getView pakietowi SDK, aby umożliwić uzyskanie reklamy i pakuje go jako element SurfacePackage, który zostanie przesłany w IPC (komunikację między procesami) do aplikacji klienckiej. Ma to kilka wad, które opisujemy poniżej. Dokument ten przedstawia wówczas proponowaną Biblioteka Jetpack, którą stworzyliśmy z myślą o tych wyzwaniach.

Uzasadnienie rozszerzania interfejsów API platformy

Interfejsy API platformy zostały zaprojektowane z myślą o elastyczności i nie muszą tworzyć między prezentacją UI a aplikacją i pakietem SDK. Ta strona kanały wykonuje te działania:

  1. Umożliwia pakietowi SDK zarządzanie wyświetleniami reklamy w trakcie jej trwania i określanie, co dzieje się z interfejsem reklamy po jej utworzeniu przez pakiet SDK.
  2. Odłącza tworzenie widoku od wiązania treści. Korzystanie z kanału dodatkowego pozwala pakietowi SDK zwrócić aplikacji obiekt odpowiadający żądaniu reklamy (treści), który może zostać powiązany z kontenerem reklamy, gdy aplikacja uzna to za stosowne.
  3. Abstrahuje podstawowe konstrukcje platformy używane do wyświetlania interfejsu w różnych procesach. (Platforma obecnie używa SurfaceControlViewhost i na jego podstawie generuje SurfacePackage).
  4. Umożliwia pakietom SDK do wyświetlania reklam w czasie działania pakietu SDK automatyczne otrzymywanie powiadomień o zmianach w interfejsie kontenera reklamy. Jeśli wydawca zmieni układ kontenera reklamy, pakiet SDK pozostaje nieświadomy tych zmian, chyba że tag wydawca jednoznacznie wywołuje interfejs API, aby go powiadomić.
  5. Synchronizuje zmiany rozmiaru interfejsu reklamy i pojemnika reklamy bez widocznych dla użytkownika zakłóceń.
  6. automatycznie zarządza zgodnością wsteczną. Interfejs SurfacePackage jest niedostępny w przypadku poziomu interfejsu API niższego niż 30. Ponadto na urządzeniach, na których nie ma środowiska wykonawczego pakietu SDK, a pakiet SDK jest lokalny dla procesu wydawcy, tworzenie SurfacePackage dla reklamy jest nieefektywne, ponieważ wyświetlenie można uzyskać bezpośrednio z pakietu SDK. Kanał boczny pozwala oddzielić tę złożoność od pakietu SDK i aplikacji w kodzie programisty.
  7. Umożliwia płynną integrację interfejsu reklamy z komponowanymi komponentami. Deweloperzy Jetpack Compose, którzy nie korzystają z widoków, mogą nadal hostować interfejs użytkownika wygenerowany przez dewelopera pakietu SDK, który nadal korzysta z widoków.

Biblioteki interfejsu

Biblioteki UI pozwalają odejść od złożoności opisanych powyżej i zapewniają kanału bocznego, za pomocą którego wydawca i pakiet SDK mogą pokazać interfejs użytkownika w różnych procesach. aktualizowany w miarę interakcji użytkownika z urządzeniem oraz 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 użytkownika (zwykle pakiet SDK) zależy od biblioteki dostawcy, a użytkownik interfejsu użytkownika (zwykle wydawca) zależy od biblioteki klienta. Klient i biblioteki dostawców stanowią kanał boczny wymagany do tworzenia utrzymywania sesji interfejsu użytkownika.

Interfejsy API

Prezentacja interfejsów API środowiska wykonawczego SDK:

SandboxedUiAdapter: utworzony przez pakiet SDK sposób uzyskiwania treści do wyświetlania w interfejsie wydawcy.

SandboxedSdkView: utworzony przez wydawcę kontener zawierający treści uzyskane za pomocą SandboxedUiAdapter.

Session: utworzone przez pakiet SDK w odpowiedzi na SandboxedUiAdapter.openSession() Reprezentuje jedną sesję interfejsu użytkownika. . W ten sposób koniec tunelu komunikacyjnego między pakietem SDK a wydawcą; otrzymuje powiadomienia o zmianach w SandboxedSdkView, takich jak okno odłączenia, zmiany rozmiaru lub zmiany konfiguracji.

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

SandboxedSdkUiSessionStateChangedListener: utworzone przez wydawcę. Listener dla zmian stanu sesji interfejsu użytkownika powiązanej z SandboxedSdkView.

Ilustracja pokazująca relacje interfejsów API w interfejsie użytkownika w czasie działania pakietu SDK.
Relacje między interfejsami API prezentacji interfejsu środowiska wykonawczego SDK.

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

Sterowanie przepływem

Poniższe diagramy przedstawiają interakcję między interfejsem klienta i dostawcy i biblioteki w różnych sytuacjach:

Poprzedni diagram pokazuje, jak wydawca może utworzyć SandboxedSdkView automatycznie lub za pomocą kodu XML, i dołączaj go do pliku SdkSandboxUiAdapter. uzyskanych z pakietu SDK za pomocą interfejsu API zdefiniowanego przez SDK. Aby obserwować wszystkie zmiany stanu interfejsu użytkownika, wydawca powinien dodać SandboxedSdkUiSessionStateChangedListener do SandboxedSdkView przed dołączeniem SdkSandboxUiAdapter.

Grafika przedstawiająca proces sesji otwartej.
Pobierz interfejs z pakietu SDK.

Ten diagram pokazuje, jak aktywność wydawcy obsługuje zmiany konfiguracji biblioteka klienta przekazuje zmianę konfiguracji do SDK, aby mogli odpowiednio zaktualizować interfejs. Na przykład: gdy użytkownik obraca urządzenie, a wydawca deklaruje obsługę. przez zmiany konfiguracji – przez ustawienie android:configChanges=["orientation"]

Zmiana interfejsu inicjowana przez wydawcę.

Schemat pokazujący, jak pakiet SDK może zażądać zmiany w kontenerze reklamy za pomocą SessionClient. Ten interfejs API jest uruchamiany, gdy pakiet SDK chce zmienić rozmiar reklamy, a wydawca musi zmienić rozmiar kontenera reklamy, aby dopasować go do nowych wymiarów. Może się to zdarzyć w odpowiedzi na interakcje użytkownika, na przykład mraid.resize()

Zmiany w interfejsie wywołane przez pakiet SDK.

Ten diagram pokazuje, jak sesja jest zamykana po odłączeniu interfejsu SandboxedSdkView bezpośrednio w oknie. Sesję można też zamknąć w dowolnym momencie (np. gdy użytkownik utraci połączenie z internetem) za pomocą wywołania pakietu SDK:SessionClient.onSessionError().

Zamykanie sesji interfejsu użytkownika.

Kolejność Z

Biblioteka UI klienta używa wewnętrznie interfejsu SurfaceView do hostowania interfejsu użytkownika pakietu SDK. SurfaceView może użyć kolejności Z, by wyświetlić swój interfejs na górze strony wydawcy lub poniżej niego. Jest to kontrolowane przez metodę SandboxedSdkView.orderProviderUiAboveClientUi(), która przyjmuje wartość logiczną setOnTop.

Gdy setOnTop = true, wszystkie android.view.MotionEvent w grupie SandboxedSdkView są wysyłane do pakietu SDK. Gdy false, są one wysyłane do wydawcy. Domyślnie zdarzenia związane z ruchu są wysyłane do pakietu SDK.

Wydawcy zwykle nie muszą zmieniać domyślnej kolejności wyświetleń reklam w kolejności Z. Jeśli jednak wyświetlasz UI zasłaniający reklamę, np. menu, w tagu Kolejność nakładania elementów powinna być tymczasowo odwrócona od wartości domyślnej i przywrócona, gdy element interfejsu zostanie zamknięty. Sprawdzamy, jak zautomatyzować ten proces w bibliotece interfejsu klienta.

Przewijanie

Jeśli interfejs reklamy jest w porządku Z nad oknem wydawcy, MotionEvents z poziomu są wysyłane do pakietu SDK. Gesty przewijania i przesuwania inicjowane w interfejsie reklamy są traktowane w szczególny sposób:

  1. Gesty przewijania w pionie i przesuwania są wysyłane do kontenera. Zapewnia to dobre wrażenia użytkownika, gdy kontener wydawcy, w którym znajduje się interfejs reklamy, można przewijać w poziomie. Nie wymaga to żadnych dodatkowych czynności pakiet SDK lub wydawca.
  2. Gesty przewijania poziomego i przesuwania są wysyłane do pakietu SDK i obsługiwane przez niego. Ten zapewnia wygodę korzystania, gdy interfejs reklamy można przewijać w poziomie (np. karuzela reklam).

Przewodnik po implementacji

Pakiet SDK powinien zawierać:

  • SandboxedUiAdapter: ta wartość jest zwracana wydawcy w odpowiedzi na żądanie Interfejs API zdefiniowany przez pakiet SDK, taki jak loadAd. Metoda openSession() tej implementacji powinna służyć do wysyłania żądania reklamy do serwerów pakietu SDK i przygotowywania widoku reklamy dla tego żądania.
  • Session**: zwracany w odpowiedzi na SandboxedUiAdapter.openSession. Umożliwia ona bibliotece klienta uzyskanie interfejsu reklamy i powiadamia pakiet SDK o zmianach w tym interfejsie API. Tutaj należy zastosować wszystkie metody Session.

Wydawca powinien wykonać te czynności:

  1. Utwórz SandboxedSdkView za pomocą kodu XML lub automatycznie.
  2. Podłącz SandboxedSdkUiSessionStateChangedListener do SandboxedSdkView, aby obserwować zmiany w interfejsie.
  3. Dołącz dostarczony SandboxedUiAdapter pakiet SDK do projektu SandboxedSdkView.
  4. Dodaj do okna plik SandboxedSdkView w zwykły sposób i pozwól bibliotece klienta zajmuje się tworzeniem i utrzymywaniem sesji interfejsu za pomocą pakietu SDK.
  5. W odpowiednich momentach reaguj na zmiany stanu zgłaszane przez SandboxedSdkUiSessionChangedListener Jeśli na przykład pakiet SDK zamknie sesję nieoczekiwanie, wydawca może zastąpić element SandboxedSdkView obrazem statycznym lub usunąć go z hierarchii widoku.
  6. Podczas wykonywania przejść, które mogą zasłaniać interfejs reklamy, takich jak menu, tymczasowo ustaw wartość orderProviderUiAboveClientUi na false, aby umieścić interfejs reklamy poniżej okna wydawcy. Gdy zamkniesz menu, wywołaj funkcję orderProviderUiAboveClientUi do true.

Przyszłość interfejsów API platformy

Gdy biblioteki interfejsu przejdą do wersji beta, planujemy wycofać interfejsy API środowiska wykonawczego platformy SDK związane z prezentacją interfejsu użytkownika, a mianowicie SdkSandboxManager.requestSurfacePackage() i SandbxedSdkProvider.getView().

Pytania otwarte

  1. Czy istnieje więcej typowych przypadków użycia interfejsu reklamy, które biblioteki UI powinny obsługiwać automatycznie?
  2. Których frameworków interfejsu użytkownika używasz do wyświetlania interfejsu reklamy? Czy przewidujesz problemy z integracją bibliotek interfejsu z tymi frameworkami?
  3. Czy przewijany interfejs reklam umieszczony w kontenerze wydawcy z możliwością przewijania jest powszechnym zastosowaniem dla Pana/Pani firmy? Jaki jest kierunek przewijania w interfejsie użytkownika reklamy i kontener w tym przypadku? Jakiego działania oczekujesz, gdy użytkownik przewija interfejs reklamy?