अपने वेब सेंडर ऐप्लिकेशन में Cast SDK टूल को इंटिग्रेट करें

इस डेवलपर गाइड में, Cast SDK का इस्तेमाल करके, अपने वेब सेंडर ऐप्लिकेशन में Google Cast की सुविधा जोड़ने का तरीका बताया गया है.

शब्दावली

मोबाइल डिवाइस या ब्राउज़र, सेंडर होता है. यह कॉन्टेंट चलाने की सुविधा को कंट्रोल करता है; Google Cast डिवाइस, रिसीवर होता है. यह कॉन्टेंट को स्क्रीन पर दिखाता है, ताकि उसे चलाया जा सके.

Web Sender SDK में दो हिस्से होते हैं: फ़्रेमवर्क एपीआई (cast.framework) और बेस एपीआई (chrome.cast) आम तौर पर, आसान और उच्च-स्तरीय फ़्रेमवर्क एपीआई पर कॉल किए जाते हैं. इसके बाद, इन्हें निचले स्तर के बेस एपीआई से प्रोसेस किया जाता है.

सेंडर फ़्रेमवर्क का मतलब, फ़्रेमवर्क एपीआई, मॉड्यूल, और उनसे जुड़े संसाधनों से है. ये लोअर-लेवल की फ़ंक्शनैलिटी के लिए रैपर उपलब्ध कराते हैं. सेंडर ऐप्लिकेशन या Google Cast Chrome ऐप्लिकेशन का मतलब, वेब (एचटीएमएल/JavaScript) ऐप्लिकेशन से है. यह ऐप्लिकेशन, सेंडर डिवाइस पर Chrome ब्राउज़र में चलता है. वेब रिसीवर ऐप्लिकेशन, Chromecast या Google Cast डिवाइस पर चलने वाले HTML/JavaScript ऐप्लिकेशन को कहते हैं.

सेंडर फ़्रेमवर्क, एसिंक्रोनस कॉलबैक डिज़ाइन का इस्तेमाल करता है. इससे सेंडर ऐप्लिकेशन को इवेंट के बारे में सूचना मिलती है. साथ ही, Cast ऐप्लिकेशन की लाइफ़साइकल की अलग-अलग स्थितियों के बीच ट्रांज़िशन होता है.

लाइब्रेरी लोड करना

Google Cast की सुविधाओं को लागू करने के लिए, आपके ऐप्लिकेशन को Google Cast Web Sender SDK की जगह के बारे में पता होना चाहिए. इसके बारे में यहां बताया गया है. वेब सेंडर फ़्रेमवर्क एपीआई को लोड करने के लिए, loadCastFramework यूआरएल क्वेरी पैरामीटर जोड़ें. आपके ऐप्लिकेशन के सभी पेजों पर, लाइब्रेरी का रेफ़रंस इस तरह होना चाहिए:

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

फ़्रेमवर्क

Web Sender SDK, cast.framework.* नेमस्पेस का इस्तेमाल करता है. नेमस्पेस, इन चीज़ों के बारे में बताता है:

• ऐसे तरीके या फ़ंक्शन जो एपीआई पर कार्रवाइयां शुरू करते हैं
• एपीआई में लिसनर फ़ंक्शन के लिए इवेंट लिसनर

इस फ़्रेमवर्क में ये मुख्य कॉम्पोनेंट शामिल हैं:

• CastContext एक सिंगलटन ऑब्जेक्ट है. यह Cast की मौजूदा स्थिति के बारे में जानकारी देता है. साथ ही, Cast की स्थिति और Cast सेशन की स्थिति में हुए बदलावों के लिए इवेंट ट्रिगर करता है.
• CastSession ऑब्जेक्ट, सेशन को मैनेज करता है. यह स्थिति की जानकारी देता है और इवेंट ट्रिगर करता है. जैसे, डिवाइस की आवाज़ में बदलाव, म्यूट की स्थिति, और ऐप्लिकेशन का मेटाडेटा.
• कास्ट बटन एलिमेंट, जो एक सामान्य एचटीएमएल कस्टम एलिमेंट है. यह एचटीएमएल बटन को बढ़ाता है. अगर दिया गया कास्ट बटन काफ़ी नहीं है, तो कास्ट बटन लागू करने के लिए, कास्ट की स्थिति का इस्तेमाल किया जा सकता है.
• RemotePlayerController डेटा बाइंडिंग की सुविधा देता है, ताकि रिमोट प्लेयर को आसानी से लागू किया जा सके.

नेमस्पेस के बारे में पूरी जानकारी के लिए, Google Cast Web Sender API का रेफ़रंस देखें.

कास्ट बटन

आपके ऐप्लिकेशन में मौजूद कास्ट बटन कॉम्पोनेंट को पूरी तरह से फ़्रेमवर्क मैनेज करता है. इसमें, एलिमेंट के दिखने की सेटिंग को मैनेज करने के साथ-साथ क्लिक इवेंट को हैंडल करने की सुविधा भी शामिल है.

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

इसके अलावा, बटन को प्रोग्रामैटिक तरीके से भी बनाया जा सकता है:

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

ज़रूरत के मुताबिक, एलिमेंट पर साइज़ या पोज़िशनिंग जैसी कोई भी स्टाइल लागू की जा सकती है. कनेक्ट किए गए वेब रिसीवर की स्थिति के लिए रंग चुनने के लिए --connected-color एट्रिब्यूट का इस्तेमाल करें. साथ ही, डिसकनेक्ट की गई स्थिति के लिए --disconnected-color एट्रिब्यूट का इस्तेमाल करें.

डेटा लेयर में इवेंट बनाने की प्रोसेस

फ़्रेमवर्क एपीआई लोड होने के बाद, ऐप्लिकेशन हैंडलर window.__onGCastApiAvailable को कॉल करेगा. आपको यह पक्का करना चाहिए कि ऐप्लिकेशन, सेंडर लाइब्रेरी लोड करने से पहले, window पर इस हैंडलर को सेट करे.

इस हैंडलर में, CastContext के setOptions(options) तरीके को कॉल करके, कास्ट इंटरैक्शन को शुरू किया जाता है.

उदाहरण के लिए:

<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 ऑब्जेक्ट के सिंगलटन इंस्टेंस को वापस पाता है. इसके बाद, यह applicationID को सेट करने के लिए, CastOptions ऑब्जेक्ट का इस्तेमाल करके setOptions(options) का इस्तेमाल करता है.

अगर डिफ़ॉल्ट मीडिया रिसीवर का इस्तेमाल किया जा रहा है, तो आपको रजिस्टर करने की ज़रूरत नहीं है. इसके बजाय, Web Sender SDK की ओर से पहले से तय किए गए कॉन्स्टेंट का इस्तेमाल करें. यह applicationID के बजाय, यहां दिखाया गया है:

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

मीडिया नियंत्रण

CastContext शुरू होने के बाद, ऐप्लिकेशन getCurrentSession() का इस्तेमाल करके, किसी भी समय मौजूदा CastSession को वापस पा सकता है.

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

loadMedia(loadRequest) का इस्तेमाल करके, कनेक्ट किए गए कास्ट डिवाइस पर मीडिया लोड करने के लिए CastSession का इस्तेमाल किया जा सकता है. सबसे पहले, contentId और contentType का इस्तेमाल करके, MediaInfo बनाएं. साथ ही, कॉन्टेंट से जुड़ी कोई अन्य जानकारी भी दें. इसके बाद, इससे LoadRequest बनाएं और अनुरोध के लिए सभी ज़रूरी जानकारी सेट करें. आखिर में, अपने CastSession पर loadMedia(loadRequest) को कॉल करें.

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 वाला तरीका, Promise दिखाता है. इसका इस्तेमाल, नतीजे को बेहतर बनाने के लिए ज़रूरी कार्रवाइयां करने के लिए किया जा सकता है. अगर Promise अस्वीकार कर दिया जाता है, तो फ़ंक्शन का तर्क chrome.cast.ErrorCode होगा.

RemotePlayer में जाकर, प्लेयर के स्टेटस वाले वैरिएबल ऐक्सेस किए जा सकते हैं. RemotePlayer के साथ होने वाले सभी इंटरैक्शन, RemotePlayerController की मदद से हैंडल किए जाते हैं. इनमें मीडिया इवेंट कॉलबैक और कमांड शामिल हैं.

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

RemotePlayerController की मदद से, ऐप्लिकेशन को लोड किए गए मीडिया को पूरी तरह से कंट्रोल करने की सुविधा मिलती है. जैसे, मीडिया को चलाना, रोकना, बंद करना, और आगे-पीछे करना.

• चलाएं/रोकें: playerController.playOrPause();
• STOP: playerController.stop();
• SEEK: 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>

मीडिया का स्टेटस

मीडिया चलाने के दौरान कई इवेंट होते हैं. इन्हें कैप्चर किया जा सकता है. इसके लिए, RemotePlayerController ऑब्जेक्ट पर अलग-अलग cast.framework.RemotePlayerEventType इवेंट के लिए लिसनर सेट करें.

मीडिया के स्टेटस की जानकारी पाने के लिए, 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;
  });

जब वीडियो को रोकने, चलाने, फिर से शुरू करने या आगे-पीछे करने जैसे इवेंट होते हैं, तो ऐप्लिकेशन को उन पर कार्रवाई करनी होगी. साथ ही, उसे Cast डिवाइस पर मौजूद Web Receiver ऐप्लिकेशन के साथ सिंक करना होगा. ज़्यादा जानकारी के लिए, स्टेटस अपडेट देखें.

सेशन मैनेजमेंट की सुविधा कैसे काम करती है

Cast SDK टूल में कास्ट सेशन का कॉन्सेप्ट पेश किया गया है. इसे सेट अप करने के लिए, डिवाइस से कनेक्ट करना, Web Receiver ऐप्लिकेशन लॉन्च करना (या उसमें शामिल होना), उससे कनेक्ट करना, और मीडिया कंट्रोल चैनल को शुरू करना होता है. कास्ट सेशन और वेब रिसीवर के लाइफ़साइकल के बारे में ज़्यादा जानने के लिए, वेब रिसीवर की ऐप्लिकेशन के लाइफ़ साइकल से जुड़ी गाइड देखें.

सेशन को क्लास CastContext मैनेज करती है. आपका ऐप्लिकेशन, cast.framework.CastContext.getInstance() के ज़रिए इसे वापस पा सकता है. अलग-अलग सेशन को क्लास Session की सबक्लास के तौर पर दिखाया जाता है. उदाहरण के लिए, CastSession का मतलब है कि सेशन, कास्ट डिवाइसों से किए गए हैं. आपका ऐप्लिकेशन, CastContext.getCurrentSession() के ज़रिए, चालू Cast सेशन को ऐक्सेस कर सकता है.

सेशन की स्थिति पर नज़र रखने के लिए, CastContextEventType.SESSION_STATE_CHANGED इवेंट टाइप के लिए, CastContext में एक लिसनर जोड़ें.

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 इवेंट को कॉल किया गया हो.

ज़्यादा जानकारी के लिए, वेब रिसीवर पर स्ट्रीम ट्रांसफ़र करना देखें.