Cast SDK'sını Web Gönderen Uygulamanıza entegre etme

Bu geliştirici kılavuzunda, Google SDK'sı ile yayın SDK'sı kullanılarak Google Cast desteğinin nasıl ekleneceği açıklanmaktadır.

Terminoloji

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

Web Gönderen SDK'sı iki bölümden oluşur: Framework API (cast.framework) ve Base API (chrome.cast) Genel olarak, daha basit ve daha üst düzey Framework API'de çağrı yaparsınız. Bunlar daha sonra alt düzey Base API tarafından işlenir.

Gönderen çerçevesi, Framework API'si, modülü ve alt düzey işlevlerle ilgili sarmalayıcı sunan ilgili kaynakları ifade eder. Gönderen uygulaması veya Google Cast Chrome uygulaması, gönderen cihazdaki bir Chrome tarayıcıda çalışan bir web (HTML/JavaScript) uygulamasını belirtir. Web Alıcı uygulaması, Chromecast veya bir Google Cast cihazında çalışan HTML/JavaScript uygulamasını belirtir.

Gönderen çerçevesi, gönderene etkinlikleri uygulama hakkında bilgi vermek ve Yayın 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ükle

Uygulamanızın Google Cast özelliklerini kullanabilmesi 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 şekilde kitaplığa başvurmalı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.* namespace'i kullanır. Ad alanı aşağıdakileri temsil eder:

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

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

• CastContext, geçerli Yayın durumu hakkında bilgi veren ve Yayın durumu ile Yayınlama oturumu durumu değişikliklerini tetikleyen bir tekli nesnedir.
• Oturumu CastSession nesnesi yönetir. Bu nesne, durum bilgisi sağlar ve cihaz hacmi, sesi kapatma durumu ve uygulama meta verileri gibi etkinlikleri tetikler.
• HTML düğmesini genişleten basit bir HTML özel öğesi olan Yayınla düğmesi öğesi. Sağlanan Cast düğmesi yeterli değilse Yayınla düğmesi uygulamak için Yayınlama durumunu kullanabilirsiniz.
• RemotePlayerController, uzaktan oynatıcının uygulanmasını kolaylaştırmak için veri bağlama 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ınla düğmesi bileşeni tamamen çerçeve tarafından işlenir. Buna görünürlük yönetimi ve tıklama etkinliği işleme dahildir.

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

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

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

Öğeye gerekli şekilde boyut veya konumlandırma gibi ek stiller uygulayabilirsiniz. Bağlı Web Alıcısı durumunun rengini seçmek için --connected-color özelliğini ve bağlantısı kesilmiş durumu için --disconnected-color değerini kullanın.

Başlatma

Framework API yüklendikten sonra uygulama window.__onGCastApiAvailable işleyicisini çağırır. Gönderen kitaplığı yüklenmeden önce uygulamanın bu işleyiciyi window üzerinde ayarladığından emin olmalısınız.

Bu işleyicide CastContext setOptions(options) yöntemini çağırarak Yayın 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 şekilde başlatırsınız:

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

Uygulama ilk olarak, çerçeve tarafından sağlanan CastContext nesnesinin singleton örneğini alır. Ardından applicationID özelliğini ayarlamak için CastOptions nesnesini kullanarak setOptions(options) aracını kullanır.

Kayıt gerektirmeyen Varsayılan Medya Alıcısı'nı kullanıyorsanız Web Gönderme SDK'sı tarafından tanımlanan, applicationID yerine sabit bir değer kullanırsınız:

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

Medya kontrolü

CastContext ilk kullanıma sunulduğunda uygulama, getCurrentSession() kullanarak geçerli CastSession metnini istediği zaman alabilir.

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

CastSession, loadMedia(loadRequest) ile bağlı Cast cihazına medya yüklemek için kullanılabilir. İlk olarak, contentId ve contentType özelliklerinin yanı sıra içerikle ilgili diğer bilgileri kullanarak bir MediaInfo oluşturun. Ardından, istekle ilgili tüm bilgileri ekleyerek oradan bir LoadRequest oluşturun. Son olarak, CastSession üzerinden 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 Vaat döndürür. Vaat reddedilirse işlev bağımsız değişkeni chrome.cast.ErrorCode olur.

RemotePlayer üzerinden oyuncu durumu değişkenlerine erişebilirsiniz. Medya etkinliği geri çağırmaları ve komutlar dahil, 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, yüklenen medya için uygulamaya PLAY, DURAKLAT, DURDUR ve SEEK'in tüm medya kontrolünü sağlar.

• OYNATMA/DURAKLATMA: playerController.playOrPause();
• DURDUR: playerController.stop();
• EYLÜL: playerController.seek();

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

Angular için bir 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 nesnesindeki çeşitli cast.framework.RemotePlayerEventType etkinlikleri için işleyiciler ayarlanarak yakalanabilen çeşitli etkinlikler gerçekleşir.

Medya durumu bilgilerini almak için, oynatma değiştiğinde ve CastSession.getMediaSession().media değiştiğinde 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 bu işlemler üzerinde işlem yapması ve Yayın cihazındaki kendisi ile 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ı, bir cihaza bağlanma, bir Web Alıcısı uygulamasını başlatma (veya uygulamaya katılma), bu uygulamaya bağlanma ve bir medya kontrol kanalı başlatma adımlarını birleştiren Yayın oturumu kavramını ortaya koydu. Yayınlama oturumları ve Web Alıcısı yaşam döngüsü hakkında daha fazla bilgi için Web Alıcısı'na Uygulama yaşam döngüsü kılavuzuna bakın.

Oturumlar, uygulamanızın cast.framework.CastContext.getInstance() üzerinden alabileceği CastContext sınıfı tarafından yönetilir. Her oturum, 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ınlama oturumuna CastContext.getCurrentSession() üzerinden erişebilir.

Oturum durumunu izlemek amacıyla CastContextEventType.SESSION_STATE_CHANGED etkinlik türü için CastContext öğesine bir dinleyici 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ın iletişim kutusundan "yayını durdur" düğmesini tıklaması gibi bağlantı kesintileri için dinleyicinize RemotePlayerEventType.IS_CONNECTED_CHANGED etkinlik türü için bir dinleyici ekleyebilirsiniz. Dinleyicinizde RemotePlayer bağlantısının kesilip kesilmediğini kontrol edin. Varsa 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ı, Yayın 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 durumunu korumak, kullanıcıların sesli komutlar, Google Home uygulaması veya akıllı ekranları kullanarak mevcut ses ve video akışlarını cihazlar arasında taşıyabileceği akış aktarımının temelini oluşturur. Medya, bir cihazda (kaynak) oynamaya devam eder ve başka bir cihazda (hedef) devam eder. En son donanım yazılımına sahip tüm Cast cihazları, akış aktarımında kaynak veya hedef işlevi görebilir.

Akış aktarımı sırasında yeni hedef cihazı almak için cast.framework.SessionState.SESSION_RESUMED etkinliği arandığında CastSession#getCastDevice() numaralı telefonu arayın.

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