Jeda Iklan

Ringkasan

Web Receiver SDK memiliki dukungan bawaan untuk jeda iklan dan iklan pengiring dalam streaming media tertentu. Iklan Display Google menyediakan API untuk menyetel posisi iklan, sumber iklan, perilaku jeda iklan dan klip jeda iklan yang terkait. Dalam panduan ini, Break merujuk pada interval untuk pemutaran yang berisi satu atau beberapa iklan atau bumper dan setiap iklan atau bumper disebut sebagai BreakClip. Jeda ini terkait dengan media yang sedang dimuat atau diputar.

Jenis iklan

Web Receiver SDK mendukung penyisipan iklan sisi klien (CSAI) dan server penyisipan iklan gabungan (SSAI). Iklan yang digabungkan klien dapat ditetapkan secara manual oleh aplikasi atau diekstrak dari file template VAST dan VMAP. Iklan yang digabungkan di server harus ditetapkan secara manual sebelum konten dimuat sebagai iklan yang disematkan atau secara dinamis selama pemutaran konten sebagai diperluas yang disematkan iklan. Penerapan untuk setiap jenis iklan ini dijelaskan secara mendetail di bawah.

// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.m3u8';
clipClient.contentType = 'application/vnd.apple.mpegurl';

// Optional: Used when HLS ad container formats differ from the main content's.
clipClient.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;

// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
    'break_postroll_client', ['bc_client'], -1);
breakPostrollClient.isEmbedded = false; // Optional: default is false.
breakPostrollClient.expanded = false; // Optional: default is false.

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/ads.xml'

// Create the BreakClip.
let clipVast = new cast.framework.messages.BreakClip('bc_vast');
clipVast.vastAdsRequest = vastTemplate;

// Create the Break using the BreakClip id above.
let breakPostrollVast = new cast.framework.messages.Break(
    'break_postroll_vast', ['bc_vast'], -1);
breakPostrollVast.isEmbedded = false; // Optional: default is false.
breakPostrollVast.expanded = false; // Optional: default is false.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  }
]

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "GENERATED:0"
    ],
    "position": 0,
    "isWatched": true
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  },
  {
    "id": "GENERATED:0",
    "contentId": "https://example.com/break-clip-1.mpd",
    "contentType": "application/dash+xml",
    "title": "Ad Title Extracted from Template",
    "duration": 10,
    "whenSkippable": 5,
    "clickThroughUrl": "https://example.com/ad-target"
  }
]

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/vmap.xml'

// Add it to the MediaInformation of the LoadRequest.
loadRequestData.media.vmapAdsRequest = vastTemplate;

// Create the BreakClip.
let clipEmbedded = new cast.framework.messages.BreakClip('bc_embedded');
clipEmbedded.title = 'The Ad Title to be displayed during playback';
clipEmbedded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbedded = new cast.framework.messages.Break(
    'break_preroll_embedded', ['bc_embedded'], 0);
breakPrerollEmbedded.isEmbedded = true;
breakPrerollEmbedded.expanded = false; // Optional: default is false.

// Create the BreakClip.
let clipEmbeddedExpanded =
    new cast.framework.messages.BreakClip('bc_embedded_expanded');
clipEmbeddedExpanded.title = 'The Ad Title to be displayed during playback';
clipEmbeddedExpanded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbeddedExpanded = new cast.framework.messages.Break(
    'break_preroll_embedded_expanded', ['bc_embedded_expanded'], 0);
breakPrerollEmbeddedExpanded.isEmbedded = true;
breakPrerollEmbeddedExpanded.expanded = true;

Jenis linimasa pemain

Saat membuat instance pemutar, Web Receiver SDK memilih jenis linimasa untuk mendukung pemutaran iklan selama pemutaran konten. Setiap linimasa memungkinkan iklan tertentu jenis jeda iklan yang akan ditambahkan. Jenis linimasa ditentukan oleh jenis iklan yang ada selama waktu pemuatan di MediaInformation dari LoadRequestData Jika ada jeda iklan yang disematkan, linimasa embedded akan dipilih. Jika Terdapat jeda iklan yang digabungkan klien, linimasa stitched dipilih. Jika tidak ada iklan, SDK akan menggunakan embedded secara default {i>timeline<i} (rentang waktu). Setelah dipilih, linimasa tidak dapat diubah untuk saat ini item media. Tabel di bawah memberikan deskripsi mendetail tentang setiap linimasa.

Gambar 1 sampai 3 di bawah mengilustrasikan beberapa konten dengan beragam jenis iklan dan nilai linimasa terkait. Konten dikonfigurasi dengan jeda pre-roll yang berisi dua klip jeda iklan serta jeda mid-roll dan post-roll yang berisi klip jeda tunggal. Waktu pengaturan waktu sejak awal pemutaran konten, waktu media konten utama, dan waktu jeda saat ini memutar klip jeda sejajar di bawah setiap gambar.

Posisi jeda

Web Receiver SDK memungkinkan developer menentukan lokasi jeda iklan dilakukan dengan menyetel position dari Break. Nilai ini sesuai dengan waktu media konten utama dan dapat digunakan untuk membuat jeda iklan pre-roll, mid-roll, dan post-roll. Hal ini didefinisikan sebagai berikut:

Matriks interoperabilitas

Sebagai referensi cepat, Tabel 1 menampilkan ringkasan jenis dan kompatibilitasnya dengan fitur terkait iklan.

Acara

Saat peristiwa kerusakan tombol terjadi, SDK transmisi akan mengirimkan peristiwa jenis BreaksEvent Aplikasi penerima dapat berlangganan paket tersebut menggunakan PlayerManager addEventListener Compute Engine API.

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

Jenis peristiwa tercantum dalam Tabel 2 bersama dengan deskripsi detail tentang ketika mereka dipecat.

Penyisipan iklan

SDK Cast memungkinkan aplikasi menyisipkan dan menghapus iklan pada berbagai momen dari sesi transmisi. Dua jenis penyisipan iklan adalah statis dan dinamis. Penyisipan iklan statis mengharuskan iklan ditentukan di bagian LoadRequestData sebelum pembuatan pemutar. Penyisipan iklan dinamis menggunakan BreakManager addBreak API untuk menyisipkan jeda di konten yang sudah dimuat. Setiap jenis penyisipan metode ini kompatibel dengan jenis iklan tertentu. Kompatibilitas ringkasan disediakan dalam matriks interoperabilitas.

Penyisipan iklan statis

Penyisipan iklan statis ditandai dengan menambahkan metadata iklan yang relevan sebelum hingga pembuatan pemutar. Informasi ini disediakan di MediaInformation dari LoadRequestData. Misalnya, ini dapat diatur dalam alamat IP permintaan pemuatan awal atau dapat disisipkan oleh aplikasi Penerima Web dengan mencegat permintaan LOAD. Setelah LoadRequestData ditampilkan ke Web Receiver SDK untuk diproses, pemutar akan dibuat. Lihat selengkapnya di memuat media. Contoh di bawah menampilkan iklan yang digabungkan klien secara manual yang ditambahkan dalam permintaan LOAD interseptor.

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

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {

  // Create the BreakClip.
  let clipClient = new cast.framework.messages.BreakClip('bc_client');
  clipClient.title = 'The Ad Title to be displayed during playback';
  clipClient.contentId = 'https://example.com/ad.mp4';
  clipClient.contentType = 'video/mp4';

  // Create the Break using the BreakClip id above.
  let breakPostrollClient = new cast.framework.messages.Break(
      'break_postroll_client', ['bc_client'], -1);

  // Set the ad information in the load request data.
  let media = loadRequestData.media;
  media.breakClips = [clipClient];
  media.breaks = [breakPostrollClient];

  return loadRequestData;
});

Penyisipan iklan dinamis

Penyisipan iklan dinamis ditandai dengan menetapkan jeda iklan selama konten berlangsung pemutaran. Hal ini dilakukan dengan mendapatkan instance BreakManager dan memanggil tindakan addBreak Compute Engine API. Proses ini memerlukan minimal dua parameter, diperluas tersemat Break dan array dari BreakClip Properti ketiga opsional disertakan untuk memaksa pengiriman perubahan ke pengirim yang terhubung melalui siaran MediaStatus jika disetel ke true. Kapan menambahkan klip jeda dan jeda, ID yang sesuai harus unik. Iklan-iklan ini hanya dapat ditambahkan setelah pemain telah dibuat. Web Receiver SDK diaktifkan tindakan PLAYER_LOADING setelah pemutar dibuat. Lihat contoh di bawah ini yang menampilkan penggunaan dalam pengendali peristiwa yang merespons perubahan metadata ID3 dari streaming dan membuat objek Break dan BreakClip untuk memasukkannya ke linimasa.

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

playerManager.addEventListener(cast.framework.events.EventType.ID3, (event) => {

  // Create the BreakClip.
  let clipEmbeddedExpanded = parseBreakClipFromData(event.segmentData);
  let breakEmbeddedExpanded = parseExpandedBreakFromData(event.segmentData);

  // Add the break and break clip.
  breakManager.addBreak(breakEmbeddedExpanded, [clipEmbeddedExpanded]);
});

Penghapusan iklan dinamis

Untuk menghapus jeda dinamis, aplikasi harus memanggil removeBreakById selama pemutaran. Fungsi ini mengambil ID string jeda untuk dihapus dari {i>timeline<i}. breakId yang ditentukan harus menunjuk ke penyematan yang disematkan jeda iklan diluaskan. Jika ada jenis jeda iklan lainnya yang terdeteksi, jeda iklan akan tetap ada di linimasa. Lihat contoh di bawah yang menghapus jeda.

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

breakManager.removeBreakById('break_midroll_embedded_expanded');

Perilaku istirahat

SDK menentukan perilaku default saat pemain masuk dan meninggalkan jeda dan menyediakan cara untuk menyesuaikannya lebih lanjut menggunakan beberapa API yang disediakan inci BreakManager

Perilaku jeda default

Saat Break dimasukkan melalui pemutaran reguler atau dengan mencari di atas Break, SDK akan mengevaluasi apakah pengguna sudah melihatnya atau belum dengan memeriksa tindakan isWatched saat ini. Saat dibuat, nilai default jeda untuk properti ini adalah false. Jika properti true, jeda tidak akan diputar saat dimasukkan dan main konten akan terus diputar. Jika properti adalah false, jedanya akan yang diputar saat dimasukkan.

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

Selama pemutaran jeda, SDK akan menyiarkan update yang relevan ke aplikasi pengirim di MediaStatus Aplikasi ini akan menggunakan siaran tersebut untuk memperbarui UI iklan dengan membaca tindakan breakStatus saat ini. Properti ini hanya ditentukan selama pemutaran jeda.

Aplikasi penerima juga dapat secara langsung mengkueri informasi yang berkaitan dengan posisi titik pemutaran terhadap waktu BreakClip saat ini ditampilkan dengan memanggil PlayerManager getBreakClipCurrentTimeSec Demikian pula, aplikasi dapat mengkueri durasi BreakClip saat ini dengan menelepon getBreakClipDurationSec.

Perilaku jeda kustom

Perilaku default untuk klip retak dan rusak dapat dimodifikasi menggunakan setBreakClipLoadInterceptor dan setBreakSeekInterceptor yang tersedia di BreakManager.

Intersepsi percobaan istirahat

Intersepsi pencarian jeda memungkinkan aplikasi mengontrol perilaku pencarian di atas jeda iklan. Fungsi ini dipicu saat operasi pencarian diminta yang bergerak maju atau mundur selama satu atau beberapa jeda. Saat dipanggil, BreakSeekData diteruskan sebagai parameter ke fungsi callback. Objek BreakSeekData berisi array Break objek yang properti position-nya disetel ke angka antara waktu pemutaran didefinisikan sebagai seekFrom dan waktu destinasi pencarian seekTo.

Pencegat ini memungkinkan objek Break di setiap jeda untuk diubah. Jika diterapkan, pencegat pencarian jeda harus menentukan iklan mana jeda untuk diputar dengan menampilkan objek BreakSeekData yang dimodifikasi secara opsional. Tujuan pemain akan melanjutkan untuk memutar semua jeda yang termasuk dalam nilai yang ditampilkan. Jika nilai dari null atau tidak ada yang ditampilkan dari pencegat pencarian jeda, jedanya akan dilewati.

Lihat contoh di bawah ini untuk implementasi sederhana pencegat yang mengganti perilaku default untuk menonton semua jeda iklan yang dicari dengan pengecualian jeda yang sudah ditonton.

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

breakManager.setBreakSeekInterceptor((breakSeekData) => {

  // Filter the breaks array by removing watched breaks.
  const unwatchedBreaks =
      breakSeekData.breaks.filter(adBreak => !adBreak.isWatched);
  breakSeekData.breaks = unwatchedBreaks;

  return breakSeekData;
});

Memutus interseptor pemuatan klip

Dengan menggunakan intersepsi pemuatan klip jeda, objek BreakClip dapat diubah sebelum pemutarannya dimulai.

Intersepsi pemuatan klip jeda hanya dipanggil untuk jeda linimasa yang digabungkan dan dapat diatur menggunakan setBreakClipLoadInterceptor Sebelum memasukkan Break, interseptor ini dipanggil sekali untuk setiap individu BreakClip ditentukan dalam jeda tersebut. SDK meneruskan BreakClip sebagai parameter fungsi callback. Aplikasi kemudian dapat memodifikasi BreakClip ini dan menampilkannya sehingga SDK dapat mengambil dan menampilkan jeda iklan dengan konfigurasi yang telah diperbarui. Jika null atau tidak ada yang ditampilkan, jeda iklan klip dilewati.

Lihat di bawah untuk contoh yang mengubah contentUrl klip jeda dengan fungsi utilitas memanggil getUrlFromClipId dengan id dari BreakClip dipetakan ke URL.

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

breakManager.setBreakClipLoadInterceptor(
    (breakClip, breakClipLoadInterceptorContext) => {

  // Obtains the URL of a break clip id from a function call.
  breakClip.contentUrl = getUrlFromClipId(breakClip.id);

  return breakClip;
});

Iklan Dilewati

Web Receiver SDK menyediakan API untuk melewati jeda iklan dan klip jeda individual dalam jeda iklan. SDK ini juga memungkinkan pengguna secara opsional melewati klip jeda dengan berinteraksi dengan aplikasi pengirim atau perangkat layar pintar mereka.

Klip jeda yang dapat dilewati pengguna

Menetapkan klip jeda iklan sebagai dapat dilewati akan memungkinkan pengguna berinteraksi dengan pengirim yang terhubung aplikasi dan perangkat layar pintar untuk memilih melewati bagian lainnya dari sedang memutar klip jeda. Menyetel whenSkippable ke jumlah detik non-negatif akan mengaktifkan fitur ini untuk Objek BreakClip. Pemutar akan menganggap klip jeda dapat dilewati setelah klip jeda telah diputar selama jumlah detik tersebut. Menetapkan nilai ini ke 0 memungkinkan pengguna untuk langsung melewati klip jeda.

// Create the BreakClip.
let clip = new cast.framework.messages.BreakClip('bc');
clip.title = 'The Ad Title to be displayed during playback';
clip.whenSkippable = 10; // Users can skip the clip after 10 seconds of playback.

Informasi ini dapat ditetapkan dalam permintaan pemuatan asli pengirim atau di aplikasi penerima. Jika dilewati, klip jeda iklan di jeda iklan linimasa yang digabungkan akan berhenti memutar klip jeda saat ini. Pemutar akan memuat jika ada, atau memuat konten utama. Jika dilewati, klip jeda dalam linimasa yang disematkan akan mengarah ke akhir klip jeda iklan melanjutkan pemutaran streaming pada saat itu.

Melewati iklan secara terprogram

Iklan juga dapat dilewati secara otomatis tanpa interaksi pengguna.

Agar tidak dapat memutar jeda aplikasi, aplikasi harus menyetel isWatched properti Break hingga true. Hal ini dapat dilakukan kapan saja selama proses pemuatan urutan video, atau pemutaran konten. Properti isWatched dievaluasi oleh pemutar ketika position jeda terpenuhi dalam waktu konten utama saat ini. Di pada saat itu, pemain akan menentukan apakah jeda harus dimasukkan atau tidak. Lihat contoh di bawah ini yang melakukan loop pada semua jeda dan memodifikasi saat pemutar sedang dimuat.

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

playerManager.addEventListener(cast.framework.events.EventType.PLAYER_LOADING,
    (event) => {

  // Obtain the breaks and iterate through each item to skip all ad breaks.
  let breaks = breakManager.getBreaks();
  breaks.forEach((brk) => {
    brk.isWatched = true;
  });
});

Untuk melewati klip jeda tertentu secara terprogram, intersepsi pemuatan klip jeda harus digunakan. Menurut menampilkan null atau tidak menampilkan nilai dalam fungsi callback, klip di jeda tersebut akan dilewati.

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

breakManager.setBreakClipLoadInterceptor(
      (breakClip, breakClipLoadInterceptorContext) => {
  return null;
});