مكوّنات النظام وتدفقات المستخدمين

يتم وصف المكوّنات التي تتفاعل مع Media في الجدول التالي:

مسارات المستخدم

تشغيل تطبيق الوسائط

يجب تشغيل الوسائط باستخدام النية الضمنية التالية CAR_INTENT_ACTION_MEDIA_TEMPLATE. يمكن أن يتضمّن هذا الغرض المعلومات التالية كبيانات إضافية:

• ‫android.car.intent.extra.MEDIA_COMPONENT (اختياري). سلسلة إضافية لتمثيل اسم المكوّن المسطّح الخاص بـ MediaBrowserService في تطبيق الوسائط الذي سيتم الاتصال به. إذا لم يتم توفيرها، تعرض "الوسائط" تطبيق الوسائط المحدّد حاليًا. يتم استخدام هذا الغرض من نقاط الدخول التالية:

  • واجهة مستخدِم النظام: يُستخدم للرجوع إلى تجربة "الوسائط" أو لبدء استخدامها للمرة الأولى. في هذه الحالة، سيتم استخدام Intent المذكور أعلاه بدون أي إضافات لعرض تطبيق الوسائط المحدّد حاليًا.

  • الشاشة الرئيسية والمساعدون ومركز الإشعارات: يمكن للمستخدمين الانتقال إلى "الوسائط" لعرض تطبيق الوسائط المحدّد حاليًا. وفي جميع الحالات، يتم تشغيل Intent الضمني بدون إضافات.

  • مشغّل التطبيقات: عندما يختار المستخدمون تطبيق وسائط من مشغّل التطبيقات، يتضمّن الغرض أعلاه الإضافة CAR_EXTRA_MEDIA_COMPONENT، التي تحتوي على تطبيق الوسائط المحدّد. وتحدّد الوسائط هذا التطبيق على أنّه التطبيق المحدّد حديثًا ويتم الاتصال به. لمعرفة التفاصيل، يُرجى الاطّلاع على القسم أدناه، دمج مشغّل التطبيقات مع مشغّل الوسائط.

من "مشغّل التطبيقات" إلى دمج الوسائط

لا يُسمح لتطبيقات الوسائط بتوفير أي نشاط تمّت إضافة تعليق توضيحي إليه باستخدام الفئة android.intent.category.LAUNCHER. نتيجةً لذلك، يجب أن تنفّذ "مشغّل التطبيقات" (أو ما يعادله) منطقًا خاصًا لمعالجة دمج مصدر الوسائط:

• يجب أن تفحص أداة تشغيل التطبيقات النظام بحثًا عن حِزم تنفّذ MediaBrowserService.SERVICE_INTERFACE. بالنسبة إلى هذه الحِزم، يسترد "مشغّل التطبيقات" رمز الخدمة بشكل مشابه للرمز المستخدَم لاسترداد الأنشطة الأخرى.

• يجمع "مشغّل التطبيقات" بعد ذلك هذه الحِزم مع الحِزم التي تنفّذ أنشطة android.intent.category.LAUNCHER. إذا كان التطبيق يوفّر عملية تنفيذ MediaBrowserService ونشاطًا خاصًا بمشغّل التطبيقات، ستكون الأولوية للخدمة.

  في وقت كتابة هذا المستند، لا يمكن لأي تطبيق مصدر وسائط توفير نشاط مشغّل.

• يمكن العثور على مثال لهذا المنطق في رمز AOSP على الرابط AppLauncherUtils#getAllLauncherApps().

مسار تسجيل الدخول وخيارات الإعداد

يمكن أن تتضمّن تطبيقات الوسائط نشاط "الإعدادات" المحسَّن للمركبات. يمكن استخدام هذا النشاط لتنفيذ مسارات المستخدمين التي لا تتناولها واجهات برمجة التطبيقات الخاصة بالوسائط في Android، مثل:

• تسجيل الدخول
• تسجيل الخروج
• تبديل الحسابات
• الشاشة التي سجّل المستخدم الدخول إليها حاليًا (إن وُجدت)
• إعدادات الخدمة

يتم تعريف نشاط "الإعدادات" من خلال تطبيق الوسائط باستخدام فلتر الأهداف التالي:

<activity android:name=".AppSettingsActivity"
          android:exported="true
          android:theme="@style/SettingsActivity"
           android:label="@string/app_settings_activity_title">
   <intent-filter>
       <action android:name="android.intent.action.APPLICATION_PREFERENCES"/>
   </intent-filter>
</activity>

يجب أن تنفّذ الوسائط المنطق التالي:

• تأكَّد من أنّ تطبيق الوسائط المحدّد حاليًا يتضمّن نشاطًا يتضمّن Intent Filter المحدّد.

• إذا كان الأمر كذلك، اسمح للمستخدم بالانتقال إلى النشاط.

• إذا كانت "قيود تجربة المستخدم في السيارة" سارية (على سبيل المثال، إذا كانت السيارة تتحرّك)، يجب إيقاف هذا العنصر لأنّ نشاط "الإعدادات" ليس واجهة مستخدم محسّنة للسائق.

معالجة الأخطاء وتسجيل الدخول المطلوب

تتفاعل الوسائط مع تطبيقات الوسائط من خلال واجهة برمجة التطبيقات لجلسات الوسائط في Android. في إطار واجهة برمجة التطبيقات هذه، تتلقّى Media كائن PlaybackState، الذي يوضّح الحالة الحالية لتطبيق الوسائط.

تبدأ عملية تسجيل الدخول عندما يغيّر تطبيق الوسائط الحالة من PlaybackState إلى STATE_ERROR، بما في ذلك رمز خطأ معيّن (راجِع التفاصيل أدناه). في هذه الحالة، يعرض تطبيق "الوسائط" وصف الخطأ وعنصر تحكّم للانتقال إلى نشاط تسجيل الدخول الذي ينفّذه تطبيق الوسائط.

يمكن أن تستخدم التطبيقات هذا المسار نفسه للإشارة إلى حالات أخرى من الأخطاء (على سبيل المثال، خطأ في الاتصال بالخادم).

كجزء من معالجة الأخطاء العادية PlaybackState، يجب أن يتحقّق Media من الإدخال التالي.

• رمز الخطأ PlaybackState يساوي PlaybackStateCompat#ERROR_CODE_AUTHENTICATION_EXPIRED. تشير هذه الإشارة إلى أنّ تطبيق الوسائط يتطلّب تسجيل الدخول لمواصلة التشغيل. يمكن تلقّي رموز خطأ أخرى تشير إلى أنواع أخرى من حالات الخطأ.

• تحتوي رسالة الخطأ PlaybackState (التي تضبطها تطبيقات الوسائط باستخدام الطريقة PlaybackStateCompat.Builder#setErrorMessage) على شرح يمكن قراءته (على سبيل المثال، "لم يتم تسجيل الدخول"). يجب عرض هذه الرسالة للمستخدم ويجب أن تكون محسّنة لتجنُّب تشتيت الانتباه أثناء القيادة (DO).

• يمكن أن يتضمّن PlaybackState اختياريًا الإضافات التالية (التي تضبطها تطبيقات الوسائط باستخدام الطريقة PlaybackStateCompat.Builder#setExtras) مع المفاتيح التالية.

  • android.media.extras.ERROR_RESOLUTION_ACTION_LABEL. اضبط القيمة على سلسلة تتضمّن الرسالة التي يمكن لشخص عادي قراءتها والتي سيتم عرضها على الزر الذي ينقر عليه المستخدم لبدء عملية تسجيل الدخول.

  • android.media.extras.ERROR_RESOLUTION_ACTION_INTENT. اضبط القيمة باستخدام PendingIntent ليتم تفعيلها عندما ينقر المستخدم على الزر المذكور أعلاه. يشير هذا الرمز PendingIntent إلى نشاط تسجيل دخول مخصّص نفّذه تطبيق الوسائط نفسه.

• تكون حالة PlaybackState مساوية STATE_ERROR. يشير ذلك إلى أنّه لا يمكن إجراء أي عملية أخرى إلى أن يكتمل تسجيل الدخول.