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

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

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

مقدمة

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

التبعيات

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

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

الإعداد

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

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 ضمن علامة "التطبيق" في ملف 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 بإطار عمل Google 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، يتعامل إطار العمل إلى حد كبير مع التحكُّم في الأجهزة. لا يحتاج تطبيق المُرسِل إلى الاتصال بالجهاز (ويجب عدم محاولة معالجته) وتشغيل تطبيق "جهاز استقبال الويب" باستخدام GoogleApiClient. يتم الآن تمثيل التفاعل بين المرسل ومستلم الويب كـ "جلسة". تعالج الفئة SessionManager دورة حياة الجلسة وتبدأ الجلسات وتوقفها تلقائيًا استجابة لإيماءات المستخدم: تبدأ الجلسة عندما يختار المستخدم جهاز بث في مربّع حوار "البث" وتنتهي عندما ينقر المستخدم على الزر "إيقاف البث" في مربّع الحوار "إرسال" أو عند إنهاء تطبيق المُرسِل نفسه. يمكن إشعار تطبيق المرسِل بأحداث مراحل الجلسة من خلال تسجيل SessionManagerListener مع SessionManager. تحدّد عمليات معاودة الاتصال SessionManagerListener طرق معاودة الاتصال لجميع أحداث مراحل نشاط الجلسة.

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

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

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

منطق إعادة الربط

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

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

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

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

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

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

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

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

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

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

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

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

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

تراكب تمهيدي

لا يوفر الإصدار 2 واجهة مستخدم تمهيدية تظهر على سطح الفيديو.

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

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

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

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

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

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

في 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.