Menambahkan Dukungan Ad Breaks API ke Penerima Web

1. Ringkasan

Logo Google Cast

Codelab ini menguraikan cara membuat aplikasi Penerima Web Kustom yang menggunakan Cast Ad Breaks API.

Apa itu Google Cast?

Google Cast memungkinkan pengguna mentransmisikan konten dari perangkat seluler ke TV. Pengguna kemudian dapat menggunakan perangkat seluler sebagai remote control untuk pemutaran media di TV.

Google Cast SDK memungkinkan Anda memperluas aplikasi untuk mengontrol TV atau sistem suara. SDK Cast memungkinkan Anda menambahkan komponen UI yang diperlukan berdasarkan Checklist Desain Google Cast.

Checklist Desain Google Cast disediakan untuk menstandarkan penerapan Cast agar pengalaman pengguna menjadi intuitif di semua platform yang didukung.

Apa yang akan kita buat?

Setelah menyelesaikan codelab ini, Anda akan membuat Penerima Cast yang memanfaatkan Break API.

Yang akan Anda pelajari

  • Cara menyertakan jeda VMAP dan VAST dalam konten untuk Transmisi
  • Cara melewati klip jeda iklan
  • Cara menyesuaikan perilaku jeda default pada pencarian

Yang akan Anda butuhkan

Pengalaman

Pastikan Anda memiliki pengalaman berikut sebelum melanjutkan codelab ini.

  • Pengetahuan umum pengembangan Web.
  • Membuat aplikasi Penerima Web Cast.

Bagaimana Anda akan menggunakan tutorial ini?

Hanya membacanya Membacanya dan menyelesaikan latihan

Bagaimana Anda menilai pengalaman membuat aplikasi web?

Pemula Menengah Mahir

2. Mendapatkan kode contoh

Download semua kode contoh ke komputer Anda...

dan mengekstrak file zip yang didownload.

3. Men-deploy penerima secara lokal

Agar dapat menggunakan penerima web dengan perangkat Cast, perangkat Cast perlu dihosting di tempat yang dapat dijangkau perangkat Cast. Jika sudah memiliki server yang mendukung https, lewati petunjuk berikut dan catat URL karena Anda akan membutuhkannya di bagian selanjutnya.

Jika tidak memiliki server yang tersedia untuk digunakan, Anda dapat menggunakan Firebase Hosting atau ngrok.

Menjalankan server

Setelah layanan pilihan Anda disiapkan, buka app-start dan mulai server Anda.

Catat URL untuk penerima yang dihosting. Anda akan menggunakannya di bagian berikutnya.

4. Mendaftarkan aplikasi di Konsol Developer Cast

Anda harus mendaftarkan aplikasi Anda agar dapat menjalankan penerima khusus, seperti yang disertakan dalam codelab ini, di perangkat Chromecast. Setelah Anda mendaftarkan aplikasi, ID aplikasi akan dibuat sehingga Aplikasi Pengirim harus dikonfigurasi untuk meluncurkan aplikasi Penerima Web.

Gambar Konsol Developer Google Cast SDK dengan tombol 'Tambahkan Aplikasi Baru' ditandai

Klik "Tambahkan aplikasi baru"

Gambar layar 'Aplikasi Penerima Baru' dengan opsi 'Penerima Kustom' ditandai

Pilih "Penerima Kustom", dan inilah yang sedang kita buat.

Gambar layar 'Penerima Kustom Baru' yang menampilkan URL yang diketikkan seseorang di kolom 'URL Aplikasi Penerima'

Masukkan detail penerima baru Anda. Pastikan untuk menggunakan URL yang mengarah ke tempat Anda berencana menghosting aplikasi Penerima Web. Catat ID Aplikasi yang dibuat oleh konsol setelah Anda mendaftarkan aplikasi. Aplikasi pengirim akan dikonfigurasi untuk menggunakan ID tersebut di bagian selanjutnya.

Anda juga harus mendaftarkan perangkat Google Cast agar dapat mengakses aplikasi penerima sebelum memublikasikannya. Setelah dipublikasikan, aplikasi penerima akan tersedia untuk semua perangkat Google Cast. Untuk tujuan codelab ini, sebaiknya gunakan aplikasi penerima yang tidak dipublikasikan.

Gambar Konsol Developer Google Cast SDK dengan tombol 'Tambahkan Perangkat Baru' ditandai

Klik "Tambahkan Perangkat baru"

Gambar dialog 'Tambahkan Perangkat Penerima Transmisi'

Masukkan nomor seri yang tercetak di bagian belakang perangkat Transmisi dan berikan nama deskriptif. Anda juga dapat menemukan nomor seri dengan mentransmisikan layar di Chrome saat mengakses Konsol Developer SDK Google Cast

Perlu waktu 5-15 menit hingga penerima dan perangkat siap untuk pengujian. Setelah menunggu 5-15 menit, Anda harus memulai ulang perangkat Transmisi.

5. Menyiapkan Project Start

Sebelum memulai codelab ini, sebaiknya tinjau panduan developer iklan yang memberikan ringkasan tentang API jeda iklan.

Dukungan untuk Google Cast perlu ditambahkan ke aplikasi awal yang Anda download. Berikut adalah beberapa terminologi Google Cast yang digunakan dalam codelab ini:

  • aplikasi pengirim berjalan di perangkat seluler atau laptop,
  • aplikasi penerima berjalan di perangkat Google Cast.

Sekarang Anda siap untuk mengerjakan project awal menggunakan editor teks favorit Anda:

  1. Pilih direktori ikon folderapp-start dari download kode contoh Anda.
  2. Buka js/receiver.js dan index.html

Perhatikan bahwa saat Anda mengerjakan codelab ini, solusi hosting web yang telah Anda pilih harus diperbarui dengan perubahan yang telah dibuat. Pastikan Anda menerapkan perubahan ke situs host saat melanjutkan validasi dan mengujinya.

Desain Aplikasi

Seperti yang telah disebutkan, codelab menggunakan aplikasi pengirim untuk memulai Sesi Cast, dan aplikasi penerima yang akan dimodifikasi untuk menggunakan API jeda iklan.

Dalam codelab ini, Alat Transmisi dan Perintah akan bertindak sebagai Pengirim Web untuk meluncurkan aplikasi penerima. Untuk memulai, buka alat di browser Chrome. Masukkan ID Aplikasi Penerima yang diberikan di Konsol Developer SDK Cast, lalu klik Setel guna mengonfigurasi aplikasi pengirim untuk pengujian.

Catatan: Jika Anda mendapati bahwa ikon transmisi tidak muncul, pastikan Penerima Web dan perangkat transmisi telah terdaftar dengan benar di Konsol Developer Cast. Jika Anda belum melakukannya, nyalakan ulang semua perangkat transmisi yang baru saja didaftarkan.

Aplikasi penerima adalah fokus utama codelab ini dan terdiri dari satu tampilan utama yang ditentukan di index.html dan satu file JavaScript yang disebut js/receiver.js. Hal ini dijelaskan lebih lanjut di bawah.

index.html

File html ini berisi UI untuk aplikasi penerima yang disediakan oleh elemen cast-media-player. Kode ini juga memuat library CAF SDK dan Cast Debug Logger.

receiver.js

Skrip ini mengelola semua logika untuk aplikasi penerima. Saat ini, skrip ini berisi penerima CAF dasar untuk melakukan inisialisasi konteks transmisi dan memuat aset video saat inisialisasi. Beberapa kemampuan pencatat log debug juga telah ditambahkan untuk menyediakan logging kembali ke alat Cast dan Command.

6. Menambahkan VMAP ke Konten Anda

SDK Penerima Web Cast memberikan dukungan untuk iklan yang ditentukan melalui Playlist Multi-Iklan Video Digital, juga dikenal sebagai VMAP. Struktur XML menentukan jeda iklan media dan metadata klip jeda iklan yang terkait. Untuk menyisipkan iklan ini, SDK menyediakan properti vmapAdsRequest di objek MediaInformation.

Di file js/receiver.js, buat objek VastAdsRequest. Temukan fungsi interseptor permintaan LOAD dan ganti dengan kode berikut. File ini berisi contoh URL tag VMAP dari DoubleClick dan memberikan nilai correlator acak untuk memastikan bahwa permintaan berikutnya ke URL yang sama menghasilkan template XML dengan jeda iklan yang belum ditonton.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      const vmapUrl =
          'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
          Math.floor(Math.random() * Math.pow(10, 10));
      let vmapRequest = new cast.framework.messages.VastAdsRequest();
      vmapRequest.adTagUrl = vmapUrl;
      loadRequestData.media.vmapAdsRequest = vmapRequest;

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

Simpan perubahan ke js/receiver.js dan upload file ke server web Anda. Mulai sesi Transmisi di Alat Transmisi dan Perintah dengan mengklik ikon Cast. Iklan VMAP akan diputar, diikuti dengan konten utama.

7. Menambahkan VAST ke Konten Anda

Seperti yang disebutkan sebelumnya, ada dukungan untuk berbagai jenis iklan di SDK Penerima Web. Bagian ini menyoroti API yang tersedia untuk mengintegrasikan iklan Template Penayangan Iklan Video Digital yang juga dikenal sebagai VAST. Jika Anda telah menerapkan kode VMAP dari bagian sebelumnya, berikan komentar.

Salin perintah berikut ke file js/receiver.js Anda setelah interseptor permintaan pemuatan. Video ini berisi enam klip jeda VAST dari DoubleClick dan nilai correlator acak. Klip jeda ini ditetapkan ke 5 jeda. Setiap position jeda ditetapkan ke waktu dalam detik yang sesuai dengan konten utama, termasuk jeda pre-roll (position ditetapkan ke 0) dan jeda post-roll (position ditetapkan ke -1).

const addVASTBreaksToMedia = (mediaInformation) => {
  mediaInformation.breakClips = [
    {
      id: 'bc1',
      title: 'bc1 (Pre-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('preroll')
      }
    },
    {
      id: 'bc2',
      title: 'bc2 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc3',
      title: 'bc3 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc4',
      title: 'bc4 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc5',
      title: 'bc5 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc6',
      title: 'bc6 (Post-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('postroll')
      }
    }
  ];

  mediaInformation.breaks = [
    {id: 'b1', breakClipIds: ['bc1'], position: 0},
    {id: 'b2', breakClipIds: ['bc2'], position: 15},
    {id: 'b3', breakClipIds: ['bc3', 'bc4'], position: 60},
    {id: 'b4', breakClipIds: ['bc5'], position: 100},
    {id: 'b5', breakClipIds: ['bc6'], position: -1}
  ];
};

Catatan: Properti breakClipIds jeda adalah array yang berarti bahwa beberapa klip jeda iklan dapat ditetapkan ke setiap jeda.

Di js/receiver.js file, cari intersepsi pesan LOAD dan ganti dengan kode berikut. Perhatikan bahwa pekerjaan VMAP diberi komentar untuk menampilkan iklan jenis VAST.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      // const vmapUrl =
      //     'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
      //     Math.floor(Math.random() * Math.pow(10, 10));
      // let vmapRequest = new cast.framework.messages.VastAdsRequest();
      // vmapRequest.adTagUrl = vmapUrl;
      // loadRequestData.media.vmapAdsRequest = vmapRequest;

      // Append VAST ad breaks to the MediaInformation.
      addVASTBreaksToMedia(loadRequestData.media);

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

Simpan perubahan ke js/receiver.js dan upload file ke server web Anda. Mulai sesi Transmisi di Alat Transmisi dan Perintah dengan mengklik ikon Cast. Iklan VAST akan diputar, diikuti dengan konten utama.

8. Jeda Jeda Iklan Dilewati

CAF memiliki class bernama BreakManager yang membantu Anda menerapkan aturan bisnis kustom untuk perilaku iklan. Salah satu fitur ini memungkinkan aplikasi untuk melewati jeda dan memisahkan klip secara terprogram berdasarkan beberapa kondisi. Contoh ini menunjukkan cara melewati jeda iklan yang posisinya berada dalam 30 detik pertama konten, tetapi bukan jeda post-roll. Saat menggunakan iklan VAST yang dikonfigurasi di bagian sebelumnya, terdapat 5 jeda yang ditentukan: 1 jeda pre-roll, 3 jeda iklan mid-roll (pada detik ke-15, 60, dan 100), dan terakhir, satu jeda post-roll. Setelah menyelesaikan langkah-langkah tersebut, hanya pre-roll dan mid-roll yang posisinya di 15 detik akan dilewati.

Untuk melakukannya, aplikasi harus memanggil API yang tersedia melalui BreakManager guna menyetel interseptor untuk pemuatan jeda. Salin baris berikut ke dalam file js/receiver.js Anda, setelah baris yang berisi variabel context dan playerManager untuk mendapatkan referensi ke instance.

const breakManager = playerManager.getBreakManager();

Aplikasi harus menyiapkan interseptor dengan aturan untuk mengabaikan jeda iklan apa pun yang terjadi sebelum 30 detik sambil memperhatikan setiap jeda post-roll (karena nilai position-nya adalah -1). Interseptor ini berfungsi seperti interseptor LOAD di PlayerManager, tetapi jeda ini khusus untuk memuat klip jeda iklan. Tetapkan string ini setelah intersepsi permintaan LOAD, dan sebelum deklarasi fungsi addVASTBreaksToMedia.

Salin perintah berikut ke dalam file js/receiver.js.

breakManager.setBreakClipLoadInterceptor((breakClip, breakContext) => {
  /**
   * The code will skip playback of break clips if the break position is within
   * the first 30 seconds.
   */
  let breakObj = breakContext.break;
  if (breakObj.position >= 0 && breakObj.position < 30) {
    castDebugLogger.debug(
        'MyAPP.LOG',
        'Break Clip Load Interceptor skipping break with ID: ' + breakObj.id);
    return null;
  } else {
    return breakClip;
  }
});

Catatan: Menampilkan null di sini akan melewatkan BreakClip yang diproses. Jika Break tidak memiliki klip jeda iklan yang ditentukan, jeda itu sendiri akan dilewati.

Simpan perubahan ke js/receiver.js dan upload file ke server web Anda. Mulai sesi Transmisi di Alat Transmisi dan Perintah dengan mengklik ikon Cast. Iklan VAST akan diproses. Perhatikan bahwa iklan pre-roll dan mid-roll pertama (dengan position berdurasi 15 detik) tidak akan diputar.

9. Menyesuaikan Perilaku Pencarian Istirahat

Saat mencari jeda sebelumnya, implementasi default mendapatkan semua item Break yang posisinya berada di antara nilai seekFrom dan seekTo operasi pencarian. Dari daftar jeda ini, SDK akan memutar Break yang position-nya paling dekat dengan nilai seekTo dan yang properti isWatched-nya ditetapkan ke false. Properti isWatched jeda iklan tersebut kemudian disetel ke true dan pemutar mulai memutar klip jedanya. Setelah jeda ditonton, konten utama melanjutkan pemutaran dari posisi seekTo. Jika tidak ada jeda seperti itu, jeda tidak akan diputar dan konten utama akan terus diputar di posisi seekTo.

Untuk menyesuaikan jeda iklan mana yang diputar pada pencarian, SDK Cast menyediakan setBreakSeekInterceptor API di BreakManager. Jika aplikasi menyediakan logika kustomnya melalui API tersebut, SDK akan memanggilnya setiap kali operasi pencarian dilakukan di satu atau beberapa jeda. Fungsi callback meneruskan objek yang berisi semua jeda antara posisi seekFrom dan posisi seekTo. Selanjutnya, aplikasi perlu mengubah dan menampilkan BreakSeekData.

Untuk menampilkan penggunaannya, contoh di bawah mengganti perilaku default dengan mengambil semua jeda yang telah dicari, dan hanya memutar jeda pertama yang muncul di linimasa.

Salin kode berikut ke file js/receiver.js Anda di bawah definisi ke setBreakClipLoadInterceptor.

breakManager.setBreakSeekInterceptor((breakSeekData) => {
  /**
   * The code will play an unwatched break between the seekFrom and seekTo
   * position. Note: If the position of a break is less than 30 then it will be
   * skipped due to the setBreakClipLoadInterceptor code.
   */
  castDebugLogger.debug(
      'MyAPP.LOG',
      'Break Seek Interceptor processing break ids ' +
          JSON.stringify(breakSeekData.breaks.map(adBreak => adBreak.id)));

  // Remove all other breaks except for the first one.
  breakSeekData.breaks.splice(1,breakSeekData.breaks.length);
  return breakSeekData;
});

Catatan: Jika fungsi tidak menampilkan nilai atau jika menampilkan null, jeda tidak akan diputar.

Simpan perubahan ke js/receiver.js dan upload file ke server web Anda. Mulai sesi Transmisi di Alat Transmisi dan Perintah dengan mengklik ikon Cast. Iklan VAST akan diproses. Perhatikan bahwa iklan pre-roll dan mid-roll pertama (dengan position berdurasi 15 detik) tidak akan diputar.

Tunggu hingga waktu pemutaran mencapai 30 detik untuk melewati semua jeda yang dilewati oleh interseptor pemuatan klip jeda. Setelah tercapai, kirim perintah pencari dengan membuka tab Media Control. Isi input Seek Into Media dengan 300 detik, lalu klik tombol TO. Catat log yang dicetak di Break Seek Interceptor. Perilaku default kini harus diganti untuk memutar jeda mendekati waktu seekFrom.

10. Selamat

Sekarang Anda sudah mengetahui cara menambahkan iklan ke aplikasi penerima menggunakan SDK Penerima Cast terbaru.

Untuk detail selengkapnya, lihat Panduan Developer Jeda Iklan.