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

يتيح لك الإجراء التالي تحويل تطبيق المرسِل على Android من الإصدار 2 من حزمة تطوير البرامج (SDK) الخاصة بخدمة Cast إلى حزمة تطوير البرامج (SDK) الخاصة بإطار عمل CAF للمرسِل، والتي تستند إلى العنصر الفردي CastContext.

تستخدم حزمة تطوير البرامج (SDK) الخاصة بـ Cast CAF Sender‏ CastContext لإدارة GoogleAPIClient نيابةً عنك. تتولّى CastContext إدارة دورات الحياة والأخطاء وعمليات معاودة الاتصال نيابةً عنك، ما يسهّل بشكل كبير عملية تطوير تطبيق متوافق مع Cast.

مقدمة

• لا يزال يتم توزيع CAF Sender كجزء من "خدمات Google Play" باستخدام أداة إدارة حزمة تطوير البرامج (SDK) لنظام التشغيل Android.
• تمت إضافة حِزم جديدة تتحمّل مسؤولية الالتزام بقائمة التحقّق من تصميم Google Cast (com.google.android.gms.cast.framework.*)
• توفّر حزمة تطوير البرامج (SDK) الخاصة بـ 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;
}

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

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

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

يمثّل الصف CastSession جلسة مع جهاز Cast. يحتوي الصف على طرق للتحكّم في مستوى صوت الجهاز وحالات كتم الصوت، وهو ما كان يتم سابقًا في الإصدار 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.

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

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

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

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

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

عنصر مركّب تمهيدي

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

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

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

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

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

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

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

في حزمة تطوير البرامج (SDK) الخاصة بإطار عمل CAF، يتوفّر 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 فئة مساعدة تسهّل عليك إنشاء وحدة تحكّم موسّعة خاصة بك.

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

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

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

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

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

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

نماذج التطبيقات

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