Tworzenie aplikacji do multimediów do aut

Android Auto i Android Automotive OS pomagają dostarczać treści z aplikacji multimedialnych użytkownikom w samochodzie. Aplikacja multimedialna do samochodów musi udostępniać usługę przeglądarki multimedialnej, aby Android Auto i system operacyjny Android Automotive lub inna aplikacja z przeglądarką multimedialną mogły wykrywać i wyświetlać Twoje treści.

W tym przewodniku zakładamy, że masz już aplikację do multimediów, która odtwarza dźwięk na telefonie, i jest ona zgodna z architekturą aplikacji do multimediów na Androida.

W tym przewodniku opisaliśmy wymagane komponenty MediaBrowserService i MediaSession, których aplikacja potrzebuje do działania w Android Auto lub systemie operacyjnym Android Automotive. Po zakończeniu konfigurowania podstawowej infrastruktury multimediów możesz dodać obsługę Androida Auto i dodać obsługę systemu operacyjnego Android Automotive do swojej aplikacji multimedialnej.

.

Zanim zaczniesz

  1. Zapoznaj się z dokumentacją interfejsu API do multimediów na Androida.
  2. Wskazówki dotyczące projektowania znajdziesz w artykule Tworzenie aplikacji do multimediów.
  3. Zapoznaj się z kluczowymi terminami i koncepcjami wymienionymi w tej sekcji.

Najważniejsze terminy i koncepcje

Usługa przeglądarki multimediów
Usługa na Androida zaimplementowana przez aplikację do multimediów, zgodną z interfejsem API MediaBrowserServiceCompat. Twoja aplikacja korzysta z tej usługi, aby udostępniać treści.
Przeglądarka multimediów
Interfejs API używany przez aplikacje do multimediów do wykrywania usług przeglądarki multimediów i wyświetlania ich treści. Android Auto i Android Automotive OS używają przeglądarki multimediów do znajdowania usługi przeglądarki multimediów aplikacji.
Element multimedialny

Przeglądarka multimediów porządkuje treści w drzewie obiektów MediaItem. Element multimediów może mieć jedną lub obie z tych flag:

  • FLAG_PLAYABLE: oznacza, że element jest elementem końcowym w drzewie treści. Element reprezentuje pojedynczy strumień dźwięku, np. utwór z albumu, rozdział w audiobooku lub odcinek podcastu.
  • FLAG_BROWSABLE: wskazuje, że element jest węzłem w drzewie treści i ma elementy podrzędne. Na przykład element reprezentuje album, a jego elementy podrzędne to utwory na albumie.

Element multimedialny, który można przeglądać i odtwarzać, działa jak playlista. Możesz wybrać sam element, aby odtworzyć wszystkie jego elementy podrzędne, lub przejrzeć jego elementy podrzędne.

Zoptymalizowane pod kątem pojazdów

Aktywność w aplikacji na system operacyjny Android Automotive, która jest zgodna z wytycznymi dotyczącymi projektowania na ten system. Interfejs tych czynności nie jest generowany przez system operacyjny Android Automotive, dlatego musisz zadbać o to, aby Twoja aplikacja była zgodna ze wskazówkami dotyczącymi projektowania. Zazwyczaj obejmuje to większe docelowe elementy dotykowe i rozmiary czcionek, obsługę trybu dziennego i nocnego oraz wyższe współczynniki kontrastu.

Interfejsy zoptymalizowane pod kątem pojazdów mogą być wyświetlane tylko wtedy, gdy nie obowiązują ograniczenia dotyczące wygody korzystania z samochodu (CUXR), ponieważ te interfejsy mogą wymagać dodatkowej uwagi lub interakcji ze strony użytkownika. CUXR nie działa, gdy samochód jest zatrzymywany lub zaparkowany, ale zawsze obowiązuje, gdy samochód jest w ruchu.

Nie musisz projektować działań dla Androida Auto, ponieważ Android Auto tworzy własny interfejs zoptymalizowany pod kątem samochodu, korzystając z informacji z Twojej usługi przeglądarki multimedialnej.

Konfigurowanie plików manifestu aplikacji

Zanim utworzysz usługę przeglądarki multimediów, musisz skonfigurować pliki manifestu aplikacji.

Zdefiniuj usługę przeglądarki multimedialnej

Zarówno Android Auto, jak i system operacyjny Android Automotive łączą się z Twoją aplikacją za pomocą przeglądarki multimediów, aby przeglądać elementy multimedialne. W pliku manifestu zadeklaruj usługę przeglądarki multimediów, aby umożliwić systemom operacyjnym Android Auto i Android Automotive wykrywanie usługi i łączenie się z Twoją aplikacją.

Ten fragment kodu pokazuje, jak w pliku manifestu zadeklarować usługę przeglądarki multimediów. Uwzględnij ten kod w pliku manifestu modułu systemu operacyjnego Android Automotive i w pliku manifestu aplikacji na telefon.

<application>
    ...
    <service android:name=".MyMediaBrowserService"
             android:exported="true">
        <intent-filter>
            <action android:name="android.media.browse.MediaBrowserService"/>
        </intent-filter>
    </service>
    ...
</application>

Określanie ikon aplikacji

Musisz określić ikony aplikacji, których Android Auto i system operacyjny Android Automotive mogą używać do reprezentowania aplikacji w interfejsie systemu. Wymagane są 2 typy ikon:

  • Ikona programu uruchamiającego
  • Ikona atrybucji

Ikona programu uruchamiającego

Ikona programu uruchamiającego reprezentuje aplikację w interfejsie systemu, np. w menu z aplikacją i na panelu z ikonami. Możesz określić, że chcesz użyć ikony z aplikacji mobilnej, aby reprezentować aplikację multimedialną w samochodzie, za pomocą tej deklaracji w pliku manifestu:

<application
    ...
    android:icon="@mipmap/ic_launcher"
    ...
/>

Aby użyć innej ikony niż ikona aplikacji mobilnej, w pliku manifestu ustaw właściwość android:icon elementu <service> usługi przeglądarki multimediów:

<application>
    ...
    <service
        ...
        android:icon="@mipmap/auto_launcher"
        ...
    />
</application>

Ikona atrybucji

Rysunek 1. Ikona atrybucji na karcie multimediów.

Ikona informacji o autorze utworu jest używana w miejscach, w których treści multimedialne mają pierwszeństwo, np. na kartach. Rozważ ponowne użycie małej ikony używanej w powiadomieniach. Ta ikona musi być monochromatyczna. Ikona reprezentująca aplikację może być określona w deklaracji pliku manifestu w ten sposób:

<application>
    ...
    <meta-data
        android:name="androidx.car.app.TintableAttributionIcon"
        android:resource="@drawable/ic_status_icon" />
    ...
</application>

Tworzenie usługi przeglądarki multimediów

Usługę przeglądarki multimediów można utworzyć przez rozszerzenie klasy MediaBrowserServiceCompat. Zarówno Android Auto, jak i system operacyjny Android Automotive mogą używać Twojej usługi do tych celów:

  • Przejrzyj hierarchię treści aplikacji, aby wyświetlić menu użytkownikowi.
  • Aby sterować odtwarzaniem dźwięku, pobierz token obiektu MediaSessionCompat aplikacji.

Możesz też użyć usługi przeglądarki multimediów, aby umożliwić innym klientom dostęp do multimediów z Twojej aplikacji. Mogą to być inne aplikacje na telefonie użytkownika lub inne zdalne aplikacje.

Przepływ pracy w usłudze przeglądarki multimediów

W tej sekcji opisano, jak Android Automotive OS i Android Auto współpracują z Twoją usługą przeglądarki multimediów podczas typowej procedury użytkownika.

  1. Użytkownik uruchamia aplikację na systemie operacyjnym Android Automotive lub w aplikacji Android Auto.
  2. System operacyjny Android Automotive lub Android Auto łączy się z przeglądarką multimediów w Twojej aplikacji za pomocą metody onCreate(). W ramach implementacji metody onCreate() musisz utworzyć i zarejestrować obiekt MediaSessionCompat oraz jego obiekt wywołania zwrotnego.
  3. System operacyjny Android Automotive lub Android Auto wywołuje metodę onGetRoot() Twojej usługi, aby pobrać element multimedialny wyższego poziomu w hierarchii treści. Element multimedialny wyższego poziomu nie jest wyświetlany. Zamiast tego służy do pobierania dodatkowych treści z aplikacji.
  4. System operacyjny Android Automotive lub Android Auto wywołuje metodę onLoadChildren() usługi, aby pobrać elementy podrzędne głównego elementu multimedialnego. System operacyjny Android Automotive i Android Auto wyświetlają te elementy multimedialne jako najwyższy poziom elementów treści. Więcej informacji o tym, czego system oczekuje na tym poziomie, znajdziesz na stronie Struktura menu głównego.
  5. Jeśli użytkownik wybierze przeglądalny element multimedialny, metoda onLoadChildren() Twojej usługi zostanie wywołana ponownie, aby pobrać podrzędne wybranego elementu menu.
  6. Jeśli użytkownik wybierze odtwarzany element multimediów, system operacyjny Android Automotive lub Android Auto wywoła odpowiednią metodę wywołania sesji multimediów, aby wykonać to działanie.
  7. Jeśli aplikacja obsługuje tę funkcję, użytkownik może też wyszukiwać Twoje treści. W takim przypadku system operacyjny Android Automotive lub Android Auto wywołuje metodę onSearch() usługi.

Tworzenie hierarchii treści

Android Auto i system operacyjny Android Automotive wywołują usługę przeglądarki multimediów w aplikacji, aby dowiedzieć się, jakie treści są dostępne. Aby obsługiwać tę funkcję, musisz zaimplementować w swojej usłudze przeglądarki multimediów 2 metody: onGetRoot() i onLoadChildren().

Implementacja metody onGetRoot

Metoda onGetRoot() usługi zwraca informacje o węźle głównym hierarchii treści. Android Auto i Android Automotive OS używają tego węzła głównego do żądania pozostałych treści za pomocą metody onLoadChildren().

Ten fragment kodu pokazuje prostą implementację metody onGetRoot():

Kotlin

override fun onGetRoot(
    clientPackageName: String,
    clientUid: Int,
    rootHints: Bundle?
): BrowserRoot? =
    // Verify that the specified package is allowed to access your
    // content. You'll need to write your own logic to do this.
    if (!isValid(clientPackageName, clientUid)) {
        // If the request comes from an untrusted package, return null.
        // No further calls will be made to other media browsing methods.

        null
    } else MediaBrowserServiceCompat.BrowserRoot(MY_MEDIA_ROOT_ID, null)

Java

@Override
public BrowserRoot onGetRoot(String clientPackageName, int clientUid,
    Bundle rootHints) {

    // Verify that the specified package is allowed to access your
    // content. You'll need to write your own logic to do this.
    if (!isValid(clientPackageName, clientUid)) {
        // If the request comes from an untrusted package, return null.
        // No further calls will be made to other media browsing methods.

        return null;
    }

    return new MediaBrowserServiceCompat.BrowserRoot(MY_MEDIA_ROOT_ID, null);
}

Bardziej szczegółowy przykład tej metody znajdziesz w opisie metody onGetRoot() w przykładowej aplikacji Universal Android Music Player na GitHubie.

Dodaj weryfikację pakietu dla funkcji onGetRoot()

Po wywołaniu metody onGetRoot() usługi pakiet wywołujący przekazuje do usługi informacje identyfikacyjne. Usługa może użyć tych informacji, aby zdecydować, czy pakiet może uzyskać dostęp do Twoich treści. Możesz na przykład ograniczyć dostęp do treści aplikacji do listy zatwierdzonych pakietów, porównując clientPackageName z listą dozwolonych i sprawdzając certyfikat użyty do podpisania pliku APK pakietu. Jeśli nie można zweryfikować pakietu, wróć do null, aby odmówić dostępu do treści.

Aby zapewnić aplikacjom systemowym, takim jak Android Auto i Android Automotive, dostęp do treści, usługa musi zawsze zwracać wartość niezerową BrowserRoot, gdy te aplikacje systemowe wywołują metodę onGetRoot(). Sygnatura aplikacji systemowej Android Automotive może się różnić w zależności od marki i modelu samochodu, dlatego musisz zezwolić na połączenia ze wszystkich aplikacji systemowych, aby zapewnić pełną obsługę systemu operacyjnego Android Automotive.

Ten fragment kodu pokazuje, jak usługa może sprawdzić, czy wywoływany pakiet jest aplikacją systemową:

fun isKnownCaller(
    callingPackage: String,
    callingUid: Int
): Boolean {
    ...
    val isCallerKnown = when {
       // If the system is making the call, allow it.
       callingUid == Process.SYSTEM_UID -> true
       // If the app was signed by the same certificate as the platform
       // itself, also allow it.
       callerSignature == platformSignature -> true
       // ... more cases
    }
    return isCallerKnown
}

Ten fragment kodu to fragment klasy PackageValidator z przykładowej aplikacji Universal Android Music Player na GitHub. Więcej informacji o implementowaniu weryfikacji pakietu za pomocą metody onGetRoot() Twojej usługi znajdziesz w tej klasie.

Oprócz zezwolenia na dostęp do aplikacji systemowych musisz też zezwolić Asystentowi Google na połączenie z urządzeniem MediaBrowserService. Pamiętaj, że Asystent Google ma osobne nazwy pakietów na potrzeby telefonu (w tym Androida Auto) i Androida Automotive.

Implementacja funkcji onLoadChildren()

Po otrzymaniu obiektu wierzchołka systemu Android Auto i Android Automotive OS tworzą menu najwyższego poziomu, wywołując funkcję onLoadChildren() obiektu wierzchołka, aby uzyskać jego elementy podrzędne. Aplikacje klienckie tworzą podmenu, wywołując tę samą metodę za pomocą obiektów węzłów podrzędnych.

Każdy węzeł w hierarchii treści jest reprezentowany przez obiekt MediaBrowserCompat.MediaItem. Każdy z tych elementów multimedialnych jest identyfikowany za pomocą unikalnego ciągu znaków identyfikatora. Aplikacje klienta traktują te ciągi identyfikatorów jako nieprzezroczyste tokeny. Gdy aplikacja klienta chce przejść do podmenu lub odtworzyć element multimedialny, przekazuje token. Twoja aplikacja jest odpowiedzialna za powiązanie tokena z odpowiednim elementem multimedialnym.

Ten fragment kodu pokazuje prostą implementację metody onLoadChildren():

Kotlin

override fun onLoadChildren(
    parentMediaId: String,
    result: Result<List<MediaBrowserCompat.MediaItem>>
) {
    // Assume for example that the music catalog is already loaded/cached.

    val mediaItems: MutableList<MediaBrowserCompat.MediaItem> = mutableListOf()

    // Check whether this is the root menu:
    if (MY_MEDIA_ROOT_ID == parentMediaId) {

        // Build the MediaItem objects for the top level
        // and put them in the mediaItems list.
    } else {

        // Examine the passed parentMediaId to see which submenu we're at
        // and put the children of that menu in the mediaItems list.
    }
    result.sendResult(mediaItems)
}

Java

@Override
public void onLoadChildren(final String parentMediaId,
    final Result<List<MediaBrowserCompat.MediaItem>> result) {

    // Assume for example that the music catalog is already loaded/cached.

    List<MediaBrowserCompat.MediaItem> mediaItems = new ArrayList<>();

    // Check whether this is the root menu:
    if (MY_MEDIA_ROOT_ID.equals(parentMediaId)) {

        // Build the MediaItem objects for the top level
        // and put them in the mediaItems list.
    } else {

        // Examine the passed parentMediaId to see which submenu we're at
        // and put the children of that menu in the mediaItems list.
    }
    result.sendResult(mediaItems);
}

Pełny przykład tej metody znajdziesz w metodzie onLoadChildren() w przykładowej aplikacji Universal Android Music Player na GitHub.

Struktura menu głównego

Rysunek 2. Treści główne wyświetlane jako karty nawigacyjne.

Android Auto i system operacyjny Android Automotive mają określone ograniczenia dotyczące struktury menu głównego. Są one przekazywane do usługi MediaBrowserService za pomocą wskazówek dotyczących głównego węzła, które można odczytać za pomocą argumentu Bundle przekazanego do onGetRoot(). Dzięki tym wskazówkom system może optymalnie wyświetlać treści główne jako karty nawigacyjne. Jeśli nie zastosujesz tych wskazówek, niektóre treści z katalogu głównego mogą zostać usunięte lub uczynione mniej wykrywalnymi przez system. Wysyłane są 2 wskazówki:

Aby odczytać odpowiednie wskazówki dotyczące serwera głównego, użyj tego kodu:

Kotlin

import androidx.media.utils.MediaConstants

// Later, in your MediaBrowserServiceCompat.
override fun onGetRoot(
    clientPackageName: String,
    clientUid: Int,
    rootHints: Bundle
): BrowserRoot {

  val maximumRootChildLimit = rootHints.getInt(
      MediaConstants.BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_LIMIT,
      /* defaultValue= */ 4)
  val supportedRootChildFlags = rootHints.getInt(
      MediaConstants.BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_SUPPORTED_FLAGS,
      /* defaultValue= */ MediaItem.FLAG_BROWSABLE)

  // Rest of method...
}

Java

import androidx.media.utils.MediaConstants;

// Later, in your MediaBrowserServiceCompat.
@Override
public BrowserRoot onGetRoot(
    String clientPackageName, int clientUid, Bundle rootHints) {

    int maximumRootChildLimit = rootHints.getInt(
        MediaConstants.BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_LIMIT,
        /* defaultValue= */ 4);
    int supportedRootChildFlags = rootHints.getInt(
        MediaConstants.BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_SUPPORTED_FLAGS,
        /* defaultValue= */ MediaItem.FLAG_BROWSABLE);

    // Rest of method...
}

Możesz rozgałęzić logikę struktury hierarchii treści na podstawie wartości tych wskazówek, zwłaszcza jeśli Twoja hierarchia różni się w przypadku integracji MediaBrowser spoza Androida Auto i systemu operacyjnego Android Automotive. Jeśli na przykład zwykle wyświetlasz główny element do odtworzenia, możesz go umieścić w elementach do przeglądania z poziomu głównego ze względu na wartość podpowiedzi obsługiwanych flag.

Oprócz wskazówek dotyczących wskazówek dotyczących katalogu głównego należy przestrzegać kilku dodatkowych wskazówek, aby zapewnić optymalne renderowanie kart:

  • Do każdego elementu karty dołącz monochromatyczne, najlepiej białe, ikony.
  • Każdy element na karcie powinien mieć krótkie, ale przydatne etykiety. Krótkie etykiety zmniejszają ryzyko obcięcia ciągów znaków.

Wyświetlanie multimediów

Elementy graficzne w przypadku elementów multimedialnych muszą być przekazywane jako identyfikatory URI lokalne za pomocą wartości ContentResolver.SCHEME_CONTENT lub ContentResolver.SCHEME_ANDROID_RESOURCE. Ten lokalny identyfikator URI musi mieć format bitmapy lub grafiki wektorowej, którą można narysować w zasobach aplikacji. W przypadku obiektów MediaDescriptionCompat reprezentujących elementy w hierarchii treści przekaż identyfikator URI za pomocą setIconUri(). W przypadku obiektów MediaMetadataCompat reprezentujących aktualnie odtwarzany element, przekaż identyfikator URI przez putString(), używając dowolnego z tych kluczy:

W podanych niżej krokach opisano, jak pobrać grafikę z identyfikatora URI internetowego i ujawnić ją za pomocą identyfikatora URI lokalnego. Pełniejszy przykład znajdziesz w implementacji funkcji openFile() i otaczających ją metod w przykładowej aplikacji Universal Android Music Player.

  1. Utwórz identyfikator URI content:// odpowiadający identyfikatorowi URI witryny. Usługa przeglądarki multimediów i sesja multimediów przekazują ten identyfikator URI treści do Androida Auto i systemu operacyjnego Android Automotive.

    Kotlin

    fun Uri.asAlbumArtContentURI(): Uri {
  return Uri.Builder()
    .scheme(ContentResolver.SCHEME_CONTENT)
    .authority(CONTENT_PROVIDER_AUTHORITY)
    .appendPath(this.getPath()) // Make sure you trust the URI
    .build()
}

    Java

    public static Uri asAlbumArtContentURI(Uri webUri) {
  return new Uri.Builder()
    .scheme(ContentResolver.SCHEME_CONTENT)
    .authority(CONTENT_PROVIDER_AUTHORITY)
    .appendPath(webUri.getPath()) // Make sure you trust the URI!
    .build();
}

  2. W implementacji ContentProvider.openFile() sprawdź, czy istnieje plik dla odpowiedniego identyfikatora URI. Jeśli nie, pobierz plik obrazu i prześlij go do pamięci podręcznej. Ten fragment kodu używa funkcji Glide.

    Kotlin

    override fun openFile(uri: Uri, mode: String): ParcelFileDescriptor? {
  val context = this.context ?: return null
  val file = File(context.cacheDir, uri.path)
  if (!file.exists()) {
    val remoteUri = Uri.Builder()
        .scheme("https")
        .authority("my-image-site")
        .appendPath(uri.path)
        .build()
    val cacheFile = Glide.with(context)
        .asFile()
        .load(remoteUri)
        .submit()
        .get(DOWNLOAD_TIMEOUT_SECONDS, TimeUnit.SECONDS)

    cacheFile.renameTo(file)
    file = cacheFile
  }
  return ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY)
}

    Java

    @Nullable
@Override
public ParcelFileDescriptor openFile(@NonNull Uri uri, @NonNull String mode)
    throws FileNotFoundException {
  Context context = this.getContext();
  File file = new File(context.getCacheDir(), uri.getPath());
  if (!file.exists()) {
    Uri remoteUri = new Uri.Builder()
        .scheme("https")
        .authority("my-image-site")
        .appendPath(uri.getPath())
        .build();
    File cacheFile = Glide.with(context)
        .asFile()
        .load(remoteUri)
        .submit()
        .get(DOWNLOAD_TIMEOUT_SECONDS, TimeUnit.SECONDS);

    cacheFile.renameTo(file);
    file = cacheFile;
  }
  return ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY);
}

Więcej informacji o dostawcach treści znajdziesz w artykule o tworzeniu dostawcy treści.

Zastosuj style treści

Po zbudowaniu hierarchii treści za pomocą elementów możliwych do przeglądania lub gier możesz zastosować style treści, które określają sposób wyświetlania tych elementów w samochodzie.

Możesz używać tych stylów treści:

Pozycje na liście

W tym stylu treści priorytetem są tytuły i metadane, a nie obrazy.

Elementy siatki

W tym stylu treści priorytetem są obrazy, a nie tytuły i metadane.

Ustaw domyślne style treści

Możesz ustawić globalne ustawienia domyślne wyświetlania elementów multimedialnych, dodając określone stałe wartości do pakietu dodatkowych elementów BrowserRoot metody onGetRoot() Twojej usługi. Android Auto i system operacyjny Android Automotive odczytują ten pakiet i szukają w nim tych stałych wartości, aby określić odpowiedni styl.

Jako klucze w pakiecie można używać tych dodatków:

Klucze mogą być mapowane na te wartości liczb całkowitych, aby wpływać na sposób wyświetlania tych elementów:

  • DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM: odpowiednie elementy są wyświetlane jako elementy listy.
  • DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM: odpowiednie elementy są wyświetlane jako elementy siatki.
  • DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM: odpowiednie elementy są wyświetlane jako elementy listy „Kategoria”. Są to te same elementy co zwykłe elementy listy, z tym wyjątkiem, że wokół ikon elementów stosuje się marginesy, ponieważ ikony lepiej wyglądają, gdy są małe. Ikony muszą być elementami, które można rysować wektorowo. Ten podpowiedź powinien być udostępniany tylko w przypadku elementów, które można przeglądać.
  • DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_GRID_ITEM:odpowiadające elementy są wyświetlane jako elementy siatki „Kategoria”. Są to te same elementy co zwykłe elementy siatki, z tą różnicą, że wokół ikon elementów są stosowane marginesy, ponieważ ikony lepiej wyglądają, gdy są małe. Ikony muszą być elementami, które można rysować wektorowo. Ten podpowiedź powinien być udostępniany tylko w przypadku elementów, które można przeglądać.

Ten fragment kodu pokazuje, jak ustawić domyślny styl treści dla elementów do przeglądania w kratce i elementów do odtwarzania w listach:

Kotlin

import androidx.media.utils.MediaConstants

@Nullable
override fun onGetRoot(
    @NonNull clientPackageName: String,
    clientUid: Int,
    @Nullable rootHints: Bundle
): BrowserRoot {
    val extras = Bundle()
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM)
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM)
    return BrowserRoot(ROOT_ID, extras)
}

Java

import androidx.media.utils.MediaConstants;

@Nullable
@Override
public BrowserRoot onGetRoot(
    @NonNull String clientPackageName,
    int clientUid,
    @Nullable Bundle rootHints) {
    Bundle extras = new Bundle();
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM);
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM);
    return new BrowserRoot(ROOT_ID, extras);
}

Ustawianie stylów treści dla poszczególnych elementów

Interfejs Content Style API umożliwia zastąpienie domyślnego stylu treści dla elementów podrzędnych dowolnego przeglądalnego elementu multimedialnego, a także samego elementu multimedialnego.

Aby zastąpić domyślne elementy podrzędne przeglądalnego elementu multimedialnego, utwórz pakiet dodatkowych elementów w MediaDescription elementu multimedialnego i dodaj te same podpowiedzi, które zostały wymienione wcześniej. DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE dotyczy dzieci, które mogą grać w danym elemencie, a DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE – elementów podrzędnych, które można przeglądać.

Aby zastąpić domyślne ustawienie konkretnego elementu multimedialnego właściwiego, a nie jego elementów podrzędnych, utwórz pakiet dodatkowych elementów w MediaDescription elementu multimedialnego i dodaj podpowiedź z kluczem DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM. Aby określić sposób prezentacji elementu, użyj tych samych wartości co w poprzednim kroku.

Ten fragment kodu pokazuje, jak utworzyć możliwy do przeglądania element MediaItem, który zastępuje domyślny styl treści zarówno w przypadku samego wydawcy, jak i jego elementów podrzędnych. Jest on stylizowany jako element listy kategorii, a jego przeglądalne elementy podrzędne jako elementy listy, a elementy podrzędne do odtworzenia jako elementy siatki:

Kotlin

import androidx.media.utils.MediaConstants

private fun createBrowsableMediaItem(
    mediaId: String,
    folderName: String,
    iconUri: Uri
): MediaBrowser.MediaItem {
    val mediaDescriptionBuilder = MediaDescription.Builder()
    mediaDescriptionBuilder.setMediaId(mediaId)
    mediaDescriptionBuilder.setTitle(folderName)
    mediaDescriptionBuilder.setIconUri(iconUri)
    val extras = Bundle()
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM)
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM)
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM)
    mediaDescriptionBuilder.setExtras(extras)
    return MediaBrowser.MediaItem(
        mediaDescriptionBuilder.build(), MediaBrowser.MediaItem.FLAG_BROWSABLE)
}

Java

import androidx.media.utils.MediaConstants;

private MediaBrowser.MediaItem createBrowsableMediaItem(
    String mediaId,
    String folderName,
    Uri iconUri) {
    MediaDescription.Builder mediaDescriptionBuilder = new MediaDescription.Builder();
    mediaDescriptionBuilder.setMediaId(mediaId);
    mediaDescriptionBuilder.setTitle(folderName);
    mediaDescriptionBuilder.setIconUri(iconUri);
    Bundle extras = new Bundle();
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM);
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM);
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM);
    mediaDescriptionBuilder.setExtras(extras);
    return new MediaBrowser.MediaItem(
        mediaDescriptionBuilder.build(), MediaBrowser.MediaItem.FLAG_BROWSABLE);
}

Grupowanie elementów za pomocą podpowiedzi dotyczących tytułów

Aby pogrupować powiązane elementy multimedialne, użyj wskazówki dotyczącej poszczególnych elementów. Każdy element multimedialny w grupie musi zadeklarować pakiet dodatkowych treści w sekcji MediaDescription, która zawiera mapowanie z kluczem DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE i identyczną wartością ciągu znaków. Zlokalizuj ten ciąg znaków, który jest używany jako tytuł grupy.

Ten fragment kodu pokazuje, jak utworzyć MediaItem z nag��ówkiem podgrupy "Songs":

Kotlin

import androidx.media.utils.MediaConstants

private fun createMediaItem(
    mediaId: String,
    folderName: String,
    iconUri: Uri
): MediaBrowser.MediaItem {
    val mediaDescriptionBuilder = MediaDescription.Builder()
    mediaDescriptionBuilder.setMediaId(mediaId)
    mediaDescriptionBuilder.setTitle(folderName)
    mediaDescriptionBuilder.setIconUri(iconUri)
    val extras = Bundle()
    extras.putString(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE,
        "Songs")
    mediaDescriptionBuilder.setExtras(extras)
    return MediaBrowser.MediaItem(
        mediaDescriptionBuilder.build(), /* playable or browsable flag*/)
}

Java

import androidx.media.utils.MediaConstants;

private MediaBrowser.MediaItem createMediaItem(String mediaId, String folderName, Uri iconUri) {
   MediaDescription.Builder mediaDescriptionBuilder = new MediaDescription.Builder();
   mediaDescriptionBuilder.setMediaId(mediaId);
   mediaDescriptionBuilder.setTitle(folderName);
   mediaDescriptionBuilder.setIconUri(iconUri);
   Bundle extras = new Bundle();
   extras.putString(
       MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE,
       "Songs");
   mediaDescriptionBuilder.setExtras(extras);
   return new MediaBrowser.MediaItem(
       mediaDescriptionBuilder.build(), /* playable or browsable flag*/);
}

Aplikacja musi przekazywać wszystkie elementy multimedialne, które chcesz zgrupować, jako ciągły blok. Załóżmy na przykład, że chcesz w tej kolejności wyświetlić 2 grupy elementów multimedialnych – „Utwory” i „Albumy” oraz że aplikacja przekazuje 5 elementów multimedialnych w tej kolejności:

  1. Element multimedialny A o nazwie extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  2. Element multimedialny B z extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums")
  3. Element multimedialny C z extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  4. Element multimedialny D z extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  5. Element multimedialny E z extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums")

Ponieważ elementy multimedialne w grupach „Utwory” i „Albumy” nie są przechowywane razem w ciągłych blokach, Android Auto i system operacyjny Android Automotive interpretują je jako 4 grupy:

  • Grupa 1 o nazwie „Utwory” zawierająca element multimedialny A
  • Grupa 2 o nazwie „Albumy” zawierająca element multimedialny B
  • Grupa 3 o nazwie „Utwory” zawierająca elementy multimedialne C i D
  • Grupa 4 o nazwie „Albumy” zawierająca element multimedialny E

Aby wyświetlić te elementy w 2 grupach, aplikacja musi przekazywać elementy multimedialne w takim porządku:

  1. Element multimedialny A z extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  2. Element multimedialny C z extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  3. Element multimedialny D z extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  4. Element multimedialny B z extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums")
  5. Element multimedialny E z extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums")

Wyświetlanie dodatkowych wskaźników metadanych

Możesz dodać dodatkowe wskaźniki metadanych, aby szybko uzyskać informacje o treści w drzewie przeglądarki multimediów i podczas odtwarzania. W drzewie przeglądania Android Auto i system operacyjny Android Automotive odczytują dodatkowe informacje powiązane z elementem i szukają określonych stałych, aby określić, które wskaźniki wyświetlić. Podczas odtwarzania multimediów Android Auto i Android Automotive OS odczytują metadane sesji multimediów i szukają określonych stałych wartości, aby określić, jakie wskaźniki mają być wyświetlane.

Rysunek 3. Widok odtwarzania z metadanymi identyfikującymi utwór i wykonawcę oraz ikoną wskazującą treści dla dorosłych.

Rysunek 4. Widok przeglądania z kropką dla nieodtworzonych treści w pierwszym elemencie i paskiem postępu dla częściowo odtworzonych treści w drugim elemencie.

W obu dodatkowych elementach MediaItem opisu i MediaMetadata dodatkowych:

W dodatkowych elementach tekstu reklamy MediaItem można stosować tylko te stałe:

Aby wyświetlać wskaźniki, które pojawiają się, gdy użytkownik przegląda drzewo wyszukiwania multimediów, utwórz pakiet dodatkowych informacji, który zawiera co najmniej jedną z tych stałych wartości, a następnie prześlij ten pakiet do metody MediaDescription.Builder.setExtras().

Ten fragment kodu pokazuje, jak wyświetlać wskaźniki dla treści dla dorosłych, które są w 70% ukończone:

Kotlin

import androidx.media.utils.MediaConstants

val extras = Bundle()
extras.putLong(
    MediaConstants.METADATA_KEY_IS_EXPLICIT,
    MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
extras.putInt(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS,
    MediaConstants.DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_PARTIALLY_PLAYED)
extras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.7)
val description =
    MediaDescriptionCompat.Builder()
        .setMediaId(/*...*/)
        .setTitle(resources.getString(/*...*/))
        .setExtras(extras)
        .build()
return MediaBrowserCompat.MediaItem(description, /* flags */)

Java

import androidx.media.utils.MediaConstants;

Bundle extras = new Bundle();
extras.putLong(
    MediaConstants.METADATA_KEY_IS_EXPLICIT,
    MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT);
extras.putInt(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS,
    MediaConstants.DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_PARTIALLY_PLAYED);
extras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.7);
MediaDescriptionCompat description =
    new MediaDescriptionCompat.Builder()
        .setMediaId(/*...*/)
        .setTitle(resources.getString(/*...*/))
        .setExtras(extras)
        .build();
return new MediaBrowserCompat.MediaItem(description, /* flags */);

Aby wyświetlać wskaźniki dla obecnie odtwarzanego elementu multimedialnego, możesz zadeklarować wartości Long dla METADATA_KEY_IS_EXPLICIT lub EXTRA_DOWNLOAD_STATUS w MediaMetadataCompat elementu mediaSession. W widoku odtwarzania nie możesz wyświetlać wskaźników DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS ani DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE.

Ten fragment kodu pokazuje, jak wskazać, że w widoku odtwarzania bieżący utwór jest wulgarny i został pobrany:

Kotlin

import androidx.media.utils.MediaConstants

mediaSession.setMetadata(
    MediaMetadataCompat.Builder()
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_TITLE, "Song Name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "Artist name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_ALBUM_ART_URI,
            albumArtUri.toString())
        .putLong(
            MediaConstants.METADATA_KEY_IS_EXPLICIT,
            MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
        .putLong(
            MediaDescriptionCompat.EXTRA_DOWNLOAD_STATUS,
            MediaDescriptionCompat.STATUS_DOWNLOADED)
        .build())

Java

import androidx.media.utils.MediaConstants;

mediaSession.setMetadata(
    new MediaMetadataCompat.Builder()
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_TITLE, "Song Name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "Artist name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_ALBUM_ART_URI,
            albumArtUri.toString())
        .putLong(
            MediaConstants.METADATA_KEY_IS_EXPLICIT,
            MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
        .putLong(
            MediaDescriptionCompat.EXTRA_DOWNLOAD_STATUS,
            MediaDescriptionCompat.STATUS_DOWNLOADED)
        .build());

Aktualizuj pasek postępu w widoku przeglądania podczas odtwarzania treści

Jak już wspomnieliśmy, możesz użyć dodatku DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, aby wyświetlić pasek postępu częściowo odtworzonych treści w widoku przeglądania. Jeśli jednak użytkownik nadal będzie odtwarzać częściowo odtwarzane treści z Androida Auto lub Androida Automotive, z czasem wskaźnik staje się niedokładny.

W przypadku Androida Auto i Androida Automotive OS, aby pasek postępu był aktualny, w polach MediaMetadataCompat i PlaybackStateCompat możesz podać dodatkowe informacje, aby powiązać bieżące treści z elementami multimedialnymi w widoku przeglądania. Aby element multimedialny miał automatycznie aktualizowany pasek postępu, musi spełniać te wymagania:

Ten fragment kodu pokazuje, jak wskazać, że aktualnie odtwarzany element jest powiązany z elementem w widoku przeglądania:

Kotlin

import androidx.media.utils.MediaConstants

// When the MediaItem is constructed to show in the browse view.
// Suppose the item was 25% complete when the user launched the browse view.
val mediaItemExtras = Bundle()
mediaItemExtras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.25)
val description =
    MediaDescriptionCompat.Builder()
        .setMediaId("my-media-id")
        .setExtras(mediaItemExtras)
        // ...and any other setters.
        .build()
return MediaBrowserCompat.MediaItem(description, /* flags */)

// Elsewhere, when the user has selected MediaItem for playback.
mediaSession.setMetadata(
    MediaMetadataCompat.Builder()
        .putString(MediaMetadata.METADATA_KEY_MEDIA_ID, "my-media-id")
        // ...and any other setters.
        .build())

val playbackStateExtras = Bundle()
playbackStateExtras.putString(
    MediaConstants.PLAYBACK_STATE_EXTRAS_KEY_MEDIA_ID, "my-media-id")
mediaSession.setPlaybackState(
    PlaybackStateCompat.Builder()
        .setExtras(playbackStateExtras)
        // ...and any other setters.
        .build())

Java

import androidx.media.utils.MediaConstants;

// When the MediaItem is constructed to show in the browse view.
// Suppose the item was 25% complete when the user launched the browse view.
Bundle mediaItemExtras = new Bundle();
mediaItemExtras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.25);
MediaDescriptionCompat description =
    new MediaDescriptionCompat.Builder()
        .setMediaId("my-media-id")
        .setExtras(mediaItemExtras)
        // ...and any other setters.
        .build();
return MediaBrowserCompat.MediaItem(description, /* flags */);

// Elsewhere, when the user has selected MediaItem for playback.
mediaSession.setMetadata(
    new MediaMetadataCompat.Builder()
        .putString(MediaMetadata.METADATA_KEY_MEDIA_ID, "my-media-id")
        // ...and any other setters.
        .build());

Bundle playbackStateExtras = new Bundle();
playbackStateExtras.putString(
    MediaConstants.PLAYBACK_STATE_EXTRAS_KEY_MEDIA_ID, "my-media-id");
mediaSession.setPlaybackState(
    new PlaybackStateCompat.Builder()
        .setExtras(playbackStateExtras)
        // ...and any other setters.
        .build());

Rysunek 5. Widok odtwarzania z opcją „Wyniki wyszukiwania” umożliwiającą wyświetlanie multimediów związanych z wyszukiwaniem głosowym użytkownika.

Aplikacja może udostępniać kontekstowe wyniki wyszukiwania wyświetlane użytkownikom, gdy inicjują zapytanie. Android Auto i Android Automotive OS wyświetlają te wyniki za pomocą interfejsów wyszukiwania lub funkcji, które opierają się na zapytaniach wprowadzonych wcześniej w ramach sesji. Więcej informacji znajdziesz w sekcji Obsługa komend głosowych tego przewodnika.

Aby wyświetlać przeglądalne wyniki wyszukiwania, dodaj stały klucz BROWSER_SERVICE_EXTRAS_KEY_SEARCH_SUPPORTED do pakietu dodatkowych funkcji metody onGetRoot() usługi, mapując go na wartość logiczną true.

Ten fragment kodu pokazuje, jak włączyć obsługę w metodie onGetRoot():

Kotlin

import androidx.media.utils.MediaConstants

@Nullable
fun onGetRoot(
    @NonNull clientPackageName: String,
    clientUid: Int,
    @Nullable rootHints: Bundle
): BrowserRoot {
    val extras = Bundle()
    extras.putBoolean(
        MediaConstants.BROWSER_SERVICE_EXTRAS_KEY_SEARCH_SUPPORTED, true)
    return BrowserRoot(ROOT_ID, extras)
}

Java

import androidx.media.utils.MediaConstants;

@Nullable
@Override
public BrowserRoot onGetRoot(
    @NonNull String clientPackageName,
    int clientUid,
    @Nullable Bundle rootHints) {
    Bundle extras = new Bundle();
    extras.putBoolean(
        MediaConstants.BROWSER_SERVICE_EXTRAS_KEY_SEARCH_SUPPORTED, true);
    return new BrowserRoot(ROOT_ID, extras);
}

Aby zacząć dostarczać wyniki wyszukiwania, zastąpij metodę onSearch() w swojej usłudze przeglądarki multimediów. Android Auto i Android Automotive OS przekazują zapytania użytkownika do tej metody, gdy użytkownik wywoła interfejs zapytania wyszukiwania lub „Wyniki wyszukiwania”.

Aby ułatwić przeglądanie wyników wyszukiwania z metody onSearch() w usłudze, możesz je uporządkować za pomocą elementów tytułu. Jeśli na przykład Twoja aplikacja odtwarza muzykę, możesz uporządkować wyniki wyszukiwania według albumu, wykonawcy i utworów.

Ten fragment kodu pokazuje prostą implementację metody onSearch():

Kotlin

fun onSearch(query: String, extras: Bundle) {
  // Detach from results to unblock the caller (if a search is expensive).
  result.detach()
  object:AsyncTask() {
    internal var searchResponse:ArrayList
    internal var succeeded = false
    protected fun doInBackground(vararg params:Void):Void {
      searchResponse = ArrayList()
      if (doSearch(query, extras, searchResponse))
      {
        succeeded = true
      }
      return null
    }
    protected fun onPostExecute(param:Void) {
      if (succeeded)
      {
        // Sending an empty List informs the caller that there were no results.
        result.sendResult(searchResponse)
      }
      else
      {
        // This invokes onError() on the search callback.
        result.sendResult(null)
      }
      return null
    }
  }.execute()
}
// Populates resultsToFill with search results. Returns true on success or false on error.
private fun doSearch(
    query: String,
    extras: Bundle,
    resultsToFill: ArrayList
): Boolean {
  // Implement this method.
}

Java

@Override
public void onSearch(final String query, final Bundle extras,
                        Result<List<MediaItem>> result) {

  // Detach from results to unblock the caller (if a search is expensive).
  result.detach();

  new AsyncTask<Void, Void, Void>() {
    List<MediaItem> searchResponse;
    boolean succeeded = false;
    @Override
    protected Void doInBackground(Void... params) {
      searchResponse = new ArrayList<MediaItem>();
      if (doSearch(query, extras, searchResponse)) {
        succeeded = true;
      }
      return null;
    }

    @Override
    protected void onPostExecute(Void param) {
      if (succeeded) {
       // Sending an empty List informs the caller that there were no results.
       result.sendResult(searchResponse);
      } else {
        // This invokes onError() on the search callback.
        result.sendResult(null);
      }
    }
  }.execute()
}

/** Populates resultsToFill with search results. Returns true on success or false on error. */
private boolean doSearch(String query, Bundle extras, ArrayList<MediaItem> resultsToFill) {
    // Implement this method.
}

Niestandardowe działania w przeglądarce

Pojedyncze niestandardowe działanie przeglądania.

Rysunek 6. Pojedyncze niestandardowe działanie przeglądania

Niestandardowe działania przeglądania umożliwiają dodawanie niestandardowych ikon i etykietek do obiektów MediaItem w aplikacji multimedialnej w samochodzie oraz obsługę interakcji użytkownika z tymi działaniami. Dzięki temu możesz rozszerzyć funkcjonalność aplikacji do multimediów na różne sposoby, np. dodając działania „Pobierz”, „Dodaj do kolejki”, „Odtwórz radio”, „Ulubione” lub „Usuń”.

Menu rozszerzone niestandardowych działań przeglądania.

Rysunek 7. Rozszerzenie działania przeglądania niestandardowego

Jeśli liczba działań niestandardowych jest większa niż dozwolona przez OEM-a, użytkownik zobaczy menu przepełnienia.

Jak to działa?

Każde niestandardowe działanie przeglądania jest zdefiniowane za pomocą:

  • Identyfikator działania (unikalny ciąg znaków)
  • Etykieta działania (tekst wyświetlany użytkownikowi)
  • URI ikony działania (obiekt rysowalny wektorowo, który można zabarwić)

Listę niestandardowych działań związanych z przeglądaniem definiujesz globalnie w ramach BrowseRoot. Następnie możesz dołączyć podzbiór tych działań do poszczególnych kont MediaItem.

Gdy użytkownik wejdzie w interakcję z niestandardowym działaniem przeglądania, aplikacja otrzyma wywołanie zwrotne w ciągu onCustomAction(). Następnie możesz wykonać działanie i w razie potrzeby zaktualizować listę działań dla MediaItem. Przydaje się to przy stanowych działaniach takich jak „Dodaj do ulubionych” czy „Pobierz”. W przypadku działań, które nie wymagają aktualizacji, takich jak „Odtwórz radio”, nie musisz aktualizować listy działań.

Niestandardowe działania związane z przeglądaniem w korzeniach węzła przeglądania.

Rysunek 8. Pasek narzędzi niestandardowych działań przeglądania

Możesz też dołączyć niestandardowe działania przeglądania do korzenia węzła przeglądania. Te działania będą widoczne na dodatkowym pasku narzędzi pod paskiem głównym.

Jak zaimplementować niestandardowe działania przeglądania

Aby dodać do projektu niestandardowe działania przeglądania:

  1. Zastąp 2 metody w implementacji MediaBrowserServiceCompat:
  2. Analizowanie limitów działań w czasie wykonywania:
    • W onGetRoot() użyj klucza BROWSER_ROOT_HINTS_KEY_CUSTOM_BROWSER_ACTION_LIMIT w rootHints Bundle, aby uzyskać maksymalną liczbę dozwolonych działań dla każdego MediaItem. Limit równy 0 oznacza, że funkcja nie jest obsługiwana przez system.
  3. Utwórz globalną listę niestandardowych działań przeglądania:
    • Dla każdej czynności utwórz obiekt Bundle z tymi kluczami: * EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID: identyfikator działania * EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL: etykieta działania * EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI: identyfikator URI ikony działania * dodaj wszystkie obiekty Bundle działania do listy.
  4. Dodaj listę globalną do BrowseRoot:
  5. Dodaj działania do obiektów MediaItem:
    • Możesz dodawać działania do poszczególnych obiektów MediaItem, dodając listę identyfikatorów działań w dodatkowych elementach MediaDescriptionCompat za pomocą klucza DESCRIPTION_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID_LIST. Ta lista musi być podzbiorem globalnej listy działań zdefiniowanej w sekcji BrowseRoot.
  6. Obsługa działań i zwracanie postępów lub wyników:

Oto kilka zmian, które możesz wprowadzić w BrowserServiceCompat, aby zacząć korzystać z niestandardowych działań przeglądania.

Zastąpić BrowserServiceCompat

Musisz zastąpić te metody w pliku MediaBrowserServiceCompat. 

public void onLoadItem(String itemId, @NonNull Result<MediaBrowserCompat.MediaItem> result)
 

public void onCustomAction(@NonNull String action, Bundle extras, @NonNull Result<Bundle> result)

Limit działań analizy

Sprawdź, ile niestandardowych działań związanych z przeglądaniem jest obsługiwanych. 

public BrowserRoot onGetRoot(@NonNull String clientPackageName, int clientUid, Bundle rootHints) {
    rootHints.getInt(
            MediaConstants.BROWSER_ROOT_HINTS_KEY_CUSTOM_BROWSER_ACTION_LIMIT, 0)
}

Tworzenie niestandardowego działania przeglądania

Każde działanie musi być zapakowane w osobną Bundle.

  • Identyfikator działania 
    bundle.putString(MediaConstants.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID,
                "<ACTION_ID>")
  • Etykieta działania 
    bundle.putString(MediaConstants.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL,
                "<ACTION_LABEL>")
  • Identyfikator URI ikony działania 
    bundle.putString(MediaConstants.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI,
                "<ACTION_ICON_URI>")

Dodaj niestandardowe działania przeglądania do kampanii Parceable ArrayList

Dodaj wszystkie obiekty działania niestandardowego podczas przeglądania Bundle do obiektu ArrayList. 

private ArrayList<Bundle> createCustomActionsList(
                                        CustomBrowseAction browseActions) {
    ArrayList<Bundle> browseActionsBundle = new ArrayList<>();
    for (CustomBrowseAction browseAction : browseActions) {
        Bundle action = new Bundle();
        action.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID,
                browseAction.mId);
        action.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL,
                getString(browseAction.mLabelResId));
        action.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI,
                browseAction.mIcon);
        browseActionsBundle.add(action);
    }
    return browseActionsBundle;
}

Dodawanie listy niestandardowych działań związanych z przeglądaniem do katalogu źródeł

public BrowserRoot onGetRoot(@NonNull String clientPackageName, int clientUid,
                             Bundle rootHints) {
    Bundle browserRootExtras = new Bundle();
    browserRootExtras.putParcelableArrayList(
            BROWSER_SERVICE_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ROOT_LIST,
            createCustomActionsList()));
    mRoot = new BrowserRoot(ROOT_ID, browserRootExtras);
    return mRoot;
}

Dodaj działania do: MediaItem

MediaDescriptionCompat buildDescription (long id, String title, String subtitle,
                String description, Uri iconUri, Uri mediaUri,
                ArrayList<String> browseActionIds) {

    MediaDescriptionCompat.Builder bob = new MediaDescriptionCompat.Builder();
    bob.setMediaId(id);
    bob.setTitle(title);
    bob.setSubtitle(subtitle);
    bob.setDescription(description);
    bob.setIconUri(iconUri);
    bob.setMediaUri(mediaUri);

    Bundle extras = new Bundle();
    extras.putStringArrayList(
          DESCRIPTION_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID_LIST,
          browseActionIds);

    bob.setExtras(extras);
    return bob.build();
}
MediaItem mediaItem = new MediaItem(buildDescription(...), flags);

Wynik kompilacji onCustomAction

  • Przeanalizuj mediaId z Bundle extras: 
    @Override
public void onCustomAction(
          @NonNull String action, Bundle extras, @NonNull Result<Bundle> result){
  String mediaId = extras.getString(MediaConstans.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_MEDIA_ITEM_ID);
}
  • W przypadku wyników asynchronicznych odłącz wynik. result.detach()
  • Pakiet wyników kompilacji
    • Wiadomość do użytkownika 
      mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_MESSAGE,
          mContext.getString(stringRes))
    • Aktualizuj element(służy do aktualizowania działań w elemencie) 
      mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM, mediaId);
    • Otwieranie widoku odtwarzania 
      //Shows user the PBV without changing the playback state
mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_SHOW_PLAYING_ITEM, null);
    • Aktualizowanie węzła przeglądania 
      //Change current browse node to mediaId
mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_BROWSE_NODE, mediaId);
  • Jeśli wystąpił błąd, zadzwoń pod numer result.sendError(resultBundle).
  • Jeśli chcesz uzyskać informacje o postępach, zadzwoń pod numer result.sendProgressUpdate(resultBundle).
  • Na koniec zadzwoń pod numer result.sendResult(resultBundle).

Aktualizowanie stanu działania

Za pomocą metody result.sendProgressUpdate(resultBundle) z kluczem EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM możesz zaktualizować MediaItem tak, aby odzwierciedlał nowy stan działania. Dzięki temu możesz przekazywać użytkownikowi w czasie rzeczywistym informacje o postępach i wynikach jego działań.

Przykład: działanie polegające na pobraniu

Oto przykład użycia tej funkcji do implementacji działania pobierania z 3 stanami:

  1. Pobieranie: jest to początkowy stan działania. Gdy użytkownik wybierze to działanie, możesz je zastąpić opcją „Pobieranie” i wywołać funkcję sendProgressUpdate, aby zaktualizować interfejs użytkownika.
  2. Pobieranie: ten stan wskazuje, że pobieranie jest w toku. Za pomocą tego stanu możesz wyświetlić użytkownikowi pasek postępu lub inny wskaźnik.
  3. Pobrane: ten stan oznacza, że pobieranie zostało zakończone. Po zakończeniu pobierania możesz zamienić „Pobieranie” na „Pobrane” i wywołać sendResult kluczem EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM, aby wskazać, że element powinien zostać od��wieżony. Dodatkowo możesz użyć klucza EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_MESSAGE aby wyświetlić użytkownikowi wiadomość o udanym wykonaniu.

Dzięki temu możesz wyraźnie poinformować użytkownika o procesie pobierania i jego obecnym stanie. Możesz dodać jeszcze więcej szczegółów, używając ikon, które pokazują stan pobierania (25%, 50%, 75%).

Przykład: ulubione akcje

Innym przykładem jest ulubione działanie z dwoma stanami:

  1. Ulubione: to działanie jest wyświetlane w przypadku elementów, których nie ma na liście ulubionych użytkownika. Gdy użytkownik wybierze to działanie, możesz je zastąpić działaniem „Ustaw jako ulubiony” i wywołać sendResult za pomocą klawisza EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM, aby zaktualizować interfejs użytkownika.
  2. Dodane do ulubionych: to działanie jest wyświetlane w przypadku elementów, które znajdują się na liście ulubionych użytkownika. Gdy użytkownik wybierze to działanie, możesz je zastąpić działaniem „Ulubione” i wywołać sendResult za pomocą klawisza EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM, aby zaktualizować interfejs użytkownika.

Dzięki temu użytkownicy mogą w jasny i spójny sposób zarządzać ulubionymi elementami.

Te przykłady pokazują elastyczność niestandardowych działań przeglądania oraz to, jak można za ich pomocą wdrożyć różne funkcje z opiniami w czasie rzeczywistym, aby zwiększyć wygodę użytkownika w samochodowej aplikacji multimedialnej.

Pełną przykładową implementację tej funkcji znajdziesz w projekcie TestMediaApp.

Włączanie sterowania odtwarzaniem

Android Auto i system operacyjny Android Automotive wysyłają polecenia sterowania odtwarzaniem za pomocą MediaSessionCompat Twojej usługi. Musisz zarejestrować sesję i zaimplementować powiązane z nią metody wywołania zwrotnego.

Rejestrowanie sesji multimediów

W metodzie onCreate() usługi przeglądarki multimediów utwórz obiekt MediaSessionCompat, a następnie zarejestruj sesję multimediów, wywołując funkcję setSessionToken().

Ten fragment kodu pokazuje, jak utworzyć i zarejestrować sesję multimediów:

Kotlin

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

Java

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

Podczas tworzenia obiektu sesji multimediów ustawiasz obiekt wywołania zwrotnego, który jest używany do obsługi żądań sterowania odtwarzaniem. Tworzysz to obiekt wywołania zwrotnego, podając implementację klasy MediaSessionCompat.Callback w swojej aplikacji. W następnej sekcji znajdziesz informacje o wdrażaniu tego obiektu.

Implementacja poleceń dotyczących odtwarzania

Gdy użytkownik prosi o odtworzenie elementu multimedialnego z Twojej aplikacji, system operacyjny Android Automotive i Android Auto używają klasy MediaSessionCompat.Callback z obiektu MediaSessionCompat aplikacji uzyskanej z usługi przeglądarki multimediów w Twojej aplikacji. Gdy użytkownik chce sterować odtwarzaniem treści, np. wstrzymać odtwarzanie lub przejść do następnego utworu, Android Auto i system operacyjny Android Automotive wywołują jedną z metod obiektu wywołania zwrotnego.

Aby obsługiwać odtwarzanie treści, aplikacja musi rozszerzać abstrakcyjną klasę MediaSessionCompat.Callbacki implementować metody, które obsługuje.

Zaimplementuj wszystkie poniższe metody wywołania zwrotnego, które mają sens w przypadku rodzajów treści oferowanych w aplikacji:

onPrepare()
Wywoływana po zmianie źródła multimediów. System operacyjny Android Automotive wywołuje tę metodę natychmiast po uruchomieniu. Aplikacja multimedialna musi implementować tę metodę.
onPlay()
Wywoływane, gdy użytkownik wybierze odtwarzanie bez wyboru konkretnego elementu. Aplikacja musi odtworzyć domyślne treści lub, jeśli odtwarzanie zostało wstrzymane za pomocą onPause(), wznowić odtwarzanie.

Uwaga: aplikacja nie powinna automatycznie rozpoczynać odtwarzania muzyki, gdy system operacyjny Android Automotive lub Android Auto połączy się z usługą przeglądarki multimedialnej. Więcej informacji znajdziesz w sekcji ustawiania początkowego stanu odtwarzania.

onPlayFromMediaId()
Wywoływane, gdy użytkownik wybierze odtworzenie określonego elementu. Metoda otrzymuje identyfikator przypisany do elementu multimedialnego w hierarchii treści przez usługę przeglądarki multimedialnej.
onPlayFromSearch()
Wywoływane, gdy użytkownik wybierze odtwarzanie z zapytania wyszukiwania. Aplikacja musi dokonać odpowiedniego wyboru na podstawie przekazanego ciągu wyszukiwania.
onPause()
Wywoływane, gdy użytkownik wstrzyma odtwarzanie.
onSkipToNext()
Wywoływane, gdy użytkownik przejdzie do następnego elementu.
onSkipToPrevious()
Wywoływane, gdy użytkownik chce przejść do poprzedniego elementu.
onStop()
Wywoływane, gdy użytkownik zdecyduje się zatrzymać odtwarzanie.

Zastąp te metody w swojej aplikacji, aby udostępnić żądane funkcje. Nie musisz implementować metody, jeśli jej funkcje nie są obsługiwane przez Twoją aplikację. Na przykład jeśli Twoja aplikacja odtwarza transmisję na żywo, np. transmisję sportową, nie musisz implementować metody onSkipToNext(). Możesz jednak użyć domyślnej implementacji obiektu onSkipToNext().

Twoja aplikacja nie musi zawierać żadnej specjalnej logiki, aby odtwarzać treści przez głośniki samochodu. Gdy aplikacja otrzyma prośbę o odtworzenie treści, może odtworzyć dźwięk w taki sam sposób, w jaki odtwarza treści przez głośniki lub słuchawki telefonu użytkownika. Android Auto i system operacyjny Android Automotive automatycznie wysyłają treści audio do systemu samochodowego, aby odtwarzać je na głośnikach.

Więcej informacji o odtwarzaniu treści audio znajdziesz w artykułach MediaPlayer – omówienie, Omówienie aplikacji audio i Omówienie odtwarzacza ExoPlayer.

Ustawianie standardowych działań odtwarzania

Android Auto i system operacyjny Android Automotive wyświetlają elementy sterujące odtwarzaniem na podstawie działań włączonych w obiekcie PlaybackStateCompat.

Domyślnie aplikacja musi obsługiwać te działania:

Aplikacja może dodatkowo obsługiwać te działania, jeśli są one związane z jej treściami:

Możesz też utworzyć kolejkę odtwarzania, która może być wyświetlana użytkownikowi, ale nie jest to wymagane. W tym celu wywołaj metody setQueue() i setQueueTitle(), włącz działanie ACTION_SKIP_TO_QUEUE_ITEM i zdefiniuj funkcję wywołania zwrotnego onSkipToQueueItem().

Dodaj też obsługę ikony Co jest grane, która wskazuje, co jest obecnie odtwarzane. Aby to zrobić, wywołaj metodę setActiveQueueItemId() i przekaż identyfikator aktualnie odtwarzanego elementu w kolejce. setActiveQueueItemId() musisz zaktualizować każdorazowo za każdym razem, gdy zmienia się kolejka.

Przyciski wyświetlane w systemie operacyjnym Android Auto i Android Automotive oraz w kolejce odtwarzania są widoczne dla każdego włączonego działania. Gdy użytkownik kliknie przyciski, system wywoła odpowiednią funkcję z MediaSessionCompat.Callback.

Rezerwowanie niewykorzystanego miejsca

Android Auto i Android Automotive OS rezerwują w interfejsie miejsce na działania ACTION_SKIP_TO_PREVIOUS i ACTION_SKIP_TO_NEXT. Jeśli Twoja aplikacja nie obsługuje jednej z tych funkcji, Android Auto i Android Automotive OS używają tej przestrzeni do wyświetlania utworzonych przez Ciebie działań niestandardowych.

Jeśli nie chcesz wypełniać tych miejsc działaniami niestandardowymi, możesz je zarezerwować, tak aby aplikacje na Androida Auto i Androida Automotive pozostawiły puste miejsce, gdy aplikacja nie obsługuje odpowiedniej funkcji. Aby to zrobić, wywołaj metodę setExtras() z pakietem dodatków zawierającym stałe odpowiadające zarezerwowanym funkcjom. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT odpowiada ACTION_SKIP_TO_NEXT, a SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV odpowiada ACTION_SKIP_TO_PREVIOUS. Użyj tych stałych jako kluczy w pakiecie, a dla ich wartości użyj wartości logicznej true.

Ustawianie początkowego stanu odtwarzania

Ponieważ Android Auto i system operacyjny Android Automotive komunikują się z przeglądarką multimediów, sesja multimediów przekazuje stan odtwarzania treści za pomocą PlaybackStateCompat. Aplikacja nie powinna automatycznie rozpoczynać odtwarzania muzyki, gdy system operacyjny Android Automotive lub Android Auto połączy się z usługą przeglądarki multimediów. Zamiast tego korzystaj z Androida Auto i Androida Automotive, aby wznowić lub rozpocząć odtwarzanie na podstawie stanu samochodu lub działań użytkownika.

Aby to zrobić, ustaw początkową wartość PlaybackStateCompat sesji multimediów na STATE_STOPPED, STATE_PAUSED, STATE_NONE lub STATE_ERROR.

Sesje multimediów w Android Auto i Android Automotive OS trwają tylko przez czas jazdy, więc użytkownicy często je uruchamiają i zawieszają. Aby zapewnić płynne działanie między sesjami, śledź stan poprzedniej sesji użytkownika, aby po otrzymaniu prośby o wznowienie odtwarzania użytkownik mógł automatycznie wrócić do miejsca, w którym zakończył odtwarzanie, np. do ostatniego odtwarzanego elementu multimedialnego, PlaybackStateCompat i kolejki.

Dodawanie niestandardowych działań związanych z odtwarzaniem

Możesz dodać niestandardowe działania odtwarzania, aby wyświetlać dodatkowe działania obsługiwane przez Twoją aplikację multimedialną. Jeśli przestrzeń (i nie jest zarezerwowana), Android dodaje działania niestandardowe do elementów sterujących transportem. W przeciwnym razie działania niestandardowe będą widoczne w menu przepełnienia. Działania niestandardowe są wyświetlane w kolejności, w jakiej zostały dodane do PlaybackStateCompat.

Używaj działań niestandardowych, aby zapewnić działanie odmienne od działań standardowych. Nie używaj ich do zastępowania ani duplikowania standardowych działań.

Działania niestandardowe możesz dodawać za pomocą metody addCustomAction() w klasie PlaybackStateCompat.Builder.

Ten fragment kodu pokazuje, jak dodać niestandardową czynność „Uruchom kanał radiowy”:

Kotlin

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Java

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon)
    .setExtras(customActionExtras)
    .build());

Przykład tej metody znajdziesz w metodzie setCustomAction() w przykładowej aplikacji Universal Android Music Player na GitHub.

Po utworzeniu działania niestandardowego sesja multimediów może na nie odpowiedzieć, zastępując metodę onCustomAction().

Ten fragment kodu pokazuje, jak Twoja aplikacja może zareagować na działanie „Uruchom kanał radiowy”:

Kotlin

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA -> {
            ...
        }
    }
}

Java

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_START_RADIO_FROM_MEDIA.equals(action)) {
        ...
    }
}

Bardziej szczegółowy przykład tej metody znajdziesz w opisie metody onCustomAction w przykładowej aplikacji Universal Android Music Player na GitHubie.

Ikony działań niestandardowych

Każde działanie niestandardowe, które tworzysz, wymaga zasobu ikony. Aplikacje w samochodach mogą działać na wielu różnych rozmiarach i gęstościach ekranu, dlatego ikony muszą być elementami wektorowymi. Plik wektorowy umożliwia skalowanie zasobów bez utraty szczegółów. Plik wektorowy ułatwia też dopasowanie krawędzi i rogów do granic pikseli przy mniejszych rozdzielczościach.

Jeśli działanie niestandardowe zależy od stanu (np. włącza lub wyłącza ustawienie odtwarzania), zapewnij różne ikony dla różnych stanów, aby użytkownicy mogli zobaczyć zmianę po wybraniu działania.

Dodaj alternatywne style ikony dla wyłączonych działań.

Gdy działanie niestandardowe jest niedostępne w bieżącym kontekście, zamień jego ikonę na inną ikonę, która informuje o wyłączeniu działania.

Rysunek 6. Przykłady niestandardowych ikon działań

Wskaż format audio

Aby wskazać, że aktualnie odtwarzane multimedia używają specjalnego formatu dźwięku, możesz określić ikony renderowane w samochodach obsługujących tę funkcję. Możesz ustawić KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI i KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI w pakiecie dodatkowych elementów bieżąco odtwarzanego elementu multimedialnego (przekazanych do MediaSession.setMetadata()). Upewnij się, że ustawisz oba te dodatkowe elementy, aby dostosować się do różnych układów.

Dodatkowo możesz ustawić parametr KEY_IMMERSIVE_AUDIO, aby poinformować producentów OEM, że chodzi o dźwięk przestrzenny. Powinni oni bardzo uważnie rozważyć, czy zastosować efekty dźwiękowe, które mogłyby zakłócać treści dźwiękowe.

Możesz skonfigurować aktualnie odtwarzany element multimedialny tak, aby jego podpis, opis lub oba te elementy były linkami do innych elementów multimedialnych. Dzięki temu użytkownik może szybko przejść do powiązanych elementów – np. przeskoczyć do innych utworów tego samego wykonawcy lub do innych odcinków podcastu. Jeśli samochód obsługuje tę funkcję, użytkownik może kliknąć link, aby przejść do odpowiednich treści.

Aby dodać linki, skonfiguruj metadane KEY_SUBTITLE_LINK_MEDIA_ID (aby linkować z napisów) lub KEY_DESCRIPTION_LINK_MEDIA_ID (aby linkować z opisu). Szczegółowe informacje znajdziesz w dokumentacji tych pól metadanych.

Obsługa komend głosowych

Aplikacja multimedialna musi obsługiwać polecenia głosowe, aby zapewnić kierowcom bezpieczne i wygodne korzystanie z aplikacji, które nie będzie ich rozpraszać. Jeśli na przykład aplikacja odtwarza jeden element multimedialny, użytkownik może powiedzieć „Odtwórz [tytuł utworu]”, aby poprosić aplikację o odtworzenie innego utworu bez patrzenia na wyświetlacz samochodu ani dotykania go. Użytkownicy mogą inicjować zapytania, klikając odpowiednie przyciski na kierownicy lub wypowiadając słowa-klucze „OK Google”.

Gdy Android Auto lub system operacyjny Android Automotive wykryje i zinterpretuje komendę głosową, zostanie ona wysłana do aplikacji przez onPlayFromSearch(). Po otrzymaniu tego wywołania zwrotnego aplikacja znajduje treści pasujące do ciągu znaków query i rozpoczyna odtwarzanie.

Użytkownicy mogą w zapytaniach podawać różne kategorie terminów, m.in. gatunek, wykonawcę, album, nazwę utworu, stację radiową czy playlistę. Tworząc obsługę wyszukiwania, uwzględnij wszystkie kategorie, które mają sens w przypadku Twojej aplikacji. Jeśli Android Auto lub Android Automotive OS wykryje, że dane zapytanie pasuje do określonych kategorii, dodaje w parametrze extras dodatkowe korzyści. Możesz wysłać te dodatkowe informacje:

Uwzględniaj pusty ciąg znaków query, który może być wysyłany przez Androida Auto lub Androida Automotive, jeśli użytkownik nie określi zapytania. Jeśli na przykład użytkownik powie „Włącz jakąś muzykę”, W takiej sytuacji aplikacja może włączyć ostatnio odtwarzany lub nowo sugerowany utwór.

Jeśli wyszukiwanie nie może zostać przetworzone szybko, nie blokuj go w onPlayFromSearch(). Zamiast tego ustaw stan odtwarzania na STATE_CONNECTING i przeprowadź wyszukiwanie na wątku asynchronicznym.

Po rozpoczęciu odtwarzania zastanów się nad wypełnieniem kolejki sesji multimedialnej powiązanymi treściami. Jeśli na przykład użytkownik poprosi o odtworzenie albumu, aplikacja może wypełnić kolejkę listą utworów z tego albumu. Zastanów się też nad wdrożeniem obsługi wyników wyszukiwania, które można przeglądać, aby użytkownik mógł wybrać inną ścieżkę pasującą do zapytania.

Oprócz zapytań „odtwórz” systemy Android Auto i Android Automotive rozpoznają zapytania głosowe, aby umożliwić sterowanie odtwarzaniem, np. „zatrzymaj muzykę” i „następny utwór”, oraz dopasowywać te polecenia do odpowiednich wywołań sesji multimediów, takich jak onPause() i onSkipToNext().

Szczegółowe informacje o tym, jak w aplikacji wdrażać działania odtwarzania sterowane głosem, znajdziesz w artykule Asystent Google i aplikacje multimedialne.

Wdrażanie zabezpieczeń przed rozpraszaniem uwagi

Podczas korzystania z Androida Auto telefon użytkownika jest podłączony do głośników samochodu, dlatego musisz podjąć dodatkowe środki ostrożności, aby nie rozpraszać uwagi kierowcy.

Wyciszanie alarmów w samochodzie

Aplikacje multimedialne w Androidzie Auto nie mogą rozpoczynać odtwarzania dźwięku przez głośniki samochodowe, chyba że użytkownik rozpocznie odtwarzanie, na przykład przez naciśnięcie przycisku odtwarzania. Nawet alarm zaprogramowany przez użytkownika w aplikacji do obsługi multimediów nie może włączać odtwarzania muzyki przez głośniki samochodowe.

Aby spełnić ten wymóg, aplikacja może używać sygnału CarConnection przed odtworzeniem dźwięku. Aplikacja może sprawdzić, czy telefon wyświetla obraz na ekranie samochodu, obserwując LiveData dla typu połączenia z samochodem i sprawdzając, czy jest on równy CONNECTION_TYPE_PROJECTION.

Jeśli telefon użytkownika przesyła obraz, aplikacje do multimediów, które obsługują alarmy, muszą wykonywać jedną z tych czynności:

  • Wyłącz alarm.
  • odtwarzanie alarmu przez STREAM_ALARMi zapewnienie na ekranie telefonu interfejsu do wyłączania alarmu;

Obsługa reklam medialnych

Domyślnie Android Auto wyświetla powiadomienie, gdy metadane multimediów ulegną zmianie podczas odtwarzania dźwięku. Gdy aplikacja multimedialna przełączy się z odtwarzania muzyki na wyświetlanie reklamy, wyświetlenie powiadomienia użytkownikowi może go rozpraszać. Aby w tym przypadku Android Auto nie wyświetlał powiadomienia, ustaw klucz metadanych multimediów METADATA_KEY_IS_ADVERTISEMENT na METADATA_VALUE_ATTRIBUTE_PRESENT, jak pokazano w tym fragmencie kodu:

Kotlin

import androidx.media.utils.MediaConstants

override fun onPlayFromMediaId(mediaId: String, extras: Bundle?) {
    MediaMetadataCompat.Builder().apply {
        if (isAd(mediaId)) {
            putLong(
                MediaConstants.METADATA_KEY_IS_ADVERTISEMENT,
                MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
        }
        // ...add any other properties you normally would.
        mediaSession.setMetadata(build())
    }
}

Java

import androidx.media.utils.MediaConstants;

@Override
public void onPlayFromMediaId(String mediaId, Bundle extras) {
    MediaMetadataCompat.Builder builder = new MediaMetadataCompat.Builder();
    if (isAd(mediaId)) {
        builder.putLong(
            MediaConstants.METADATA_KEY_IS_ADVERTISEMENT,
            MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT);
    }
    // ...add any other properties you normally would.
    mediaSession.setMetadata(builder.build());
}

Obsługa błędów ogólnych

Gdy w aplikacji wystąpi błąd, ustaw stan odtwarzania na STATE_ERROR i wyświetl komunikat o błędzie za pomocą metody setErrorMessage(). Pełną listę kodów błędów, których możesz używać podczas ustawiania komunikatu o błędzie, znajdziesz w PlaybackStateCompat. Komunikaty o błędach muszą być widoczne dla użytkowników i muszą być zlokalizowane w jego bieżącym języku. Android Auto i Android Automotive OS mogą wyświetlić użytkownikowi komunikat o błędzie.

Jeśli na przykład treści nie są dostępne w bieżącym regionie użytkownika, możesz użyć kodu błędu ERROR_CODE_NOT_AVAILABLE_IN_REGION podczas ustawiania komunikatu o błędzie.

Kotlin

mediaSession.setPlaybackState(
    PlaybackStateCompat.Builder()
        .setState(PlaybackStateCompat.STATE_ERROR)
        .setErrorMessage(PlaybackStateCompat.ERROR_CODE_NOT_AVAILABLE_IN_REGION, getString(R.string.error_unsupported_region))
        // ...and any other setters.
        .build())

Java

mediaSession.setPlaybackState(
    new PlaybackStateCompat.Builder()
        .setState(PlaybackStateCompat.STATE_ERROR)
        .setErrorMessage(PlaybackStateCompat.ERROR_CODE_NOT_AVAILABLE_IN_REGION, getString(R.string.error_unsupported_region))
        // ...and any other setters.
        .build());

Więcej informacji o stanach błędów znajdziesz w artykule Korzystanie z sesji multimediów: stany i błędy.

Jeśli użytkownik Androida Auto musi otworzyć aplikację na telefonie, aby rozwiązać problem, przekaż mu tę informację w wiadomości. Na przykład komunikat o błędzie może zawierać komunikat „Zaloguj się w aplikacji [nazwa aplikacji]” zamiast „Zaloguj się”.

Inne materiały

Dalej
Dodaj obsługę Androida Auto