Jeda Iklan

Ringkasan

Web Receiver SDK memiliki dukungan native untuk jeda iklan dan iklan pengiring dalam streaming media tertentu. Hal ini memberikan dua cara untuk menggabungkan jeda iklan pada penerima: penggabungan sisi klien dan sisi server menggunakan jeda dan klip istirahat.

Sebelum memulai pengembangan pada jeda iklan, pahami penyiapan Penerima Web Kustom. Cast SDK Ad Breaks API memastikan pengguna memiliki pengalaman yang konsisten di semua perangkat yang kompatibel untuk Cast saat iklan menjadi bagian dari pemutaran.

Dalam panduan ini, jeda mengacu pada interval pemutaran yang berisi satu atau beberapa iklan atau bumper, dan setiap iklan atau bumper disebut sebagai klip jeda.

Diagram ini menunjukkan dua jeda iklan, masing-masing berisi dua iklan:

Peristiwa

Tabel berikut menjelaskan peristiwa yang dipicu saat jeda terjadi selama pemutaran.

Peristiwa Istirahat Deskripsi
DIBREAK_DIMULAI Diaktifkan saat klip jeda pertama dalam jeda mulai dimuat. Acaranya adalah cast.framework.events.BreaksEvent.
DIPUTAR_DIRI Diaktifkan saat klip jeda terakhir dalam jeda berakhir. Peristiwa adalah cast.framework.events.BreaksEvent.
Catatan: Peristiwa ini diaktifkan meskipun pengguna melewati klip jeda terakhir dalam jeda untuk mengakhiri jeda.
BREAK_CLIP_LOADING Diaktifkan saat klip jeda mulai dimuat. Acaranya adalah cast.framework.events.BreaksEvent.
BREAK_CLIP_STARTED Diaktifkan saat klip jeda dimulai. Acaranya adalah cast.framework.events.BreaksEvent.
BREAK_CLIP_ENDED Diaktifkan saat klip jeda berakhir. Peristiwa adalah cast.framework.events.BreaksEvent.
Catatan: Peristiwa ini dipicu meskipun pengguna melewati klip jeda iklan. Harap periksa properti endedReason dari BreaksEvent. Untuk mengetahui durasi klip istirahat ditonton, periksa getBreakClipCurrentTimeSec dan getBreakClipDurationSec dari PlayerManager.

Peristiwa ini dapat digunakan untuk analisis dan pelacakan pemutaran iklan. Saat VMAP (Playlist Multi-Iklan Video) dan VAST (Template Penayangan Iklan Video) digunakan, setiap peristiwa pelacakan standar yang diberikan dalam respons akan otomatis dikirim oleh SDK.

Saat jeda diputar, Web Receiver SDK akan menyiarkan MediaStatus dengan breakStatus ke semua pengirim yang terhubung. Pengirim dapat menggunakan informasi ini untuk mengupdate UI dan menekan operasi pencarian apa pun.

Web Receiver SDK menyediakan dua cara untuk menggabungkan jeda iklan ke penerima: penggabungan sisi klien dan sisi server.

Penggabungan iklan sisi klien

Untuk penggabungan iklan sisi klien, yang juga disebut sebagai proses sematan, informasi iklan yang diperlukan harus ditentukan dengan objek Break dan BreakClip saat media sedang dimuat. Cuplikan berikut adalah contoh fungsi yang menambahkan jeda pre-roll, mid-roll, dan post-roll. Dalam hal ini, referensi ke third_party dan metodenya adalah contoh fungsi bantuan yang mungkin dimiliki developer di aplikasi mereka. Cuplikan tersebut juga menunjukkan cara mengaktifkan peristiwa pelacakan saat pengguna menonton klip jeda hingga selesai dengan memproses peristiwa BREAK_CLIP_ENDED, lalu memeriksa nilai endedReason.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    title: third_party.getBreakClipTitle('bc1'),
    contentId: third_party.getBreakClipUrl('bc1'),
    contentType: third_party.getBreakClipContentType('bc1'),
    posterUrl: third_party.getBreakClipPosterUrl('bc1')
  },
  {
    id: 'bc2'
    ...
  },
  {
    id: 'bc3'
    ...
  },
  {
    id: 'bc4'
    ...
  }];
  mediaInformation.breaks = [
  {
    id: 'b1',
    breakClipIds: ['bc1', 'bc2'],
    position: 0  //pre-roll position
  },
  {
    id: 'b2',
    breakClipIds: ['bc3'],
    position: 10*60 //ten minutes
  },{
    id: 'b3',
    breakClipIds: ['bc4'],
    position: -1  //post-roll position (-1 is only valid client stitching; for server-side ad stitching, exact position is required)
  }];
}

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.addEventListener(cast.framework.events.EventType.BREAK_CLIP_ENDED, function(event){
  if(event.endedReason === cast.framework.events.EndedReason.END_OF_STREAM){
    //call your ad tracking code here for break clip watched to completion
  }
});


playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    loadRequestData => {
      addBreakToMedia(loadRequestData.media);
      return loadRequestData;
    });
context.start();

Iklan VAST

Web Receiver SDK mendukung iklan VAST standar IAB. Untuk menyertakan iklan VAST di media Anda, buat objek vastAdsRequest dan tetapkan objek tersebut ke properti vastAdsRequest dari BreakClip. Objek vastAdsRequest harus memiliki properti adsResponse atau properti adTagUrl yang ditentukan.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    vastAdsRequest:{
      adTagUrl: 'https://castsample.com/vast?rand=' + Math.floor(Math.random()* 10000)
    }
  }];
}

Web Receiver SDK mengirimkan permintaan ke adTagUrl yang ditentukan dan mengurai respons XML untuk menghasilkan objek BreakClip. Di bawah ini adalah contoh objek BreakClip yang dihasilkan oleh SDK kita.

{
  "id": "GENERATED:0",
  "contentId": "https://file.mp4",
  "contentType": "video/mp4",
  "title": "Preroll",
  "duration": 10,
  "clickThroughUrl": "https://click"
}

Iklan VMAP

Web Receiver SDK juga mendukung standar VMAP IAB. Saat VMAP diberikan, Cast SDK akan mengurai respons VMAP dan membuat objek Break untuk entri <AdBreak> yang diberikan dalam respons. Cara ini juga akan menghasilkan BreakClips yang sesuai dengan objek vastAdsRequest untuk setiap entri <AdSource> yang disediakan di VMAP. Untuk menggunakan VMAP untuk menyisipkan iklan ke dalam konten, buat objek vastAdsRequest dan tetapkan ke properti vmapAdsRequest dari objek MediaInformation sebagai bagian dari permintaan pemuatan Anda.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.vmapAdsRequest = {
    adTagUrl: 'https://castsample.com/vmap?rand=' + Math.floor(Math.random()* 10000)
  };
}

Penggabungan iklan sisi server

Untuk penyambungan sisi server, yang juga disebut sebagai iklan tersemat, server diharapkan menyediakan satu aliran yang berisi media dan iklan utama. Dalam hal ini, developer diharapkan menyediakan duration dan contentType dari BreakClip. contentUrl dihilangkan. Selain itu, isEmbedded harus disetel ke benar (true).

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    title: third_party.getBreakClipTitle('bc1'),
    posterUrl: third_party.getBreakClipPosterUrl('bc1'),
    duration: third_party.getBreakClipDuration('bc1')
  },
  {
    id: 'bc2'
    ...
  },
  {
    id: 'bc3'
    ...
  },
  {
    id: 'bc4'
    ...
  }];
  mediaInformation.breaks = [
  {
    id: 'b1',
    breakClipIds: ['bc1', 'bc2'],
    position: 0,
    isEmbedded: true
  },
  {
    id: 'b2',
    breakClipIds: ['bc3', 'bc4'],
    position: 10*60,
    isEmbedded: true
  }];
}

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    loadRequestData => {
      addBreakToMedia(loadRequestData.media);
      return loadRequestData;
    });
context.start();

Perilaku jeda

Perilaku jeda default

  1. Setelah dimulai, jeda akan ditandai sebagai isWatched. Jika pengguna kemudian menggeser ke titik yang lebih awal dari jeda, konten akan mulai diputar seperti biasa, dan jeda akan dilewati seperti sebelumnya.
  2. Jika pengguna menggeser setelah jeda tanpa menonton jeda, jeda yang terakhir diputar antara posisi seekFrom dan seekTo akan diputar sebelum pemutaran konten dimulai.

Perilaku jeda kustom

default behavior untuk klip jeda dan jeda dapat diubah menggunakan metode setBreakClipLoadInterceptor dan setBreakSeekInterceptor pada objek BreakManager.

setBreakClipLoadInterceptor

setBreakClipLoadInterceptor dipanggil sebelum jeda terjadi. Fungsi ini dipanggil satu kali per klip jeda. Objek ini meneruskan objek BreakClip ke dalam fungsi callback.

Misalnya, jika ada jeda pre-roll, setBreakClipLoadInterceptor akan dipanggil untuk jeda pre-roll segera setelah pemutaran dimulai. Segera setelah pre-roll selesai diputar, setBreakClipLoadInterceptor untuk istirahat berikutnya akan dipanggil.

Jika null atau tidak ada apa pun yang ditampilkan dalam fungsi callback ke setBreakClipLoadInterceptor, klip jeda akan dilewati. Semua pencegat untuk jeda akan segera dipanggil.

Dengan menggunakan setBreakClipLoadInterceptor, objek BreakClip dapat diubah sebelum pemutarannya dimulai.

setBreakSeekInterceptor

setBreakSeekInterceptor dipicu setelah operasi pencarian dan meneruskan objek BreakSeekData ke fungsi callback. Objek BreakSeekData berisi array Jeda yang posisinya ditentukan antara waktu pemutaran saat ini dan mencari waktu tujuan (misalnya seekFrom dan seekTo). Setelah operasi pencarian maju, perilaku default-nya adalah memutar jeda yang belum diputar sebelum waktu seekTo. Setelah jeda selesai diputar, pemutaran konten dilanjutkan dari posisi seekTo.

Interseptor ini memungkinkan objek BreakClip di masing-masing Jeda untuk diubah.

Jika ingin menyesuaikan perilaku, Anda dapat mengimplementasikan setBreakSeekInterceptor untuk mengganti default behavior. Jika setBreakSeekInterceptor diimplementasikan, Anda harus secara eksplisit menentukan jeda yang akan diputar.

  • Jika nilai null atau tidak ada yang ditampilkan dari setBreakSeekInterceptor, jeda akan dilewati.
  • Jika objek yang sama yang diteruskan ke fungsi callback akan ditampilkan, default behavior akan diganti dan semua jeda akan diputar. Selain itu, jika pengguna menggeser ke titik sebelumnya, mereka akan melihat jeda meskipun sebelumnya telah menonton jeda tersebut. Jika setBreakSeekInterceptor tidak diterapkan, jeda yang telah ditonton akan dilewati.

Membuat klip jeda dapat dilewati

Agar klip jeda dapat dilewati, tentukan jumlah detik yang harus ditunggu sebelum klip jeda dapat dilewati di objek BreakClip.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(media) {
  media.breakClips = [
  {
    id: 'bc1',
    ...
    whenSkippable: 10 //to allow user to skip break clip from sender after 10 seconds
  }];
}

Lewati otomatis iklan

Iklan dapat dilewati secara otomatis tanpa interaksi pengguna. Dua cara untuk melewati iklan adalah:

  1. Penetapan properti isWatched dari Break ke true akan otomatis melewati jeda.
    playerManager.addEventListener(cast.framework.events.category.CORE, function(event){
      if(event.type === cast.framework.events.EventType.PLAYER_LOADING){
        let breaks = playerManager.getBreaks();
        for(let i in breaks){
          breaks[i].isWatched = true;
        }
      }
    });
  2. BreakClip dapat dilewati dengan menampilkan nilai null dalam callBack setBreakClipLoadInterceptor.
    playerManager.getBreakManager().setBreakClipLoadInterceptor(breakClip => {
      return null;
    });