Şablonlu medya uygulaması oluşturma

Şablonlu medya uygulamaları beta sürümündedir

Şu anda herkes Google Play Store'daki dahili test ve kapalı test kanallarında şablonlu medya uygulamaları yayınlayabilir. Açık kanallarda ve üretim kanallarında yayınlamaya daha sonra izin verilecektir.

Erken erişim iş ortağı olmak için kendinizi aday gösterin →

Araç Uygulama Kitaplığı şablonlarını kullanan medya uygulamaları, medya tarama ve oynatma deneyimlerini özelleştirirken bu deneyimin araç ekranları için optimize edilmesini ve sürüş sırasında dikkat dağıtıcı unsurları en aza indirmesini sağlayabilir.

Bu kılavuzda, telefonda ses çalan bir medya uygulamanızın olduğu ve medya uygulamanızın Android medya uygulaması mimarisine uygun olduğu varsayılmaktadır. Araç Uygulama Kitaplığı, uygulama içi deneyimi Arabalar için medya uygulamaları oluşturma MediaBrowser veri yapısı kullanılarak oluşturulan şablonlar yerine başka şablonlarla değiştirmenize olanak tanır. Oynatma kontrolleri için MediaSession, öneriler ve diğer akıllı deneyimler için ise MediaBrowserService veya MediaLibraryService sağlamanız gerekir.

Park-to-drive deneyimleri artık beta sürümünde kullanılabilir

Şablonlu medya uygulamaları artık Android Automotive OS'te park halinden sürüşe geçiş deneyimi ekleyebilir. Bu sayede uygulamanız, park halindeyken uyarlanabilir yerel etkinlikler ekleyebilir ve araç hareket halindeyken şablonlu medya oynatma deneyimine sorunsuz bir şekilde geçiş yapabilir.

Park-to-drive deneyimiyle yayınlama isteğinizi bildirin →

Uygulamanızın manifest dosyasını yapılandırma

Arabalar için Android Uygulama Kitaplığı'nı kullanma bölümünde açıklanan adımlara ek olarak, şablonlu medya uygulamaları için aşağıdakiler gereklidir:

Manifestinizde kategori desteğini beyan etme

Uygulamanızın, CarAppService öğesinin intent filtresinde androidx.car.app.category.MEDIA araba uygulaması kategorisini beyan etmesi gerekir.

<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>

MediaPlaybackTemplate erişimi elde etmek için uygulamanızın manifest dosyasında androidx.car.app.MEDIA_TEMPLATES iznini de beyan etmesi gerekir:

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

Minimum Car App API düzeyini ayarlama

MediaPlaybackTemplate kullanan medya uygulamaları yalnızca CAL API 8 ve sonraki sürümlerde desteklenir. Minimum Car App API level değerinizin 8 olarak ayarlandığından emin olun.

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

İlişkilendirme simgesi sağlama

Car Uygulama Kitaplığı kullanılarak oluşturulan medya uygulamaları için atıf simgesi eklediğinizden emin olun.

Android Auto desteğini beyan etme

Uygulamanızın manifest dosyasında aşağıdakilerin bulunduğundan emin olun:

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

Ardından, xml kaynaklarınızda şablon bildirimini automotive_app_desc.xml öğesine ekleyin. Şu şekilde görünmelidir:

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

Android Automotive OS desteğini beyan etme

Araç Uygulama Kitaplığı'nın etkin olduğu bir medya uygulamasını Android Automotive OS'te iki farklı şekilde dağıtabilirsiniz: tek bir APK veya iki ayrı APK olarak. Tek bir APK dağıtırsanız bu APK, Araç Uygulama Kitaplığı ana makinesiyle Android Automotive OS için etkinleştirilmiş araçları destekler. Etkinleştirilmemiş araçlarda ise eski Android sürümleri (Android 10 - Android 13) için bile MediaBrowserService veya MediaLibraryService uygulamasına geri döner. İki ayrı APK dağıtmayı seçerseniz uygulamanızın MediaBrowserService veya MediaLibraryService sürümünü etkileme endişesi duymadan Araç Uygulama Kitaplığı sürümündeki yeni eklemeleri güncelleyebilirsiniz.

Tek bir APK dağıtma

Araba Uygulama Kitaplığı ve uygulamanızın MediaBrowserService veya MediaLibraryService sürümleri için tek bir APK dağıtırken android.software.car.templates_host.media değerini android:required="false" olarak ayarlamak çok önemlidir.

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

Ardından, AAOS için Car App Library yönergelerini uygulayın ve başlatılabilir bir CarAppActivity (veya trambolin etkinliği) ekleyin. Manifest dosyasında etkinliği android:enabled="false" olarak ayarlamanız gerekir. Ardından, CarAppActivity bileşenini alternatif olarak belirten MediaBrowserService beyanına bir meta veri etiketi ekleyin. Aşağıdaki örnek manifest dosyasına bakın:

<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>

Google Play dağıtımı

Araba Uygulama Kitaplığı ve MediaBrowserService veya MediaLibraryService içeren APK'nız, daha yüksek bir sürüm kodu ve Android 14'ü (34) hedefleyen minSdk ile etkinleştirilmelidir.

İki APK ile dağıtım

Biri Car App Library'yi, diğeri ise MediaBrowserService veya MediaLibraryService'yi kullanan iki ayrı APK dağıtmak için aşağıdaki adımları uygulayarak doğru araç özelliklerinin doğru şekilde hedeflendiğinden emin olun.

Uygulamanızın Araç Uygulama Kitaplığı sürümü için ayrı bir APK oluştururken android.software.car.templates_host.media değerini android:required=true olarak ayarlamanız gerekir. Bu sayede uygulama yalnızca Car App Library ana makinesi desteğiyle sertifikalandırılmış Android Automotive OS derlemelerinde dağıtılır.

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

android.software.car.templates_host.media öğesini kullanıp android:required=true olarak ayarlamanın yanı sıra, başlatılabilir Car App Library etkinliğiniz için Android Automotive OS'i etkinleştirmek üzere aşağıdaki adımları uygulayın.

Play Dağıtımı

Araç Uygulama Kitaplığı'nı kullanan APK, Automotive OS özel kanalında dağıtılmalıdır.

Sesli işlemleri destekleme

Uygulamanızı sesle etkinleştirerek kullanıcıların yaygın işlemleri ellerini kullanmadan tamamlamasına olanak tanıyın. Daha ayrıntılı uygulama talimatları için medya için sesli işlemleri destekleme konusuna bakın. Şablonlu bir medya uygulamasında sesli komut aldığınızda MediaBrowserService veya MediaLibraryService öğenizi arama sonuçlarıyla güncellemeniz gerekmez. Bunun yerine, medya oynatma şablonunuza bir işlem ekleyerek kullanıcının bu oynatma veya arama sorgusuna göre daha fazla içerik bulmasına olanak tanıyabilirsiniz. VC-1 kalite yönergesine uymak için sesli komutların desteklenmesi gerekir.

Oynatma şablonunuzu oluşturma

MediaPlaybackTemplate, Uygulama kitaplığı medya uygulamanızda medya oynatma bilgilerini gösterir. Bu şablon, başlık ve özelleştirilebilir işlemler içeren bir üstbilgi ayarlamanıza olanak tanır. Medya bilgileri ve oynatma kontrolleri, uygulamanızın MediaSession durumuna göre ana makine tarafından doldurulur.

Şekil 1: Üst kısımda sırayı açmak için başlık işlemi içeren MediaPlaybackTemplate.

Bu kod örneğinde, kullanıcının şarkı sırasının bulunduğu ekrana gitmesine olanak tanıyan bir başlık işlemi ayarlayan örnek bir oynatma şablonunun nasıl oluşturulacağı gösterilmektedir.

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()

MediaPlaybackTemplate kullanırken CarAppService uygulamanızdaki MediaPlaybackManager yöntemini kullanarak bir MediaSession jetonu kaydedin. Bunu yapmazsanız ana makineye MediaPlaybackTemplate gönderildiğinde hata gösterilir.

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, medya oynatma bilgilerini ve kontrollerini Android Auto'da göstermek için gereklidir. Bu, ana makinenin medyaya özel bildirimler oluşturması için de önemlidir.

Standart MediaSessionCompat.Token yerine PlatformToken kullanan Media3 kitaplığını kullanan uygulamalarda, MediaLibrarySession.Callback uygulamanızda oturumun temel platform jetonunu (session.platformToken) döndüren özel bir SessionCommand uygulamanız gerekir. CarAppService uygulamanızda bu özel komutu oturuma gönderin. Platform jetonunu aldıktan sonra MediaSessionCompat.Token.fromToken(platformToken) kullanarak dönüştürün ve bu uyumluluk jetonunu .registerMediaPlaybackToken() içindeki Car Uygulama kitaplığı'na iletin.

Şablonları kullanarak medyayı düzenleme

Şarkı veya albüm gibi medyaları göz atmak için düzenlemek istiyorsanız SectionedItemTemplate kullanmanızı öneririz. Bu sayede, resim ve metin öğelerinin listelerini birleştiren düzenler oluşturmak için GridSection ve RowSection öğelerini birlikte kullanabilirsiniz.

Şekil 2: RowSection içeren bir SectionedItemTemplate ve ardından GridSection

TabTemplate içinde SectionedItemTemplate kullanma

Uygulamanızdaki medyayı kategorilere ayırmanın kolay bir yolu, TabTemplate içinde SectionedItemTemplate kullanmaktır.

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

Car Uygulama kitaplığı 1.9 bileşenleri ve özellikleri

Car Uygulama kitaplığı API 1.9 sürümü, benzersiz gezinme özellikleri için özelleştirilmiş bileşenler sunar. Bunlar arasında çipler, ilerleme çubukları, sıkıştırılmış öğeler, etkileşimli ve genişletilmiş başlık, öne çıkan bölümler ve banner'lar yer alır.

Şekil 3: Chips, Condensed Items, Interactive Header, Grid Items ve Minimized Control Panel içeren bir SectionedItemTemplate

Şekil 4: Expanded Header, Spotlight Sections ve Progress Bars öğelerini içeren iki medya tarama ekranı

Bu şablonları kullanarak medya uygulamanızın kullanıcı arayüzünü tasarlama hakkında daha fazla bilgi için Medya uygulamaları başlıklı makaleyi inceleyin.

Oynatma kontrollerine gitme

Medya öğelerine göz atarken kullanıcının dikkatini dağıtmadan hızlıca MediaPlaybackTemplate ekranına gidebilmesi önemlidir. MFT-1 kalite şartını karşılamak için uygulamanızda tüm medya tarama ekranlarından MediaPlaybackTemplate ekranına erişmenin bir yolu olmalıdır.

SectionedItemTemplate kullanıyorsanız medya oynatma ekranına gitmenizi sağlayan bir işlem düğmesi ekleyerek bunu yapabilirsiniz. Standart Car Uygulama Kitaplığı Action.MEDIA_PLAYBACK işlemini kullanın. Medya uygulamaları bu işlemi küçültülmüş kontrol paneli olarak gösterir. Car App Library API 1.9 veya sonraki sürümleri kullanıyorsanız MFT-1 kalite şartını karşılamak için bu işlem gereklidir. Diğer şablonlarda ise bunu yapmak için üstbilgi işlemi kullanılabilir.

Sistem medya oynatma intent'lerini işleme

Uygulama, medya kartı gibi bir sistem medya oynatma yüzeyinden başlatıldığında kullanıcının MediaPlaybackTemplate sayfasına yönlendirilmesi gerekir. Kullanıcılara sorunsuz bir deneyim sunmak için medya uygulamalarının bu Intent Action işlemini gerçekleştirmesini zorunlu kılıyoruz.

Car App Library bileşeninizin (CarAppActivity veya trambolin Activity) intent filtresine androidx.car.app.media.action.SHOW_MEDIA_PLAYBACK işlemini ekleyin.

onNewIntent() öğesinin çağrılması için etkinliğinizde singleTask veya singleTop değerinde bir launchMode kullanıldığından emin olun.

<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>

Session sınıfınızda, gelen intent'i ayrıştırmak için onNewIntent() yöntemini geçersiz kılın. Gelen intent işlemi SHOW_MEDIA_PLAYBACK ile eşleşirse kullanıcıyı Ne Çalıyor? ekranınıza yönlendirin.

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

Trambolin etkinliği kullanıyorsanız onCreate() içinde intent işlemini kontrol edin. finish() yöntemini çağırmadan önce bu işlemi CarAppActivity oluşturma amacına iletin.

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