Menambahkan Fitur Inti ke Penerima Web Kustom Anda

Halaman ini berisi cuplikan kode dan deskripsi fitur yang tersedia untuk aplikasi Penerima Web Khusus.

  1. Elemen cast-media-player yang mewakili UI pemutar bawaan yang disertakan dengan Penerima Web.
  2. Penataan gaya seperti CSS kustom untuk elemen cast-media-player untuk menata gaya berbagai Elemen UI seperti background-image, splash-image, dan font-family.
  3. Elemen skrip untuk memuat framework Penerima Web.
  4. kode JavaScript untuk mencegat pesan dan menangani peristiwa.
  5. Antrean untuk putar otomatis.
  6. Opsi untuk mengonfigurasi pemutaran.
  7. Opsi untuk menetapkan konteks Web Receiver.
  8. Opsi untuk menetapkan perintah yang didukung oleh aplikasi Web Receiver.
  9. Panggilan JavaScript untuk memulai aplikasi Penerima Web.

Opsi dan konfigurasi aplikasi

Mengonfigurasi aplikasi

Tujuan CastReceiverContext adalah kelas terluar yang diekspos ke developer, dan mengelola pemuatan library yang mendasarinya dan menangani inisialisasi Web Receiver SDK. SDK menyediakan API yang memungkinkan pengembang 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 ini menunjukkan cara mengganti perilaku default untuk mendeteksi apakah koneksi pengirim masih terhubung secara aktif. Ketika Penerima Web belum dapat berkomunikasi dengan pengirim untuk maxInactivity detik, peristiwa SENDER_DISCONNECTED akan dikirim. Konfigurasi di bawah akan mengganti waktu tunggu ini. Ini dapat berguna saat melakukan {i>debugging<i} masalah karena mencegah aplikasi Penerima Web dari menutup sesi Chrome Remote Debugger saat ada 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 pemutaran seperti DRM informasi tambahan, konfigurasi percobaan ulang, dan pengendali permintaan menggunakan cast.framework.PlaybackConfig Informasi ini ditangani oleh PlayerManager dan dievaluasi pada saat pemain dibuat. Pemain dibuat setiap kali beban baru diteruskan ke Web Receiver SDK. Modifikasi pada PlaybackConfig setelah pemain dibuat akan dievaluasi di berikutnya pemuatan konten. SDK menyediakan metode berikut untuk mengubah PlaybackConfig.

  • CastReceiverOptions.playbackConfig untuk mengganti opsi konfigurasi default saat menginisialisasi CastReceiverContext.
  • PlayerManager.getPlaybackConfig() untuk mendapatkan konfigurasi saat ini.
  • PlayerManager.setPlaybackConfig() untuk mengganti konfigurasi saat ini. Setelan ini diterapkan ke semua pemuatan berikutnya atau sampai digantikan lagi.
  • PlayerManager.setMediaPlaybackInfoHandler() menerapkan konfigurasi tambahan hanya untuk item media yang dimuat atas konfigurasi saat ini. Pengendali dipanggil tepat sebelum pemain pembuatan konten. Perubahan yang dibuat di sini tidak bersifat permanen dan tidak disertakan dalam kueri ke getPlaybackConfig(). Saat item media berikutnya dimuat, pengendali ini akan dipanggil lagi.

Contoh di bawah ini menunjukkan cara menyetel PlaybackConfig saat melakukan inisialisasi CastReceiverContext. Konfigurasi mengganti 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 di 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 pemuatan tertentu menggunakan pengendali info pemutaran media. Pengendali memanggil aplikasi mengimplementasikan metode 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. Tujuan pemroses peristiwa mengambil cast.framework.events.EventType (atau rangkaian parameter ini) yang menentukan peristiwa yang seharusnya memicu pemroses. Array{i> <i}yang telah dikonfigurasi sebelumnya cast.framework.events.EventType yang berguna untuk proses debug dapat ditemukan di cast.framework.events.category. Parameter peristiwa memberikan informasi tambahan tentang peristiwa.

Misalnya, jika Anda ingin tahu kapan mediaStatus disiarkan, Anda bisa menggunakan logika berikut untuk menangani acara:

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 mencegat pesan dan mengeksekusi kode kustom pada pesan tersebut. Pencegat pesan mengambil cast.framework.messages.MessageType yang menetapkan jenis pesan yang harus dicegat.

Pencegat harus menampilkan permintaan yang dimodifikasi atau Promise yang menyelesaikan dengan nilai permintaan yang diubah. Menampilkan null akan mencegah pemanggilan sebagai pengendali pesan default. Lihat Memuat media untuk detail selengkapnya.

Misalnya, jika Anda ingin mengubah data permintaan pemuatan, Anda dapat menggunakan metode logika berikut untuk mencegat 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 akan ditampilkan aplikasi yang tepat cast.framework.messages.ErrorType dan cast.framework.messages.ErrorReason

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 ini:

  • 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 mendengarkan pesan, menyadapnya, dan mengubah data permintaan itu sendiri.
  • Intersepsi pesan paling baik digunakan untuk menangani logika khusus yang berkaitan dengan data permintaan.

Memuat media

MediaInformation menyediakan berbagai properti untuk memuat media di Pesan cast.framework.messages.MessageType.LOAD termasuk entity, contentUrl, dan contentId.

  • entity adalah properti yang disarankan untuk digunakan dalam penerapan Anda, baik bagi pengirim maupun aplikasi penerima. Properti adalah URL deep link yang dapat berupa playlist atau konten media. Aplikasi Anda harus mengurai URL ini dan mengisi setidaknya satu dari dua {i>field<i} lainnya.
  • contentUrl sesuai dengan URL yang dapat diputar yang akan digunakan pemutar untuk memuat konten. Misalnya, URL ini bisa mengarah ke manifes DASH.
  • contentId dapat berupa URL konten yang dapat diputar (mirip dengan contentUrl ) atau ID unik untuk konten atau playlist yang dimuat. Jika menggunakan properti ini sebagai ID, aplikasi Anda harus mengisi URL yang dapat dimainkan di contentUrl.

Sebaiknya gunakan entity untuk menyimpan ID atau parameter kunci yang sebenarnya, dan gunakan contentUrl sebagai URL media. Contohnya ditampilkan di cuplikan berikut yang berisi entity dalam permintaan LOAD dan contentUrl yang dapat dimainkan 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

Tujuan getDeviceCapabilities memberikan informasi perangkat pada perangkat Cast yang terhubung dan video atau perangkat audio yang terpasang padanya. Metode getDeviceCapabilities memberikan dukungan informasi untuk Asisten Google, Bluetooth, serta layar dan audio yang terhubung perangkat.

Metode ini menampilkan objek yang dapat Anda kueri dengan meneruskan salah satu metode enum yang ditentukan untuk mendapatkan kemampuan perangkat untuk enum tersebut. Enum tersebut adalah didefinisikan 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, secara berurutan.

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 Anda melalui pengirim aplikasi (Web, Android, dan iOS), perintah suara di aplikasi yang dilengkapi dengan Asisten perangkat, kontrol sentuh di layar smart, dan remote control di Android TV perangkat. SDK Cast menyediakan berbagai API agar aplikasi Penerima Web dapat menangani interaksi ini, memperbarui UI aplikasi melalui status tindakan pengguna, dan secara opsional mengirim perubahan untuk memperbarui layanan backend.

Perintah media yang didukung

Status kontrol UI didorong oleh MediaStatus.supportedMediaCommands untuk pengontrol, penerima, dan remote control yang diperluas pengirim iOS dan Android aplikasi yang berjalan di perangkat sentuh, dan aplikasi penerima di perangkat Android TV. Ketika seorang bitwise tertentu Command diaktifkan dalam properti, tombol yang yang terkait dengan tindakan tersebut diaktifkan. Jika nilai tidak ditetapkan, maka tombol akan dinonaktifkan. Nilai ini dapat diubah di Penerima Web dengan:

  1. Menggunakan PlayerManager.setSupportedMediaCommands untuk menyetel atribut Commands
  2. Menambahkan perintah baru menggunakan addSupportedMediaCommands
  3. Menghapus perintah yang ada menggunakan removeSupportedMediaCommands
playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

Saat penerima menyiapkan MediaStatus yang diupdate, penerima akan menyertakan perubahan di properti supportedMediaCommands. Saat statusnya adalah 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 Accessing UI controls kami.

Mengelola status tindakan pengguna

Saat pengguna berinteraksi dengan UI atau mengirimkan perintah suara, mereka dapat mengontrol pemutaran konten dan properti yang terkait dengan item yang diputar. 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 tersebut, hal berikut harus dilakukan:

  • Setel 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. Klien kemudian melakukan panggilan untuk memperbarui UserActionState pada 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. {i>Function<i} ini memeriksa UserActionRequestData untuk melihat jenis perubahan yang diminta pengguna dan hanya melakukan panggilan jaringan jika tindakan 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 menggunakan UserActionRequestData dan menambahkan atau menghapus UserActionState dari MediaInformation. Memperbarui UserActionState dari MediaInformation mengubah status tombol yang dikaitkan dengan tindakan yang diminta. Perubahan ini tercermin dalam UI kontrol tampilan, aplikasi remote control, dan UI Android TV. Ini juga disiarkan melalui pesan MediaStatus keluar untuk memperbarui 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 {i>default<i} dari perintah ini adalah 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 Asisten- perangkat seluler, Anda harus terlebih dahulu menyetel perintah media yang didukung yang rencananya akan Anda dukung. Kemudian Anda harus melaksanakan perintah tersebut dengan mengaktifkan tindakan CastReceiverOptions.enforceSupportedCommands saat ini. UI pada pengirim Cast SDK dan perangkat yang mendukung sentuhan akan berubah menjadi mencerminkan konfigurasi ini. Jika penanda tidak diaktifkan, suara masuk akan dieksekusi.

Misalnya, jika Anda mengizinkan PAUSE dari aplikasi pengirim dan perangkat yang mendukung sentuhan, Anda juga harus mengonfigurasi penerima untuk mencerminkan hal tersebut setelan. Saat dikonfigurasi, semua perintah suara yang masuk akan dihapus, jika tidak termasuk dalam daftar perintah yang didukung.

Pada contoh di bawah ini, kami menyediakan CastReceiverOptions saat memulai CastReceiverContext. Kami telah menambahkan dukungan untuk perintah PAUSE dan memberlakukan pemain untuk hanya mendukung perintah itu. Sekarang jika perintah suara meminta operasi lain seperti SEEK, tindakan tersebut akan ditolak. Pengguna akan diberi tahu bahwa perintah tersebut 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 Anda membatasi Anda dapat mencegat pesan masuk. Di sini, kita menangkap permintaan 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 penyebab error, 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 adanya Asisten aktivitas seperti mendengarkan ucapan pengguna atau berbicara FocusState pesan NOT_IN_FOCUS 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 jeda media saat FocusState adalah NOT_IN_FOCUS dengan mencegat pesan ketik FOCUS_STATE.

Misalnya, sebaiknya jeda pemutaran buku audio jika ada pengalaman pengguna yang baik Asisten merespons kueri pengguna.

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

Ketika pengguna tidak secara eksplisit menyatakan bahasa untuk teks, bahasa yang digunakan untuk teks adalah bahasa yang sama dengan bahasa perintah yang diucapkan. Dalam skenario ini, isSuggestedLanguage pesan masuk tersebut menunjukkan apakah bahasa terkait disarankan atau diminta secara eksplisit oleh pengguna.

Misalnya, isSuggestedLanguage disetel ke true untuk perintah "Ok Google, nyalakan teks," karena bahasa disimpulkan oleh bahasa yang perintah lisan yang digunakan. 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 {i>metadata<i} untuk konten Anda lengkap dan akurat. Hal ini memastikan bahwa perintah suara ditangani dengan benar oleh Asisten dan metadata muncul dengan benar di berbagai jenis antarmuka baru seperti aplikasi Google Home dan layar smart seperti Google Home Hub.

Transfer streaming

Mempertahankan status sesi adalah dasar dari transfer streaming, dengan pengguna dapat memindahkan streaming audio dan video yang ada di seluruh perangkat menggunakan perintah suara, Google Home Aplikasi, 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 di atau transfer data.

Alur peristiwa untuk transfer streaming adalah:

  1. Di perangkat sumber:
    1. Media berhenti diputar.
    2. Aplikasi Penerima Web menerima perintah untuk menyimpan media saat ini status.
    3. Aplikasi Penerima Web dimatikan.
  2. Di perangkat tujuan:
    1. Aplikasi Penerima Web dimuat.
    2. Aplikasi Penerima Web menerima perintah untuk memulihkan media yang tersimpan status.
    3. 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:

  1. Perbarui supportedMediaCommands dengan perintah STREAM_TRANSFER: 
    playerManager.addSupportedMediaCommands(
cast.framework.messages.Command.STREAM_TRANSFER, true);
  2. Ganti pesan SESSION_STATE dan RESUME_SESSION (opsional) penyerang seperti yang dijelaskan dalam Mempertahankan sesi status Hanya ganti jika memerlukan data khusus untuk disimpan sebagai bagian dari {i>snapshot<i} sesi. Jika tidak, nilai default untuk mempertahankan status sesi akan mendukung transfer streaming.

Mempertahankan status sesi

Web Receiver SDK menyediakan implementasi default untuk aplikasi Penerima Web untuk mempertahankan status sesi dengan mengambil cuplikan status media saat ini, mengonversi status menjadi permintaan pemuatan, dan melanjutkan sesi dengan permintaan pemuatan.

Permintaan pemuatan yang dihasilkan oleh Penerima Web dapat diganti di Insepsi pesan SESSION_STATE jika perlu. Jika Anda ingin menambahkan data kustom ke dalam permintaan pemuatan, sebaiknya masukkan 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 pemutaran saat ini item dalam antrean.

Operasi pramuat melakukan pra-download beberapa segmen dari item yang akan datang. Spesifikasi dilakukan pada preloadTime nilai pada Objek QueueItem (setelan default 20 detik jika tidak diberikan). Waktu dinyatakan dalam detik, relatif terhadap akhir item yang sedang diputar . Hanya nilai positif yang valid. Misalnya, jika nilainya 10 detik, item ini akan dipramuat 10 detik detik sebelum item sebelumnya selesai. Jika waktu untuk melakukan pramuat lebih tinggi daripada waktu yang tersisa pada currentItem, pramuat akan terjadi segera setelah sebaik mungkin. Jadi, jika nilai pramuat yang sangat besar ditentukan pada queueItem, satu dapat mencapai efek kapan pun kita memutar item yang saat ini kita sudah melakukan pramuat item berikutnya. Namun, kita membiarkan pengaturan dan pilihan kepada developer karena nilai ini dapat memengaruhi performa bandwidth dan streaming dari item yang sedang diputar.

Pramuat akan berfungsi untuk konten HLS, DASH, dan Smooth streaming secara default.

File video dan audio MP4 biasa seperti MP3 tidak akan dimuat sebelumnya sebagai Cast perangkat hanya mendukung satu elemen media dan tidak dapat digunakan untuk pramuat saat item konten yang sudah 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 pengirim (Android, iOS, Web). Objek peristiwa (yang adalah manifesasi pesan) yang diteruskan ke pemroses peristiwa memiliki elemen data (event.data) tempat data menggunakan properti elemen jenis peristiwa tertentu.

Aplikasi Penerima Web dapat memilih untuk mendengarkan pesan pada namespace. Dengan melakukannya, aplikasi {i>Web Receiver <i}dikatakan mendukung protokol namespace itu. Hal ini tergantung pada setiap pengirim yang terhubung yang ingin untuk berkomunikasi pada namespace itu untuk menggunakan protokol yang sesuai.

Semua namespace ditentukan oleh string dan harus diawali dengan "urn:x-cast:" diikuti oleh beberapa {i>string<i}. Misalnya, "urn:x-cast:com.example.cast.mynamespace".

Berikut ini adalah cuplikan kode untuk Penerima Web untuk mendengarkan pesan khusus 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 dari Penerima Web dengan mengirim pesan ke pengirim yang terhubung. Penerima Web aplikasi dapat mengirim pesan menggunakan sendCustomMessage(namespace, senderId, message) aktif CastReceiverContext Penerima Web dapat mengirim pesan ke pengirim individu, baik sebagai tanggapan atas pesan yang diterima atau karena perubahan status aplikasi. Melebihi point-to-point pesan (dengan batas 64 kb), Penerima Web juga dapat menyiarkan pesan ke semua pengirim yang terhubung.

Transmisi untuk perangkat audio

Lihat panduan Google Cast untuk perangkat audio guna mendapatkan dukungan terkait audio pemutaran saja.

Android TV

Bagian ini membahas cara {i>Google Web Receiver <i}menggunakan {i>input<i} 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 pemutaran media pesan yang ditentukan untuk namespace urn:x-cast:com.google.cast.media, sebagai yang dijelaskan dalam Pesan Pemutaran Media. Nama aplikasi harus mendukung pesan ini untuk mengontrol media aplikasi pemutaran untuk memungkinkan kontrol pemutaran dasar dari kontrol Android TV input.

Panduan untuk kompatibilitas Android TV

Berikut adalah beberapa rekomendasi dan kesalahan umum yang harus dihindari untuk memastikan aplikasi Anda kompatibel dengan Android TV:

  • Perlu diketahui bahwa string agen pengguna berisi "Android" dan "CrKey"; beberapa situs mungkin mengalihkan ke situs khusus seluler karena mendeteksi "Android" label. 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 pengaturan waktu yang berbeda Chromecast, informasi ini dapat mengungkapkan masalah yang disembunyikan di Chromecast.
  • Saat memperbarui media, gunakan peristiwa terkait media yang diaktifkan oleh <audio>/<video> elemen, seperti timeupdate, pause, dan waiting. Hindari penggunaan jaringan peristiwa terkait seperti progress, suspend, dan stalled, karena cenderung bergantung pada platform. Lihat Peristiwa media untuk mengetahui informasi selengkapnya tentang cara menangani peristiwa media di penerima.
  • Saat mengonfigurasi sertifikat HTTPS situs penerima, pastikan untuk menyertakan CA perantara. Lihat Halaman pengujian SSL Qualsys untuk verifikasi: apakah jalur sertifikasi tepercaya untuk situs Anda menyertakan CA sertifikat berlabel “download tambahan”, maka sertifikat tersebut mungkin tidak dimuat di perangkat berbasis Android di berbagai platform Google.
  • Meskipun Chromecast menampilkan laman penerima pada bidang grafis 720p, komponen Platform transmisi termasuk Android TV dapat menampilkan halaman hingga 1080p. Pastikan laman penerima Anda dapat diskalakan dengan baik pada berbagai resolusi.
Sebelumnya
Penerima Web Kustom
Berikutnya
HLS di Migrasi Shaka Player