Interfejsy API do prezentacji interfejsu środowiska wykonawczego SDK

Prześlij opinię

Środowisko wykonawcze SDK umożliwia uruchamianie pakietów SDK do wyświetlania reklam w środowisku piaskownicy, co uniemożliwia ich działanie dostępu 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. Jest ich kilka wady, 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. Pozwala pakietowi SDK zarządzać wieloma wyświetleniami reklam od początku ich śledzenia i rozumie, co dzieje się z interfejsem reklamy po utworzeniu go przez SDK.
  2. Rozdziela tworzenie widoku i wiązania treści. Użycie kanału bocznego pozwala pakiet SDK zwraca obiekt odpowiadający żądaniu reklamy wysłanemu do aplikacji. (treść), która może być powiązana z kontenerem reklamy według uznania aplikacji. odpowiednie.
  3. Przedstawia podstawowe konstrukcje platformy używane do przedstawiania UI (Platforma korzysta obecnie z interfejsów SurfaceControlViewhost oraz który generuje na jego podstawie element SurfacePackage).
  4. Włącza automatyczne otrzymywanie powiadomień przez pakiety SDK do wyświetlania reklam w środowisku wykonawczym SDK gdy zmieni się interfejs 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 kontenera reklamy bez Widoczny dla użytkownika zakłócenie.
  6. Automatycznie zarządza zgodnością wsteczną. SurfacePackage to nie dostępne przed poziomem API 30. a także na urządzeniach, na których nie ma pakietu SDK. a pakiet SDK obsługuje lokalny proces wydawcy, nie marnuje czasu utwórz SurfacePackage dla reklamy, jeśli obejrzenie 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 reklam z elementami kompozycyjnymi. Jetpack Compose programiści, którzy nie obsługują widoków danych, również mogą hostować przez dewelopera pakietu SDK, który nadal obsługuje widoki.

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 SDK) zależy od biblioteki dostawcy i konsumenta 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: utworzone przez pakiet SDK, które umożliwia pozyskiwanie treści. w interfejsie wydawcy.

SandboxedSdkView – utworzony przez wydawcę kontener, w którym znajdują się: treści uzyskane za pomocą SandboxedUiAdapter.

Session: utworzone przez pakiet SDK w odpowiedzi na SandboxedUiAdapter.openSession() Reprezentuje 1 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: tworzony przez bibliotekę klienta, po stronie wydawcy. tunelu komunikacyjnego między pakietem SDK a wydawcą.

SandboxedSdkUiSessionStateChangedListener: utworzone przez wydawcę. O detektor zmian stanu sesji UI powiązanej z SandboxedSdkView

Ilustracja przedstawiająca relacje interfejsu API prezentacji interfejsu SDK środowiska wykonawczego.
Relacje między interfejsami API prezentacji interfejsu środowiska wykonawczego SDK.

Więcej informacji znajdziesz w dokumentacji referencyjnej interfejsu privacysandbox-ui. dla tych interfejsów API.

Sterowanie przepływem pracy

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. Obserwowanie wszystkich stanów UI zmian, wydawca powinien dodać atrybut SandboxedSdkUiSessionStateChangedListener do SandboxedSdkView przed załączeniem elementu 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 wyzwalany, gdy pakiet SDK chce zmienić rozmiar musi zmienić rozmiar kontenera reklamy, aby zmieścił się w reklamie wymiarów. Może się to zdarzyć w odpowiedzi na interakcje użytkownika, na przykład mraid.resize()

Zmiana interfejsu inicjowana 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 traci połączenie sieciowe) przez pakiet SDK przez wywołanie SessionClient.onSessionError()

Zamknij sesję 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. Zależy to od SandboxedSdkView.orderProviderUiAboveClientUi(), która akceptuje wartość logiczna setOnTop.

Gdy setOnTop jest true, co android.view.MotionEvent dnia Do pakietu SDK jest wysyłana wartość 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 w kolejności Z. Jeśli jednak wyświetlasz UI zasłaniający reklamę, np. menu, w tagu Kolejność nakładania elementów powinna zostać tymczasowo odwrócona od domyślnej i przywrócona, gdy element interfejsu zostanie zamknięty. Sprawdzamy, jak można to zautomatyzować 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 wykonywane w interfejsie reklamy pojawiają się specjalne traktowanie:

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

Przewodnik po implementacji

Pakiet SDK powinien implementować te elementy:

  • SandboxedUiAdapter: ta wartość jest zwracana wydawcy w odpowiedzi na żądanie Interfejs API zdefiniowany przez pakiet SDK, taki jak loadAd. Metoda openSession() tego powinna być używana do wysyłania żądania reklamy do serwerów SDK przygotować wyświetlenie reklamy dla tego żądania.
  • Session**: ten element jest zwracany w odpowiedzi na żądanie SandboxedUiAdapter.openSession połączenie. Zapewnia to klientowi aby uzyskać interfejs użytkownika reklamy i powiadomić SDK o zmianach. Wszystkie Tutaj należy wdrożyć Session metod.

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 Na przykład: jeśli pakiet SDK zamknie , wydawca może zastąpić funkcję SandboxedSdkView funkcją statyczny obraz lub usunąć go z hierarchii widoków.
  6. Podczas przejścia, które może obejmować interfejs reklamy, np. przy użyciu menu, tymczasowo orderProviderUiAboveClientUi na fałsz, by określić położenie interfejsu reklamy poniżej okna wydawcy. Po zamknięciu menu wywołaj orderProviderUiAboveClientUi do true.

Przyszłość interfejsów API platformy

Po przejściu bibliotek interfejsu w wersji beta planujemy wycofać środowisko wykonawcze SDK interfejsy API platformy związane z prezentacją UI, SdkSandboxManager.requestSurfacePackage() i SandbxedSdkProvider.getView().

Pytania otwarte

  1. Czy istnieją inne typowe przypadki użycia interfejsu reklamy, które biblioteki UI powinny automatycznie obsługiwać?
  2. Jakich platform interfejsu używasz do wyświetlania reklam? Czy przewidujesz problemy integrowanie bibliotek UI z tymi platformami?
  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 po zainicjowaniu przez użytkownika przewinąć w interfejsie reklamy?