Bermigrasi ke Penerima Web

Panduan ini menjelaskan cara memigrasikan aplikasi Cast Receiver v2 ke aplikasi Web Receiver terbaru.

Cast Application Framework (CAF) SDK yang baru, juga dikenal sebagai Web Receiver v3, merupakan upgrade besar dari Receiver v2 SDK. Web Receiver SDK menyediakan SDK yang mudah dan sederhana untuk mengembangkan aplikasi Media Web Receiver.

Penerima Web menyediakan API yang lebih konsisten dengan API pengirim CAF yang baru. Ini menyediakan integrasi penuh pemutar (MPL dan Shaka) dan implementasi dan dukungan penuh untuk media Google Cast dan perintah suara Asisten Google. CAF SDK juga menyediakan UI default yang dapat dengan mudah diberi gaya menggunakan CSS, dan layanan data binding untuk menyederhanakan implementasi UI.

Mengapa bermigrasi?

Dengan memigrasikan aplikasi Receiver v2 ke Penerima Web, banyak kode yang berkaitan dengan pemain dapat dihilangkan, sehingga Anda dapat berkonsentrasi pada penulisan logika bisnis khusus aplikasi.

CAF mengintegrasikan pemutar MPL dan Shaka dengan lancar untuk mendukung berbagai jenis konten, termasuk—Live Streaming HTTP (TS dan CMAF), MPEG-DASH, Smooth Streaming, dan jenis yang didukung oleh properti sumber Elemen Media (MP3, MP4, Icecast, dll.). Untuk daftar lengkap, lihat Media yang Didukung untuk Google Cast. Saat ini CAF tidak mendukung pemutar yang disediakan pengguna.

Melakukan migrasi ke CAF akan menambahkan dukungan untuk kontrol suara dengan Asisten Google. Setiap perintah suara Asisten Google baru akan otomatis didukung saat menggunakan CAF.

Selain mendukung perintah media baru—seperti "ubah trek berdasarkan bahasa” dan "ubah kecepatan pemutaran”—CAF juga menyediakan antrean yang lebih baik, dukungan iklan bawaan, dan dukungan langsung yang lebih baik.

Apa yang berubah?

Web Receiver API mencoba mengikuti konvensi yang diperkenalkan oleh pengirim CAF untuk Android dan iOS, dan sangat berbeda dengan v2.

Penerima Web menggunakan namespace baru cast.framework, bukan namespace cast.receiver untuk semua API yang diekspos. Banyak objek data yang digunakan oleh v2 sama di CAF dan diekspos di namespace cast.framework.messages (sebagian besar di bawah cast.receiver.media).

Layanan v2 berikut diganti dengan layanan CAF yang sesuai:

  • Class CastReceiverManager diganti dengan CastReceiverContext yang merupakan singleton yang mengelola sesi transmisi, pengirim, mengirim pesan kustom, dan peristiwa sistem global. CastReceiverOptions dapat digunakan untuk menyediakan opsi aplikasi global (seperti antrean, versi penerima, konfigurasi pemutaran, dll.) ke konteks.
  • Class MediaManager diganti dengan PlayerManager yang merupakan properti singleton CastReceiverContext, dan mengelola sesi media, permintaan media, permintaan suara Asisten Google (CommandAndControlManager di v2), dan mengaktifkan peristiwa media. Konfigurasi untuk pemutar (cast.player.api.Host dalam MPL) disediakan oleh PlaybackConfig, yang dapat disediakan secara global atau per permintaan pemuatan.

PlayerManager juga memperlihatkan class sub-pengelola baru:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

// Set global options.
const options = new cast.framework.CastReceiverOptions();
options.versionCode = DEVELOPERS_APP_VERSION;

context.start(options);

Logika bisnis penerima

Penerima peristiwa mengekspos penerima v2 (seperti CastReceiverManager.onReady atau MediaManager.onLoad) untuk menambahkan logika bisnis. Di CAF, pengendali peristiwa diganti dengan pemroses peristiwa (CastReceiverContext.addEventListener) dan intersep pesan (PlayerManager.setMessageInterceptor). Penerima Web dapat memiliki beberapa pemroses peristiwa untuk sebuah peristiwa (pemroses tidak memengaruhi peristiwa), dan satu intersep peristiwa per pesan. Interseptor dapat memperbarui permintaan atau menanganinya (menampilkan permintaan yang dimodifikasi, pesan yang berhasil, atau pesan error), dan dapat menjadi pengendali asinkron yang menampilkan promise.

Intersep permintaan pemuatan adalah tempat paling umum untuk menambahkan logika khusus aplikasi. Untuk permintaan pemuatan dari pengirim, interseptor beban dapat mengonversi ID konten menjadi URL konten. Interseptor beban juga dipanggil untuk permintaan pramuat dan pracache jika intersep eksplisit tidak diberikan untuk pramuat atau pracache.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      // Resolve entity to content id
      if (request.media.entity && !request.media.contentId) {
        return getMediaByEntity(request.media.entity).then(
            media => {
              request.media.contentId = media.url;
              return request;
            });
      }
      return request;
    });

Pengendali status media kustom v2 juga diganti dengan intersepsi pesan untuk pesan status media. Aplikasi Penerima Web yang tidak ingin mengekspos URL media dalam status media dapat menyediakan resolver URL (PlayerManager.setMediaUrlResolver), yang menyediakan URL media untuk permintaan pemuatan. URL tersebut digunakan oleh CAF secara internal dan tidak diberikan dalam status media.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.MEDIA_STATUS,
    status => {
      // Disable seek.
      status.supportedMediaCommands &=
          ~cast.framework.messages.Command.SEEK
      return status;
    });

Peristiwa

Penerima Web menyediakan serangkaian peristiwa ekstensif dari CastReceiverContext dan PlayerManager. Aplikasi Penerima Web dapat memiliki beberapa pemroses pada peristiwa apa pun, dan juga dapat menyediakan satu pemroses untuk beberapa peristiwa. (Lihat cast.framework.events.category untuk beberapa grup peristiwa.)

Peristiwa ini mencakup permintaan pengguna, progres pemutaran, pemrosesan pemutar, dan peristiwa elemen media tingkat rendah (CAF tidak mengekspos elemen media itu sendiri).

Aplikasi Penerima Web dapat menambahkan pemroses peristiwa untuk ditindaklanjuti (misalnya, menambahkan definisi jalur teks saat pemuatan selesai), atau untuk analisis.

// Log all media commands
playerManager.addEventListener(
    cast.framework.events.category.REQUEST,
    event => logEvent(event.type));

Bus pesan khusus

CAF tidak mengekspos bus pesan di API, tetapi menyediakan CastReceiverContext.addCustomMessageListener untuk menambahkan pemroses pesan bagi namespace tertentu (hanya satu per namespace) dan CastReceiverContext.sendCustomMessage untuk mengirim pesan di namespace. Semua namespace harus dideklarasikan sebelum memulai Penerima Web (yaitu, sebelum memanggil CastReceiverContext.start). Namespace dapat dideklarasikan dengan menambahkan pemroses pesan ke namespace tersebut atau dapat diberikan sebagai opsi awal di CastReceiverOptions.customNamespaces.

const options = new cast.framework.CastReceiverOptions();
options.customNamespaces = {
    CUSTOM_NS: cast.framework.system.MessageType.JSON
};
context.start(options);

context.sendCustomMessage(CUSTOM_NS, {
  type: 'status'
  message: 'Playing'
});

UI default

CAF menyediakan UI Penerima Web default yang menampilkan status progres pemutaran dan metadata media sesuai kebutuhan. UI default disediakan sebagai elemen kustom (<cast-media-player>) yang dapat diberi gaya dengan gaya seperti CSS.

<style>
   cast-media-player { --splash-image: url("splash.png"); }
</style>
<cast-media-player></cast-media-player>

Untuk penyesuaian lainnya, aplikasi Penerima Web dapat mengimplementasikan UI-nya sendiri. Penerima Web menyediakan class cast.framework.ui.PlayerDataBinder untuk membantu mengikat objek UI ke status pemutaran Penerima Web.