Mengintegrasikan Cast SDK ke Aplikasi Pengirim Web Anda

Panduan pengembang ini menjelaskan cara menambahkan dukungan Google Cast ke Web Anda Aplikasi pengirim menggunakan Cast SDK.

Terminologi

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

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

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

Framework pengirim menggunakan desain callback asinkron untuk memberi tahu pengirim aplikasi peristiwa dan transisi antara berbagai status kehidupan aplikasi Cast siklus.

Memuat library

Agar aplikasi Anda dapat menerapkan fitur Google Cast, aplikasi perlu mengetahui 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 cast.framework.* namespace. Namespace ini mewakili hal berikut:

  • Metode atau fungsi yang memanggil operasi pada 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, serta memicu peristiwa untuk status Transmisi dan sesi Transmisi perubahan status.
  • CastSession mengelola sesi -- objek tersebut memberikan status dan memicu peristiwa, seperti perubahan volume perangkat, status bisukan audio, 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.

Ulas Referensi API Pengirim Web Google Cast untuk deskripsi lengkap tentang namespace.

Tombol Cast

Komponen tombol Cast di aplikasi Anda ditangani sepenuhnya oleh framework. 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 bisa menerapkan gaya tambahan, seperti ukuran atau penempatan, ke sesuai kebutuhan. Gunakan atribut --connected-color untuk memilih warna untuk status Penerima Web yang tersambung, dan --disconnected-color untuk status tidak terhubung.

Inisialisasi

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

Dalam pengendali ini, Anda melakukan inisialisasi interaksi Cast dengan memanggil setOptions(options) dari CastContext

Contoh:

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

Kemudian, inisialisasi API seperti 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 kerangka kerja. Kemudian menggunakan setOptions(options) menggunakan Objek CastOptions untuk menetapkan applicationID.

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

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

Kontrol media

Setelah CastContext telah diinisialisasi, aplikasi dapat mengambil CastSession kapan saja waktu 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 lainnya yang terkait dengan konten. Kemudian buat LoadRequest dari sana, mengatur semua informasi yang relevan untuk permintaan itu. 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 apa pun yang diperlukan untuk mendapatkan hasil yang sukses. Jika Promise ditolak, argumen fungsi akan berupa chrome.cast.ErrorCode

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

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

RemotePlayerController memberi aplikasi kontrol media penuh atas PUTAR, JEDA, BERHENTI, dan LIHAT media yang telah dimuat.

  • PUTAR/JEDA: playerController.playOrPause();
  • BERHENTI: playerController.stop();
  • LIHAT: playerController.seek();

RemotePlayer dan RemotePlayerController dapat berupa digunakan dengan framework data binding, seperti Polymer atau Angular, untuk menerapkan 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 menyetel pendengar untuk berbagai cast.framework.RemotePlayerEventType acara di objek RemotePlayerController.

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

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 menjeda, memutar, melanjutkan, atau mencari terjadi, aplikasi harus melakukan tindakan pada perangkat tersebut dan melakukan sinkronisasi antara aplikasi itu sendiri dan aplikasi Web Receiver di Cast perangkat seluler. Lihat Pembaruan status untuk informasi selengkapnya.

Cara kerja pengelolaan sesi

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

Sesi dikelola oleh kelas 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 data yang aktif saat ini Sesi transmisi melalui CastContext.getCurrentSession()

Untuk memantau status sesi, tambahkan pemroses ke CastContext untuk tindakan 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 "hentikan transmisi" tombol dari dialog Cast, Anda dapat menambahkan pemroses untuk RemotePlayerEventType.IS_CONNECTED_CHANGED di pemroses Anda. Di pemroses, periksa apakah RemotePlayer sama dengan terputus. Jika ya, perbarui status pemutar lokal sesuai kebutuhan. Contoh:

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

Pengguna dapat langsung mengontrol penghentian Cast melalui Cast framework pengirim dapat menghentikan transmisi menggunakan 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);
}

Transfer streaming

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

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

Lihat Transfer streaming di Penerima Web untuk informasi selengkapnya.