Halaman ini berisi cuplikan kode dan deskripsi fitur yang tersedia untuk aplikasi Penerima Web Khusus.
- Elemen
cast-media-player
yang merepresentasikan UI pemutar bawaan yang disediakan dengan Penerima Web. - Gaya visual mirip CSS kustom untuk elemen
cast-media-player
untuk menata gaya berbagai elemen UI sepertibackground-image
,splash-image
, danfont-family
. - Elemen skrip untuk memuat framework Penerima Web.
- kode JavaScript untuk mencegat pesan dan menangani peristiwa.
- Antrean untuk putar otomatis.
- Opsi untuk mengonfigurasi pemutaran.
- Opsi untuk menetapkan konteks Web Receiver.
- Opsi untuk menetapkan perintah yang didukung oleh aplikasi Web Receiver.
- Panggilan JavaScript untuk memulai aplikasi Penerima Web.
Opsi dan konfigurasi aplikasi
Mengonfigurasi aplikasi
CastReceiverContext
adalah class terluar yang diekspos ke developer, dan mengelola pemuatan
library dasar dan menangani inisialisasi Web Receiver SDK. SDK
menyediakan API yang memungkinkan developer aplikasi mengonfigurasi SDK melalui
CastReceiverOptions
.
Konfigurasi ini dievaluasi sekali per peluncuran aplikasi dan diteruskan ke
SDK saat menetapkan parameter opsional dalam panggilan ke
start
.
Contoh di bawah menunjukkan cara mengganti perilaku default untuk mendeteksi apakah
koneksi pengirim masih terhubung secara aktif. Saat Penerima Web tidak
dapat berkomunikasi dengan pengirim selama
maxInactivity
detik, peristiwa SENDER_DISCONNECTED
akan dikirim. Konfigurasi di bawah ini mengganti waktu tunggu ini. Tindakan ini dapat berguna saat men-debug masalah karena mencegah
aplikasi Penerima Web menutup sesi Chrome Remote Debugger saat tidak ada
pengirim yang terhubung dalam status IDLE
.
const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; // Development only
context.start(options);
Mengonfigurasi pemutar
Saat memuat konten, Web Receiver SDK menyediakan cara untuk mengonfigurasi variabel
pemutaran seperti informasi
DRM,
konfigurasi coba lagi, dan pengendali permintaan menggunakan
cast.framework.PlaybackConfig
.
Informasi ini ditangani oleh
PlayerManager
dan dievaluasi pada saat pemain dibuat. Pemutar dibuat
setiap kali beban baru diteruskan ke Web Receiver SDK. Modifikasi pada
PlaybackConfig
setelah pemain dibuat akan dievaluasi pada pemuatan
konten berikutnya. SDK menyediakan metode berikut untuk mengubah
PlaybackConfig
.
CastReceiverOptions.playbackConfig
untuk mengganti opsi konfigurasi default saat melakukan inisialisasiCastReceiverContext
.PlayerManager.getPlaybackConfig()
untuk mendapatkan konfigurasi saat ini.PlayerManager.setPlaybackConfig()
untuk mengganti konfigurasi saat ini. Setelan ini diterapkan ke semua pemuatan berikutnya atau hingga diganti lagi.PlayerManager.setMediaPlaybackInfoHandler()
guna menerapkan konfigurasi tambahan hanya untuk item media yang dimuat di atas konfigurasi saat ini. Pengendali dipanggil tepat sebelum pembuatan pemain. Perubahan yang dibuat di sini tidak bersifat permanen dan tidak disertakan dalam kueri untukgetPlaybackConfig()
. Saat item media berikutnya dimuat, pengendali ini akan dipanggil lagi.
Contoh di bawah menunjukkan cara menetapkan PlaybackConfig
saat menginisialisasi
CastReceiverContext
. Konfigurasi menggantikan permintaan keluar untuk
mendapatkan manifes. Pengendali menentukan bahwa permintaan Access-Control CORS harus dibuat menggunakan kredensial seperti cookie atau header otorisasi.
const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});
Contoh di bawah menunjukkan cara mengganti PlaybackConfig
menggunakan pengambil
dan penyetel yang disediakan dalam PlayerManager
. Setelan ini mengonfigurasi pemutar untuk
melanjutkan pemutaran konten setelah 1 segmen dimuat.
const playerManager =
cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);
Contoh di bawah menunjukkan cara mengganti PlaybackConfig
untuk permintaan pemuatan
tertentu menggunakan pengendali info pemutaran media. Pengendali memanggil
metode yang diimplementasikan aplikasi getLicenseUrlForMedia
untuk mendapatkan licenseUrl
dari
contentId
item saat ini.
playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
const mediaInformation = loadRequestData.media;
playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);
return playbackConfig;
});
Pemroses peristiwa
Web Receiver SDK memungkinkan aplikasi Web Receiver Anda menangani peristiwa pemutar. Pemroses peristiwa menggunakan parameter cast.framework.events.EventType
(atau array parameter ini) yang menentukan peristiwa yang harus memicu pemroses. Array cast.framework.events.EventType
yang telah dikonfigurasi sebelumnya dan berguna untuk proses debug dapat ditemukan di cast.framework.events.category
.
Parameter peristiwa memberikan informasi tambahan tentang peristiwa.
Misalnya, jika ingin mengetahui kapan
perubahan mediaStatus
disiarkan, Anda dapat menggunakan logika berikut untuk menangani
peristiwa:
const playerManager =
cast.framework.CastReceiverContext.getInstance().getPlayerManager();
playerManager.addEventListener(
cast.framework.events.EventType.MEDIA_STATUS, (event) => {
// Write your own event handling code, for example
// using the event.mediaStatus value
});
Intersepsi pesan
Web Receiver SDK memungkinkan aplikasi Web Receiver Anda menangkap pesan dan
menjalankan kode kustom pada pesan tersebut. Pencegat pesan menggunakan parameter cast.framework.messages.MessageType
yang menentukan jenis pesan yang harus dicegat.
Intersepsi harus menampilkan permintaan yang diubah atau Promise yang di-resolve
dengan nilai permintaan yang diubah. Menampilkan null
akan mencegah pemanggilan pengendali pesan default. Lihat Memuat media untuk detail selengkapnya.
Misalnya, jika ingin mengubah data permintaan pemuatan, Anda dapat menggunakan logika berikut untuk menangkap dan mengubahnya:
const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, loadRequestData => {
const error = new cast.framework.messages.ErrorData(
cast.framework.messages.ErrorType.LOAD_FAILED);
if (!loadRequestData.media) {
error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
return error;
}
if (!loadRequestData.media.entity) {
return loadRequestData;
}
return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
loadRequestData.credentials)
.then(asset => {
if (!asset) {
throw cast.framework.messages.ErrorReason.INVALID_REQUEST;
}
loadRequestData.media.contentUrl = asset.url;
loadRequestData.media.metadata = asset.metadata;
loadRequestData.media.tracks = asset.tracks;
return loadRequestData;
}).catch(reason => {
error.reason = reason; // cast.framework.messages.ErrorReason
return error;
});
});
context.start();
Penanganan error
Saat terjadi error pada pencegat pesan, aplikasi Penerima Web harus menampilkan
cast.framework.messages.ErrorType
dan
cast.framework.messages.ErrorReason
yang sesuai.
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, loadRequestData => {
const error = new cast.framework.messages.ErrorData(
cast.framework.messages.ErrorType.LOAD_CANCELLED);
if (!loadRequestData.media) {
error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
return error;
}
...
return fetchAssetAndAuth(loadRequestData.media.entity,
loadRequestData.credentials)
.then(asset => {
...
return loadRequestData;
}).catch(reason => {
error.reason = reason; // cast.framework.messages.ErrorReason
return error;
});
});
Intersepsi pesan vs pemroses peristiwa
Beberapa perbedaan utama antara intersepsi pesan dan pemroses peristiwa adalah sebagai berikut:
- Pemroses peristiwa tidak mengizinkan Anda mengubah data permintaan.
- Pemroses peristiwa paling baik digunakan untuk memicu analisis atau fungsi kustom.
playerManager.addEventListener(cast.framework.events.category.CORE,
event => {
console.log(event);
});
- Intersepsi pesan memungkinkan Anda memproses pesan, menangkapnya, dan mengubah data permintaan itu sendiri.
- Intersepsi pesan paling baik digunakan untuk menangani logika kustom sehubungan dengan permintaan data.
Memuat media
MediaInformation
menyediakan banyak properti untuk memuat media dalam
pesan cast.framework.messages.MessageType.LOAD
, termasuk entity
,
contentUrl
, dan contentId
.
entity
adalah properti yang disarankan untuk digunakan dalam penerapan Anda bagi aplikasi pengirim dan penerima. Properti ini adalah URL deep link yang dapat berupa playlist atau konten media. Aplikasi Anda harus mengurai URL ini dan mengisi setidaknya satu dari dua kolom lainnya.contentUrl
sesuai dengan URL yang dapat diputar yang akan digunakan pemain untuk memuat konten. Misalnya, URL ini bisa mengarah ke manifes DASH.contentId
dapat berupa URL konten yang dapat diputar (serupa dengan properticontentUrl
) atau ID unik untuk konten atau playlist yang dimuat. Jika menggunakan properti ini sebagai ID, aplikasi Anda harus mengisi URL yang dapat diputar dicontentUrl
.
Sarannya adalah gunakan entity
untuk menyimpan ID atau parameter kunci sebenarnya, dan
gunakan contentUrl
untuk URL media. Contohnya ditunjukkan dalam
cuplikan berikut, tempat entity
ada dalam permintaan LOAD
dan
contentUrl
yang dapat diputar diambil:
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, loadRequestData => {
...
if (!loadRequestData.media.entity) {
// Copy the value from contentId for legacy reasons if needed
loadRequestData.media.entity = loadRequestData.media.contentId;
}
return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
loadRequestData.credentials)
.then(asset => {
loadRequestData.media.contentUrl = asset.url;
...
return loadRequestData;
});
});
Kemampuan perangkat
Metode
getDeviceCapabilities
memberikan informasi perangkat pada perangkat Transmisi yang terhubung dan perangkat video atau
audio yang terpasang padanya. Metode getDeviceCapabilities
memberikan informasi
dukungan untuk Asisten Google, Bluetooth, serta perangkat layar dan audio
yang terhubung.
Metode ini menampilkan objek yang dapat Anda kueri dengan meneruskan salah satu
enum yang ditentukan guna mendapatkan kemampuan perangkat untuk enum tersebut. Enum
ditentukan dalam
cast.framework.system.DeviceCapabilities
.
Contoh ini memeriksa apakah perangkat Web Receiver dapat memutar HDR dan
DolbyVision (DV) dengan tombol IS_HDR_SUPPORTED
dan IS_DV_SUPPORTED
.
const context = cast.framework.CastReceiverContext.getInstance();
context.addEventListener(cast.framework.system.EventType.READY, () => {
const deviceCapabilities = context.getDeviceCapabilities();
if (deviceCapabilities &&
deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED]) {
// Write your own event handling code, for example
// using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED] value
}
if (deviceCapabilities &&
deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED]) {
// Write your own event handling code, for example
// using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED] value
}
});
context.start();
Menangani interaksi pengguna
Pengguna dapat berinteraksi dengan aplikasi Web Receiver melalui aplikasi pengirim (Web, Android, dan iOS), perintah suara di perangkat yang dilengkapi dengan Asisten, kontrol sentuh di layar smart, dan remote control di perangkat Android TV. Cast SDK menyediakan berbagai API agar aplikasi Penerima Web dapat menangani interaksi ini, mengupdate UI aplikasi melalui status tindakan pengguna, dan secara opsional mengirim perubahan untuk mengupdate layanan backend apa pun.
Perintah media yang didukung
Status kontrol UI didorong oleh
MediaStatus.supportedMediaCommands
untuk pengontrol yang diperluas pengirim iOS dan Android, aplikasi penerima dan remote control
yang berjalan di perangkat sentuh, serta aplikasi penerima di perangkat Android TV. Jika
Command
bitwise tertentu diaktifkan dalam properti, tombol yang terkait
dengan tindakan tersebut akan diaktifkan. Jika nilai tidak disetel, tombol akan
dinonaktifkan. Nilai ini dapat diubah di Penerima Web dengan:
- Menggunakan
PlayerManager.setSupportedMediaCommands
untuk menetapkanCommands
spesifik - Menambahkan perintah baru menggunakan
addSupportedMediaCommands
- Menghapus perintah yang ada menggunakan
removeSupportedMediaCommands
.
playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
cast.framework.messages.Command.PAUSE);
Saat penerima menyiapkan MediaStatus
yang diperbarui, penerima akan menyertakan
perubahan dalam properti supportedMediaCommands
. Saat status
disiarkan, aplikasi pengirim yang terhubung akan memperbarui tombol di UI-nya
sebagaimana mestinya.
Untuk informasi selengkapnya tentang perintah media dan perangkat sentuh yang didukung, lihat
panduan
Accessing UI controls
.
Mengelola status tindakan pengguna
Saat berinteraksi dengan UI atau mengirimkan perintah suara, pengguna dapat mengontrol
pemutaran konten dan properti yang terkait dengan pemutaran item. Permintaan
yang mengontrol pemutaran ditangani secara otomatis oleh SDK. Permintaan yang
mengubah properti untuk item yang sedang diputar, seperti perintah LIKE
,
mengharuskan aplikasi penerima menanganinya. SDK menyediakan serangkaian
API untuk menangani jenis permintaan ini. Untuk mendukung permintaan ini, hal-hal berikut
harus dilakukan:
- Tetapkan
MediaInformation
userActionStates
dengan preferensi pengguna saat memuat item media. - Intersep pesan
USER_ACTION
dan tentukan tindakan yang diminta. - Update
MediaInformation
UserActionState
untuk mengupdate UI.
Cuplikan berikut menangkap permintaan LOAD
dan mengisi
MediaInformation
LoadRequestData
. Dalam hal ini, pengguna menyukai
konten yang sedang dimuat.
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
const userActionLike = new cast.framework.messages.UserActionState(
cast.framework.messages.UserAction.LIKE);
loadRequestData.media.userActionStates = [userActionLike];
return loadRequestData;
});
Cuplikan berikut mencegat pesan USER_ACTION
dan menangani panggilan
backend dengan perubahan yang diminta. Selanjutnya, aplikasi akan melakukan panggilan untuk mengupdate
UserActionState
di penerima.
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.USER_ACTION,
(userActionRequestData) => {
// Obtain the media information of the current content to associate the action to.
let mediaInfo = playerManager.getMediaInformation();
// If there is no media info return an error and ignore the request.
if (!mediaInfo) {
console.error('Not playing media, user action is not supported');
return new cast.framework.messages.ErrorData(messages.ErrorType.BAD_REQUEST);
}
// Reach out to backend services to store user action modifications. See sample below.
return sendUserAction(userActionRequestData, mediaInfo)
// Upon response from the backend, update the client's UserActionState.
.then(backendResponse => updateUserActionStates(backendResponse))
// If any errors occurred in the backend return them to the cast receiver.
.catch((error) => {
console.error(error);
return error;
});
});
Cuplikan berikut menyimulasikan panggilan ke layanan backend. Fungsi tersebut memeriksa UserActionRequestData
untuk melihat jenis perubahan yang diminta pengguna dan hanya melakukan panggilan jaringan jika tindakan ini didukung oleh backend.
function sendUserAction(userActionRequestData, mediaInfo) {
return new Promise((resolve, reject) => {
switch (userActionRequestData.userAction) {
// Handle user action changes supported by the backend.
case cast.framework.messages.UserAction.LIKE:
case cast.framework.messages.UserAction.DISLIKE:
case cast.framework.messages.UserAction.FOLLOW:
case cast.framework.messages.UserAction.UNFOLLOW:
case cast.framework.messages.UserAction.FLAG:
case cast.framework.messages.UserAction.SKIP_AD:
let backendResponse = {userActionRequestData: userActionRequestData, mediaInfo: mediaInfo};
setTimeout(() => {resolve(backendResponse)}, 1000);
break;
// Reject all other user action changes.
default:
reject(
new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType.INVALID_REQUEST));
}
});
}
Cuplikan berikut mengambil UserActionRequestData
dan menambahkan atau
menghapus UserActionState
dari MediaInformation
. Memperbarui
UserActionState
MediaInformation
akan mengubah status tombol yang
terkait dengan tindakan yang diminta. Perubahan ini tercermin dalam UI
kontrol layar smart, aplikasi remote control, dan UI Android TV. Pengontrol ini juga
disiarkan melalui pesan MediaStatus
keluar untuk mengupdate UI
pengontrol yang diperluas untuk pengirim iOS dan Android.
function updateUserActionStates(backendResponse) {
// Unwrap the backend response.
let mediaInfo = backendResponse.mediaInfo;
let userActionRequestData = backendResponse.userActionRequestData;
// If the current item playing has changed, don't update the UserActionState for the current item.
if (playerManager.getMediaInformation().entity !== mediaInfo.entity) {
return;
}
// Check for existing userActionStates in the MediaInformation.
// If none, initialize a new array to populate states with.
let userActionStates = mediaInfo.userActionStates || [];
// Locate the index of the UserActionState that will be updated in the userActionStates array.
let index = userActionStates.findIndex((currUserActionState) => {
return currUserActionState.userAction == userActionRequestData.userAction;
});
if (userActionRequestData.clear) {
// Remove the user action state from the array if cleared.
if (index >= 0) {
userActionStates.splice(index, 1);
}
else {
console.warn("Could not find UserActionState to remove in MediaInformation");
}
} else {
// Add the UserActionState to the array if enabled.
userActionStates.push(
new cast.framework.messages.UserActionState(userActionRequestData.userAction));
}
// Update the UserActionState array and set the new MediaInformation
mediaInfo.userActionStates = userActionStates;
playerManager.setMediaInformation(mediaInfo, true);
return;
}
Perintah suara
Perintah media berikut saat ini didukung di Web Receiver SDK untuk
perangkat yang dilengkapi dengan Asisten. Implementasi default perintah ini
ditemukan di
cast.framework.PlayerManager
.
Perintah | Deskripsi |
---|---|
Putar | Memutar atau melanjutkan pemutaran dari status dijeda. |
Jeda | Jeda konten yang sedang diputar. |
Sebelumnya | Langsung ke item media sebelumnya di antrean media Anda. |
Berikutnya | Langsung ke item media berikutnya di antrean media Anda. |
Hentikan | Menghentikan media yang sedang diputar. |
Ulangi Tidak Ada | Nonaktifkan pengulangan item media dalam antrean setelah item terakhir dalam antrean selesai diputar. |
Ulangi Satu | Mengulangi media yang sedang diputar tanpa batas. |
Ulangi Semua | Ulangi semua item dalam antrean setelah item terakhir dalam antrean diputar. |
Mengulangi Semua dan Acak | Setelah item terakhir dalam antrean selesai diputar, acak antrean dan ulangi semua item dalam antrean. |
Acak | Acak item media di antrean media. |
Teks Tertutup AKTIF / NONAKTIF | Mengaktifkan / Menonaktifkan Pemberian Teks Tertutup untuk media Anda. Aktifkan / Nonaktifkan juga tersedia berdasarkan bahasa. |
Lompat ke waktu absolut | Melompat ke waktu absolut yang ditentukan. |
Mencari ke waktu relatif terhadap waktu saat ini | Melompat maju atau mundur selama jangka waktu yang ditentukan relatif terhadap waktu pemutaran saat ini. |
Main Lagi | Mulai ulang media yang sedang diputar atau putar item media yang terakhir diputar jika tidak ada yang sedang diputar. |
Menetapkan kecepatan pemutaran | Memvariasikan kecepatan pemutaran media. Hal ini seharusnya ditangani secara default. Anda dapat menggunakan pencegat pesan SET_PLAYBACK_RATE untuk mengganti permintaan tarif masuk. |
Perintah media yang didukung dengan suara
Untuk mencegah perintah suara memicu perintah media di perangkat yang dilengkapi dengan
Asisten, Anda harus terlebih dahulu menyetel
perintah media yang didukung
yang akan Anda dukung. Kemudian, Anda harus menerapkan perintah tersebut dengan mengaktifkan properti CastReceiverOptions.enforceSupportedCommands
. UI pada pengirim Cast SDK dan perangkat yang mendukung sentuhan akan berubah untuk
mencerminkan konfigurasi ini. Jika flag tidak diaktifkan, perintah
suara yang masuk akan dijalankan.
Misalnya, jika Anda mengizinkan PAUSE
dari aplikasi pengirim dan
perangkat yang mendukung sentuhan, Anda juga harus mengonfigurasi penerima untuk mencerminkan setelan
tersebut. Jika dikonfigurasi, semua perintah suara yang masuk akan dihapus jika tidak
disertakan dalam daftar perintah yang didukung.
Pada contoh di bawah, kami menyediakan CastReceiverOptions
saat memulai
CastReceiverContext
. Kami telah menambahkan dukungan untuk perintah PAUSE
dan
menerapkan pemain agar hanya mendukung perintah tersebut. Sekarang, jika perintah suara
meminta operasi lain seperti SEEK
, perintah tersebut akan ditolak. Pengguna akan
diberi tahu bahwa perintah belum didukung.
const context = cast.framework.CastReceiverContext.getInstance();
context.start({
enforceSupportedCommands: true,
supportedCommands: cast.framework.messages.Command.PAUSE
});
Anda dapat menerapkan logika terpisah untuk setiap perintah yang ingin dibatasi. Hapus
flag enforceSupportedCommands
dan untuk setiap perintah yang ingin
dibatasi, Anda dapat menangkap pesan masuk. Di sini, kami menangkap permintaan
yang disediakan oleh SDK sehingga perintah SEEK
yang dikeluarkan untuk perangkat yang dilengkapi dengan Asisten
tidak memicu pencarian di aplikasi Web Receiver Anda.
Untuk perintah media yang tidak didukung aplikasi Anda, tampilkan alasan
error yang sesuai, seperti
NOT_SUPPORTED
.
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.SEEK,
seekData => {
// Block seeking if the SEEK supported media command is disabled
if (!(playerManager.getSupportedMediaCommands() & cast.framework.messages.Command.SEEK)) {
let e = new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType
.INVALID_REQUEST);
e.reason = cast.framework.messages.ErrorReason.NOT_SUPPORTED;
return e;
}
return seekData;
});
Latar belakang dari aktivitas suara
Jika platform Cast mengalihkan suara aplikasi Anda ke latar belakang karena aktivitas
Asisten seperti mendengarkan ucapan pengguna atau berbicara kembali, pesan
FocusState
dari NOT_IN_FOCUS
akan dikirim ke aplikasi Penerima Web saat
aktivitas dimulai. Pesan lain dengan IN_FOCUS
dikirim saat aktivitas berakhir.
Bergantung pada aplikasi Anda dan media yang diputar, Anda mungkin ingin
menjeda media saat FocusState
adalah NOT_IN_FOCUS
dengan menangkap jenis
pesan FOCUS_STATE
.
Misalnya, sebaiknya jeda pemutaran buku audio jika Asisten merespons kueri pengguna akan memberikan pengalaman pengguna yang baik.
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.FOCUS_STATE,
focusStateRequestData => {
// Pause content when the app is out of focus. Resume when focus is restored.
if (focusStateRequestData.state == cast.framework.messages.FocusState.NOT_IN_FOCUS) {
playerManager.pause();
} else {
playerManager.play();
}
return focusStateRequestData;
});
Bahasa teks yang ditentukan suara
Jika pengguna tidak menyatakan bahasa untuk teks secara eksplisit, bahasa yang digunakan untuk teks adalah bahasa yang sama dengan bahasa perintah yang diucapkan.
Dalam skenario ini, parameter
isSuggestedLanguage
dari pesan masuk menunjukkan apakah bahasa terkait
disarankan atau diminta secara eksplisit oleh pengguna.
Misalnya, isSuggestedLanguage
disetel ke true
untuk perintah "OK Google,
aktifkan teks", karena bahasa disimpulkan oleh bahasa
penggunaan perintah. Jika bahasa diminta secara eksplisit, seperti dalam "Ok
Google, aktifkan teks bahasa Inggris", isSuggestedLanguage
disetel ke false
.
Transmisi suara dan metadata
Meskipun perintah suara ditangani oleh Penerima Web secara default, Anda harus memastikan bahwa metadata untuk konten sudah lengkap dan akurat. Hal ini memastikan bahwa perintah suara ditangani dengan benar oleh Asisten dan metadata muncul dengan benar di seluruh jenis antarmuka baru seperti aplikasi Google Home dan layar smart seperti Google Home Hub.
Transfer streaming
Mempertahankan status sesi adalah dasar dari 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). Setiap perangkat Cast dengan firmware terbaru dapat berfungsi sebagai sumber atau tujuan dalam transfer streaming.
Alur peristiwa untuk transfer streaming adalah:
- Di perangkat sumber:
- Media berhenti diputar.
- Aplikasi Penerima Web menerima perintah untuk menyimpan status media saat ini.
- Aplikasi Penerima Web dimatikan.
- Di perangkat tujuan:
- Aplikasi Penerima Web dimuat.
- Aplikasi Penerima Web menerima perintah untuk memulihkan status media yang tersimpan.
- Pemutaran media akan dilanjutkan.
Elemen status media meliputi:
- Posisi atau stempel waktu tertentu dari lagu, video, atau item media.
- Berada di antrean yang lebih luas (seperti playlist atau radio artis).
- Pengguna terautentikasi.
- Status pemutaran (misalnya, diputar atau dijeda).
Mengaktifkan transfer streaming
Untuk menerapkan transfer streaming untuk Penerima Web Anda:
- Perbarui
supportedMediaCommands
dengan perintahSTREAM_TRANSFER
:playerManager.addSupportedMediaCommands( cast.framework.messages.Command.STREAM_TRANSFER, true);
- Jika ingin, ganti interseptor pesan
SESSION_STATE
danRESUME_SESSION
seperti yang dijelaskan dalam Mempertahankan status sesi. Ganti parameter ini hanya jika data kustom perlu disimpan sebagai bagian dari snapshot sesi. Jika tidak, penerapan default untuk mempertahankan status sesi akan mendukung transfer streaming.
Mempertahankan status sesi
Web Receiver SDK menyediakan implementasi default untuk aplikasi Penerima Web guna mempertahankan status sesi dengan mengambil snapshot status media saat ini, mengonversi status menjadi permintaan pemuatan, dan melanjutkan sesi dengan permintaan pemuatan.
Permintaan pemuatan yang dibuat oleh Penerima Web dapat diganti dalam
intersepsi pesan SESSION_STATE
jika perlu. Jika Anda ingin menambahkan data kustom ke dalam permintaan pemuatan, sebaiknya tempatkan data tersebut di loadRequestData.customData
.
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.SESSION_STATE,
function (sessionState) {
// Override sessionState.loadRequestData if needed.
const newCredentials = updateCredentials_(sessionState.loadRequestData.credentials);
sessionState.loadRequestData.credentials = newCredentials;
// Add custom data if needed.
sessionState.loadRequestData.customData = {
'membership': 'PREMIUM'
};
return sessionState;
});
Data kustom dapat diambil dari
loadRequestData.customData
di interseptor pesan RESUME_SESSION
.
let cred_ = null;
let membership_ = null;
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.RESUME_SESSION,
function (resumeSessionRequest) {
let sessionState = resumeSessionRequest.sessionState;
// Modify sessionState.loadRequestData if needed.
cred_ = sessionState.loadRequestData.credentials;
// Retrieve custom data.
membership_ = sessionState.loadRequestData.customData.membership;
return resumeSessionRequest;
});
Pramuat konten
Penerima Web mendukung pramuat item media setelah item pemutaran saat ini dalam antrean.
Operasi pramuat akan melakukan pra-download beberapa segmen item mendatang. Spesifikasi dilakukan pada nilai preloadTime di objek QueueItem (default ke 20 detik jika tidak disediakan). Waktu dinyatakan dalam detik, sesuai dengan akhir item yang sedang diputar . Hanya nilai positif yang valid. Misalnya, jika nilainya 10 detik, item ini akan dipramuat 10 detik sebelum item sebelumnya selesai. Jika waktu untuk melakukan pramuat lebih tinggi daripada waktu yang tersisa pada currentItem, pramuat akan terjadi secepat mungkin. Jadi, jika nilai pramuat yang sangat besar ditentukan pada queueItem, kita dapat mencapai efek setiap kali kita memutar item saat ini. Kita sudah melakukan pramuat item berikutnya. Namun, kami menyerahkan setelan dan pilihan ini kepada developer karena nilai ini dapat memengaruhi performa bandwidth dan streaming dari item yang diputar saat ini.
Pramuat akan berfungsi untuk konten HLS, DASH, dan Smooth streaming secara default.
File video dan audio MP4 reguler seperti MP3 tidak akan dipramuat karena perangkat Cast hanya mendukung satu elemen media dan tidak dapat digunakan untuk melakukan pramuat saat item konten yang ada masih diputar.
Pesan kustom
Pertukaran pesan adalah metode interaksi utama untuk aplikasi Penerima Web.
Pengirim mengirimkan pesan ke Penerima Web menggunakan API pengirim untuk platform yang dijalankan pengirim (Android, iOS, Web). Objek peristiwa (yang merupakan manifesasi pesan) yang diteruskan ke pemroses peristiwa memiliki elemen data (event.data
) tempat data mengambil properti dari jenis peristiwa tertentu.
Aplikasi Penerima Web dapat memilih untuk memproses pesan pada namespace yang ditentukan. Dengan melakukannya, aplikasi Penerima Web dikatakan mendukung protokol namespace tersebut. Selanjutnya, setiap pengirim terhubung yang ingin berkomunikasi pada namespace tersebut untuk menggunakan protokol yang sesuai.
Semua namespace ditentukan oleh string dan harus diawali dengan "urn:x-cast:
"
diikuti dengan string apa pun. Misalnya,
"urn:x-cast:com.example.cast.mynamespace
".
Berikut adalah cuplikan kode untuk Penerima Web untuk memproses pesan kustom dari pengirim yang terhubung:
const context = cast.framework.CastReceiverContext.getInstance();
const CUSTOM_CHANNEL = 'urn:x-cast:com.example.cast.mynamespace';
context.addCustomMessageListener(CUSTOM_CHANNEL, function(customEvent) {
// handle customEvent.
});
context.start();
Demikian pula, aplikasi Penerima Web dapat terus memberi tahu pengirim tentang status Penerima Web dengan mengirim pesan ke pengirim yang terhubung. Aplikasi Penerima Web
dapat mengirim pesan menggunakan
sendCustomMessage(namespace, senderId, message)
pada
CastReceiverContext
.
Penerima Web dapat mengirim pesan ke pengirim individu, baik sebagai respons terhadap pesan yang diterima maupun karena perubahan status aplikasi. Selain fitur pesan point-to-point (dengan batas 64 kb), Web Receiver juga dapat menyiarkan pesan ke semua pengirim yang terhubung.
Transmisi untuk perangkat audio
Lihat panduan Google Cast untuk perangkat audio guna mendapatkan dukungan untuk pemutaran audio saja.
Android TV
Bagian ini membahas cara Google Web Receiver menggunakan input Anda sebagai pemutaran, dan kompatibilitas Android TV.
Mengintegrasikan aplikasi Anda dengan remote control
Google Web Receiver yang berjalan di perangkat Android TV menerjemahkan input dari
input kontrol perangkat (yaitu remote control genggam) sebagai pesan pemutaran
media yang ditentukan untuk namespace urn:x-cast:com.google.cast.media
, seperti
yang dijelaskan dalam Pesan Pemutaran Media. Aplikasi
Anda harus mendukung pesan ini untuk mengontrol pemutaran media
aplikasi agar dapat mengizinkan kontrol pemutaran dasar dari input kontrol
Android TV.
Panduan untuk kompatibilitas Android TV
Berikut beberapa rekomendasi dan kesalahan umum yang harus dihindari untuk memastikan aplikasi Anda kompatibel dengan Android TV:
- Perhatikan bahwa string agen pengguna berisi "Android" dan "CrKey"; beberapa situs mungkin mengalihkan ke situs khusus seluler karena mendeteksi label "Android". Jangan berasumsi bahwa "Android" dalam string agen pengguna selalu menunjukkan pengguna seluler.
- Tumpukan media Android dapat menggunakan GZIP transparan untuk mengambil data. Pastikan
data media Anda dapat merespons
Accept-Encoding: gzip
. - Peristiwa media HTML5 Android TV dapat dipicu dalam waktu yang berbeda dengan Chromecast. Hal ini dapat mengungkapkan masalah yang tersembunyi di Chromecast.
- Saat memperbarui media, gunakan peristiwa terkait media yang diaktifkan oleh elemen
<audio>/<video>
, sepertitimeupdate
,pause
, danwaiting
. Hindari penggunaan peristiwa terkait jaringan sepertiprogress
,suspend
, danstalled
, karena peristiwa tersebut cenderung bergantung pada platform. Lihat Peristiwa media untuk mengetahui informasi selengkapnya tentang cara menangani peristiwa media di penerima Anda. - Saat mengonfigurasi sertifikat HTTPS situs penerima, pastikan untuk menyertakan sertifikat CA perantara. Lihat halaman pengujian SSL Qualsys untuk memverifikasi: jika jalur sertifikasi tepercaya untuk situs Anda menyertakan sertifikat CA berlabel “download tambahan”, file tersebut mungkin tidak dimuat di platform berbasis Android.
- Meskipun Chromecast menampilkan halaman penerima pada bidang grafis 720p, platform Transmisi lainnya termasuk Android TV dapat menampilkan halaman hingga 1080p. Pastikan halaman penerima dapat diskalakan dengan baik pada berbagai resolusi.