تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تفعيل عنصر التحكّم في التشغيل

لتفعيل تشغيل الوسائط في Android Auto وAndroid Automotive OS (AAOS)، نفِّذ عناصر التحكّم في التشغيل من خلال تسجيل جلسة وسائط ومعالجة طُرق معاودة الاتصال الخاصة بها. توضّح هذه الصفحة كيفية تنفيذ ما يلي:

سجِّل عنصر MediaSessionCompat في خدمة متصفّح الوسائط.
نفِّذ طرق MediaSessionCompat.Callback للردّ على طلبات المستخدمين بشأن التشغيل.
ضبط إجراءات التشغيل العادية والمخصّصة
اضبط حالة التشغيل الأولية لجلسة الوسائط.
أضِف رموزًا للإشارة إلى تنسيق الصوت.
إنشاء روابط من عناصر الوسائط التي يتم تشغيلها حاليًا

يرسل كلّ من Android Auto وAndroid Automotive OS أوامر التحكّم في التشغيل من خلال MediaSessionCompat لخدمتك. يجب تسجيل جلسة وتنفيذ طرق معاودة الاتصال المرتبطة بها.

تسجيل جلسة وسائط

في طريقة onCreate الخاصة بخدمة متصفّح الوسائط، أنشئ مثيلاً من MediaSessionCompat، ثم استدعِ setSessionToken لتسجيل جلسة الوسائط. يوضّح مقتطف الرمز البرمجي التالي كيفية إنشاء جلسة وسائط وتسجيلها:

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

عند إنشاء عنصر جلسة الوسائط، عليك ضبط عنصر ردّ الاتصال الذي يتم استخدامه للتعامل مع طلبات التحكّم في التشغيل. يمكنك إنشاء عنصر معاودة الاتصال هذا من خلال توفير تنفيذ للفئة MediaSessionCompat.Callback لتطبيقك. يناقش القسم التالي كيفية تنفيذ هذا العنصر.

تنفيذ أوامر التشغيل

عندما يطلب المستخدم تشغيل وسائط من تطبيقك، يستخدم نظام التشغيل Android Automotive وAndroid Auto فئة MediaSessionCompat.Callback من عنصر MediaSessionCompat في تطبيقك الذي تم الحصول عليه من خدمة متصفّح الوسائط في تطبيقك. عندما يريد المستخدم التحكّم في تشغيل المحتوى، مثل إيقاف التشغيل مؤقتًا أو الانتقال إلى المقطع الصوتي التالي، يستدعي نظاما التشغيل Android Auto وAndroid Automotive OS إحدى طرق عنصر معاودة الاتصال.

للتعامل مع تشغيل المحتوى، يجب أن يوسّع تطبيقك الفئة المجردة MediaSessionCompat.Callback وأن ينفّذ الطرق التي يتيحها تطبيقك.

نفِّذ كل طريقة من طرق معاودة الاتصال هذه التي تتناسب مع نوع المحتوى الذي يقدّمه تطبيقك:

onPrepare: يستدعي نظام التشغيل Android Automotive OS هذه الطريقة عند تغيير مصدر الوسائط.
onPlay: يتم استدعاؤه عندما يختار المستخدم تشغيل المحتوى بدون تحديد عنصر معيّن. يجب أن يشغّل تطبيقك المحتوى التلقائي أو يستأنف التشغيل إذا تم إيقافه مؤقتًا باستخدام onPause.

ملاحظة: يجب ألا يبدأ تطبيقك تشغيل الموسيقى تلقائيًا عند اتصال نظام التشغيل Android Automotive أو Android Auto بخدمة متصفّح الوسائط. لمزيد من المعلومات، اطّلِع على ضبط PlaybackState الأولي.
onPlayFromMediaId: يتم استدعاؤه عندما يختار المستخدم تشغيل عنصر معيّن. تتلقّى الطريقة المعرّف الذي خصّصته خدمة متصفّح الوسائط لعنصر الوسائط في التسلسل الهرمي للمحتوى.
onPlayFromSearch: يتم استدعاؤه عندما يختار المستخدم تشغيل المحتوى من طلب بحث. يجب أن يتخذ التطبيق خيارًا مناسبًا استنادًا إلى سلسلة البحث التي تم إدخالها.
onPause: يتم استدعاؤه عندما يختار المستخدم إيقاف التشغيل مؤقتًا.
onSkipToNext: يتم استدعاؤه عندما يختار المستخدم الانتقال إلى العنصر التالي.
onSkipToPrevious: يتم استدعاؤه عندما يختار المستخدم الانتقال إلى العنصر السابق.
onStop: يتم استدعاؤه عندما يختار المستخدم إيقاف التشغيل. يمكنك تجاهل هذه الطرق في تطبيقك لتقديم النتيجة المحدّدة. لست بحاجة إلى تنفيذ طريقة إذا كان الغرض منها غير متوافق مع تطبيقك. على سبيل المثال، إذا كان تطبيقك يعرض بثًا مباشرًا، مثل بث رياضي، لست بحاجة إلى تنفيذ onSkipToNext. بدلاً من ذلك، استخدِم التنفيذ التلقائي لسياسة onSkipToNext.

لا يحتاج تطبيقك إلى أي منطق خاص لتشغيل المحتوى من خلال مكبّرات صوت السيارة. عندما يتلقّى تطبيقك طلبًا بتشغيل محتوى، يتم تشغيل الصوت بالطريقة نفسها التي يتم بها تشغيل المحتوى من خلال مكبّرات صوت الهاتف أو السمّاعات. يرسل نظاما التشغيل Android Auto وAAOS تلقائيًا محتوى الصوت إلى نظام السيارة لتشغيله عبر مكبّرات صوت السيارة.

لمزيد من المعلومات حول تشغيل المحتوى الصوتي، يمكنك الاطّلاع على نظرة عامة على "مشغّل الوسائط" ونظرة عامة على تطبيق الصوت ونظرة عامة على ExoPlayer.

ضبط إجراءات التشغيل العادية

تعرض Android Auto وAAOS عناصر التحكّم في التشغيل استنادًا إلى الإجراءات المفعَّلة في عنصر PlaybackStateCompat. يجب أن يتيح تطبيقك تلقائيًا تنفيذ الإجراءات التالية:

يمكن أن يتيح تطبيقك أيضًا الإجراءات التالية إذا كانت ذات صلة بمحتوى التطبيق:

بالإضافة إلى ذلك، يمكنك اختياريًا إنشاء قائمة تشغيل لعرضها على المستخدم. لإجراء ذلك، استدعِ الطريقتَين setQueue وsetQueueTitle، وفعِّل الإجراء ACTION_SKIP_TO_QUEUE_ITEM، وحدِّد دالة معاودة الاتصال onSkipToQueueItem.

أضِف أيضًا دعمًا لرمز التعرّف التلقائي على الموسيقى، وهو مؤشر للمحتوى الذي يتم تشغيله. لإجراء ذلك، استدعِ طريقة setActiveQueueItemId ومرِّر معرّف العنصر الذي يتم تشغيله في قائمة الانتظار. عليك تعديل setActiveQueueItemId كلما حدث تغيير في قائمة الانتظار.

تعرض Android Auto وAAOS أزرارًا لكل إجراء مفعَّل بالإضافة إلى قائمة التشغيل. عندما ينقر المستخدمون على هذه الأزرار، يستدعي النظام الدالة المعالجة المقابلة من MediaSessionCompat.Callback.

حجز مساحة غير مستخدَمة

تحجز كلّ من Android Auto وAAOS مساحة في واجهة المستخدم لإجراءَي ACTION_SKIP_TO_PREVIOUS وACTION_SKIP_TO_NEXT. إذا كان تطبيقك لا يتيح إحدى هذه الوظائف، سيستخدم Android Auto وAAOS المساحة لعرض أي إجراءات مخصّصة تنشئها.

إذا كنت لا تريد ملء هذه المساحات بإجراءات مخصّصة، يمكنك حجزها لكي لا يعرض نظاما التشغيل Android Auto وAAOS أي محتوى فيها عندما لا يتيح تطبيقك الوظيفة المقابلة.

لإجراء ذلك، استدعِ طريقة setExtras مع حزمة إضافات تحتوي على ثوابت تتوافق مع الوظائف المحجوزة. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT يتوافق مع ACTION_SKIP_TO_NEXT، و SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV يتوافق مع ACTION_SKIP_TO_PREVIOUS. استخدِم هذه الثوابت كمفاتيح في الحزمة، واستخدِم القيمة المنطقية true كقيم.

ضبط PlaybackState الأوّلي

أثناء تواصل Android Auto وAAOS مع خدمة متصفّح الوسائط، تُرسل جلسة الوسائط حالة تشغيل المحتوى باستخدام PlaybackStateCompat.

يجب ألا يبدأ تطبيقك تشغيل الموسيقى تلقائيًا عند اتصال نظام التشغيل Android Automotive أو Android Auto بخدمة متصفّح الوسائط. بدلاً من ذلك، اعتمد على Android Auto وAAOS لاستئناف التشغيل أو بدئه استنادًا إلى حالة السيارة أو إجراءات المستخدم.

لإجراء ذلك، اضبط القيمة الأولية PlaybackStateCompat لجلسة الوسائط على STATE_STOPPED أو STATE_PAUSED أو STATE_NONE أو STATE_ERROR.

لا تستمر جلسات الوسائط في Android Auto وAAOS إلا لمدة الرحلة، لذا يبدأ المستخدمون هذه الجلسات ويوقفونها بشكل متكرر. لتعزيز تجربة سلسة بين الرحلات، يجب تتبُّع حالة الجلسة السابقة للمستخدم، حتى يتمكّن المستخدم تلقائيًا من استئناف التشغيل من حيث توقّف عند تلقّي تطبيق الوسائط طلب استئناف التشغيل، مثل آخر عنصر وسائط تم تشغيله وPlaybackStateCompat وقائمة الانتظار.

إضافة إجراءات تشغيل مخصّصة

يمكنك إضافة إجراءات تشغيل مخصّصة لعرض إجراءات إضافية يتيحها تطبيق الوسائط. إذا سمحت المساحة بذلك (ولم تحجزها)، سيضيف Android الإجراءات المخصّصة إلى عناصر التحكّم في النقل. بخلاف ذلك، ستظهر الإجراءات المخصّصة في قائمة القائمة الكاملة. يعرض Android الإجراءات المخصّصة بالترتيب الذي تضيفها به إلى PlaybackStateCompat.

استخدِم الإجراءات المخصّصة لتقديم سلوك مختلف عن الإجراءات العادية. لا تستخدِمها لاستبدال الإجراءات العادية أو تكرارها.

لإضافة إجراءات مخصّصة، استخدِم طريقة addCustomAction في فئة PlaybackStateCompat.Builder. يوضّح مقتطف الرمز البرمجي هذا كيفية إضافة إجراء مخصّص إلى "بدء قناة راديو":

Kotlin

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

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

Java

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

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

للاطّلاع على مثال أكثر تفصيلاً لهذه الطريقة، راجِع طريقة setCustomAction في تطبيق Universal Android Music Player النموذجي على GitHub. بعد إنشاء الإجراء المخصّص، يمكن لجلسة الوسائط الردّ على الإجراءات من خلال إلغاء طريقة onCustomAction.

تعرض مقتطفة الرمز البرمجي هذه كيف يمكن لتطبيقك الاستجابة لإجراء "بدء تشغيل قناة راديو":

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)) {
        ...
    }
}

لمزيد من المعلومات، يُرجى الاطّلاع على طريقة onCustomAction في تطبيق Universal Android Music Player النموذجي على GitHub.

إنشاء رموز للإجراءات المخصّصة

يتطلّب كل إجراء مخصّص تنشئه رمزًا.

إذا كان وصف هذا الرمز يتطابق مع أحد الثوابت CommandButton.ICON_، اضبط قيمة العدد الصحيح للمفتاح EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT ضمن الإضافات الخاصة بالإجراء المخصّص. في الأنظمة المتوافقة، يؤدي ذلك إلى تجاهل مصدر الرمز الذي تم تمريره إلى CustomAction.Builder، ما يتيح لمكوّنات النظام عرض الإجراء الخاص بك وإجراءات التشغيل الأخرى بشكل متّسق.

يجب أيضًا تحديد مصدر أيقونة. يمكن تشغيل التطبيقات على السيارات بأحجام وكثافات شاشة مختلفة، لذا يجب أن تكون الرموز التي تقدّمها رسومات متّجهة. استخدِم متّجهًا قابلاً للرسم لتغيير حجم مواد العرض بدون فقدان التفاصيل. يمكن أن يضبط الرسم المتّجهي حوافّه وزواياه على حدود وحدات البكسل بدقة أقل.

إذا كان الإجراء المخصّص يحتفظ بحالة (إذا كان يفعّل أو يوقف إعداد التشغيل)، يجب توفير رموز مختلفة للحالات المختلفة لمساعدة المستخدمين على ملاحظة التغيير عند اختيار الإجراء.

توفير أنماط رموز بديلة للإجراءات غير المفعَّلة

عندما لا يتوفّر إجراء مخصّص للسياق الحالي، استبدِل رمز الإجراء المخصّص برمز بديل يعرض الإجراء على أنّه غير مفعّل.

تحديد تنسيق الصوت

للإشارة إلى أنّ الوسائط التي يتم تشغيلها تستخدم تنسيقًا صوتيًا خاصًا، يمكنك تحديد الرموز التي يتم عرضها في السيارات المتوافقة مع هذه الميزة. يمكنك ضبط KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI وKEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI في حزمة الإضافات الخاصة بعنصر الوسائط الذي يتم تشغيله حاليًا (يتم تمريره إلى MediaSession.setMetadata). اضبط كلتا الإضافتين لاستيعاب التنسيقات المختلفة.

بالإضافة إلى ذلك، يمكنك ضبط KEY_IMMERSIVE_AUDIO extra لإعلام مصنّعي المعدات الأصلية للسيارات بأنّ هذا المحتوى يتضمّن صوتًا غامرًا، وعليهم توخّي الحذر الشديد عند تحديد ما إذا كانوا سيطبّقون تأثيرات صوتية قد تتداخل مع المحتوى الغامر.

إضافة روابط من المحتوى الذي يتم تشغيله حاليًا

يمكنك ضبط عنصر الوسائط الذي يتم تشغيله بحيث يكون العنوان الفرعي أو الوصف أو كلاهما عبارة عن روابط تؤدي إلى عناصر وسائط أخرى. ويتيح ذلك للمستخدم الانتقال بسرعة إلى عناصر ذات صلة، مثل الانتقال إلى أغانٍ أخرى للفنان نفسه أو إلى حلقات أخرى من برنامج بودكاست. إذا كانت السيارة تتيح هذه الميزة، يمكن للمستخدمين النقر على الرابط لتصفّح هذا المحتوى.

لإضافة روابط، اضبط البيانات الوصفية KEY_SUBTITLE_LINK_MEDIA_ID (للربط من الشرح) أو KEY_DESCRIPTION_LINK_MEDIA_ID (للربط من الوصف). للحصول على التفاصيل، يُرجى الاطّلاع على المستندات المرجعية الخاصة بحقول البيانات الوصفية هذه.

تفعيل عنصر التحكّم في التشغيل تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تسجيل جلسة وسائط

Kotlin

Java

تنفيذ أوامر التشغيل

ضبط إجراءات التشغيل العادية

حجز مساحة غير مستخدَمة

ضبط PlaybackState الأوّلي

إضافة إجراءات تشغيل مخصّصة

Kotlin

Java

Kotlin

Java

إنشاء رموز للإجراءات المخصّصة

توفير أنماط رموز بديلة للإجراءات غير المفعَّلة

تحديد تنسيق الصوت

إضافة روابط من المحتوى الذي يتم تشغيله حاليًا

تفعيل عنصر التحكّم في التشغيل