Mem-build aplikasi media dengan template

Aplikasi media berbasis template masih dalam versi beta
Saat ini, siapa pun dapat memublikasikan aplikasi media berbasis template ke jalur pengujian internal dan pengujian tertutup di Google Play Store. Publikasi ke jalur terbuka dan jalur produksi akan diizinkan pada lain waktu.
Ajukan diri Anda untuk menjadi partner akses awal →

Aplikasi media yang menggunakan template Library Aplikasi Mobil dapat menyesuaikan pengalaman penjelajahan dan pemutaran media sekaligus memastikan pengalaman tersebut dioptimalkan untuk layar mobil dan meminimalkan gangguan saat mengemudi.

Panduan ini mengasumsikan bahwa Anda sudah memiliki aplikasi media yang memutar audio di ponsel dan bahwa aplikasi media Anda sesuai dengan arsitektur aplikasi media Android. Library Aplikasi Mobil memberi Anda kemampuan untuk mengganti pengalaman dalam aplikasi dengan template, bukan yang dibuat menggunakan struktur data Buat aplikasi media untuk mobil MediaBrowser. Anda tetap harus menyediakan MediaSession untuk kontrol pemutaran, dan MediaBrowserService atau MediaLibraryService, yang digunakan untuk rekomendasi dan pengalaman smart lainnya.

Mengonfigurasi manifes aplikasi Anda

Selain langkah-langkah yang dijelaskan dalam Menggunakan Library Aplikasi Android untuk Mobil, hal berikut diperlukan untuk aplikasi media berbasis template:

Mendeklarasikan dukungan kategori dalam manifes Anda

Aplikasi Anda harus mendeklarasikan androidx.car.app.category.MEDIA kategori aplikasi mobil dalam filter intent CarAppService.

<application>
    ...
   <service
       ...
        android:name=".MyCarAppService"
        android:exported="true">
      <intent-filter>
        <action android:name="androidx.car.app.CarAppService" />
        <category android:name="androidx.car.app.category.MEDIA"/>
      </intent-filter>
    </service>
    ...
<application>

Untuk mendapatkan akses ke MediaPlaybackTemplate, aplikasi Anda juga harus mendeklarasikan izin androidx.car.app.MEDIA_TEMPLATES dalam file manifesnya:

<manifest ...>
  ...
  <uses-permission android:name="androidx.car.app.MEDIA_TEMPLATES"/>
  ...
</manifest>

Menetapkan level API aplikasi mobil minimum

Aplikasi media yang menggunakan MediaPlaybackTemplate hanya didukung di CAL API 8 dan yang lebih tinggi. Pastikan Car App API level minimum Anda ditetapkan ke 8.

<application ...>
  ...
  <meta-data
    android:name="androidx.car.app.minCarApiLevel"
    android:value="8"/>
  ...
</application>

Menyediakan ikon atribusi

Pastikan untuk menambahkan ikon atribusi untuk aplikasi media yang dibuat menggunakan Library Aplikasi Mobil.

Mendeklarasikan dukungan Android Auto

Pastikan hal berikut disertakan dalam manifes aplikasi Anda:

<application>
  ...
  <meta-data android:name="com.google.android.gms.car.application"
      android:resource="@xml/automotive_app_desc"/>
  ...
</application>

Kemudian, tambahkan deklarasi template ke automotive_app_desc.xml di resource xml Anda. Tampilannya akan terlihat seperti berikut:

<automotiveApp xmlns:android="http://schemas.android.com/apk/res/android">
 <uses name="media"/>
 <uses name="template"/>
</automotiveApp>

Mendeklarasikan dukungan Android Automotive OS

Ada dua cara berbeda untuk mendistribusikan aplikasi media yang diaktifkan Library Aplikasi Mobil di Android Automotive OS: sebagai APK tunggal atau sebagai dua APK terpisah. Jika Anda mendistribusikan APK tunggal, APK tersebut akan mendukung kendaraan yang diaktifkan untuk Android Automotive OS dengan host Library Aplikasi Mobil dan kembali ke aplikasi MediaBrowserService atau MediaLibraryService jika tidak, bahkan untuk versi Android yang lebih lama (Android 10 - Android 13). Jika memilih untuk mendistribusikan dua APK terpisah, Anda dapat memperbarui penambahan baru ke versi Library Aplikasi Mobil dengan lebih mudah tanpa khawatir akan memengaruhi versi MediaBrowserService atau MediaLibraryService aplikasi Anda.

Mendistribusikan APK tunggal

Saat mendistribusikan APK tunggal untuk Library Aplikasi Mobil dan MediaBrowserService atau MediaLibraryService versi aplikasi Anda, penting untuk menetapkan "" ke android:required="false".

<uses-feature android:name="android.software.car.templates_host.media" android:required="false"/>

Selanjutnya, ikuti panduan Library Aplikasi Mobil untuk AAOS dan perkenalkan CarAppActivity yang dapat diluncurkan (atau aktivitas trampolin). Anda harus menetapkan aktivitas ke android:enabled="false" dalam manifes. Selanjutnya, tambahkan tag metadata ke deklarasi MediaBrowserService yang menunjukkan komponen CarAppActivity sebagai pengganti. Lihat contoh manifes di bawah:

<service android:name=".media.MyMediaService"
    android:exported="true"
    android:label="@string/app_name">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaLibraryService"/>
    </intent-filter>

    <!-- Link to Car App Library Activity -->
    <meta-data
        android:name="androidx.car.app.media.CalMediaActivityComponent" 
        android:value="com.example.mediaapp.LaunchableTrampoline"/>
</service>

<activity
    android:name=".LaunchableTrampoline"
    android:exported="true"
    android:theme="@android:style/Theme.DeviceDefault.NoActionBar"
    android:launchMode="singleTask"
    android:label="@string/app_name_cal"
    android:enabled="false"> <!-- Set to false -->

    <meta-data android:name="distractionOptimized" android:value="true" />

    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <action android:name="androidx.car.app.media.action.SHOW_MEDIA_PLAYBACK"/>
        <category android:name="android.intent.category.LAUNCHER"/>
    </intent-filter>
</activity>

Distribusi Play

APK Anda dengan Library Aplikasi Mobil dan MediaBrowserService atau MediaLibraryService harus diaktifkan dengan kode versi yang lebih tinggi dan minSdk yang menargetkan Android 14 (34).

Mendistribusikan dengan dua APK

Untuk mendistribusikan dua APK terpisah, satu menggunakan Library Aplikasi Mobil dan yang lainnya menggunakan MediaBrowserService atau MediaLibraryService, ikuti langkah-langkah berikut untuk memastikan kemampuan kendaraan yang benar ditargetkan dengan benar.

Saat membuat APK terpisah untuk versi Library Aplikasi Mobil aplikasi Anda, Anda harus menetapkan android.software.car.templates_host.media ke android:required=true. Hal ini memastikan aplikasi hanya didistribusikan pada build Android Automotive OS yang disertifikasi dengan dukungan untuk host Library Aplikasi Mobil.

<uses-feature android:name="android.software.car.templates_host.media" android:required="true"/>

Selain menggunakan android.software.car.templates_host.media dan menetapkannya ke android:required=true di atas, ikuti langkah-langkah berikut untuk mengaktifkan Android Automotive OS untuk aktivitas Library Aplikasi Mobil yang dapat diluncurkan.

Distribusi Play

APK yang menggunakan Library Aplikasi Mobil harus didistribusikan di jalur khusus Automotive OS.

Mendukung voice action

Aktifkan suara di aplikasi Anda untuk memungkinkan pengguna menyelesaikan tindakan umum tanpa menggunakan tangan. Lihat mendukung voice action untuk media guna mengetahui petunjuk penerapan yang lebih mendetail. Dengan aplikasi media berbasis template, jika Anda menerima perintah suara, Anda tidak perlu memperbarui MediaBrowserService atau MediaLibraryService dengan hasil penelusuran. Sebagai gantinya, pertimbangkan untuk menambahkan tindakan di template pemutaran media Anda agar pengguna dapat menemukan lebih banyak konten berdasarkan kueri pemutaran atau penelusuran tersebut. Mendukung perintah suara diperlukan untuk memenuhi VC-1 panduan kualitas.

Membuat Template Pemutaran

MediaPlaybackTemplate menampilkan informasi pemutaran media di aplikasi media Library Aplikasi Mobil Anda. Template ini memungkinkan Anda menetapkan header dengan judul dan tindakan yang dapat disesuaikan, sementara informasi media dan kontrol pemutaran diisi oleh host berdasarkan status MediaSession aplikasi Anda.

Pemutar musik menampilkan Sounds of Spring oleh Summer Fielding dengan potret persegi seorang wanita yang sedang bermain gitar.

Gambar 1: MediaPlaybackTemplate dengan tindakan header untuk membuka antrean di bagian atas.

Contoh kode ini menunjukkan cara membuat contoh template pemutaran yang menetapkan tindakan header yang memungkinkan pengguna membuka layar dengan antrean lagu.

val playbackTemplate = MediaPlaybackTemplate.Builder()
      .setHeader(
        Header.Builder()
          .setStartHeaderAction(Action.BACK)
          .addEndHeaderAction(
                Action.Builder()
                  .setTitle(model.context.getString(R.string.queue_button_title))
                  .setIcon(
                    CarIcon.Builder(
                        IconCompat.createWithResource(
                          model.context,
                          R.drawable.gs_queue_music_vd_theme_24,
                        ))
                      .build())
                  .setOnClickListener(showQueueScreen())
                  .build())
          .setTitle(model.context.getString(R.string.media_playback_view_title))
          .build())
      .build()

Saat menggunakan MediaPlaybackTemplate, daftarkan token MediaSession menggunakan MediaPlaybackManager di CarAppService Anda. Jika tidak melakukannya, error akan ditampilkan saat MediaPlaybackTemplate dikirim ke host.

import androidx.car.app.media.MediaPlaybackManager
…

override fun onCreateSession(sessionInfo: SessionInfo): Session {
    return object : Session() {
        …

        init {
          lifecycle.addObserver(
            LifecycleEventObserver { _, event ->
              if (event == ON_CREATE) {
                val token = ... // MediaSessionCompat.Token
                (carContext.getCarService(CarContext.MEDIA_PLAYBACK_SERVICE) as MediaPlaybackManager)
                  .registerMediaPlaybackToken(token)
              }
              ...
            }
          )
        }
    }
}

.registerMediaPlaybackToken diperlukan untuk menampilkan informasi dan kontrol pemutaran media ke Android Auto. Hal ini juga penting agar host dapat membuat notifikasi khusus media.

Untuk aplikasi yang menggunakan library Media3, yang menggunakan PlatformToken, bukan MediaSessionCompat.Token standar, Anda harus menerapkan SessionCommand kustom di MediaLibrarySession.Callback yang menampilkan token platform yang mendasarinya: session.platformToken. Di CarAppService, kirim perintah kustom ini ke sesi. Setelah menerima token platform, konversikan menggunakan MediaSessionCompat.Token.fromToken(platformToken) dan teruskan token kompatibilitas ini ke Library Aplikasi Mobil di .registerMediaPlaybackToken().

Mengatur media menggunakan template

Untuk mengatur media untuk penjelajahan seperti lagu atau album, sebaiknya gunakan SectionedItemTemplate, yang memungkinkan Anda menggunakan GridSection dan RowSection bersama-sama untuk membuat tata letak yang menggabungkan daftar gambar dan item teks.

Antarmuka aplikasi musik menampilkan lagu dan album yang baru diputar, termasuk dua baris vertikal dan tiga potret gambar album horizontal.

Gambar 2: SectionedItemTemplate yang berisi RowSection diikuti oleh GridSection

Menggunakan SectionedItemTemplate di dalam TabTemplate

Salah satu cara mudah untuk mengategorikan media dalam aplikasi Anda adalah menggunakan yang SectionedItemTemplate di dalam yang TabTemplate.

val template =
      SectionedItemTemplate.Builder()...build();
val tabTemplate = 
      TabTemplate.Builder(tabCallback)
          .setTabContents(TabContents.Builder(template).build)
          .setHeaderAction(Action.APP_ICON)
          …
          .build();

Komponen dan fitur library aplikasi mobil 1.9

Car App Library API Versi 1.9 memperkenalkan komponen yang disesuaikan untuk kemampuan penjelajahan yang unik, seperti Chip, Progress Bar, Item Ringkas, Header Interaktif dan Diperluas, Bagian Sorotan dan Banner.

Antarmuka aplikasi musik menampilkan lagu dan album yang baru diputar, termasuk dua baris vertikal dan tiga potret gambar album horizontal.

Gambar 3: SectionedItemTemplate yang berisi Chips, Condensed Items, Interactive Header, Grid Items, dan Minimized Control Panel

Antarmuka aplikasi musik menampilkan lagu dan album yang baru diputar, termasuk dua baris vertikal dan tiga potret gambar album horizontal.

Gambar 4: Dua layar penjelajahan media yang menampilkan Expanded Header, Spotlight Sections, dan Progress Bars

Untuk detail selengkapnya tentang cara mendesain antarmuka pengguna aplikasi media menggunakan template ini, lihat Aplikasi media.

Saat menjelajahi media, pengguna harus dapat dengan cepat membuka MediaPlaybackTemplate dengan gangguan minimal.Untuk memenuhi MFT-1 persyaratan kualitas, aplikasi Anda harus memiliki cara untuk mengakses MediaPlaybackTemplate dari semua layar penjelajahan media.

Jika menggunakan SectionedItemTemplate, Anda dapat melakukannya dengan menambahkan tombol tindakan yang mengarahkan Anda ke layar pemutar media. Gunakan tindakan Action.MEDIA_PLAYBACK Library Aplikasi Mobil standar. Aplikasi media akan menampilkan tindakan ini sebagai Panel kontrol yang diminimalkan, yang diperlukan untuk memenuhi persyaratan kualitas MFT-1 jika Anda menggunakan Car App Library API 1.9 atau yang lebih tinggi. Untuk template lainnya, tindakan header adalah cara lain untuk melakukannya.

Menangani intent pemutaran media sistem

Pengguna harus diarahkan ke MediaPlaybackTemplate saat aplikasi diluncurkan dari platform pemutaran media sistem, seperti kartu media. Kami mewajibkan aplikasi media menangani Intent Action ini untuk memberikan pengalaman yang lancar bagi pengguna.

Tambahkan tindakan androidx.car.app.media.action.SHOW_MEDIA_PLAYBACK ke intent-filter komponen Library Aplikasi Mobil Anda (baik CarAppActivity maupun Activity trampolin Anda).

Pastikan aktivitas Anda menggunakan launchMode singleTask atau singleTop sehingga onNewIntent() dipanggil.

<activity
    android:name=".LaunchableTrampoline"
    android:exported="true"
    android:theme="@android:style/Theme.DeviceDefault.NoActionBar"
    android:launchMode="singleTask"
    android:label="@string/app_name_cal"
    android:enabled="false">

    <meta-data android:name="distractionOptimized" android:value="true" />

    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <action android:name="androidx.car.app.media.action.SHOW_MEDIA_PLAYBACK"/>
        <category android:name="android.intent.category.LAUNCHER"/>
    </intent-filter>
</activity>

Di class Session, ganti onNewIntent() untuk mengurai intent masuk. Jika tindakan intent masuk cocok dengan SHOW_MEDIA_PLAYBACK, arahkan pengguna ke layar yang sedang diputar.

@Override
public void onNewIntent(@NonNull Intent intent) {
    super.onNewIntent(intent);
    if (SHOW_MEDIA_PLAYBACK.equals(intent.getAction())) {
        ScreenManager screenManager = getCarContext().getCarService(ScreenManager.class);
        // Avoid redundant navigation if already on the playing screen
        if (screenManager.getTop() instanceof MyMediaPlayScreen) {
            return;
        }
        screenManager.push(MyMediaPlayScreen.createScreenFromPlaying(
                getCarContext(), mMediaSessionController));
    }
}

Jika Anda menggunakan aktivitas trampolin, periksa tindakan intent dalam onCreate(). Teruskan tindakan ini ke intent pembuatan CarAppActivity sebelum memanggil finish().

public class LaunchableTrampoline extends AppCompatActivity {
    private static final String SHOW_MEDIA_PLAYBACK = "androidx.car.app.media.action.SHOW_MEDIA_PLAYBACK";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Intent receivedIntent = getIntent();
        String action;

        if (SHOW_MEDIA_PLAYBACK.equals(receivedIntent.getAction())) {
            action = SHOW_MEDIA_PLAYBACK;
        } else {
            action = Intent.ACTION_MAIN;
        }

        Intent intent = new Intent(action);
        intent.setClassName(getPackageName(), "androidx.car.app.activity.CarAppActivity");
        startActivity(intent);
        finish();
    }
}