Menambahkan Fitur Lanjutan ke Aplikasi Pengirim Web Anda

Jeda Iklan

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

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

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

Di web, tentukan Jeda Iklan dalam perintah pemuatan 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. Track API memungkinkan Anda bekerja dengan objek ini di 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 merepresentasikan jalur di SDK. Anda dapat mengonfigurasi jalur dan menetapkan ID unik ke 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, item media dapat memiliki beberapa subtitel (masing-masing untuk bahasa yang berbeda) atau beberapa streaming audio alternatif (untuk bahasa yang berbeda).

MediaInfo adalah class yang memodelkan item media. Untuk mengaitkan kumpulan objek Track dengan item media, update properti tracks. Pengaitan ini perlu 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 dalam 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 bersifat opsional dan Anda dapat memilih gaya atau trek aktif yang akan ditetapkan sesuai kebijaksanaan 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 langkah 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). Mengirim array activeTracksId yang tidak berisi trackId yang diaktifkan sebelumnya akan menonaktifkan jalur teks.

Menata gaya trek teks

TextTrackStyle adalah objek yang merangkum informasi gaya visual jalur teks. Setelah membuat atau memperbarui 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 mengalami error, dan memperbarui pengirim asal sebagaimana mestinya.

Aplikasi harus memungkinkan pengguna memperbarui gaya untuk jalur teks, baik menggunakan setelan yang disediakan oleh sistem atau 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 menjadi merah dengan opasitas 75% sebagai 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 menyinkronkan dengan penerima agar 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 sebelumnya atau menyetel level volume ke volume pendering/media perangkat pengirim saat aplikasi dimuat di penerima.

Lihat Kontrol volume pengirim di 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

Jika 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, tidak hanya yang secara eksplisit mendukung beberapa pengirim, karena beberapa perangkat Transmisi memiliki input kontrol (remote, tombol) yang berperilaku sebagai pengirim virtual, sehingga memengaruhi status pada penerima.

Untuk mencapainya, aplikasi Anda harus mendaftarkan semua pemroses yang diperlukan pada RemotePlayerController. Jika TextTrackStyle media saat ini berubah, semua pengirim yang terhubung akan diberi tahu dan properti yang sesuai dari 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 tersebut berbeda dengan gaya sebelumnya dan tidak akan memberi tahu semua pengirim yang terhubung.

Catatan: Daftar jalur yang terkait dengan media yang saat ini dimuat tidak dapat diubah. Jika perlu, 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 lainnya, sehingga Anda tidak perlu menerapkan sinkronisasi status Anda sendiri. Untuk penerapan indikator progres yang tepat untuk pemutaran media menggunakan API, lihat aplikasi contoh CastVideo-chrome.

Persyaratan CORS

Untuk streaming media adaptif, Google Cast memerlukan keberadaan header CORS, tetapi streaming media mp4 yang sederhana pun memerlukan CORS jika streaming media mp4 tersebut menyertakan Trek. Jika ingin mengaktifkan Trek untuk media apa pun, Anda harus mengaktifkan CORS untuk streaming lagu dan streaming media Anda. 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 jika Anda mengupdate 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 memiliki konten media yang dilindungi, halaman 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. Simpan sessionId secara lokal
3. Bergabunglah 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 merangkum fitur yang dapat Anda tambahkan ke aplikasi Web Sender. Sekarang Anda dapat membuat aplikasi pengirim untuk platform lain (Android atau iOS), atau membuat aplikasi penerima.