Panduan developer ini menjelaskan cara menambahkan dukungan Google Cast ke aplikasi Pengirim Web Anda menggunakan Cast SDK.
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 level rendah.
Framework pengirim mengacu pada Framework API, modul, dan resource terkait yang menyediakan wrapper di sekitar 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 dapat menerapkan fitur Google Cast, aplikasi Anda harus 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 Cast saat ini, dan memicu peristiwa untuk status Cast dan perubahan status sesi Cast.- Objek
CastSession
mengelola sesi -- objek ini memberikan informasi status dan memicu peristiwa, seperti perubahan pada volume perangkat, status bisukan, dan metadata aplikasi. - Elemen tombol Transmisikan, yang merupakan elemen kustom HTML sederhana yang memperluas tombol HTML. Jika tombol Transmisikan yang disediakan tidak memadai, Anda dapat menggunakan status Transmisikan untuk menerapkan tombol Transmisikan.
RemotePlayerController
menyediakan data binding untuk menyederhanakan implementasi pemutar jarak jauh.
Tinjau Referensi Google Cast Web Sender API untuk 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 untuk status Penerima Web yang terhubung, dan
--disconnected-color
untuk status yang terputus.
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 Transmisi dengan memanggil
metode
setOptions(options)
dari
CastContext
.
Contoh:
<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
if (isAvailable) {
initializeCastApi();
}
};
</script>
Kemudian, Anda melakukan 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, kode 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 sebelumnya 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
darinya, yang 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 untuk mendapatkan hasil yang berhasil.
Jika Promise ditolak, argumen fungsi akan berupa
chrome.cast.ErrorCode
.
Anda dapat mengakses variabel status pemutar 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 untuk
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 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 direkam dengan menetapkan pemroses untuk berbagai peristiwa cast.framework.RemotePlayerEventType
pada objek RemotePlayerController
.
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 pembuatannya menggabungkan langkah-langkah untuk menghubungkan ke perangkat, meluncurkan (atau bergabung) 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 Transmisi dan siklus proses Penerima Web.
Sesi dikelola oleh class
CastContext
,
yang dapat diambil aplikasi Anda melalui
cast.framework.CastContext.getInstance()
.
Setiap sesi diwakili oleh subclass dari class
Session
. Misalnya,
CastSession
mewakili sesi dengan perangkat Transmisi. Aplikasi Anda dapat mengakses sesi Cast
yang saat ini 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 "berhenti mentransmisikan" dari dialog Cast, Anda dapat menambahkan pemroses untuk jenis peristiwa RemotePlayerEventType
.IS_CONNECTED_CHANGED
di pemroses. Di pemroses, periksa apakah
RemotePlayer
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
}
});
Meskipun pengguna dapat mengontrol penghentian Cast secara langsung melalui tombol Cast
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 transfer streaming, tempat pengguna dapat 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 berlanjut 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.