نقل بيانات تطبيق Android Sender من الإصدار 2 من Cast SDK إلى إطار عمل تطبيق Cast (CAF)

تتيح لك الخطوات التالية تحويل تطبيق Android المرسِل من الإصدار 2 من Cast SDK إلى CAF Sender، والذي يستند إلى مثيل وحيد لملف برمجي هو CastContext.

تستخدِم حزمة تطوير البرامج (SDK) لبرنامج Cast CAF Sender حزمة CastContext لإدارة GoogleAPIClient نيابةً عنك. يدير CastContext دورات الحياة والأخطاء وعمليات الاستدعاء نيابةً عنك، ما يبسط بشكلٍ كبير تطوير تطبيق Cast.

مقدمة

• لا يزال يتم توزيع CAF Sender كجزء من "خدمات Google Play" باستخدام أداة إدارة حِزم تطوير البرامج (SDK) لنظام التشغيل Android.
• تمت إضافة حِزم جديدة تتحمّل مسؤولية الامتثال لقائمة التحقّق من تصميم Google Cast (com.google.android.gms.cast.framework.*).
• يقدّم CAF Sender تطبيقات مصغّرة تتوافق مع متطلبات تجربة المستخدم في Cast، ولم يوفّر الإصدار 2 أيّ مكوّنات لواجهة المستخدم، بل كان يتطلّب منك تنفيذ هذه التطبيقات المصغّرة.
• لم يعُد استخدام GoogleApiClient مطلوبًا لاستخدام Cast API.
• تتشابه ميزة الترجمة والشرح في CAF Sender مع الإصدار 2.

التبعيات

يتضمّن الإصدار 2 وCAF التبعيات نفسها على مكتبات الدعم وخدمات Google Play (9.2.0 أو الإصدارات الأحدث) كما هو موضّح في دليل ميزات مكتبة الدعم.

الحد الأدنى لإصدار حزمة تطوير البرامج (SDK) لنظام التشغيل Android الذي تتوافق معه واجهة برمجة التطبيقات CAF هو 9 (Gingerbread).

الإعداد

في CAF، يجب تنفيذ خطوة إعداد صريحة لإطار عمل Cast. ويشمل ذلك إعداد CastContext العنصر الفردي باستخدام OptionsProvider مناسب لتحديد معرّف تطبيق Web Receiver وأي خيارات عامة أخرى.

public class CastOptionsProvider implements OptionsProvider {

    @Override
    public CastOptions getCastOptions(Context context) {
        return new CastOptions.Builder()
                .setReceiverApplicationId(context.getString(R.string.app_id))
                .build();
    }

    @Override
    public List<SessionProvider> getAdditionalSessionProviders(Context context) {
        return null;
    }
}

حدِّد OptionsProvider ضمن علامة application في ملف التطبيق AndroidManifest.xml:

<application>
...
    <meta-data
        android:name=
            "com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
        android:value="com.google.sample.cast.refplayer.CastOptionsProvider" />
</application>

يمكنك بدء CastContext بشكلٍ كسول في طريقة onCreate لكل نشاط:

private CastContext mCastContext;

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.video_browser);
    setupActionBar();

    mCastContext = CastContext.getSharedInstance(this);
}

لم تكن هذه الخطوات ضرورية في الإصدار 2.

رصد الأجهزة

في CAF، يبدأ إطار العمل عملية الاكتشاف ويوقفها تلقائيًا عند انتقال التطبيق إلى المقدّمة أو الخلفية، على التوالي. يجب عدم استخدام MediaRouteSelector وMediaRouter.Callback.

زر البث ومربّع حوار البث

كما هو الحال في الإصدار 2، يتم توفير هذه المكوّنات من خلال مكتبة دعم MediaRouter.

لا يزال زر "البث" متوفّرًا في الرمز العميق MediaRouteButton ويمكن إضافته إلى نشاطك (باستخدام إما ActionBar أو Toolbar)، كعنصر قائمة في قائمتك.

<item
    android:id="@+id/media_route_menu_item"
    android:title="@string/media_route_menu_title"
    app:actionProviderClass="android.support.v7.app.MediaRouteActionProvider"
    app:showAsAction="always"/>

يمكنك إلغاء طريقة onCreateOptionMenu() لكل نشاط باستخدام CastButtonFactory لربط MediaRouteButton بإطار عمل Cast:

private MenuItem mediaRouteMenuItem;

public boolean onCreateOptionsMenu(Menu menu) {
    super.onCreateOptionsMenu(menu);
    getMenuInflater().inflate(R.menu.browse, menu);
    mediaRouteMenuItem =
        CastButtonFactory.setUpMediaRouteButton(getApplicationContext(),
                                                menu,
                                                R.id.media_route_menu_item);
    return true;
}

عندما ينقر أحد المستخدمين على الزر، يظهر مربّع حوار البث تلقائيًا.

التحكم بالجهاز

في إطار CAF، يتولّى إطار العمل بشكل كبير عملية التحكّم في الجهاز. لا يحتاج تطبيق المُرسِل إلى معالجة (ويجب ألا يحاول معالجة) الاتصال بالجهاز وتشغيل تطبيق Web Receiver باستخدام GoogleApiClient. يتم الآن تمثيل التفاعل بين المُرسِل وWeb Receiver بصفته "جلسة". تعالج فئة SessionManager دورة حياة الجلسة وتبدأ الجلسات وتوقِفها تلقائيًا استجابةً لإيماءات المستخدم: تبدأ الجلسة عندما يختار المستخدم جهاز Cast في مربّع حوار Cast وتنتهي عندما ينقر المستخدم على زرّ "إيقاف البث" في مربّع حوار Cast أو عندما ينتهي تطبيق المُرسِل نفسه. يمكن إرسال إشعار إلى تطبيق المُرسِل بشأن أحداث دورة حياة الجلسة من خلال تسجيل SessionManagerListener مع SessionManager. تحدِّد وظائف الاستدعاء SessionManagerListener methods methods طرق الاستدعاء لجميع أحداث دورة حياة الجلسة.

يمثّل الإجراء CastSession جلسة مع جهاز بث. تتضمّن الفئة طرقًا ل التحكّم في مستوى صوت الجهاز وحالات كتم الصوت، والتي تم تنفيذها سابقًا في الإصدار 2 باستخدام طرق في Cast.CastApi.

في الإصدار 2، كانت طلبات إعادة الاتصال Cast.Listener توفّر إشعارات بالتغييرات في حالة الجهاز، بما في ذلك مستوى الصوت وحالة كتم الصوت وحالة الاستعداد وما إلى ذلك.

في CAF، لا يزال يتم إرسال إشعارات تغيير حالة الصوت/كتم الصوت من خلال methods callbacks في Cast.Listener، ويتم تسجيل مستمعي هذه الإشعارات باستخدام CastSession. يتم إرسال جميع إشعارات حالة الجهاز المتبقية من خلال callbacks CastStateListener ، ويتم تسجيل مستمعي هذه الطلبات باستخدام CastSession. تأكَّد من أنّك لا تزال تلغي تسجيل المستمعين عندما تنتقل الأجزاء أو الأنشطة أو التطبيقات المرتبطة إلى الخلفية.

منطق إعادة الاتصال

كما هو الحال مع الإصدار 2، يحاول CAF إعادة إنشاء اتصالات الشبكة التي تم فقدانها بسبب فقدان إشارة WiFi مؤقتًا أو أخطاء أخرى في الشبكة. يتمّ إجراء ذلك الآن على مستوى الجلسة، ويمكن أن تدخل الجلسة في حالة "معلّقة" عند انقطاع الاتصال، وستعود إلى الحالة "متصل" عند استعادة الاتصال. يتولى إطار العمل إعادة الاتصال بتطبيق Web Receiver وإعادة ربط أي قنوات Cast كجزء من هذه العملية.

بالإضافة إلى ذلك، تضيف CAF أيضًا ميزة استئناف الجلسة تلقائيًا التي تكون مفعّلة تلقائيًا (ويمكن إيقافها من خلال CastOptions). إذا تم إرسال تطبيق المُرسِل إلى الخلفية أو إغلاقه (باستخدام ميزة المسح السريع أو بسبب تعطُّل) أثناء إجراء جلسة بث، سيحاول الإطار العمل استئناف تلك الجلسة عندما يعود تطبيق المُرسِل إلى المقدّمة أو تتم إعادة تشغيله. ويتم التعامل مع ذلك تلقائيًا من خلال SessionManager، الذي سيُصدر عمليات الاستدعاء المناسبة لأي مثيلات registered SessionManagerListener مسجَّلة.

تسجيل قناة مخصّصة

في الإصدار 2، يتم تسجيل القنوات المخصّصة (المُنفَّذة باستخدام Cast.MessageReceivedCallback) باستخدام Cast.CastApi. في CAF، يتم تسجيل القنوات المخصّصة بدلاً من ذلك باستخدام مثيل CastSession. يمكن إجراء التسجيل في أسلوب callback SessionManagerListener.onSessionStarted. بالنسبة إلى تطبيقات الوسائط، لم يعُد من الضروري تسجيل قناة التحكّم في الوسائط بشكل صريح من خلال Cast.CastApi.setMessageReceivedCallbacks. يُرجى الاطّلاع على القسم التالي للحصول على مزيد من التفاصيل.

التحكم في الوسائط

تم إيقاف فئة الإصدار 2 RemoteMediaPlayer نهائيًا ويجب عدم استخدامها. في CAF، تم استبدالها بفئة RemoteMediaClient الجديدة التي توفّر وظيفة مماثلة في واجهة برمجة تطبيقات أكثر ملاءمةً. ليس من الضروري إعداد هذا الكائن أو تسجيله بشكل صريح، لأنّ الإطار العملي سينشئ الكائن تلقائيًا ويُسجِّل قناة الوسائط الأساسية في وقت بدء الجلسة إذا كان تطبيق Web Receiver المتصل يتوافق مع مساحة أسماء الوسائط.

يمكن الوصول إلى RemoteMediaClient كطريقة getRemoteMediaClient للكائن CastSession.

في الإصدار 2، ستؤدي جميع طلبات الوسائط الصادرة عن RemoteMediaPlayer إلى عرض RemoteMediaPlayer.MediaChannelResult من خلال طلب PendingResult للاتصال.

في CAF، تُرجِع جميع طلبات الوسائط الصادرة عن RemoteMediaClient RemoteMediaClient.MediaChannelResult من خلال PendingResult مكالمة استدعاء يمكن استخدامها لتتبُّع مستوى التقدّم والنتيجة النهائية لمحاولة الربط.

سيرسل الإصدار 2 من RemoteMediaPlayer إشعارات بشأن التغييرات في حالة مشغّل الوسائط على Web Receiver عبر RemoteMediaPlayer.OnStatusUpdatedListener.

في CAF، يقدّم RemoteMediaClient عمليات استدعاء مكافئة من خلال واجهة RemoteMediaClient.Listener. يمكن تسجيل أي عدد من المستمعين باستخدام RemoteMediaClient، ما يسمح لمكونات المُرسِل المتعدّدة بمشاركة المثيل الوحيد من RemoteMediaClient المرتبط بالجلسة.

في الإصدار 2، كان على تطبيق المُرسِل تحمُّل عبء الحفاظ على مزامنة واجهة المستخدِم مع حالة مشغّل الوسائط على Web Receiver.

في CAF، تتحمّل الفئة UIMediaController معظم هذه المسؤولية.

العنصر التمهيدي على سطح الفيديو

لا يقدّم الإصدار 2 واجهة مستخدم تمهيدية للتراكب.

يوفّر CAF عرضًا مخصّصًا IntroductoryOverlay لتمييز زرّ البث عند عرضه للمستخدمين لأول مرة.

وحدة تحكّم صغيرة

في الإصدار 2، عليك تنفيذ وحدة تحكّم صغيرة من الصفر في تطبيق المُرسِل.

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

في CAF، توفّر حزمة تطوير البرامج (SDK) واجهة برمجة تطبيقات NotificationsOptions.Builder لمساعدتك في إنشاء عناصر تحكّم في الوسائط للإشعارات وشاشة القفل في تطبيق المُرسِل. يمكن تفعيل عناصر التحكّم في الإشعارات وشاشة القفل باستخدام CastOptions عند بدء CastContext.

public CastOptions getCastOptions(Context context) {
    NotificationOptions notificationOptions = new NotificationOptions.Builder()
            .setTargetActivityClassName(VideoBrowserActivity.class.getName())
            .build();
    CastMediaOptions mediaOptions = new CastMediaOptions.Builder()
            .setNotificationOptions(notificationOptions)
            .build();

    return new CastOptions.Builder()
            .setReceiverApplicationId(context.getString(R.string.app_id))
            .setCastMediaOptions(mediaOptions)
            .build();
}

وحدة تحكّم موسّعة

في الإصدار 2، عليك تنفيذ وحدة تحكّم موسّعة من البداية في تطبيق المُرسِل.

يوفّر CAF فئة مساعدة UIMediaController تسهّل عليك إنشاء ملف تحكم موسّع.

تضيف CAF عنصر تحكّم موسّع مُنشئ مسبقًا ExpandedControllerActivity يمكنك إضافته بسهولة إلى تطبيقك. لم تعُد بحاجة إلى تنفيذ عنصر تحكّم موسّع مخصّص باستخدام UIMediaController.

التركيز على الصوت

في الإصدار 2، عليك استخدام MediaSessionCompat لإدارة ميزة "التركيز على الصوت".

في وضع CAF، تتم إدارة تركيز الصوت تلقائيًا.

تسجيل تصحيح الأخطاء

لا تتوفّر خيارات تسجيل في CAF.

أمثلة على التطبيقات

لدينا دروس تطبيقية حول الترميز وعيّنات تطبيقات تستخدم إطار عمل CAF.