Mengintegrasikan Cast SDK ke Aplikasi Pengirim Web Anda

Panduan developer ini menjelaskan cara menambahkan dukungan Google Cast ke aplikasi Pengirim Web menggunakan Cast SDK.

Catatan: Sebaiknya Anda mencoba hal berikut:

• Tutorial codelab Pengirim Web Cast - Pelajari langkah demi langkah cara mengubah aplikasi video web yang ada untuk memutar konten di perangkat Google Cast.
• Aplikasi contoh CastVideos-chrome (GitHub) - Jalankan, buka, dan lihat aplikasi contoh referensi ini yang mematuhi Panduan UX dan Checklist Desain.

Terminologi

Perangkat seluler atau browser adalah pengirim, yang mengontrol pemutaran; perangkat Google Cast adalah penerima, yang menampilkan konten di layar untuk diputar.

Web Sender SDK terdiri dari dua bagian: Framework API (cast.framework) dan Base API (chrome.cast) Secara umum, Anda melakukan panggilan pada Framework API yang lebih sederhana dan lebih tinggi, yang kemudian diproses oleh Base API yang lebih rendah.

Framework pengirim mengacu pada Framework API, modul, dan resource terkait yang menyediakan wrapper seputar fungsi tingkat rendah. Aplikasi pengirim atau aplikasi Google Cast Chrome mengacu pada aplikasi web (HTML/JavaScript) yang berjalan di dalam browser Chrome di perangkat pengirim. Aplikasi Penerima Web mengacu pada aplikasi HTML/JavaScript yang berjalan di Chromecast atau perangkat Google Cast.

Framework pengirim menggunakan desain callback asinkron untuk memberi tahu aplikasi pengirim tentang peristiwa dan untuk bertransisi di antara berbagai status siklus proses aplikasi Cast.

Memuat library

Agar aplikasi Anda dapat menerapkan fitur Google Cast, aplikasi tersebut perlu mengetahui lokasi Google Cast Web Sender SDK, seperti yang ditunjukkan di bawah. Tambahkan parameter kueri URL loadCastFramework untuk memuat Web Sender Framework API juga. Semua halaman aplikasi Anda harus merujuk ke library sebagai berikut:

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

Framework

Web Sender SDK menggunakan namespace cast.framework.*. Namespace mewakili hal berikut:

• Metode atau fungsi yang memanggil operasi di API
• Pemroses peristiwa untuk fungsi pemroses di API

Framework ini terdiri dari komponen utama berikut:

• CastContext adalah objek singleton yang memberikan informasi tentang status Transmisi saat ini, dan memicu peristiwa untuk perubahan status Transmisi dan status sesi Transmisi.
• Objek CastSession mengelola sesi -- objek ini memberikan informasi status dan memicu peristiwa, seperti perubahan pada volume perangkat, status bisu, dan metadata aplikasi.
• Elemen tombol Cast, yang merupakan elemen kustom HTML sederhana yang memperluas tombol HTML. Jika tombol Cast yang disediakan tidak memadai, Anda dapat menggunakan status Cast untuk menerapkan tombol Cast.
• RemotePlayerController menyediakan data binding untuk menyederhanakan implementasi pemutar jarak jauh.

Tinjau Referensi API Google Cast Web Sender untuk mengetahui deskripsi lengkap namespace.

Tombol Cast

Komponen tombol Cast di aplikasi Anda sepenuhnya ditangani oleh framework. Hal ini mencakup pengelolaan visibilitas, serta penanganan peristiwa klik.

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

Atau, Anda dapat membuat tombol secara terprogram:

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

Anda dapat menerapkan gaya tambahan, seperti ukuran atau pemosisian, ke elemen sesuai kebutuhan. Gunakan atribut --connected-color untuk memilih warna status Penerima Web yang terhubung, dan --disconnected-color untuk status terputus.

Inisialisasi

Setelah memuat API framework, aplikasi akan memanggil pengendali window.__onGCastApiAvailable. Anda harus memastikan bahwa aplikasi menetapkan pengendali ini pada window sebelum memuat library pengirim.

Dalam pengendali ini, Anda menginisialisasi interaksi Cast dengan memanggil metode setOptions(options) dari CastContext.

Contoh:

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

Kemudian, lakukan inisialisasi API sebagai berikut:

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

Pertama, aplikasi mengambil instance singleton dari objek CastContext yang disediakan oleh framework. Kemudian, class ini menggunakan setOptions(options) menggunakan objek CastOptions untuk menetapkan applicationID.

Jika menggunakan Penerima Media Default, yang tidak memerlukan pendaftaran, Anda menggunakan konstanta yang telah ditentukan oleh Web Sender SDK, seperti yang ditunjukkan di bawah, bukan applicationID:

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

Kontrol media

Setelah CastContext diinisialisasi, aplikasi dapat mengambil CastSession saat ini kapan saja menggunakan getCurrentSession().

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

CastSession dapat digunakan untuk memuat media ke perangkat Cast yang terhubung menggunakan loadMedia(loadRequest). Pertama, buat MediaInfo, menggunakan contentId dan contentType serta informasi lain yang terkait dengan konten. Kemudian, buat LoadRequest dari permintaan tersebut, dengan menetapkan semua informasi yang relevan untuk permintaan. Terakhir, panggil loadMedia(loadRequest) di CastSession Anda.

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

Metode loadMedia akan menampilkan Promise yang dapat digunakan untuk melakukan operasi yang diperlukan agar mendapatkan hasil yang berhasil. Jika Promise ditolak, argumen fungsi akan menjadi chrome.cast.ErrorCode.

Anda dapat mengakses variabel status pemain di RemotePlayer. Semua interaksi dengan RemotePlayer, termasuk callback dan perintah peristiwa media, ditangani dengan RemotePlayerController.

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

RemotePlayerController memberi aplikasi kontrol media penuh atas PLAY, PAUSE, STOP, dan SEEK untuk media yang dimuat.

• PUTAR/JEDA: playerController.playOrPause();
• STOP: playerController.stop();
• SEEK: playerController.seek();

RemotePlayer dan RemotePlayerController dapat digunakan dengan framework data binding, seperti Polymer atau Angular, untuk mengimplementasikan pemutar jarak jauh.

Berikut adalah cuplikan kode untuk 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>

Status media

Selama pemutaran media, berbagai peristiwa terjadi yang dapat ditangkap dengan menetapkan pemroses untuk berbagai peristiwa cast.framework.RemotePlayerEventType pada objekRemotePlayerController.

Untuk mendapatkan informasi status media, gunakan peristiwa cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, yang dipicu saat pemutaran berubah dan saat CastSession.getMediaSession().media berubah.

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

Saat peristiwa seperti jeda, putar, lanjutkan, atau cari terjadi, aplikasi harus menindaklanjutinya dan menyinkronkan antara aplikasi itu sendiri dan aplikasi Penerima Web di perangkat Cast. Lihat Pembaruan status untuk mengetahui informasi selengkapnya.

Cara kerja pengelolaan sesi

Cast SDK memperkenalkan konsep sesi Cast, yang pembentukannya menggabungkan langkah-langkah menghubungkan ke perangkat, meluncurkan (atau bergabung) ke aplikasi Penerima Web, menghubungkan ke aplikasi tersebut, dan melakukan inisialisasi saluran kontrol media. Lihat Panduan siklus proses aplikasi Penerima Web untuk mengetahui informasi selengkapnya tentang sesi Cast dan siklus proses Penerima Web.

Sesi dikelola oleh class CastContext, yang dapat diambil aplikasi Anda melalui cast.framework.CastContext.getInstance(). Sesi individual diwakili oleh subclass dari class Session. Misalnya, CastSession mewakili sesi dengan perangkat Cast. Aplikasi Anda dapat mengakses sesi Transmisi yang sedang aktif melalui CastContext.getCurrentSession().

Untuk memantau status sesi, tambahkan pemroses ke CastContext untuk jenis peristiwa 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;
    }
  })

Untuk pemutusan koneksi, seperti saat pengguna mengklik tombol "hentikan transmisi" dari dialog Transmisi, Anda dapat menambahkan pemroses untuk jenis peristiwa RemotePlayerEventType.IS_CONNECTED_CHANGED di pemroses Anda. Di pemroses, periksa apakah RemotePlayer terputus. Jika ya, perbarui status pemain lokal seperlunya. Contoh:

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

Meskipun pengguna dapat langsung mengontrol penghentian Transmisi melalui tombol Transmisi framework, pengirim itu sendiri dapat menghentikan transmisi menggunakan objek CastSession saat ini.

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

Transfer streaming

Mempertahankan status sesi adalah dasar dari transfer streaming, yang memungkinkan pengguna memindahkan streaming audio dan video yang ada di seluruh perangkat menggunakan perintah suara, Aplikasi Google Home, atau layar smart. Media berhenti diputar di satu perangkat (sumber) dan dilanjutkan di perangkat lain (tujuan). Semua perangkat Cast dengan firmware terbaru dapat berfungsi sebagai sumber atau tujuan dalam transfer streaming.

Untuk mendapatkan perangkat tujuan baru selama transfer streaming, panggil CastSession#getCastDevice() saat peristiwa cast.framework.SessionState.SESSION_RESUMED dipanggil.

Lihat Transfer streaming di Penerima Web untuk mengetahui informasi selengkapnya.