Menampilkan iklan dalam konten video

2023-03-18

Peringatan

Mulai 1 Juni 2020, platform Monetisasi Microsoft Ad untuk aplikasi Windows UWP akan dimatikan. Pelajari lebih lanjut

Panduan ini menunjukkan cara menggunakan kelas AdScheduler untuk menampilkan iklan dalam konten video di aplikasi Platform Windows Universal (UWP) yang ditulis menggunakan JavaScript dengan HTML.

Catatan

Fitur ini saat ini hanya didukung untuk aplikasi UWP yang ditulis menggunakan JavaScript dengan HTML.

AdScheduler berfungsi dengan media progresif dan streaming, dan menggunakan format payload Templat Sajian Iklan Video (VAST) standar IAB 2.0/3.0 dan VMAP. Dengan menggunakan standar, AdScheduler bersifat agnostik ke layanan iklan yang berinteraksi dengannya.

Iklan untuk konten video berbeda berdasarkan apakah program berada di bawah sepuluh menit (bentuk pendek), atau lebih dari sepuluh menit (bentuk panjang). Meskipun yang terakhir lebih rumit untuk disiapkan pada layanan, sebenarnya tidak ada perbedaan dalam cara seseorang menulis kode sisi klien. Jika AdScheduler menerima payload VAST dengan satu iklan alih-alih manifes, itu diperlakukan seolah-olah manifes dipanggil untuk satu iklan pra-roll (satu jeda pada waktu 00:00).

Prasyarat

Instal Microsoft Advertising SDK dengan Visual Studio 2015 atau rilis yang lebih baru.
Proyek Anda harus menggunakan kontrol MediaPlayer untuk menayangkan konten video tempat iklan akan dijadwalkan. Kontrol ini tersedia dalam koleksi pustaka TVHelpers yang tersedia dari Microsoft di GitHub.

Contoh berikut menunjukkan cara mendeklarasikan MediaPlayer dalam markup HTML. Biasanya, markup ini berada di <body> bagian dalam file index.html (atau file html lain yang sesuai untuk proyek Anda).
```
<div id="MediaPlayerDiv" data-win-control="TVJS.MediaPlayer">
  <video src="URL to your content">
  </video>
</div>
```
Contoh berikut menunjukkan cara membuat MediaPlayer dalam kode JavaScript.
```
var mediaPlayerDiv = document.createElement("div");
document.body.appendChild(mediaPlayerDiv);

var videoElement = document.createElement("video");
videoElement.src = "<URL to your content>";
mediaPlayerDiv.appendChild(videoElement);

var mediaPlayer = new TVJS.MediaPlayer(mediaPlayerDiv);
```

Cara menggunakan kelas AdScheduler dalam kode Anda

Di Visual Studio, buka proyek Anda atau buat proyek baru.
Jika proyek Anda menargetkan CPU Apa pun, perbarui proyek Anda untuk menggunakan output build khusus arsitektur (misalnya, x86). Jika proyek Anda menargetkan CPU Apa pun, Anda tidak akan berhasil menambahkan referensi ke pustaka iklan Microsoft dalam langkah-langkah berikut. Untuk informasi selengkapnya, lihat Kesalahan referensi yang disebabkan oleh menargetkan CPU apa pun dalam proyek Anda.
Tambahkan referensi ke pustaka Microsoft Advertising SDK for JavaScript ke proyek Anda.
1. Dari jendela Penjelajah Solusi, klik kanan Referensi, dan pilih Tambahkan Referensi...
2. Di Pengelola Referensi, perluas Universal Windows, klik Ekstensi, lalu pilih kotak centang di samping Microsoft Advertising SDK for JavaScript (Versi 10.0).
3. Di Manajer Referensi, klik OK.
Tambahkan file AdScheduler.js ke proyek Anda:
1. Di Visual Studio, klik Proyek dan Kelola Paket NuGet.
2. Dalam kotak pencarian, ketik Microsoft.StoreServices.VideoAdScheduler dan instal paket Microsoft.StoreServices.VideoAdScheduler. File AdScheduler.js ditambahkan ke .. subdirektori /js dalam proyek Anda.
Buka file index.html (atau file html lainnya yang sesuai untuk proyek Anda). Di bagian , <head> setelah referensi JavaScript proyek default.css dan main.js, tambahkan referensi ke ad.js dan adscheduler.js.
```
<script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
<script src="/js/adscheduler.js"></script>
```
Catatan

Baris ini harus ditempatkan di bagian <head> setelah menyertakan main.js; jika tidak, Anda akan mengalami kesalahan saat membangun proyek Anda.
Dalam file main.js di proyek Anda, tambahkan kode yang membuat objek AdScheduler baru. Teruskan MediaPlayer yang menghosting konten video Anda. Kode harus ditempatkan sehingga berjalan setelah WinJS.UI.processAll.
```
var myMediaPlayer = document.getElementById("MediaPlayerDiv");
var myAdScheduler = new MicrosoftNSJS.Advertising.AdScheduler(myMediaPlayer);
```
Gunakan metode requestSchedule atau requestScheduleByUrl dari objek AdScheduler untuk meminta jadwal iklan dari server dan menyisipkannya ke garis waktu MediaPlayer, lalu putar media video.
- Jika Anda adalah mitra Microsoft yang telah menerima izin untuk meminta jadwal iklan dari server iklan Microsoft, gunakan requestSchedule dan tentukan ID aplikasi dan ID unit iklan yang diberikan kepada Anda oleh perwakilan Microsoft Anda.
  
  Metode ini mengambil bentuk Promise, yang merupakan konstruksi asinkron di mana dua pointer fungsi diteruskan: pointer untuk fungsi onComplete untuk memanggil ketika janji berhasil diselesaikan dan pointer untuk fungsi onError untuk memanggil jika kesalahan ditemui. Dalam fungsi onComplete, mulai pemutaran konten video Anda. Iklan akan mulai diputar pada waktu yang dijadwalkan. Dalam fungsi onError Anda, tangani kesalahan lalu mulai pemutaran video Anda. Konten video Anda akan diputar tanpa iklan. Argumen fungsi onError adalah objek yang berisi anggota berikut.
```
myAdScheduler.requestSchedule("your application ID", "your ad unit ID").then(
  function promiseSuccessHandler(schedule) {
      // Success: play the video content with the scheduled ads.
      myMediaPlayer.tvControl.play();
  },
  function promiseErrorHandler(err) {
      // Error: play the video content without the ads.
      myMediaPlayer.tvControl.play();
  });
```
- Untuk meminta jadwal iklan dari server iklan non-Microsoft, gunakan requestScheduleByUrl, dan teruskan URI server. Metode ini juga mengambil bentuk Promise yang menerima pointer untuk fungsi onComplete dan onError . Payload iklan yang dikembalikan dari server harus sesuai dengan format payload Video Ad Serving Template (VAST) atau Video Multiple Ad Playlist (VMAP).
```
myAdScheduler.requestScheduleByUrl("your URL").then(
  function promiseSuccessHandler(schedule) {
      // Success: play the video content with the scheduled ads.
      myMediaPlayer.winControl.play();
  },
  function promiseErrorHandler(evt) {
      // Error: play the video content without the ads.
      myMediaPlayer.winControl.play();
  });
```
Catatan

Anda harus menunggu requestSchedule atau requestScheduleByUrl kembali sebelum mulai memutar konten video utama di MediaPlayer. Mulai memutar media sebelum requestSchedule kembali (dalam kasus iklan pra-roll) akan mengakibatkan pra-roll mengganggu konten video utama. Anda harus memanggil putar meskipun fungsi gagal, karena AdScheduler akan memberi tahu MediaPlayer untuk melewati iklan dan langsung berpindah ke konten. Anda mungkin memiliki persyaratan bisnis yang berbeda, seperti menyisipkan iklan bawaan jika iklan tidak berhasil diambil dari jarak jauh.

Selama pemutaran, Anda dapat menangani peristiwa tambahan yang memungkinkan aplikasi melacak kemajuan dan/atau kesalahan yang mungkin terjadi setelah proses pencocokan iklan awal. Kode berikut menunjukkan beberapa peristiwa ini, termasuk onPodStart, onPodEnd, onPodCountdown, onAdProgress, onAllComplete, dan onErrorOccurred.

// Raised when an ad pod starts. Make the countdown timer visible.
myAdScheduler.onPodStart = function (sender, data) {
    myCounterDiv.style.visibility = "visible";
}

// Raised when an ad pod ends. Hide the countdown timer.
myAdScheduler.onPodEnd = function (sender, data) {
    myCounterDiv.style.visibility = "hidden";
}

// Raised when an ad is playing and indicates how many seconds remain  
// in the current pod of ads. This is useful when the app wants to show 
// a visual countdown until the video content resumes.
myAdScheduler.onPodCountdown = function (sender, data) {
    myCounterText = "Content resumes in: " +
    Math.ceil(data.remainingPodTime) + " seconds.";
}

// Raised during each quartile of progress through the ad clip.
myAdScheduler.onAdProgress = function (sender, data) {
}

// Raised when the ads and content are complete.
myAdScheduler.onAllComplete = function (sender) {
}

// Raised when an error occurs during playback after successfully scheduling.
myAdScheduler.onErrorOccurred = function (sender, data) {
}

Anggota AdScheduler

Bagian ini menyediakan beberapa detail tentang anggota objek AdScheduler . Untuk informasi selengkapnya tentang anggota ini, lihat komentar dan definisi dalam file AdScheduler.js di proyek Anda.

permintaanJadwal

Metode ini meminta jadwal iklan dari server iklan Microsoft dan menyisipkannya ke garis waktu MediaPlayer yang diteruskan ke konstruktor AdScheduler .

Parameter ketiga opsional (adTags) adalah kumpulan pasangan nama/nilai JSON yang dapat digunakan untuk aplikasi yang memiliki penargetan lanjutan. Misalnya, aplikasi yang memutar berbagai video terkait otomatis dapat melengkapi ID unit iklan dengan membuat dan model mobil yang ditampilkan. Parameter ini dimaksudkan untuk digunakan hanya oleh mitra yang menerima persetujuan dari Microsoft untuk menggunakan tag iklan.

Item berikut harus dicatat saat merujuk ke adTags:

Parameter ini adalah opsi yang sangat jarang digunakan. Penerbit harus bekerja sama dengan Microsoft sebelum menggunakan adTags.
Nama dan nilai harus ditentukan sebelumnya pada layanan iklan. Tag iklan tidak terbuka dengan istilah atau kata kunci pencarian yang diakhir.
Jumlah tag maksimum yang didukung adalah 10.
Nama tag dibatasi hingga 16 karakter.
Nilai tag memiliki maksimal 128 karakter.

PermintaanJadwalDenganUri

Metode ini meminta jadwal iklan dari server iklan non-Microsoft yang ditentukan dalam URI dan menyisipkannya ke garis waktu MediaPlayer yang diteruskan ke konstruktor AdScheduler . Payload iklan yang dikembalikan oleh server iklan harus sesuai dengan format payload Video Ad Serving Template (VAST) atau Video Multiple Ad Playlist (VMAP).

mediaTimeout

Properti ini mendapatkan atau mengatur jumlah milidetik yang harus diputar media. Nilai 0 menginformasikan sistem untuk tidak pernah waktu habis. Defaultnya adalah 30000 ms (30 detik).

putarMediaYangTerlewati

Properti ini mendapatkan atau menetapkan nilai Boolean yang menunjukkan apakah media terjadwal akan diputar jika pengguna melompat ke titik melewati waktu mulai terjadwal.

Klien iklan dan pemutar media akan menerapkan aturan dalam hal apa yang terjadi pada iklan selama penerusan cepat dan putar balik konten video utama. Dalam kebanyakan kasus, pengembang aplikasi tidak mengizinkan iklan untuk sepenuhnya dilewati tetapi ingin memberikan pengalaman yang wajar bagi pengguna. Dua opsi berikut termasuk dalam kebutuhan sebagian besar pengembang:

Izinkan pengguna akhir untuk melewati pod iklan sesering mungkin.
Izinkan pengguna untuk melewati pod iklan tetapi memutar pod terbaru saat pemutaran dilanjutkan.

Properti playSkippedMedia memiliki kondisi berikut:

Iklan tidak dapat dilewati atau diteruskan dengan cepat setelah iklan dimulai.
Semua iklan dalam pod iklan akan diputar setelah pod dimulai.
Setelah diputar, iklan tidak akan diputar lagi selama konten utama (film, episode, dll.); penanda iklan akan ditandai sebagai diputar atau dihapus.
Iklan pra-peluncuran tidak dapat dilewati.

Saat meneruskan konten yang berisi iklan, atur playSkippedMedia ke false untuk melewati pra-putar dan mencegah jeda iklan terbaru diputar. Kemudian, setelah konten dimulai, atur playSkippedMedia ke true untuk memastikan bahwa pengguna tidak dapat meneruskan dengan cepat melalui iklan berikutnya.

Catatan

Pod adalah sekelompok iklan yang diputar secara berurutan, seperti sekelompok iklan yang diputar selama jeda komersial. Untuk detail selengkapnya, lihat spesifikasi IAB Digital Video Ad Serving Template (VAST).

requestTimeout

Properti ini mendapatkan atau mengatur jumlah milidetik untuk menunggu respons permintaan iklan sebelum waktu habis. Nilai 0 menginformasikan sistem untuk tidak pernah waktu habis. Defaultnya adalah 30000 ms (30 detik).

jadwal

Properti ini mendapatkan data jadwal yang diambil dari server iklan. Objek ini mencakup hierarki lengkap data yang sesuai dengan struktur payload Video Ad Serving Template (VAST) atau Video Multiple Ad Playlist (VMAP).

onAdProgress

Kejadian ini dinaikkan ketika pemutaran iklan mencapai titik pemeriksaan kuartil. Parameter kedua penanganan aktivitas (eventInfo) adalah objek JSON dengan anggota berikut:

progress: Status pemutaran iklan (salah satu nilai enum MediaProgress yang ditentukan dalam AdScheduler.js).
klip: Klip video yang sedang diputar. Objek ini tidak dimaksudkan untuk digunakan dalam kode Anda.
adPackage: Objek yang mewakili bagian dari payload iklan yang sesuai dengan iklan yang sedang diputar. Objek ini tidak dimaksudkan untuk digunakan dalam kode Anda.

padaSemuaSelesai

Acara ini dimunculkan ketika konten utama mencapai akhir dan iklan pasca-pemutaran terjadwal juga berakhir.

saatGangguanTerjadi

Kejadian ini dimunculkan ketika AdScheduler mengalami kesalahan. Untuk informasi selengkapnya tentang nilai kode kesalahan, lihat ErrorCode.

onPodCountdown

Kejadian ini dimunculkan ketika iklan diputar dan menunjukkan berapa banyak waktu yang tersisa di pod saat ini. Parameter kedua penanganan aktivitas (eventData) adalah objek JSON dengan anggota berikut:

remainingAdTime: Jumlah detik yang tersisa untuk iklan saat ini.
remainingPodTime: Jumlah detik yang tersisa untuk pod saat ini.

Catatan

onPodEnd

Kejadian ini dimunculkan ketika pod iklan berakhir. Parameter kedua penanganan aktivitas (eventData) adalah objek JSON dengan anggota berikut:

startTime: Waktu mulai pod, dalam hitung detik.
pod: Objek yang mewakili pod. Objek ini tidak dimaksudkan untuk digunakan dalam kode Anda.

onPodStart

Kejadian ini dimunculkan ketika pod iklan dimulai. Parameter kedua penanganan aktivitas (eventData) adalah objek JSON dengan anggota berikut:

startTime: Waktu mulai pod, dalam hitung detik.
pod: Objek yang mewakili pod. Objek ini tidak dimaksudkan untuk digunakan dalam kode Anda.

Bagikan melalui

Menampilkan iklan dalam konten video

Prasyarat

Cara menggunakan kelas AdScheduler dalam kode Anda

Anggota AdScheduler

permintaanJadwal

PermintaanJadwalDenganUri

mediaTimeout

putarMediaYangTerlewati

requestTimeout

jadwal

onAdProgress

padaSemuaSelesai

saatGangguanTerjadi

onPodCountdown

onPodEnd

onPodStart

Saran dan Komentar

Sumber Daya Tambahan: