دمج حزمة SDK للإرسال في تطبيق Web Sender

يوضّح دليل المطوِّر هذا كيفية إضافة دعم Google Cast إلى شبكة الويب تطبيق المُرسِل الذي يستخدم حزمة تطوير البرامج (SDK) لتقنية Google Cast

ملاحظة: ننصحك بتجربة ما يلي:

• Cast Web Sender دليل تعليمي حول الترميز - معرفة خطوة بخطوة لكيفية تعديل تطبيق فيديو حالي على الويب لتشغيله المحتوى على جهاز Google Cast.
• نموذج تطبيق Cast Videos-chrome (GitHub) - قم بتشغيل هذا النموذج المرجعي والتنقل فيه وعرضه، الذي يتوافق مع إرشادات تجربة المستخدم قائمة التحقّق من التصميم

المصطلحات

الجهاز الجوّال أو المتصفّح هو المُرسِل الذي يتحكّم في التشغيل جهاز Google Cast هو جهاز الاستقبال الذي يعرض المحتوى على شاشة التشغيل.

تتألف حزمة Web Sender SDK من جزأين هما: واجهة برمجة تطبيقات إطار العمل (cast.framework) وBase API (chrome.cast) بشكل عام، يمكنك إجراء اتصالات باستخدام واجهة برمجة تطبيقات إطار العمل الأبسط وعالية المستوى، التي تتم معالجتها بعد ذلك باستخدام واجهة برمجة تطبيقات Base ذات المستوى الأدنى.

يشير إطار عمل المُرسِل إلى واجهة برمجة تطبيقات إطار العمل والوحدة والأدوات المرتبطة بها. الموارد التي توفر برنامج تضمين حول الوظائف منخفضة المستوى. تشير رسالة الأشكال البيانية يشير تطبيق المُرسِل أو تطبيق Google Cast على Chrome إلى تطبيق ويب (HTML/JavaScript) يعمل داخل متصفّح Chrome على جهاز مرسِل. يشير تطبيق مستقبِل الويب إلى إلى تطبيق HTML/JavaScript يعمل على جهاز Chromecast أو جهاز Google Cast

يستخدم إطار عمل المرسِل تصميمًا غير متزامن لمعاودة الاتصال لإعلام المُرسِل للأحداث والانتقال بين الحالات المختلفة لحياة تطبيق Cast الدورة.

تحميل المكتبة

لكي يتمكن تطبيقك من تنفيذ ميزات Google Cast، يحتاج إلى معرفة موقع حزمة SDK لـ Google Cast Web Sender، كما هو موضح أدناه. إضافة مَعلمة طلب البحث loadCastFramework لعنوان URL لتحميل Web Sender Work API كذلك. يجب أن تشير جميع صفحات تطبيقك إلى المكتبة على النحو التالي:

<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

إطار العمل

تستخدم حزمة Web Sender SDK ملف cast.framework.* مساحة الاسم. تمثل مساحة الاسم ما يلي:

• الطرق أو الدوال التي تستدعي عمليات على واجهة برمجة التطبيقات
• أدوات معالجة الأحداث لدوال المستمعين في واجهة برمجة التطبيقات

ويتكون إطار العمل من هذه المكوّنات الأساسية:

• CastContext هو كائن فرديتون يقدم معلومات عن حالة البث الحالية، وتؤدي إلى تشغيل الأحداث لحالة البث وجلسة البث تغيرات الحالة.
• CastSession يدير العنصر الجلسة - فإنه يوفر حالة المعلومات التي تؤدي إلى تشغيل الأحداث، مثل التغييرات في مستوى صوت الجهاز وحالة كتم الصوت والبيانات الوصفية للتطبيق.
• عنصر زر البث، وهو عنصر HTML مخصص بسيط لتوسيع زر HTML. إذا لم يكن زر البث المقدَّم كافيًا، يمكنك استخدام حالة البث لتنفيذ زر البث.
• RemotePlayerController ربط البيانات لتبسيط تنفيذ المشغّل البعيد.

مراجعة مرجع واجهة برمجة التطبيقات Google Cast Web Sender الخاص الوصف الكامل لمساحة الاسم.

زر الإرسال

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

<google-cast-launcher></google-cast-launcher>

بدلاً من ذلك، يمكنك إنشاء الزر آليًا:

document.createElement("google-cast-launcher");

يمكنك تطبيق أي نمط إضافي، مثل الحجم أو الموضع، على العنصر حسب الضرورة. استخدِم السمة --connected-color من أجل اختيار لون حالة جهاز استقبال الويب المتصل --disconnected-color للحالة غير المتصلة.

الإعداد

بعد تحميل واجهة برمجة التطبيقات لإطار العمل، سيستدعي التطبيق المعالِج. window.__onGCastApiAvailable يجب التأكّد من أنّ التطبيق يضبط هذا المعالج على window قبل تحميل مكتبة المُرسِلين.

يمكنك إعداد تفاعل البث من خلال استدعاء setOptions(options) طريقة CastContext

على سبيل المثال:

<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
  if (isAvailable) {
    initializeCastApi();
  }
};
</script>

بعد ذلك، يمكنك إعداد واجهة برمجة التطبيقات على النحو التالي:

initializeCastApi = function() {
  cast.framework.CastContext.getInstance().setOptions({
    receiverApplicationId: applicationId,
    autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
  });
};

أولاً يسترد التطبيق مثيل المفردة كائن CastContext الذي يقدمه إطار العمل. بعد ذلك، تستخدم setOptions(options) باستخدام كائن CastOptions لضبط applicationID.

في حال استخدام جهاز استقبال الوسائط التلقائي الذي لا يتطلّب التسجيل، استخدام حزمة SDK ثابتة محددة مسبقًا بواسطة Web Sender، كما هو موضح أدناه، بدلاً من applicationID:

cast.framework.CastContext.getInstance().setOptions({
  receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});

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

بعد CastContext ؛ يمكن للتطبيق استرداد البيانات الحالية CastSession في أي وقت وقت استخدام getCurrentSession()

var castSession = cast.framework.CastContext.getInstance().getCurrentSession();

يمكن استخدام "CastSession" لتحميل الوسائط إلى جهاز البث المتصل باستخدام loadMedia(loadRequest) أولاً، أنشئ MediaInfo، باستخدام contentId وcontentType بالإضافة إلى أي معلومات أخرى المتعلقة بالمحتوى. ثم أنشئ LoadRequest منه، مع تعيين كل المعلومات ذات الصلة بالطلب. أَخِيرًا، الِاتِّصَالْ بِـ loadMedia(loadRequest) عَلَى CastSession.

var mediaInfo = new chrome.cast.media.MediaInfo(currentMediaURL, contentType);
var request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
  function() { console.log('Load succeed'); },
  function(errorCode) { console.log('Error code: ' + errorCode); });

ستعرض الطريقة loadMedia الوعد يمكن استخدامها لإجراء أي عمليات ضرورية للحصول على نتيجة ناجحة. إذا تم رفض الوعد، فستكون وسيطة الدالة هي chrome.cast.ErrorCode

يمكنك الوصول إلى متغيرات حالة اللاعبين في RemotePlayer جميع التفاعلات مع "RemotePlayer"، بما في ذلك عمليات معاودة الاتصال بأحداث الوسائط الأوامر، تتم معالجتها من خلال RemotePlayerController

var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);

يمنح RemotePlayerController التطبيق إمكانية التحكّم الكامل في الوسائط "تشغيل" و"إيقاف مؤقت" و"إيقاف" و"البحث عن الوسائط" التي تم تحميلها

• تشغيل/إيقاف مؤقت: playerController.playOrPause();
• إيقاف: playerController.stop();
• البحث: playerController.seek();

يمكن أن يكون RemotePlayer وRemotePlayerController مع أطر ربط البيانات، مثل Polymer أو Angular، لتطبيق عن بُعد.

في ما يلي مقتطف رمز لـ Angular:

<button id="playPauseButton" class="playerButton"
  ng-disabled="!player.canPause"
  ng-click="controller.playOrPause()">
    {{player.isPaused ? 'Play' : 'Pause'}}
</button>
<script>
var player = new cast.framework.RemotePlayer();
var controller = new cast.framework.RemotePlayerController(player);
// Listen to any player update, and trigger angular data binding
update.controller.addEventListener(
  cast.framework.RemotePlayerEventType.ANY_CHANGE,
  function(event) {
    if (!$scope.$$phase) $scope.$apply();
  });
</script>

حالة الوسائط

أثناء تشغيل الوسائط، تقع أحداث متنوعة يمكن التقاطها من خلال المستمعين لمختلف cast.framework.RemotePlayerEventType الأحداث في الكائن RemotePlayerController.

للحصول على معلومات حالة الوسائط، يمكنك استخدام cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED الحدث، الذي يتم تشغيله عند تغيير التشغيل وعند إجراء CastSession.getMediaSession().media التغييرات.

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, function() {
    // Use the current session to get an up to date media status.
    let session = cast.framework.CastContext.getInstance().getCurrentSession();

    if (!session) {
        return;
    }

    // Contains information about the playing media including currentTime.
    let mediaStatus = session.getMediaSession();
    if (!mediaStatus) {
        return;
    }

    // mediaStatus also contains the mediaInfo containing metadata and other
    // information about the in progress content.
    let mediaInfo = mediaStatus.media;
  });

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

آلية عمل إدارة الجلسات

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

يدير الصف الجلسات CastContext، الذي يمكن لتطبيقك استرداده من خلال cast.framework.CastContext.getInstance() يتم تمثيل الجلسات الفردية من خلال الفئات الفرعية للفئة. Session على سبيل المثال: CastSession الجلسات التي تتضمن أجهزة بث. يمكن لتطبيقك الوصول إلى واجهة برمجة التطبيقات النشطة حاليًا بث الجلسة عبر CastContext.getCurrentSession()

لمراقبة حالة الجلسة، أضِف مستمعًا إلى CastContext عن الـ نوع الحدث CastContextEventType.SESSION_STATE_CHANGED.

var context = cast.framework.CastContext.getInstance();
context.addEventListener(
  cast.framework.CastContextEventType.SESSION_STATE_CHANGED,
  function(event) {
    switch (event.sessionState) {
      case cast.framework.SessionState.SESSION_STARTED:
      case cast.framework.SessionState.SESSION_RESUMED:
        break;
      case cast.framework.SessionState.SESSION_ENDED:
        console.log('CastContext: CastSession disconnected');
        // Update locally as necessary
        break;
    }
  })

بالنسبة إلى قطع الاتصال، على سبيل المثال عندما ينقر المستخدم على "إيقاف البث" زر من مربع الحوار "إرسال"، يمكنك إضافة مستمع RemotePlayerEventType.IS_CONNECTED_CHANGED نوع الحدث في المستمع. في المستمع، تحقق مما إذا كان RemotePlayer هو غير متصل. في هذه الحالة، يُرجى تعديل حالة المشغّل المحلي حسب الضرورة. على سبيل المثال:

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
    if (!player.isConnected) {
      console.log('RemotePlayerController: Player disconnected');
      // Update local player to disconnected state
    }
  });

في حين أنه يمكن للمستخدم التحكم مباشرةً في إنهاء البث من خلال إطار العمل البث فإن المرسل نفسه يمكنه إيقاف البث باستخدام CastSession الخاص بك.

function stopCasting() {
  var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
  // End the session and pass 'true' to indicate
  // that Web Receiver app should be stopped.
  castSession.endSession(true);
}

نقل البث

يتم الاحتفاظ بحالة الجلسة أساس نقل البث، حيث يمكن للمستخدمين نقل ملفات الصوت والفيديو الحالية على جميع الأجهزة باستخدام الطلبات الصوتية وGoogle Home التطبيقات أو الشاشات الذكية. يتوقف تشغيل الوسائط على أحد الأجهزة (المصدر) ويستمر على جهاز آخر ( الوجهة). يمكن لأي جهاز بث يتضمّن أحدث البرامج الثابتة العمل كمصادر أو وجهات في نقل البث.

للحصول على الجهاز الوجهة الجديد أثناء نقل البث، يُرجى الاتصال CastSession#getCastDevice() عندما cast.framework.SessionState.SESSION_RESUMED الحدث.

عرض نقل البث على جهاز الاستقبال على الويب لمزيد من المعلومات.