Mem-build aplikasi media dengan template

Aplikasi media dengan template masih dalam versi beta
Saat ini, siapa pun dapat memublikasikan aplikasi media menggunakan template ke jalur pengujian internal dan jalur pengujian tertutup di Google Play Store. Publikasi ke jalur terbuka dan jalur produksi akan diizinkan pada lain waktu.

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 aplikasi media Anda sesuai dengan arsitektur aplikasi media Android. Koleksi aplikasi Mobil memberi Anda kemampuan untuk mengganti pengalaman aplikasi dengan template, bukan yang dibuat menggunakan struktur data MediaBrowser Membuat aplikasi media untuk mobil. Anda tetap harus menyediakan MediaSession untuk kontrol pemutaran, dan MediaBrowserService atau MediaLibraryService, yang digunakan untuk rekomendasi dan pengalaman cerdas lainnya.

Pengalaman parkir ke berkendara kini tersedia dalam versi beta
Aplikasi media dengan template kini memenuhi syarat untuk menambahkan pengalaman parkir ke mengemudi di Android Automotive OS. Hal ini memungkinkan aplikasi Anda menambahkan aktivitas native adaptif saat diparkir dan beralih dengan lancar ke pengalaman pemutaran media yang menggunakan template saat mobil sedang dikemudikan.

Mengonfigurasi manifes aplikasi Anda

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

Mendeklarasikan dukungan kategori dalam manifes Anda

Aplikasi Anda harus mendeklarasikan kategori aplikasi mobil androidx.car.app.category.MEDIA 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>

Memberikan 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. Hasilnya 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 mendukung Library Aplikasi Mobil di Android Automotive OS: sebagai APK tunggal atau sebagai dua APK terpisah. Jika Anda mendistribusikan satu APK, APK tersebut akan mendukung kendaraan yang diaktifkan untuk Android Automotive OS dengan host Koleksi aplikasi Mobil dan beralih 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 mengupdate penambahan baru ke versi Library Aplikasi Mobil tanpa khawatir akan memengaruhi versi MediaBrowserService atau MediaLibraryService aplikasi Anda.

Mendistribusikan satu APK

Saat mendistribusikan satu APK untuk Library Aplikasi Mobil dan versi MediaBrowserService atau MediaLibraryService aplikasi Anda, penting untuk menetapkan android.software.car.templates_host.media 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 berikut:

<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 satu lagi 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 dari aplikasi Anda, Anda harus menetapkan android.software.car.templates_host.media ke android:required=true. Hal ini memastikan aplikasi hanya didistribusikan di build Android Automotive OS yang disertifikasi dengan dukungan untuk host Koleksi aplikasi Mobil.

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

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

Play Distribution

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

Mendukung voice action

Aktifkan suara di aplikasi Anda agar pengguna dapat menyelesaikan tindakan umum secara handsfree. Lihat mendukung voice action untuk media untuk mengetahui petunjuk penerapan yang lebih mendetail. Dengan aplikasi media yang menggunakan 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 untuk memungkinkan pengguna menemukan lebih banyak konten berdasarkan kueri pemutaran atau penelusuran tersebut. Mendukung perintah suara diperlukan untuk memenuhi pedoman kualitas VC-1.

Membuat Template Pemutaran

MediaPlaybackTemplate menampilkan informasi pemutaran media di aplikasi media Library Aplikasi Mobil Anda. Template ini memungkinkan penetapan 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 sepanjang 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 Anda menggunakan MediaPlaybackTemplate, daftarkan token MediaSession menggunakan MediaPlaybackManager di CarAppService Anda. Jika tidak, 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 mengekspos informasi dan kontrol pemutaran media ke Android Auto. Hal ini juga penting bagi host untuk membuat notifikasi khusus media.

Untuk aplikasi yang menggunakan library Media3, yang menggunakan PlatformToken, bukan MediaSessionCompat.Token standar, Anda harus mengimplementasikan SessionCommand kustom di MediaLibrarySession.Callback yang menampilkan token platform yang mendasari sesi: session.platformToken. Di CarAppService, kirim perintah kustom ini ke sesi. Setelah Anda 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 yang akan dijelajahi 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 dengan GridSection

Menggunakan SectionedItemTemplate di dalam TabTemplate

Salah satu cara mudah untuk mengategorikan media dalam aplikasi Anda adalah menggunakan SectionedItemTemplate di dalam 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, Status Progres, 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 terkait cara mendesain antarmuka pengguna aplikasi media yang menggunakan template ini, lihat Aplikasi media.

Saat menjelajahi media, penting bagi pengguna untuk dapat dengan cepat membuka MediaPlaybackTemplate dengan gangguan minimal.Untuk memenuhi persyaratan kualitas MFT-1, 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 pemutaran media. Gunakan tindakan Action.MEDIA_PLAYBACK Library Aplikasi Mobil standar. Aplikasi media akan menampilkan tindakan ini sebagai Panel kontrol yang diperkecil, yang diperlukan untuk memenuhi persyaratan kualitas MFT-1 jika Anda menggunakan Koleksi aplikasi Mobil API 1.9 atau yang lebih tinggi. Untuk template lain, tindakan header adalah cara lain untuk mencapai hal ini.

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 filter intent komponen Koleksi aplikasi Mobil (CarAppActivity atau trampolin Activity).

Pastikan aktivitas Anda menggunakan launchMode dari 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 yang masuk. Jika tindakan intent yang masuk cocok dengan SHOW_MEDIA_PLAYBACK, arahkan pengguna ke layar Now Playing.

@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();
    }
}