Cast SDK'sını Web Gönderen Uygulamanıza Entegre Edin

Bu geliştirici kılavuzunda, Cast SDK'sı kullanarak Web Gönderen uygulamanıza Google Cast desteğini nasıl ekleyeceğiniz açıklanmaktadır.

Terminoloji

Mobil cihaz veya tarayıcı, oynatmayı kontrol eden gönderendir. Google Cast cihazı, oynatma için ekranda içeriği görüntüleyen alıcıdır.

Web Gönderen SDK'sı iki bölümden oluşur: Çerçeve API'si (cast.framework) ve Base API (chrome.cast)

Gönderen çerçevesi; Çerçeve API'sini, modülü ve alt düzey işlevlerle ilgili sarmalayıcı sağlayan ilişkili kaynakları ifade eder. Gönderen uygulaması veya Google Cast Chrome uygulaması, gönderen cihazındaki bir Chrome tarayıcıda çalışan web (HTML/JavaScript) uygulamasını belirtir. Web Alıcısı uygulaması, Chromecast veya Google Cast cihazında çalışan bir HTML/JavaScript uygulamasını belirtir.

Gönderen çerçevesi, gönderen uygulamayı etkinlikler hakkında bilgilendirmek ve Cast uygulaması yaşam döngüsünün çeşitli durumları arasında geçiş yapmak için eşzamansız bir geri çağırma tasarımı kullanır.

Kitaplığı yükleme

Uygulamanızın Google Cast özelliklerini uygulayabilmesi için aşağıda gösterildiği gibi Google Cast Web Gönderen SDK'sının konumunu bilmesi gerekir. Web Gönderen Çerçevesi API'sini de yüklemek için loadCastFramework URL sorgu parametresini ekleyin. Uygulamanızın tüm sayfaları, aşağıdaki gibi kitaplığa atıfta bulunmalıdır:

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

Çerçeve

Web Gönderen SDK'sı cast.framework.* ad alanını kullanır. Ad alanı aşağıdakileri temsil eder:

  • API'de işlem çağıran yöntemler veya işlevler
  • API'deki işleyici işlevleri için etkinlik işleyiciler

Çerçeve şu ana bileşenlerden oluşur:

  • CastContext, mevcut Yayın durumu hakkında bilgi sağlayan ve Yayın durumu ile Yayın oturum durumu değişiklikleri için etkinlikleri tetikleyen bir tekil nesnedir.
  • CastSession nesnesi oturumu yönetir. Durum bilgilerini sağlar ve cihaz hacminde, sesi kapatma durumunda ve uygulama meta verilerinde yapılan değişiklikler gibi etkinlikleri tetikler.
  • HTML düğmesini genişleten basit bir HTML özel öğesi olan Yayınla düğmesi öğesi. Sağlanan Yayınla düğmesi yeterli değilse bir Yayın düğmesini uygulamak için Yayınla düğmesini kullanabilirsiniz.
  • RemotePlayerController, uzak oynatıcının uygulanmasını kolaylaştırmak için veri bağlama işlemi sağlar.

Ad alanının tam açıklaması için Google Cast Web Gönderen API Referansı'nı inceleyin.

Yayınla düğmesi

Uygulamanızdaki Yayın düğmesi bileşeni tamamen çerçeve tarafından işlenir. Bu, görünürlük yönetiminin yanı sıra tıklama olaylarını işlemeyi de içerir.

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

Alternatif olarak, düğmeyi programlı olarak da oluşturabilirsiniz:

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

Gerektiğinde öğeye herhangi bir ek stili (ör. boyut veya konumlandırma) uygulayabilirsiniz. Bağlı Web Alıcısı durumunun rengini seçmek için --connected-color, bağlantı kesildi durumu için --disconnected-color özelliğini kullanın.

Başlatma

Framework API'yi yükledikten sonra uygulama, işleyiciyi window.__onGCastApiAvailable çağırır. Gönderen kitaplığını yüklemeden önce, uygulamanın bu işleyiciyi window üzerinde ayarladığından emin olmanız gerekir.

Bu işleyicide CastContext'in setOptions(options) yöntemini çağırarak yayınlama etkileşimini başlatırsınız.

Örneğin:

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

Ardından, API'yi aşağıdaki gibi başlatırsınız:

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

İlk olarak uygulama, çerçeve tarafından sağlanan CastContext nesnesinin tekil örneğini alır. Ardından, applicationID değerini ayarlamak için bir CastOptions nesnesi kullanarak setOptions(options) aracını kullanır.

Kayıt gerektirmeyen Varsayılan Medya Alıcısı'nı kullanıyorsanız applicationID yerine aşağıda gösterildiği gibi Web Gönderen SDK'sı tarafından önceden tanımlanmış bir sabit değer kullanırsınız:

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

Medya kontrolü

CastContext başlatıldıktan sonra uygulama herhangi bir zamanda getCurrentSession() kullanarak geçerli CastSession bilgisini alabilir.

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

CastSession, loadMedia(loadRequest) ile bağlı yayın cihazına medya yüklemek için kullanılabilir. Öncelikle contentId ve contentType ile birlikte içerikle ilgili diğer bilgileri kullanarak bir MediaInfo oluşturun. Ardından, istekle ilgili tüm bilgileri ayarlayarak bundan bir LoadRequest oluşturun. Son olarak, CastSession cihazınızda loadMedia(loadRequest) numaralı telefonu arayın.

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 yöntemi, başarılı bir sonuç için gerekli işlemleri gerçekleştirmek üzere kullanılabilecek bir Promise döndürür. Promise reddedilirse işlev bağımsız değişkeni chrome.cast.ErrorCode olur.

Oyuncu durumu değişkenlerine RemotePlayer bölümünden erişebilirsiniz. Medya etkinliği geri çağırmaları ve komutları dahil olmak üzere RemotePlayer ile yapılan tüm etkileşimler RemotePlayerController ile işlenir.

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

RemotePlayerController, uygulamaya yüklenen medya için PLAY, DURAKLATMA, DURDUR ve GÖRE tam medya kontrolünü verir.

  • OYNATMA/DURAKLAT: playerController.playOrPause();
  • DURDUR: playerController.stop();
  • BULUNUN: playerController.seek();

RemotePlayer ve RemotePlayerController, bir uzaktan oynatıcı uygulamak için Polymer veya Angular gibi veri bağlama çerçeveleriyle kullanılabilir.

Angular için kod snippet'i aşağıda verilmiştir:

<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>

Medya durumu

Medya oynatma sırasında, RemotePlayerController nesnesine çeşitli cast.framework.RemotePlayerEventType etkinlikleri için işleyiciler ayarlayarak yakalanabilen çeşitli etkinlikler meydana gelir.

Medya durumu bilgilerini almak için oynatma değiştiğinde ve CastSession.getMediaSession().media değiştiğinde tetiklenen cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED etkinliğini kullanın.

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;
  });

Duraklatma, oynatma, devam ettirme veya arama gibi etkinlikler gerçekleştiğinde, uygulamanın bunlarla ilgili işlem yapması ve kendisinin Cast cihazındaki Web Alıcısı uygulaması arasında senkronizasyon yapması gerekir. Daha fazla bilgi için Durum güncellemeleri bölümüne bakın.

Oturum yönetiminin işleyiş şekli

Cast SDK'sı; cihaza bağlanma, Web Alıcısı uygulamasını başlatma (veya buna katılma), uygulamaya bağlanma ve medya kontrol kanalını başlatma adımlarının birleştirildiği Cast oturumu kavramını kullanıma sunar. Yayın oturumları ve Web Alıcısı yaşam döngüsü hakkında daha fazla bilgi için Web Alıcısı Uygulama yaşam döngüsü kılavuzuna bakın.

Oturumlar, uygulamanızın cast.framework.CastContext.getInstance() aracılığıyla alabileceği CastContext sınıfı tarafından yönetilir. Ayrı oturumlar Session sınıfının alt sınıflarıyla temsil edilir. Örneğin, CastSession yayın cihazlarıyla yapılan oturumları temsil eder. Uygulamanız, şu anda etkin olan Yayın oturumuna CastContext.getCurrentSession() üzerinden erişebilir.

Oturum durumunu izlemek amacıyla CastContextEventType.SESSION_STATE_CHANGED etkinlik türü için CastContext öğesine bir işleyici ekleyin.

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;
    }
  })

Kullanıcının Yayınla iletişim kutusundaki "yayını durdur" düğmesini tıklaması gibi bağlantı kesmek için işleyicinize RemotePlayerEventType.IS_CONNECTED_CHANGED etkinlik türü için bir işleyici ekleyebilirsiniz. İşleyicinizde RemotePlayer bağlantısının kesilip kesilmediğini kontrol edin. Durum böyleyse yerel oynatıcı durumunu gerektiği gibi güncelleyin. Örneğin:

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

Kullanıcı, çerçevenin Yayınla düğmesini kullanarak Yayın sonlandırmayı doğrudan kontrol edebilir ancak gönderenin kendisi mevcut CastSession nesnesini kullanarak yayını durdurabilir.

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);
}

Akış aktarma

Oturum durumunun korunması, akış aktarımının temelini oluşturur. Bu aşamada kullanıcılar, mevcut ses ve video akışlarını sesli komutlar, Google Home uygulaması veya akıllı ekranlar kullanarak cihazlar arasında taşıyabilir. Medyanın oynatılması bir cihazda (kaynak) durdurulur ve başka bir cihazda (hedef) devam eder. En yeni donanım yazılımına sahip her yayın cihazı, akış aktarımında kaynak veya hedef olarak kullanılabilir.

Akış aktarımı sırasında yeni hedef cihazı almak için cast.framework.SessionState.SESSION_RESUMED etkinliği çağrıldığında CastSession#getCastDevice() kodunu çağırın.

Daha fazla bilgi için Web Alıcısı'nda akış aktarımı bölümüne bakın.