Menambahkan Fitur Lanjutan ke Aplikasi Pengirim Web Anda

Jeda Iklan

Web Sender SDK memberikan dukungan untuk Jeda Iklan dan iklan pengiring dalam aliran media tertentu.

Lihat Ringkasan Jeda Iklan Penerima Web untuk mendapatkan informasi selengkapnya tentang cara kerja Jeda Iklan.

Meskipun jeda dapat ditentukan di pengirim dan penerima, sebaiknya jeda ditentukan di Penerima Web dan Penerima Android TV untuk mempertahankan perilaku yang konsisten di seluruh platform.

Di web, tentukan Jeda Iklan dalam perintah muat menggunakan BreakClip dan Break:

let breakClip1 = new BreakClip('bc0');
breakClip1.title = 'Clip title'
breakClip1.posterUrl = 'https://www.some.url';
breakClip1.duration = 60;
breakClip.whenSKippable = 5;

let breakClip2 = ...
let breakClip3 = ...

let break1 = new Break('b0', ['bc0', 'bc1', 'bc2'], 10);

let mediaInfo = new chrome.cast.media.MediaInfo(<contentId>, '<contentType');
...
mediaInfo.breakClips = [breakClip1, breakClip2, breakClip3];
mediaInfo.breaks = [break1];

let request = new chrome.cast.media.LoadRequest(mediaInfo);

cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request)

Menggunakan API jalur

Trek dapat berupa objek teks (subtitel atau teks), atau objek streaming audio atau video. API Jalur memungkinkan Anda bekerja dengan objek ini dalam aplikasi.

Catatan: Penerima Bergaya dan Media Default memungkinkan Anda hanya menggunakan trek teks dengan API. Untuk menggunakan trek audio dan video, Anda harus mengembangkan Penerima Kustom.

Objek Track mewakili jalur di SDK. Anda dapat mengonfigurasi jalur dan menetapkan ID unik pada jalur tersebut seperti ini:

var englishSubtitle = new chrome.cast.media.Track(1, // track ID
  chrome.cast.media.TrackType.TEXT);
englishSubtitle.trackContentId = 'https://some-url/caption_en.vtt';
englishSubtitle.trackContentType = 'text/vtt';
englishSubtitle.subtype = chrome.cast.media.TextTrackType.SUBTITLES;
englishSubtitle.name = 'English Subtitles';
englishSubtitle.language = 'en-US';
englishSubtitle.customData = null;

var frenchSubtitle = new chrome.cast.media.Track(2, // track ID
  chrome.cast.media.TrackType.TEXT);
frenchSubtitle.trackContentId = 'https://some-url/caption_fr.vtt';
frenchSubtitle.trackContentType = 'text/vtt';
frenchSubtitle.subtype = chrome.cast.media.TextTrackType.SUBTITLES;
frenchSubtitle.name = 'French Subtitles';
frenchSubtitle.language = 'fr';
frenchSubtitle.customData = null;

var frenchAudio = new chrome.cast.media.Track(3, // track ID
  chrome.cast.media.TrackType.AUDIO);
frenchAudio.trackContentId = 'trk0001';
frenchAudio.trackContentType = 'audio/mp3';
frenchAudio.subtype = null;
frenchAudio.name = 'French Audio';
frenchAudio.language = 'fr';
frenchAudio.customData = null;

Item media dapat memiliki beberapa trek; misalnya, dapat memiliki beberapa subtitel (masing-masing untuk bahasa berbeda) atau beberapa streaming audio alternatif (untuk bahasa berbeda).

MediaInfo adalah class yang memodelkan item media. Untuk mengaitkan kumpulan objek Track dengan item media, perbarui properti tracks. Pengaitan ini harus dilakukan sebelum media dimuat ke penerima:

var tracks = [englishSubtitle, frenchSubtitle, frenchAudio];
var mediaInfo = new chrome.cast.media.MediaInfo(mediaURL);
mediaInfo.contentType = 'video/mp4';
mediaInfo.metadata = new chrome.cast.media.GenericMediaMetadata();
mediaInfo.customData = null;
mediaInfo.streamType = chrome.cast.media.StreamType.BUFFERED;
mediaInfo.textTrackStyle = new chrome.cast.media.TextTrackStyle();
mediaInfo.duration = null;
mediaInfo.tracks = tracks;

Anda dapat menetapkan jalur aktif di permintaan activeTrackIds media.

Anda juga dapat mengaktifkan satu atau beberapa jalur yang terkait dengan item media, setelah media dimuat, dengan memanggil EditTracksInfoRequest(opt_activeTrackIds, opt_textTrackStyle) dan meneruskan ID jalur yang akan diaktifkan di opt_activeTrackIds. Perhatikan bahwa kedua parameter tersebut bersifat opsional dan Anda dapat memilih, jalur atau gaya aktif, yang ingin ditetapkan sesuai diskresi Anda. Misalnya, berikut cara mengaktifkan subtitel bahasa Prancis (2) dan audio bahasa Prancis (3):

var activeTrackIds = [2, 3];
var tracksInfoRequest = new chrome.cast.media.EditTracksInfoRequest(activeTrackIds);
media.editTracksInfo(tracksInfoRequest, successCallback, errorCallback);

Untuk menghapus semua trek audio atau video dari media saat ini, cukup setel mediaInfo.tracks=null (array kosong) dan muat ulang media.

Untuk menghapus semua trek teks dari media saat ini (misalnya, menonaktifkan subtitel), lakukan salah satu hal berikut:

• Update var activeTrackIds = [2, 3]; (ditampilkan sebelumnya) sehingga hanya menyertakan [3], trek audio.
• Setel mediaInfo.tracks=null. Perhatikan bahwa Anda tidak perlu memuat ulang media untuk menonaktifkan teks teks (track.hidden). Mengirimkan array activeTracksId yang tidak berisi trackId yang sebelumnya diaktifkan akan menonaktifkan trek teks.

Menata gaya trek teks

TextTrackStyle adalah objek yang mengenkapsulasi informasi gaya visual jalur teks. Setelah membuat atau mengupdate objek TextTrackStyle yang ada, Anda dapat menerapkannya ke item media yang sedang diputar dengan memanggil metode editTrackInfo, seperti ini:

var textTrackStyle = new chrome.cast.media.TextTrackStyle();
var tracksInfoRequest = new chrome.cast.media.EditTracksInfoRequest(textTrackStyle);
media.editTracksInfo(tracksInfoRequest, successCallback, errorCallback);

Anda dapat melacak status permintaan dengan hasil callback, baik berhasil maupun error, dan memperbarui pengirim asal sebagaimana mestinya.

Aplikasi harus mengizinkan pengguna memperbarui gaya untuk trek teks, baik menggunakan setelan yang disediakan oleh sistem maupun oleh aplikasi itu sendiri.

Anda dapat menata gaya elemen gaya trek teks berikut:

• Warna dan opasitas latar depan (teks)
• Warna dan opasitas latar belakang
• Jenis tepi
• Warna Tepi
• Skala Font
• Jenis Font
• Gaya Font

Misalnya, setel warna teks ke merah dengan opasitas 75% seperti berikut:

var textTrackStyle = new chrome.cast.media.TextTrackStyle();
textTrackStyle.foregroundColor = '#80FF0000';

Kontrol volume

Anda dapat menggunakan RemotePlayer dan RemotePlayerController untuk menyetel volume penerima.

function changeVolume(newVolume) {
  player.volumeLevel = newVolume;
  playerController.setVolumeLevel();
  // Update sender UI to reflect change
}

Aplikasi pengirim harus mematuhi panduan berikut untuk mengontrol volume:

• Aplikasi pengirim harus disinkronkan dengan penerima sehingga UI pengirim selalu melaporkan volume per penerima. Gunakan callback RemotePlayerEventType.VOLUME_LEVEL_CHANGED dan RemotePlayerEventType.IS_MUTED_CHANGED untuk mempertahankan volume pada pengirim. Lihat Pembaruan status untuk informasi selengkapnya.
• Aplikasi pengirim tidak boleh menyetel level volume pada level tertentu yang telah ditentukan atau menyetel level volume ke volume pendering/media perangkat pengirim saat aplikasi dimuat di penerima.

Lihat Kontrol volume pengirim dalam Checklist Desain.

Mengirim pesan media ke penerima

Media Messages dapat dikirim dari pengirim ke penerima. Misalnya, untuk mengirim pesan SKIP_AD ke penerima:

// Get a handle to the skip button element
const skipButton = document.getElementById('skip');
skipButton.addEventListener("click", function() {
  if (castSession) {
    const media = castSession.getMediaSession();
    castSession.sendMessage('urn:x-cast:com.google.cast.media', {
      type: 'SKIP_AD',
      requestId: 1,
      mediaSessionId: media.mediaSessionId
    });
  }
});

Pembaruan status

Saat beberapa pengirim terhubung ke penerima yang sama, setiap pengirim harus mengetahui perubahan pada penerima meskipun perubahan tersebut dimulai dari pengirim lain.

Catatan: Hal ini penting untuk semua aplikasi, bukan hanya aplikasi yang secara eksplisit mendukung beberapa pengirim, karena beberapa perangkat Cast memiliki input kontrol (remote, tombol) yang berperilaku sebagai pengirim virtual, yang memengaruhi status penerima.

Untuk mencapai tujuan ini, aplikasi Anda harus mendaftarkan semua pemroses yang diperlukan di RemotePlayerController. Jika TextTrackStyle media saat ini berubah, semua pengirim yang terhubung akan diberi tahu dan properti terkait sesi media saat ini, seperti activeTrackIds dan textTrackStyle dari kolom MediaInfo akan dikirim ke pengirim dalam callback. Dalam hal ini, SDK penerima tidak memverifikasi apakah gaya baru berbeda dari gaya sebelumnya dan akan memberi tahu semua pengirim yang terhubung.

Catatan: Daftar trek yang terkait dengan media yang saat ini dimuat tidak dapat diubah. Jika diperlukan, Anda harus memperbarui informasi jalur pada objek MediaInfo dan memuat ulang media.

Indikator progres

Menampilkan lokasi pemutaran dengan indikator progres pada pengirim adalah persyaratan untuk sebagian besar aplikasi. Cast API menggunakan protokol media Cast, yang mengoptimalkan konsumsi bandwidth untuk skenario ini dan skenario lainnya, sehingga Anda tidak perlu menerapkan sinkronisasi status Anda sendiri. Untuk implementasi indikator progres pemutaran media yang benar menggunakan API, lihat aplikasi contoh CastVideo-chrome.

Persyaratan CORS

Untuk streaming media adaptif, Google Cast memerlukan adanya header CORS, tetapi bahkan streaming media mp4 sederhana memerlukan CORS jika menyertakan Trek. Jika ingin mengaktifkan Trek untuk media apa pun, Anda harus mengaktifkan CORS untuk streaming lagu dan streaming media. Jadi, jika Anda tidak memiliki header CORS untuk media mp4 sederhana di server, lalu menambahkan trek subtitel sederhana, Anda tidak akan dapat melakukan streaming media kecuali Anda memperbarui server untuk menyertakan header CORS yang sesuai.

Anda memerlukan header berikut: Content-Type,Accept-Encoding, dan Range. Perhatikan bahwa dua header terakhir, Accept-Encoding dan Range, adalah header tambahan yang mungkin tidak Anda perlukan sebelumnya.

Karakter pengganti "*" tidak dapat digunakan untuk header Access-Control-Allow-Origin. Jika halaman memiliki konten media yang dilindungi, halaman tersebut harus menggunakan domain, bukan karakter pengganti.

Melanjutkan sesi tanpa memuat ulang halaman web

Untuk melanjutkan CastSession yang ada, gunakan requestSessionById(sessionId) dengan sessionId sesi yang Anda coba ikuti.

sessionId dapat ditemukan di CastSession aktif menggunakan getSessionId() setelah memanggil loadMedia().

Pendekatan yang direkomendasikan adalah:

1. Panggil loadMedia() untuk memulai sesi
2. Menyimpan sessionId secara lokal
3. Bergabung kembali ke sesi menggunakan requestSessionById(sessionId) jika diperlukan

let sessionId;

function rejoinCastSession() {
  chrome.cast.requestSessionById(sessionId);

  // Add any business logic to load new content or only resume the session
}

document.getElementById('play-button').addEventListener(("click"), function() {
  if (sessionId == null) {
    let castSession = cast.framework.CastContext.getInstance().getCurrentSession();
    if (castSession) {
      let mediaInfo = createMediaInfo();
      let request = new chrome.cast.media.LoadRequest(mediaInfo);
      castSession.loadMedia(request)

      sessionId = CastSession.getSessionId();
    } else {
      console.log("Error: Attempting to play media without a Cast Session");
    }
  } else {
    rejoinCastSession();
  }
});

Langkah berikutnya

Bagian ini mengakhiri fitur yang dapat Anda tambahkan ke aplikasi Pengirim Web. Kini Anda dapat membuat aplikasi pengirim untuk platform lain (Android atau iOS), atau membuat aplikasi penerima.