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

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

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

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

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

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

كما هو الحال مع الإصدار 2، تحاول &quot;إطار عمل البث المباشر&quot; إعادة إنشاء اتصالات الشبكة التي تم فقدها بسبب فقدان إشارة 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 الجديدة التي توفّر وظائف مكافئة في واجهة برمجة تطبيقات أكثر ملاءمة. ليس من الضروري تهيئة هذا العنصر أو تسجيله بشكل صريح، إذ سيقوم إطار العمل بإنشاء مثيل للعنصر وتسجيل قناة الوسائط الأساسية تلقائيًا في وقت بدء الجلسة إذا كان تطبيق "برنامج استقبال الويب" الذي يتم الاتصال به يتوافق مع مساحة اسم الوسائط.

يمكن الوصول إلى 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، كان على تطبيق المرسِل تحمّل عبء الحفاظ على مزامنة واجهة المستخدم مع حالة مشغّل الوسائط على "أداة استقبال الويب".

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

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

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

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

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

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

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

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

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

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