Menambahkan Fitur Inti ke Penerima Web Kustom Anda

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

  1. Elemen cast-media-player yang mewakili UI pemutar bawaan yang disediakan dengan Web Receiver.
  2. Gaya visual seperti CSS kustom untuk elemen cast-media-player guna menata gaya berbagai elemen UI seperti background-image, splash-image, dan font-family.
  3. Elemen skrip untuk memuat framework Web Receiver.
  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 Web Receiver.

Konfigurasi dan opsi aplikasi

Mengonfigurasi aplikasi

CastReceiverContext adalah class terluar yang diekspos ke developer, serta mengelola pemuatan library dasar dan menangani inisialisasi Web Receiver SDK. SDK menyediakan API yang memungkinkan developer aplikasi mengonfigurasi SDK melalui CastReceiverOptions. Konfigurasi ini dievaluasi sekali per peluncuran aplikasi dan diteruskan ke SDK saat menyetel parameter opsional dalam panggilan ke start.

Contoh di bawah menunjukkan cara mengganti perilaku default untuk mendeteksi apakah koneksi pengirim masih terhubung secara aktif. Jika Penerima Web tidak dapat berkomunikasi dengan pengirim selama maxInactivity detik, peristiwa SENDER_DISCONNECTED akan dikirim. Konfigurasi di bawah ini akan mengganti waktu tunggu ini. Tag ini dapat bermanfaat saat melakukan proses debug karena mencegah aplikasi Penerima Web menutup sesi Chrome Remote Debugger saat 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 variabel pemutaran seperti informasi DRM, konfigurasi percobaan ulang, dan pengendali permintaan menggunakan cast.framework.PlaybackConfig. Informasi ini ditangani oleh PlayerManager dan dievaluasi pada saat pemain dibuat. Pemutar dibuat setiap kali pemuatan baru diteruskan ke Web Receiver SDK. Perubahan pada PlaybackConfig setelah pemutar dibuat akan dievaluasi pada pemuatan konten berikutnya. 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 hingga diganti lagi.
  • PlayerManager.setMediaPlaybackInfoHandler() untuk menerapkan konfigurasi tambahan hanya untuk item media yang dimuat di atas konfigurasi saat ini. Pengendali dipanggil tepat sebelum pembuatan pemain. Perubahan yang dilakukan di sini tidak bersifat permanen dan tidak disertakan dalam kueri untuk getPlaybackConfig(). Saat item media berikutnya dimuat, pengendali ini akan dipanggil lagi.

Contoh di bawah ini menunjukkan cara menetapkan PlaybackConfig saat menginisialisasi CastReceiverContext. Konfigurasi menggantikan 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 ini menunjukkan cara mengganti PlaybackConfig untuk permintaan pemuatan tertentu menggunakan pengendali info pemutaran media. Pengendali memanggil metode yang diimplementasikan aplikasi 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

SDK Penerima Web memungkinkan aplikasi Penerima Web menangani peristiwa pemutar. Pemroses peristiwa menggunakan parameter cast.framework.events.EventType (atau array parameter ini) yang menentukan peristiwa yang harus memicu pemroses. Array cast.framework.events.EventType yang telah dikonfigurasi sebelumnya dan 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 dikirim, Anda dapat menggunakan logika berikut untuk menangani peristiwa tersebut:

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 Anda menangkap pesan dan menjalankan kode kustom pada pesan tersebut. Interseptor pesan menggunakan parameter cast.framework.messages.MessageType yang menentukan jenis pesan yang harus dicegat.

Interseptor akan menampilkan permintaan yang diubah atau Promise yang di-resolve dengan nilai permintaan yang diubah. Menampilkan null akan mencegah pemanggilan pengendali pesan default. Lihat Memuat media untuk mengetahui detail selengkapnya.

Misalnya, jika ingin mengubah data permintaan pemuatan, Anda dapat menggunakan logika berikut untuk menangkap 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 dalam intersepsi pesan, aplikasi Web Receiver 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.
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 berkaitan dengan data permintaan.

Memuat media

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

  • entity adalah properti yang disarankan untuk digunakan dalam penerapan untuk aplikasi pengirim dan 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 kolom lainnya.
  • contentUrl sesuai dengan URL yang dapat diputar yang akan digunakan pemain untuk memuat konten. Misalnya, URL ini dapat mengarah ke manifes DASH.
  • contentId dapat berupa URL konten yang dapat diputar (serupa dengan properti contentUrl) atau ID unik untuk konten atau playlist yang sedang dimuat. Jika menggunakan properti ini sebagai ID, aplikasi Anda harus mengisi URL yang dapat diputar di contentUrl.

Sebaiknya gunakan entity untuk menyimpan ID asli atau parameter kunci, dan gunakan contentUrl untuk URL media. Contohnya ditampilkan dalam cuplikan berikut dengan entity yang ada 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 tentang perangkat Cast yang terhubung dan perangkat video atau audio yang terpasang. Metode getDeviceCapabilities memberikan informasi dukungan untuk Asisten Google, Bluetooth, serta perangkat layar dan audio yang terhubung.

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

Contoh ini memeriksa apakah perangkat Penerima Web mampu memutar HDR dan DolbyVision (DV) masing-masing dengan tombol 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 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 agar aplikasi Web Receiver dapat 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 iOS dan Android, 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 disetel, 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 diupdate, perubahan akan disertakan dalam properti supportedMediaCommands. Saat status disiarkan, aplikasi pengirim yang terhubung akan mengupdate tombol di UI sebagaimana mestinya.

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

Mengelola status tindakan pengguna

Saat berinteraksi dengan UI atau mengirim perintah suara, pengguna 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 item yang sedang diputar, seperti perintah LIKE, mengharuskan aplikasi penerima menanganinya. SDK menyediakan serangkaian API untuk menangani jenis permintaan ini. Untuk mendukung permintaan ini, hal berikut harus dilakukan:

  • Tetapkan MediaInformation userActionStates dengan preferensi pengguna saat memuat item media.
  • Intersepsi pesan USER_ACTION dan tentukan tindakan yang diminta.
  • Update MediaInformation UserActionState untuk mengupdate UI.

Cuplikan berikut mencegat 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 pemanggilan backend dengan perubahan yang diminta. Kemudian, perangkat akan melakukan panggilan untuk mengupdate UserActionState di 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. Fungsi ini memeriksa UserActionRequestData untuk melihat jenis perubahan yang diminta pengguna dan hanya melakukan panggilan jaringan jika tindakan tersebut 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 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. Pesan ini juga disiarkan melalui pesan MediaStatus keluar untuk mengupdate 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 default 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 Langsung ke item media sebelumnya di antrean media.
Berikutnya Langsung buka item media berikutnya di antrean media.
Hentikan Hentikan media yang sedang diputar.
Ulangi Tidak Ada Menonaktifkan pengulangan item media dalam antrean setelah item terakhir dalam antrean selesai diputar.
Ulangi Single Mengulangi media yang sedang diputar tanpa batas.
Ulangi Semua Mengulangi 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.
Kocok Mengacak item media di antrean media.
Teks Tertutup AKTIF / NONAKTIF Mengaktifkan / Menonaktifkan Pemberian Teks Tertutup untuk media Anda. Aktifkan / Nonaktifkan juga tersedia menurut bahasa.
Berusahalah ke waktu absol Melompat ke waktu absolut yang ditentukan.
Cari ke waktu relatif terhadap waktu saat ini Melompat maju atau mundur berdasarkan 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.
Menyetel laju pemutaran Memvariasikan kecepatan pemutaran media. Hal ini seharusnya sudah ditangani secara default. Anda dapat menggunakan interseptor pesan SET_PLAYBACK_RATE untuk mengganti permintaan tarif masuk.

Perintah media yang didukung dengan suara

Untuk mencegah perintah suara memicu perintah media pada perangkat yang dilengkapi dengan Asisten, Anda harus terlebih dahulu menetapkan perintah media yang didukung yang ingin Anda dukung. 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 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, kami menyediakan CastReceiverOptions saat memulai CastReceiverContext. Kami telah menambahkan dukungan untuk perintah PAUSE dan memaksa pemutar agar hanya mendukung perintah tersebut. Sekarang, jika perintah suara meminta operasi lain seperti SEEK, operasi 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 dibatasi, Anda dapat menangkap pesan masuk. Di sini kami mencegat permintaan yang diberikan oleh SDK sehingga perintah SEEK yang dikeluarkan ke perangkat yang dilengkapi dengan Asisten tidak memicu pencarian di aplikasi Penerima Web Anda.

Untuk perintah media yang tidak didukung 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 latar belakang suara aplikasi Anda karena aktivitas Asisten seperti mendengarkan 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 diputar, Anda mungkin ingin menjeda media saat FocusState adalah NOT_IN_FOCUS dengan mencegat jenis pesan FOCUS_STATE.

Misalnya, akan menjadi pengalaman yang baik bagi pengguna 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 suara

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

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

Metadata dan transmisi suara

Meskipun perintah suara ditangani oleh Penerima Web secara default, Anda harus memastikan metadata untuk konten lengkap dan akurat. Hal ini memastikan bahwa perintah suara ditangani dengan benar oleh Asisten dan metadata muncul dengan benar di seluruh jenis antarmuka baru seperti aplikasi Google Home dan layar smart seperti Google Home Hub.

Transfer streaming

Mempertahankan status sesi adalah dasar transfer streaming, tempat pengguna dapat 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 lain (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 Web Receiver menerima perintah untuk menyimpan status media saat ini.
    3. Aplikasi Penerima Web dinonaktifkan.
  2. Di perangkat tujuan:
    1. Aplikasi Penerima Web dimuat.
    2. Aplikasi Web Receiver menerima perintah untuk memulihkan status media yang disimpan.
    3. Media akan dilanjutkan pemutaran.

Elemen status media meliputi:

  • Posisi tertentu atau stempel waktu lagu, video, atau item media.
  • Konten tersebut ditempatkan dalam 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. Jika perlu, ganti interseptor pesan SESSION_STATE dan RESUME_SESSION seperti yang dijelaskan dalam Mempertahankan status sesi. Hanya ganti opsi ini jika data khusus perlu disimpan sebagai bagian dari snapshot sesi. Jika tidak, implementasi default untuk mempertahankan status sesi akan mendukung transfer streaming.

Mempertahankan status sesi

Web Receiver SDK memberikan penerapan default untuk aplikasi Web Receiver guna mempertahankan status sesi dengan mengambil ringkasan status media saat ini, mengonversi status menjadi permintaan pemuatan, dan melanjutkan sesi dengan permintaan pemuatan.

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

Operasi pramuat akan mendownload beberapa segmen item yang akan datang terlebih dahulu. Spesifikasi dilakukan pada nilai preloadTime dalam objek QueueItem (default-nya adalah 20 detik jika tidak disediakan). Waktu dinyatakan dalam detik, relatif terhadap akhir item yang sedang diputar . Hanya nilai positif yang valid. Misalnya, jika nilainya adalah 10 detik, item ini akan dipramuat 10 detik sebelum item sebelumnya selesai. Jika waktu untuk melakukan pramuat lebih tinggi daripada waktu yang tersisa di currentItem, pramuat akan terjadi sesegera mungkin. Jadi, jika nilai pramuat yang sangat besar ditentukan pada queueItem, kita dapat mencapai efek ketika memutar item saat ini karena kita sudah memuat item berikutnya. Namun, kami menyerahkan setelan dan pilihan ini kepada developer karena nilai ini dapat memengaruhi bandwidth dan performa streaming item yang diputar saat ini.

Pramuat akan berfungsi untuk konten HLS, DASH, dan Streaming yang lancar secara default.

File video dan audio MP4 biasa seperti MP3 tidak akan dipramuat karena perangkat Transmisi hanya mendukung satu elemen media dan tidak dapat digunakan untuk melakukan pramuat saat item konten yang 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 yang dijalankan pengirim (Android, iOS, Web). Objek peristiwa (yang merupakan manifes pesan) yang diteruskan ke pemroses peristiwa memiliki elemen data (event.data) yang datanya mengambil properti jenis peristiwa tertentu.

Aplikasi Penerima Web dapat memilih untuk memproses pesan di namespace yang ditentukan. Setelah melakukannya, aplikasi Web Receiver dianggap mendukung protokol namespace tersebut. Selanjutnya, setiap pengirim terhubung yang ingin berkomunikasi di namespace tersebut bebas 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".

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 terus memberi tahu pengirim tentang status Penerima Web dengan mengirim pesan ke pengirim yang terhubung. Aplikasi Web Receiver dapat mengirim pesan menggunakan sendCustomMessage(namespace, senderId, message) pada CastReceiverContext. Penerima Web dapat mengirim pesan ke masing-masing pengirim, baik sebagai respons atas pesan yang diterima maupun karena perubahan status aplikasi. Selain fitur pesan point-to-point (dengan batas 64 kb), Penerima Web juga dapat menyiarkan pesan ke semua pengirim yang terhubung.

Cast untuk perangkat audio

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

Android TV

Bagian ini membahas cara Penerima Web Google menggunakan input Anda sebagai pemutaran, dan kompatibilitas Android TV.

Mengintegrasikan aplikasi Anda dengan remote control

Penerima Web Google 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 dapat memungkinkan kontrol pemutaran dasar dari input kontrol Android TV.

Panduan untuk 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 mungkin mengalihkan ke situs khusus seluler karena mendeteksi label "Android". Jangan berasumsi bahwa "Android" dalam string agen pengguna selalu menunjukkan pengguna seluler.
  • Stack 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 waktu yang berbeda dengan Chromecast. Hal ini dapat mengungkapkan masalah yang disembunyikan 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 peristiwa tersebut cenderung bergantung pada platform. Lihat Peristiwa media untuk informasi selengkapnya tentang penanganan peristiwa media di penerima.
  • Saat mengonfigurasi sertifikat HTTPS situs penerima, pastikan Anda menyertakan sertifikat CA perantara. Lihat halaman pengujian SSL Qualsys untuk memverifikasi: jika jalur sertifikasi tepercaya untuk situs Anda menyertakan sertifikat CA berlabel “download tambahan”, jalur tersebut mungkin tidak dimuat di platform berbasis Android.
  • Meskipun Chromecast menampilkan halaman penerima pada bidang grafis 720p, platform Cast lainnya termasuk Android TV dapat menampilkan halaman hingga 1080p. Pastikan halaman penerima dapat diskalakan dengan baik pada resolusi yang berbeda.