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

يتيح لك الإجراء التالي تحويل تطبيق المرسِل على Android من الإصدار 2 من حزمة تطوير البرامج (SDK) الخاصة بخدمة 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 singleton باستخدام 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 support.

لا يزال الزر "إرسال" متاحًا من خلال 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;
}

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

التحكّم في الجهاز

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

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

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

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

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

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

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

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

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

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

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

يمكن الوصول إلى RemoteMediaClient كإجراء getRemoteMediaClient الخاص بالكائن CastSession.

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

في "إطار عرض الإعلانات المشتركة" (CAF)، تعرض جميع طلبات الوسائط الصادرة على RemoteMediaClient RemoteMediaClient.MediaChannelResult عبر PendingResult دالة ردّ يمكن استخدامها لتتبُّع مستوى التقدّم والنتيجة النهائية للطلب.

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

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

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

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

النافذة المنبثقة التمهيدية

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

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

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

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

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

الإشعارات وشاشة القفل

في الإصدار 2، لا توفّر حزمة SDK عناصر التحكّم في الإشعارات وشاشة القفل. بالنسبة إلى حزمة SDK هذه، عليك إنشاء هذه الميزات في تطبيق المرسِل باستخدام واجهات برمجة التطبيقات لإطار عمل Android.

في "إطار عمل تطبيقات البث"، توفّر حزمة 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.