Tambahkan Fitur Inti ke Penerima Web Khusus Anda

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

Catatan: Sebaiknya Anda mencoba hal berikut:

• Tutorial codelab Penerima Web Cast - Pelajari langkah demi langkah cara membuat aplikasi Penerima Web yang kompatibel untuk Cast menggunakan Google Cast SDK yang dapat menerima transmisi video.
• Aplikasi contoh CastReceiver (GitHub) - Jalankan, navigasikan, dan lihat aplikasi contoh referensi ini yang mematuhi Panduan UX dan Checklist Desain.

1. Elemen cast-media-player yang merepresentasikan UI pemutar bawaan yang disediakan dengan Penerima Web.
2. Gaya visual seperti CSS kustom untuk elemen cast-media-player guna memberi gaya berbagai elemen UI seperti background-image, splash-image, dan font-family.
3. Elemen skrip untuk memuat framework Penerima Web.
4. Kode JavaScript untuk menangkap pesan dan menangani peristiwa.
5. Antrean untuk putar otomatis.
6. Opsi untuk mengonfigurasi pemutaran.
7. Opsi untuk menetapkan konteks Penerima Web.
8. Opsi untuk menyetel perintah yang didukung oleh aplikasi Penerima Web.
9. Panggilan JavaScript untuk memulai aplikasi Penerima Web.

Catatan: Sebaiknya gunakan elemen HTML cast-media-player, karena elemen ini menangani semua status UI pemutar beserta gayanya.

Konfigurasi dan opsi aplikasi

CastReceiverContext adalah class terluar yang terekspos ke developer, dan mengelola pemuatan library yang mendasarinya serta menangani inisialisasi Web Receiver SDK.

Jika Web Receiver API mendeteksi bahwa pengirim terputus, hal ini akan memicu peristiwa SENDER_DISCONNECTED. Jika Penerima Web belum dapat berkomunikasi dengan pengirim selama yang kami jelaskan sebagai maxInactivity detik, Penerima juga akan memicu peristiwa SENDER_DISCONNECTED. Selama pengembangan, sebaiknya setel maxInactivity ke nilai yang tinggi sehingga aplikasi Penerima Web tidak menutup saat men-debug aplikasi dengan Debugger Remote Chrome:

const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; //Development only
context.start(options);

Namun, untuk aplikasi Penerima Web yang dipublikasikan, sebaiknya jangan setel maxInactivity dan mengandalkan nilai default. Perhatikan bahwa opsi Penerima Web hanya disetel sekali dalam aplikasi.

Konfigurasi lainnya adalah cast.framework.PlaybackConfig. Hal ini dapat ditetapkan sebagai berikut:

const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
  requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});

Konfigurasi ini memengaruhi setiap pemutaran konten dan pada dasarnya memberikan perilaku penggantian. Untuk mengetahui daftar perilaku yang dapat diganti oleh developer, lihat definisi cast.framework.PlaybackConfig. Untuk mengubah konfigurasi antara konten, Anda dapat menggunakan PlayerManager untuk mendapatkan playbackConfig-nya saat ini, ubah atau tambahkan penggantian dan reset playbackConfig seperti ini:

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
            new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);

Perhatikan bahwa jika PlaybackConfig tidak diganti, getPlaybackConfig() akan menampilkan objek null. Dan semua properti di PlaybackConfig that adalah undefined akan menggunakan nilai default.

Pemroses peristiwa

Web Receiver SDK memungkinkan aplikasi Web Receiver menangani peristiwa pemutar. Pemroses peristiwa mengambil parameter cast.framework.events.EventType (atau array parameter ini) yang menentukan peristiwa yang akan memicu pemroses. Array yang telah dikonfigurasi sebelumnya dari 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 mengetahui kapan perubahan mediaStatus disiarkan, Anda dapat menggunakan logika berikut untuk menangani peristiwa:

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
});

Catatan: Framework Penerima Web akan otomatis melacak saat pengirim terhubung atau terputus darinya dan tidak memerlukan pemroses peristiwa SENDER_DISCONNECTED eksplisit dalam logika Penerima Web Anda sendiri.

Intersepsi pesan

Dengan Web Receiver SDK, aplikasi Penerima Web Anda dapat menangkap pesan dan mengeksekusi kode kustom pada pesan tersebut. Pencegat pesan menggunakan parameter cast.framework.messages.MessageType yang menentukan jenis pesan yang harus dicegat.

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

Misalnya, jika ingin mengubah data permintaan pemuatan, Anda dapat menggunakan logika berikut untuk menangkap dan memodifikasinya:

Perhatian: Jangan tambahkan atau ubah properti queueData dari LoadRequestData di intersep LOAD. Ini tidak akan berpengaruh pada pemutaran karena queueData telah dibaca dan diterapkan ke antrean. Untuk informasi selengkapnya, lihat panduan antrean.

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 intersepsi pesan, aplikasi Penerima Web Anda harus menampilkan cast.framework.messages.ErrorType dan cast.framework.messages.ErrorReason yang sesuai.

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:

• Pemroses peristiwa tidak memungkinkan Anda mengubah data permintaan.
• Pemroses peristiwa paling baik digunakan untuk memicu analisis atau fungsi kustom.

Catatan: Pemroses peristiwa juga dapat digunakan untuk memproses payung peristiwa menggunakan enum CORE, DEBUG, atau FINE.

playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });

• Intersepsi pesan memungkinkan Anda memproses pesan, mencegatnya, dan mengubah data permintaan itu sendiri.
• Intersepsi pesan paling baik digunakan untuk menangani logika kustom yang terkait dengan data permintaan.

Memuat media

MediaInformation menyediakan banyak properti untuk memuat media dalam pesan cast.framework.messages.MessageType.LOAD termasuk entity, contentUrl, dan contentId.

entity adalah properti yang disarankan dan digunakan dalam penerapan Anda untuk aplikasi pengirim dan penerima. Properti ini adalah URL deep link yang dapat berupa playlist atau konten media tertentu.

contentUrl dirancang untuk URL yang dapat diputar dan dapat digunakan setelah tersedia.

contentId tidak digunakan lagi karena ambiguitas mengenai apakah nilainya adalah URL media, ID asli, atau parameter kunci untuk pencarian kustom.

Sarannya adalah menggunakan entity untuk menyimpan ID asli atau parameter kunci, dan menggunakan contentUrl untuk URL media. Contohnya ditunjukkan dalam cuplikan berikut, dengan entity ditemukan dalam permintaan LOAD dan contentUrl yang dapat diputar 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

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

Metode ini menampilkan objek yang dapat Anda kueri dengan meneruskan salah satu enum yang ditentukan untuk mendapatkan kemampuan perangkat untuk enum tersebut. Enum ditentukan dalam cast.framework.system.DeviceCapabilities.

Contoh ini memeriksa apakah perangkat Penerima Web masing-masing mampu memutar HDR dan DolbyVision (DV) dengan kunci IS_HDR_SUPPORTED dan IS_DV_SUPPORTED.

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

Perintah media yang didukung

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

1. Menggunakan PlayerManager.setSupportedMediaCommands untuk menetapkan 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 diperbarui, penerima akan menyertakan perubahan di properti supportedMediaCommands. Saat status disiarkan, aplikasi pengirim yang terhubung akan memperbarui tombol di UI-nya sebagaimana mestinya.

Catatan: Perubahan pada supportedMediaCommands tidak akan mengubah jenis tombol yang ditampilkan. Ini ditetapkan langsung di aplikasi pengirim (iOS, Android) dan Controls API penerima. Satu-satunya pengecualian yang menggunakan supportedMediaCommands untuk mendorong perubahan ini adalah kartu pemutaran media di layar utama perangkat layar smart.

Untuk informasi selengkapnya tentang perintah media dan perangkat sentuh yang didukung, lihat panduan Accessing UI controls.

Mengelola status tindakan pengguna

Saat pengguna berinteraksi dengan UI atau mengirim 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 ini, berikut hal yang harus dilakukan:

• Mengintersep pesan USER_ACTION dan menentukan tindakan yang diminta.
• Update MediaInformation UserActionState untuk mengupdate UI.

Catatan: Jika diperlukan, Anda dapat POST melakukan tindakan ke backend yang relevan untuk mempertahankan preferensi pengguna.

Cuplikan di bawah ini mengintersep pesan USER_ACTION dan menangani pemanggilan backend dengan perubahan yang diminta. Selanjutnya, melakukan panggilan untuk mengupdate 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 di bawah ini menyimulasikan panggilan ke layanan backend. Fungsi 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 di bawah ini mengambil UserActionRequestData dan menambahkan atau menghapus UserActionState dari MediaInformation. Memperbarui UserActionState dari MediaInformation akan mengubah status tombol yang terkait dengan tindakan yang diminta. Perubahan ini tercermin dalam UI kontrol layar smart, aplikasi remote control, dan UI Android TV. Atribut ini juga disiarkan melalui pesan MediaStatus keluar untuk mengupdate UI dari 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 default dari perintah ini dapat ditemukan di cast.framework.PlayerManager.

Perintah	Deskripsi
Putar	Memutar atau melanjutkan pemutaran dari status dijeda.
Jeda	Jeda konten yang sedang diputar.
Sebelumnya	Lewati ke item media sebelumnya di antrean media.
Berikutnya	Lewati ke item media berikutnya di antrean media.
Hentikan	Hentikan media yang sedang diputar.
Tidak Ada Pengulangan	Nonaktifkan pengulangan item media di antrean setelah item terakhir dalam antrean selesai diputar.
Ulangi Satu	Mengulang media yang sedang diputar tanpa batas.
Ulangi Semua	Ulangi semua item dalam antrean setelah item terakhir dalam antrean diputar.
Ulangi Semua dan Acak	Setelah item terakhir dalam antrean selesai diputar, acak antrean dan ulangi semua item dalam antrean.
Acak	Mengacak item media di antrean media Anda. Catatan: Anda juga dapat mengacak media sebelum pemutaran menggunakan tanda shuffle, jika disetel di loadRequestData pesan LOAD.
Teks AKTIF / NONAKTIF	Mengaktifkan / Menonaktifkan Pemberian Teks Tertutup untuk media. Aktifkan / Nonaktifkan juga tersedia dalam bahasa.
Cari hingga absolut waktu	Langsung ke waktu absolut yang ditentukan.
Cari ke waktu relatif dengan waktu saat ini	Melompat maju atau mundur menurut jangka waktu yang ditentukan dibandingkan dengan waktu pemutaran saat ini.
Mainkan Lagi	Memulai ulang media yang sedang diputar atau memutar item media yang terakhir diputar jika tidak ada media yang sedang diputar.
Menetapkan kecepatan pemutaran	Variasikan kecepatan pemutaran media. Hal ini harus ditangani secara default. Anda dapat menggunakan intersep pesan SET_PLAYBACK_RATE untuk mengganti permintaan tarif yang masuk.

Perintah media yang didukung dengan suara

Agar perintah suara tidak memicu perintah media di perangkat yang dilengkapi dengan Asisten, Anda harus terlebih dahulu menetapkan perintah media yang didukung yang akan didukung. Kemudian, Anda harus menerapkan perintah tersebut dengan mengaktifkan properti CastReceiverOptions.enforceSupportedCommands. UI pada pengirim SDK Cast dan perangkat yang mendukung sentuhan akan berubah untuk mencerminkan konfigurasi ini. Jika flag ini tidak diaktifkan, perintah suara yang masuk akan dieksekusi.

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

Pada contoh di bawah ini, kami menyediakan CastReceiverOptions saat memulai CastReceiverContext. Kami telah menambahkan dukungan untuk perintah PAUSE dan mengizinkan pemain untuk hanya mendukung perintah tersebut. Sekarang, jika perintah suara meminta operasi lain seperti SEEK, perintah tersebut akan ditolak. Pengguna akan diberi tahu bahwa perintah 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 batasi, Anda dapat menangkap pesan masuk. Di sini kita menangkap permintaan yang diberikan oleh SDK sehingga perintah SEEK yang dikeluarkan untuk perangkat yang dilengkapi dengan Asisten tidak memicu pencarian di aplikasi Penerima Web Anda.

Untuk perintah media yang tidak didukung oleh aplikasi Anda, tampilkan alasan error yang sesuai, 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 memiliki latar belakang suara aplikasi karena aktivitas Asisten seperti memproses ucapan pengguna atau berbicara kembali, pesan FocusState dari NOT_IN_FOCUS akan dikirim ke aplikasi Penerima Web saat aktivitas dimulai. Pesan lain dengan IN_FOCUS dikirim saat aktivitas berakhir. Bergantung pada aplikasi dan media yang sedang diputar, Anda mungkin ingin menjeda media saat FocusState berupa NOT_IN_FOCUS dengan menangkap jenis pesan FOCUS_STATE.

Misalnya, adalah pengalaman pengguna yang baik untuk menjeda pemutaran buku audio jika 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 dengan suara

Jika pengguna tidak menyatakan secara eksplisit bahasa teks, bahasa yang digunakan untuk teks adalah bahasa yang sama dengan bahasa yang digunakan pada perintah. Dalam skenario ini, parameter isSuggestedLanguage dari pesan masuk menunjukkan apakah bahasa terkait telah disarankan atau diminta secara eksplisit oleh pengguna.

Misalnya, isSuggestedLanguage ditetapkan ke true untuk perintah "OK Google, aktifkan teks", karena bahasa disimpulkan oleh bahasa yang digunakan dalam perintah tersebut. Jika bahasa diminta secara eksplisit, misalnya dalam "Ok Google, aktifkan teks bahasa Inggris", isSuggestedLanguage akan disetel ke false.

Metadata dan transmisi suara

Meskipun perintah suara ditangani oleh Penerima Web secara default, Anda harus memastikan metadata untuk konten Anda lengkap dan akurat. Hal ini memastikan 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

Catatan: Penerima Web Audio mendukung perluasan streaming secara default, dengan perangkat tambahan yang kompatibel untuk Cast dan ditambahkan ke sesi. Penerima Web Video perlu melakukan langkah-langkah di bagian ini untuk mendukung transfer streaming.

Mempertahankan status sesi adalah dasar transfer streaming, yang memungkinkan pengguna memindahkan streaming audio dan video yang ada di seluruh perangkat menggunakan perintah suara, Aplikasi Google Home, atau layar smart. Media berhenti diputar di satu perangkat (sumber) dan berlanjut di perangkat lainnya (tujuan). Setiap perangkat Cast dengan firmware terbaru dapat berfungsi sebagai sumber atau tujuan dalam transfer streaming.

Alur peristiwa untuk transfer streaming adalah:

1. Di perangkat sumber:
   1. Media berhenti diputar.
   2. Aplikasi Penerima Web menerima perintah untuk menyimpan status media saat ini.
   3. Aplikasi Penerima Web dinonaktifkan.
2. Di perangkat tujuan:
   1. Aplikasi Penerima Web dimuat.
   2. Aplikasi Penerima Web menerima perintah untuk memulihkan status media yang disimpan.
   3. Media melanjutkan pemutaran.

Elemen status media mencakup:

• Posisi atau stempel waktu tertentu dari lagu, video, atau item media.
• Tempatnya di antrean yang lebih luas (seperti playlist atau radio artis).
• Pengguna terautentikasi.
• Status pemutaran (misalnya, diputar atau dijeda).

Mengaktifkan transfer streaming

Guna menerapkan transfer streaming untuk Penerima Web:

1. Perbarui supportedMediaCommands dengan perintah STREAM_TRANSFER:

   playerManager.addSupportedMediaCommands(
   cast.framework.messages.Command.STREAM_TRANSFER, true);

2. Secara opsional, ganti intersepsi pesan SESSION_STATE dan RESUME_SESSION seperti yang dijelaskan dalam Mempertahankan status sesi. Hanya ganti opsi ini jika data kustom perlu disimpan sebagai bagian dari snapshot sesi. Jika tidak, penerapan default untuk mempertahankan status sesi akan mendukung transfer streaming.

Mempertahankan status sesi

Web Receiver SDK menyediakan implementasi default untuk aplikasi Penerima Web guna mempertahankan status sesi dengan mengambil snapshot 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 pencegat pesan SESSION_STATE jika diperlukan. Jika Anda ingin menambahkan data kustom ke dalam permintaan pemuatan, sebaiknya tempatkan data tersebut di 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 intersepsi 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 item pemutaran saat ini dalam antrean.

Operasi pramuat akan mendownload otomatis beberapa segmen item yang akan datang. Spesifikasi dilakukan pada nilai pramuat di objek QueueItem (default adalah 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 sebelum item sebelumnya selesai. Jika waktu untuk melakukan pramuat lebih tinggi dari waktu yang tersisa di currentItem, pramuat hanya akan dilakukan sesegera mungkin. Jadi, jika nilai pramuat yang sangat besar ditentukan pada queueItem, Anda dapat mencapai efek setiap kali kami memutar item saat ini, kami sudah melakukan pramuat item berikutnya. Namun, kami membiarkan setelan dan pilihan ini untuk developer karena nilai ini dapat memengaruhi performa bandwidth dan streaming item yang diputar saat ini.

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

File video dan audio MP4 reguler seperti MP3 tidak akan dipramuat karena perangkat Transmisi hanya mendukung satu elemen media dan tidak dapat digunakan untuk pramuat saat item konten yang ada masih diputar.

Pesan kustom

Pertukaran pesan adalah metode interaksi utama untuk aplikasi Penerima Web.

Pengirim mengeluarkan pesan ke Penerima Web menggunakan API pengirim untuk platform tempat pengirim berjalan (Android, iOS, Web). Objek peristiwa (yang merupakan manifes pesan) yang diteruskan ke pemroses peristiwa memiliki elemen data (event.data) tempat data mengambil properti jenis peristiwa tertentu.

Aplikasi Penerima Web dapat memilih untuk memproses pesan di namespace yang ditentukan. Karena dilakukan, aplikasi Penerima Web dikatakan mendukung protokol namespace tersebut. Kemudian, pengirim yang terhubung ingin berkomunikasi di namespace tersebut untuk menggunakan protokol yang sesuai.

Semua namespace ditentukan oleh string dan harus diawali dengan "urn:x-cast:" diikuti dengan string apa pun. Misalnya, "urn:x-cast:com.example.cast.mynamespace".

Catatan: Namespace pesan media "urn:x-cast:com.google.cast.media" dicadangkan. Pesan media yang dikirim menggunakan API Cast di pengirim dan Penerima Web menggunakan protokol namespace media menurut konvensi. Lihat Media dan pemutar untuk mengetahui informasi lebih lanjut tentang pesan media.

Berikut adalah cuplikan kode bagi Penerima Web untuk memproses pesan kustom 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 memberi tahu pengirim tentang status Penerima Web dengan mengirim pesan ke pengirim yang terhubung. Aplikasi Penerima Web dapat mengirim pesan menggunakan sendCustomMessage(namespace, senderId, message) pada CastReceiverContext. Penerima Web dapat mengirim pesan ke setiap pengirim, baik sebagai respons atas pesan yang diterima atau karena perubahan status aplikasi. Selain pesan point-to-point (dengan batas 64 kb), Penerima Web juga dapat menyiarkan pesan ke semua pengirim yang terhubung.

Transmisi untuk perangkat audio

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

Android TV

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

Panduan kompatibilitas Android TV

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

• Perhatikan bahwa string agen pengguna berisi "Android" dan "CrKey"; beberapa situs dapat mengalihkan ke situs khusus seluler karena mendeteksi label "Android". Jangan berasumsi bahwa "Android" dalam string agen pengguna selalu menunjukkan pengguna seluler.
• Media stack 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 waktu yang berbeda dengan Chromecast. Hal ini dapat mengungkapkan masalah yang tersembunyi di Chromecast.
• Saat memperbarui media, gunakan peristiwa terkait media yang diaktifkan oleh elemen <audio>/<video>, seperti timeupdate, pause, dan waiting. Hindari penggunaan peristiwa terkait jaringan seperti progress, suspend, dan stalled, karena hal ini cenderung bergantung pada platform. Lihat Peristiwa media untuk informasi selengkapnya tentang penanganan peristiwa media di penerima.
• Saat mengonfigurasi sertifikat HTTPS situs penerima, pastikan untuk menyertakan sertifikat CA perantara. Lihat halaman pengujian SSL Qualsys untuk memverifikasi: jika jalur sertifikasi tepercaya untuk situs Anda menyertakan sertifikat CA yang berlabel "download tambahan", maka sertifikat tersebut mungkin tidak dimuat pada platform berbasis Android.
• Meskipun Chromecast menampilkan halaman penerima pada bidang grafis 720p, platform Cast lainnya termasuk Android TV dapat menampilkan halaman hingga resolusi 1080p. Pastikan halaman penerima diskalakan dengan baik dalam resolusi yang berbeda.