Interfejsy API do prezentacji interfejsu środowiska wykonawczego SDK

bookmark_border Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Środowisko wykonawcze pakietu SDK umożliwia uruchamianie pakietów SDK do wyświetlania reklam w sandboksie, co uniemożliwia im dostęp do hierarchii widoków wydawcy. Aby wyświetlać reklamy, platforma udostępnia interfejs API SandboxedSdkProvider.getView pakietowi SDK, aby uzyskać widok reklamy, a potem pakuje go w postać SurfacePackage, aby przesłać go przez interfejs IPC (komunikacja między procesami) do aplikacji klienta. Ma to kilka wad, które opisujemy poniżej. Dokument ten przedstawia proponowaną bibliotekę Jetpack, która jest tworzona, aby rozwiązać te problemy.

uzasadnienie rozszerzenia interfejsów API platformy;

Interfejsy API framework zostały zaprojektowane z myślą o elastyczności i pozostawiają tworzenie kanału side-channel do prezentacji interfejsu użytkownika aplikacji i pakietu SDK. Ten kanał poboczny:

1. Umożliwia pakietowi SDK zarządzanie wieloma wyświetleniami reklamy w trakcie jej trwania i sprawdzanie, 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 umożliwia pakietowi SDK zwrócenie aplikacji obiektu odpowiadającego żądaniu reklamy (treści), który można powiązać 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 interfejsu kontenera reklamy. Jeśli wydawca zmieni układ kontenera reklamy, pakiet SDK nie będzie o tych zmianach wiedział, chyba że wydawca wywoła interfejs API, aby go o tym powiadomić.
5. Synchronizuje zmiany rozmiaru interfejsu reklamy i pojemnika reklamy bez widocznych dla użytkownika zakłóceń.
6. automatycznie zarządza zgodnością wsteczną. SurfacePackage jest niedostępna w wersjach starszych niż API 30. Ponadto na urządzeniach, na których nie ma środowiska wykonawczego pakietu SDK, a pakiet SDK jest lokalny dla procesu wydawcy, nie ma sensu tworzyć SurfacePackage dla reklamy, gdy widok można uzyskać bezpośrednio z pakietu SDK. Kanały poboczne ukrywają złożoność pakietu SDK i kodu dewelopera aplikacji.
7. Umożliwia płynną integrację interfejsu reklam z komponowanymi usługami. 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 interfejsu użytkownika abstrahują od złożoności opisanych 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 aktualizowania go w miarę interakcji użytkownika z interfejsem i urządzeniem.

Istnieją 3 biblioteki interfejsu użytkownika: podstawowa, klient i dostawca. 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. Biblioteki klienta i dostawcy razem tworzą kanał boczny wymagany do tworzenia i utrzymywania sesji interfejsu użytkownika.

Interfejsy API

Interfejsy API do wyświetlania interfejsu użytkownika w czasie działania pakietu 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: utworzony przez pakiet SDK w odpowiedzi na zdarzenie SandboxedUiAdapter.openSession(). Reprezentuje jedną sesję interfejsu użytkownika. Stanowi on koniec tunelu komunikacyjnego między pakietem SDK a wydawcą i odbiera powiadomienia o zmianach w SandboxedSdkView, takich jak odłączanie okien, zmiana rozmiaru lub konfiguracji.

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

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

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

Kontrola przepływu

Na diagramach poniżej pokazano interakcje między bibliotekami interfejsu użytkownika klienta a dostawcy w różnych scenariuszach:

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

Ten diagram pokazuje, jak w przypadku aktywności wydawcy, która obsługuje zmiany konfiguracji, biblioteka klienta przekazuje zmianę konfiguracji do pakietu SDK, aby umożliwić mu zaktualizowanie interfejsu użytkownika. Ten proces może zostać uruchomiony na przykład wtedy, gdy użytkownik obróci urządzenie, a wydawca zadeklaruje obsługę zmian konfiguracji w swojej aktywności, ustawiając wartość android:configChanges=["orientation"].

Ten diagram pokazuje, jak pakiet SDK może poprosić o zmianę w kontenerze reklamy za pomocą metod 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 działanie użytkownika, takie jak mraid.resize().

Ten diagram pokazuje, jak sesja jest zamykana, gdy SandboxedSdkView jest odłączony od okna. Sesja może zostać zamknięta w dowolnym momencie (np. gdy użytkownik utraci łączność z internetem) przez Pakiet SDK wywołując funkcję SessionClient.onSessionError().

Kolejność Z

Biblioteka interfejsu użytkownika klienta używa wewnętrznie interfejsu SurfaceView do hostowania interfejsu użytkownika 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 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ślnego porządku wyświetleń reklam. Jednak podczas wyświetlania interfejsu, który zakrywa reklamę, np. menu, kolejność Z powinna zostać tymczasowo odwrócona względem domyślnej, a potem przywrócona, gdy element interfejsu zakrywający reklamę zostanie zamknięty. Sprawdzamy, jak zautomatyzować ten proces w bibliotece interfejsu użytkownika klienta.

Przewijanie

Gdy interfejs reklamy jest uporządkowany według kolejności Z-powyżej okna wydawcy, do pakietu SDK są wysyłane wartości MotionEvents z interfejsu reklamy. 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 wydawcy i obsługiwane przez niego. 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 dodatkowej pracy ze strony pakietu SDK ani wydawcy.
2. Gesty przewijania poziomego i przesuwania są wysyłane do pakietu SDK i przez niego obsługiwane. Zapewnia to wygodę użytkowania, gdy interfejs reklamy można przewijać poziomo (np. w przypadku karuzeli reklam).

Przewodnik po implementacji

Pakiet SDK powinien zawierać:

• SandboxedUiAdapter: wartość zwracana wydawcy w odpowiedzi na wywołanie interfejsu API zdefiniowanego w pakiecie SDK, np. 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 użytkownika reklamy i powiadamia pakiet SDK o zmianach w tym interfejsie API. Tutaj należy zastosować wszystkie metody Session.

Wydawca powinien:

1. Utwórz SandboxedSdkView za pomocą kodu XML lub programowo.
2. Dodaj SandboxedSdkUiSessionStateChangedListener do SandboxedSdkView, aby obserwować zmiany w interfejsie.
3. Załącz pakiet SDK SandboxedUiAdapter do SandboxedSdkView.
4. Dodaj SandboxedSdkView do okna jak zwykle i pozwól bibliotece klienta zająć się tworzeniem i utrzymywaniem sesji interfejsu użytkownika za pomocą pakietu SDK.
5. W odpowiednim czasie reagować na zmiany stanu zgłoszone 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 reklamy umieszczony w przewijanym kontenerze wydawcy jest częstym przypadkiem użycia? Jaki jest kierunek przewijania w przypadku interfejsu reklamy i kontenera? Jakiego zachowania oczekujesz, gdy użytkownik przewija interfejs reklamy?