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

Bu geliştirici kılavuzunda, Cast SDK'yı kullanarak web gönderen uygulamanıza Google Cast desteğinin nasıl ekleneceği açıklanmaktadır.

Not: Aşağıdakileri denemenizi öneririz:

• Cast Web Sender codelab eğitimi - Mevcut bir web video uygulamasını, Google Cast cihazında içerik oynatacak şekilde nasıl değiştireceğinizi adım adım öğrenin.
• CastVideos-chrome örnek uygulaması (GitHub) - Kullanıcı Deneyimi Kuralları ve Tasarım Kontrol Listesi'ne uygun olan bu referans örnek uygulamayı çalıştırın, uygulamada gezinin ve uygulamayı görüntüleyin.

Terminoloji

Mobil cihaz veya tarayıcı, oynatmayı kontrol eden gönderen; Google Cast cihazı ise oynatılacak içeriği ekranda gösteren alıcıdır.

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

Gönderen çerçevesi, alt düzey işlevler için bir sarmalayıcı sağlayan Framework API'yi, modülü ve ilişkili kaynakları ifade eder. Gönderen uygulama veya Google Cast Chrome uygulaması, gönderen cihazdaki Chrome tarayıcıda çalışan bir web (HTML/JavaScript) uygulamasını ifade eder. Web Alıcısı uygulaması, Chromecast veya Google Cast cihazında çalışan bir HTML/JavaScript uygulamasını ifade eder.

Gönderen çerçevesi, gönderen uygulamayı etkinlikler hakkında bilgilendirmek ve Cast uygulama 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 Google Cast Web Sender SDK'sının konumunu bilmesi gerekir. Bu konum aşağıda gösterilmiştir. Web Sender Framework API'yi de yüklemek için loadCastFramework URL sorgu parametresini ekleyin. Uygulamanızın tüm sayfaları kitaplığa aşağıdaki şekilde referans vermelidir:

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

Çerçeve

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

• API'de işlemleri ç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 oturumu durumu değişiklikleri için etkinlikleri tetikleyen tekil bir nesnedir.
• CastSession nesnesi oturumu yönetir. Durum bilgileri sağlar ve cihaz ses seviyesi, ses kapatma durumu ve uygulama meta verilerindeki değişiklikler gibi etkinlikleri tetikler.
• HTML düğmesini genişleten basit bir HTML özel öğesi olan yayın düğmesi öğesi. Sağlanan Yayınla düğmesi yeterli değilse Yayınla düğmesini uygulamak için Yayınla durumunu kullanabilirsiniz.
• RemotePlayerController, uzaktan oynatıcının uygulanmasını basitleştirmek için veri bağlama sağlar.

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

Yayınla düğmesi

Uygulamanızdaki Yayınla düğmesi bileşeni tamamen çerçeve tarafından yönetilir. 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 oluşturabilirsiniz:

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

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

Başlatma

Uygulama, çerçeve API'sini yükledikten sonra işleyiciyi çağırır: window.__onGCastApiAvailable. Uygulamanın, gönderen kitaplığını yüklemeden önce window üzerinde bu işleyiciyi ayarladığından emin olmanız gerekir.

Bu işleyicide, CastContext sınıfının setOptions(options) yöntemini çağırarak Cast 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
  });
};

Uygulama ilk olarak, ç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) yöntemini 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 Sender SDK'sı tarafından önceden tanımlanmış bir sabit 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, getCurrentSession() kullanarak istediği zaman geçerli CastSession değerini alabilir.

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

CastSession, loadMedia(loadRequest) kullanarak bağlı Cast cihazına medya yüklemek için kullanılabilir. Öncelikle contentId ve contentType ile içerikle ilgili diğer bilgileri kullanarak bir MediaInfo oluşturun. Ardından, istek için tüm alakalı bilgileri ayarlayarak bundan bir LoadRequest oluşturun. Son olarak, CastSession cihazınızdan loadMedia(loadRequest) numarasını 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 üzerinden erişebilirsiniz. Medya etkinliği geri çağırmaları ve komutları dahil olmak üzere RemotePlayer ile 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 OYNAT, DURAKLAT, DURDUR ve ARA gibi tam medya kontrolü sağlar.

• OYNAT/DURAKLAT: playerController.playOrPause();
• STOP: playerController.stop();
• SEEK: playerController.seek();

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

Angular için kod snippet'i:

<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 oynatılırken çeşitli etkinlikler gerçekleşir. Bu etkinlikler, RemotePlayerController nesnesindeki çeşitli cast.framework.RemotePlayerEventType etkinlikleri için dinleyiciler ayarlanarak yakalanabilir.

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 bu etkinliklere göre hareket etmesi ve kendisi ile 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ı, Cast oturumu kavramını sunar. Cast oturumu oluşturulurken bir cihaza bağlanma, Web Alıcı uygulamasını başlatma (veya uygulamaya katılma), bu uygulamaya bağlanma ve medya kontrol kanalı başlatma adımları birleştirilir. 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. Bağımsız oturumlar, Session sınıfının alt sınıflarıyla temsil edilir. Örneğin, CastSession Cast cihazlarıyla yapılan oturumları temsil eder. Uygulamanız, CastContext.getCurrentSession() aracılığıyla o anda etkin olan Cast oturumuna erişebilir.

Oturum durumunu izlemek için CastContextEventType.SESSION_STATE_CHANGED etkinlik türü için CastContext'e 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ınla iletişim kutusundaki "yayını durdur" düğmesini tıklaması gibi bağlantı kesme işlemleri 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. Bu durumda, yerel oyuncu 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çeve Yayınla düğmesi aracılığıyla Yayınla sonlandırmasını doğrudan kontrol edebilirken 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 koruma, akış aktarmanın temelidir. Kullanıcılar sesli komutlar, Google Home uygulaması veya akıllı ekranlar aracılığıyla mevcut ses ve video akışlarını cihazlar arasında taşıyabilir. Medya bir cihazda (kaynak) durur ve başka bir cihazda (hedef) devam eder. En yeni donanım yazılımına sahip tüm Cast cihazları, akış aktarma işleminde kaynak veya hedef olarak kullanılabilir.

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

Daha fazla bilgi için Web Alıcısı'nda akış aktarma başlıklı makaleyi inceleyin.