Bermigrasi ke Penerima Web

Panduan ini menjelaskan cara memigrasikan aplikasi Penerima Cast v2 ke versi Web terbaru Aplikasi penerima.

SDK Kerangka Kerja Aplikasi Cast (CAF) baru, yang juga dikenal sebagai Penerima Web v3, adalah upgrade besar dari SDK Receiver v2. Web Receiver SDK menyediakan SDK yang mudah dan disederhanakan untuk mengembangkan aplikasi Penerima Web media.

Penerima Web menyediakan API yang lebih konsisten dengan pengirim CAF yang baru Google Cloud Platform. Aplikasi ini menyediakan integrasi penuh dari pemutar (MPL dan Shaka) dan implementasi dan dukungan untuk media Cast dan Asisten Google perintah suara. CAF SDK juga menyediakan UI default yang mudah ditata gayanya menggunakan CSS, dan layanan data binding untuk menyederhanakan implementasi UI.

Mengapa melakukan migrasi?

Dengan memigrasikan aplikasi Receiver v2 ke {i>Web Receiver<i}, banyak kode yang berhubungan dengan pemain bisa dihilangkan, sehingga Anda dapat berkonsentrasi pada menulis logika bisnis khusus aplikasi.

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

Bermigrasi ke CAF akan menambahkan dukungan untuk kontrol suara dengan Asisten Google. Semua perintah suara baru Asisten Google akan otomatis didukung saat menggunakan CAF.

Selain mendukung perintah media baru, seperti "ubah jalur berdasarkan bahasa" dan "mengubah kecepatan pemutaran”—CAF juga memberikan antrean yang lebih baik, iklan bawaan dukungan teknis, 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 dari objek data yang digunakan oleh v2 sama dalam CAF dan diekspos di bawah tindakan cast.framework.messages namespace (sebagian besar berada 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, pengiriman pesan, dan peristiwa sistem global. Tujuan CastReceiverOptions dapat digunakan untuk menyediakan opsi aplikasi global (seperti antrean, penerima versi, konfigurasi pemutaran, dll.) ke konteks.
  • Class MediaManager diganti dengan PlayerManager yang merupakan properti CastReceiverContext singleton, dan mengelola sesi media, permintaan media, Google Permintaan suara Asisten (CommandAndControlManager di v2), dan memicu peristiwa media. Konfigurasi untuk pemain (cast.player.api.Host dalam MPL) disediakan oleh PlaybackConfig, yang dapat diberikan secara global atau per permintaan pemuatan.

PlayerManager juga mengekspos 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

Pengendali peristiwa yang terekspos penerima v2 (seperti CastReceiverManager.onReady atau MediaManager.onLoad) untuk menambahkan logika bisnis. Di CAF, pengendali peristiwa adalah diganti dengan pemroses peristiwa (CastReceiverContext.addEventListener) dan penyadapan pesan (PlayerManager.setMessageInterceptor). Penerima Web dapat memiliki beberapa pemroses peristiwa untuk sebuah peristiwa (pemroses tidak memengaruhi peristiwa), dan satu intersepsi per pesan. Intersepsi dapat memperbarui permintaan atau menanganinya (mengembalikan permintaan yang dimodifikasi, pesan error, atau pesan error), dan dapat berupa pengendali asinkron yang menampilkan promise.

Intersepsi permintaan pemuatan adalah tempat paling umum untuk menambahkan logika khusus aplikasi. Untuk permintaan pemuatan dari pengirim, beban penyadapan dapat mengonversi ID konten menjadi URL konten. Intersepsi beban adalah juga dipanggil untuk permintaan pramuat dan precache jika tidak ada intersepsi eksplisit yang disediakan untuk pramuat atau precache.

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 yang disesuaikan v2 juga diganti dengan pesan intersepsi untuk pesan status media. Aplikasi Penerima Web yang tidak ingin mengekspos URL media dalam status media dapat memberikan resolver URL (PlayerManager.setMediaUrlResolver), yang menyediakan URL media untuk permintaan pemuatan. URL tersebut digunakan oleh CAF secara internal dan tidak dicantumkan dalam status media.

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

Acara

Web Receiver menyediakan rangkaian peristiwa ekstensif baik dari CastReceiverContext dan PlayerManager. Aplikasi Penerima Web dapat memiliki beberapa pemroses pada peristiwa apa pun, dan juga dapat memberikan satu pemroses ke beberapa peristiwa. (Lihat cast.framework.events.category untuk beberapa kelompok peristiwa.)

Peristiwa tersebut mencakup semua 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 teks melacak definisi saat pemuatan selesai), atau untuk analisis.

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

Bus pesan kustom

CAF tidak mengekspos bus pesan di API, tetapi memberikan CastReceiverContext.addCustomMessageListener untuk menambahkan pemroses pesan untuk namespace tertentu (hanya satu per namespace) dan CastReceiverContext.sendCustomMessage untuk mengirim pesan pada namespace. Semua namespace harus dideklarasikan sebelum memulai Penerima Web (yakni, sebelum memanggil CastReceiverContext.start). Namespace dapat dideklarasikan dengan menambahkan pemroses pesan kepada mereka atau dapat diberikan sebagai opsi memulai 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 bisa ditata dengan gaya seperti CSS.

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

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