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

يسمح لك الإجراء التالي بتحويل تطبيق المُرسِل على Android من Cast SDK v2 إلى CAF Sender، الذي يستند إلى العنصر الأحادي CastContext.

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

مقدمة

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

الاعتمادية

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

الحد الأدنى لإصدار Android SDK الذي يتيحه 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);
}

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

رصد الأجهزة

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

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

كما هو الحال في الإصدار الثاني، يوفّر مكتبة دعم 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 أو عندما يتم إنهاء تطبيق المُرسِل نفسه. يمكن إعلام تطبيق المُرسِل بأحداث دورة حياة الجلسة من خلال تسجيل SessionManagerListener باستخدام SessionManager. تحدّد عمليات معاودة الاتصال SessionManagerListener طرق معاودة الاتصال لجميع أحداث دورة حياة الجلسة.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تراكب تمهيدي

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

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

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

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

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

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

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

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

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

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

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

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

أولويّة الصوت

في الإصدار الثاني، عليك استخدام MediaSessionCompat لإدارة أولويّة الصوت.

في CAF، تتم إدارة أولويّة الصوت تلقائيًا.

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

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

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

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